Examples Overview

The Popcorning Guinea Pig engine includes several comprehensive example projects that demonstrate various features and capabilities. These examples serve as both learning tools and starting points for your own projects.

Available Examples

1. Main Menu Example

Location: examples/main-menu/MainMenu/

A complete main menu implementation showcasing:

• Settings Management: Resolution, display mode, and monitor selection
• UI Components: Buttons, panels, sliders, and dropdowns
• Nine-Slice Textures: Scalable UI elements with proper borders
• Settings Persistence: JSON-based configuration saving/loading
• Service Integration: Audio, settings, and localization services

Key Features Demonstrated:

// Settings management
var settings = settingsService.LoadSettings("settings.json");
settingsService.ApplySettings(settings, game);

// UI component creation
var settingsButton = new Button(position, size, "Settings");
settingsButton.SetOnClick(() => {
    sceneManager.ChangeScene(new SettingsScene());
});

// Nine-slice scaling for scalable buttons
var nineSliceRects = Button.CreateNineSliceRects(texture, cornerSize: 8);
var scalableButton = new Button(texture, position, size, nineSliceRects);

2. Nine-Slice Texture Demo

Location: examples/nine-slice-texture/NineSliceExample/

Demonstrates advanced UI scaling techniques:

• Nine-Slice Scaling: Borders that don't distort when resizing
• Multiple Button States: Normal, hover, and pressed appearances
• UI Layouts: Proper spacing and alignment
• Asset Integration: Using Kenney UI assets

Key Concepts:

// Create nine-slice regions
Rectangle[] nineSliceRects = new Rectangle[9] {
    // Top row: left, center, right corners
    new Rectangle(0, 0, 8, 8),       // Top-left
    new Rectangle(8, 0, 48, 8),      // Top-center (stretches horizontally)
    new Rectangle(56, 0, 8, 8),      // Top-right
    // And so on for middle and bottom rows...
};

// Apply to button for scalable UI
var button = new Button(texture, position, size, nineSliceRects);

3. Card Game Example

Location: examples/card-game/CardGame/

A 3D card game demonstration featuring:

• 3D Card System: Physical card representations with animations
• Card Interactions: Drag, drop, flip, and hover effects
• Game Logic: Turn-based gameplay mechanics
• 3D Rendering: Camera controls and 3D positioning
• Particle Effects: Visual feedback for actions

3D Card Usage:

// Create a 3D card
var card = new Card3D(
    frontTexture: cardFrontTexture,
    backTexture: cardBackTexture,
    position: new Vector3(0, 0, 0),
    size: new Vector2(2.5f, 3.5f)
);

// Add interactive sections
card.AddSection("title", new Rectangle(10, 10, 200, 30));
card.AddSection("artwork", new Rectangle(10, 50, 200, 120));

// Animate the card
card.Flip(duration: 0.5f);
card.MoveTo(targetPosition, duration: 1.0f);

4. Unicode Test Example

Location: examples/unicode-test/UnicodeTest/

Demonstrates multi-language text rendering:

• Font Loading: Multiple language-specific fonts
• Unicode Support: Emoji, Japanese, Korean, Chinese characters
• Text Rendering: UTF-8 text from a Raylib codepoint atlas
• Localization: Dynamic language switching

Multi-language Text:

// Set up fonts for different languages
var fontPaths = new Dictionary<string, string> {
    ["en"] = "assets/Roboto-Regular.ttf",
    ["ja"] = "assets/NotoSansJP-VariableFont_wght.ttf",
    ["ko"] = "assets/NotoSansKR-VariableFont_wght.ttf",
    ["zh"] = "assets/NotoSansSC-VariableFont_wght.ttf",
    ["emoji"] = "assets/NotoColorEmoji-Regular.ttf"
};

localizationService.SetFontPaths(fontPaths);

// Render text in different languages
var label = new Label("こんにちは世界", position, fontSize, Color.WHITE);
label.SetLocalizationService(localizationService);

5. Engine Splash Screen

Location: examples/engine-splash-screen/EngineSplashScreen/

Icon generation and branding utilities:

• Icon Generation: Automated icon creation for different platforms
• Batch Processing: Generate multiple sizes and formats
• Platform Integration: Windows ICO, macOS ICNS, Linux PNG
• Build Automation: Scripts for icon pipeline

Icon Generation:

// Generate icons for all platforms
var iconGenerator = new IconGenerator();
iconGenerator.GenerateWindowsIcons(sourceImage, outputDirectory);
iconGenerator.GenerateMacOSIcons(sourceImage, outputDirectory);
iconGenerator.GenerateLinuxIcons(sourceImage, outputDirectory);

6. PGPSCN Scene Format Example

Location: examples/main-menu-pgpscn/MainMenu/

Declarative scene creation using JSON:

• Scene Definition: JSON-based scene descriptions
• UI Element Factory: Automatic UI creation from data
• Data Binding: Dynamic content updates
• Scene Loading: Runtime scene assembly

PGPSCN Scene File:

{
  "metadata": {
    "name": "MainMenu",
    "version": "1.0",
    "sceneType": "2D"
  },
  "ui": {
    "elements": [
      {
        "type": "Button",
        "id": "playButton",
        "properties": {
          "text": "Play Game",
          "position": { "x": 400, "y": 300 },
          "size": { "width": 200, "height": 50 }
        },
        "actions": [
          {
            "trigger": "onClick",
            "command": "changeScene",
            "parameters": { "scene": "GameScene" }
          }
        ]
      }
    ]
  }
}

Running the Examples

Quick Start

Each example can be run independently:

# Navigate to any example
cd examples/main-menu/MainMenu

# Build and run
dotnet build
dotnet run

Visual Studio

1. Open the example's .csproj file
2. Set as startup project
3. Press F5 to run

Learning Path

For Beginners

1. Main Menu - Learn basic UI and scene management
2. Nine-Slice Demo - Understand scalable UI design
3. Your First Game - Follow the tutorial to build from scratch

For Intermediate Developers

1. Card Game - Explore 3D systems and game logic
2. PGPSCN Example - Learn declarative scene creation
3. Unicode Test - Implement multi-language support

For Advanced Users

1. Engine Splash Screen - Build automation and tooling
2. Custom Examples - Create your own example projects
3. Engine Contributions - Extend the engine with new features

Code Patterns Demonstrated

Scene Management

public class ExampleScene : Scene
{
    public override void Load()
    {
        // Initialize UI components and resources
    }
    
    public override void Update(double deltaTime)
    {
        // Update game state and handle input
    }
    
    public override void Render(int width, int height)
    {
        // Draw scene content
    }
    
    public override void Unload()
    {
        // Clean up resources
    }
}

Service Integration

public class GameWithServices : Game
{
    private ISoundPlayer soundPlayer;
    private ISettingsService settingsService;
    private ILocalizationService localizationService;
    
    public override void Load()
    {
        // Initialize services
        soundPlayer = new SoundPlayer();
        settingsService = new SettingsService();
        localizationService = new LocalizationService();
        
        // Configure services
        localizationService.LoadLocalization("localization.json");
        var settings = settingsService.LoadSettings("settings.json");
        settingsService.ApplySettings(settings, this);
    }
}

UI Component Usage

// Button with event handling
var button = new Button(position, size, "Click Me");
button.SetOnClick(() => {
    soundPlayer.PlayMenuClick();
    sceneManager.ChangeScene(new NextScene());
});

// Slider with value callback
var volumeSlider = new Slider(position, size, 0, 100, 50);
volumeSlider.SetOnValueChanged(volume => {
    soundPlayer.UpdateSettings("playlist", volume);
});

// Dropdown with options
var resolutionDropdown = new Dropdown<Resolution>(position, size);
var resolutions = settingsService.GetSupportedResolutions();
resolutionDropdown.SetOptions(resolutions);
resolutionDropdown.SetOnSelectionChanged(resolution => {
    // Apply new resolution
});

Asset Organization

Examples follow consistent asset organization:

ExampleProject/
├── Program.cs              # Entry point
├── MyGame.cs              # Game class
├── scenes/                # Scene implementations
│   ├── MainMenuScene.cs
│   └── SettingsScene.cs
├── assets/                # Game assets
│   ├── textures/
│   ├── fonts/
│   ├── sounds/
│   └── data/
└── settings.json          # Configuration file

Building Custom Examples

Template Structure

Use this template for new examples:

using PopcorningGuineaPig.Engine;
using PopcorningGuineaPig.Engine.Scenes;
using PopcorningGuineaPig.Engine.Services;

namespace MyExample
{
    public class MyExampleGame : Game
    {
        private SceneManager sceneManager;
        
        public override void Load()
        {
            sceneManager = new SceneManager();
            sceneManager.ChangeScene(new MyExampleScene());
        }
        
        public override void Update(double deltaTime)
        {
            sceneManager.Update(deltaTime);
        }
        
        public override void Render()
        {
            sceneManager.Render();
        }
    }
}

Best Practices

1. Keep Examples Focused: Each example should demonstrate specific features
2. Include Comments: Explain what each part does
3. Error Handling: Show proper resource cleanup
4. Cross-Platform: Test on multiple operating systems
5. Asset Attribution: Include proper licensing for assets

Contributing Examples

We welcome new examples! When contributing:

1. Follow Patterns: Use established code patterns
2. Document Features: Include README with feature description
3. Test Thoroughly: Verify cross-platform compatibility
4. Keep Dependencies Minimal: Avoid unnecessary external libraries

Troubleshooting Examples

Common Issues

Example won't build:

• Check .NET version compatibility
• Verify engine project reference
• Ensure all assets are present

Graphics not appearing:

• Verify asset paths are correct
• Check coordinate systems and screen bounds
• Ensure proper resource disposal

Poor performance:

• Check for resource leaks in Update loops
• Verify proper disposal in Unload methods
• Monitor memory usage during runtime

Next Steps

After exploring the examples:

1. Core Concepts - Understand the underlying architecture
2. UI System - Learn about all UI components
3. Services - Explore service integrations
4. Advanced Features - Dive into 3D capabilities

---

The examples provide a comprehensive overview of the Popcorning Guinea Pig engine's capabilities. Use them as reference implementations and starting points for your own projects.