PacDessert1436.MonoGame.StartKitVB 1.2.12

MonoGame 2D StartKit VB.NET

⚠️ Special Reminders

Extra edge-case fix for iOS users:

• The 1.x line previously lacked the iOS platform check in GameMain.vb. If you are using version 1.2.9 or earlier and targeting iOS, add this line inside the Initialize() method:

If OperatingSystem.IsAndroid() OrElse OperatingSystem.IsIOS() Then

• This fix is included in versions 1.2.10 and later for both templates (blank and full demo). Version 1.2.12 is the current recommended 1.x release. Direct iOS device validation is still limited because no iOS test device has yet been available, so iOS support should be considered provisional. No action is required if you only deploy to Android, Windows, Linux, or macOS.

For patching GameManager.vb: See Important Notes on GameManager.vb for concise guidance on safe shutdown and input handling.

For users of v1.2.5, v1.2.8, and v1.2.8.1:

• v1.2.5 contains a critical null-reference crash that can occur when pausing, returning to the menu, and then restarting the demo game. If you are still using v1.2.5, add the following snippet at the top of the Update() method in GameMain.vb:

With _gameManager
    If .Player IsNot Nothing AndAlso .Player.Joystick Is Nothing Then
        .Player.Joystick = _renderer.Joystick
    End If
End With

• v1.2.8 and v1.2.8.1 both had important issues, where scheduling methods generated by ModuleEventRaiser.Generator could swallow exceptions when loggerAction was missing, and empty Catch blocks were found in the high-score load/save logic in Essentials.vb. These were fixed in v1.2.8.1 and v1.2.8.2 respectively.
• If you are using v1.2.8, upgrade ModuleEventRaiser.Generator to v1.2.5.1 as soon as possible. v1.2.8.2 or later is strongly recommended for the high-score logging fix; earlier versions require manual changes to the Catch blocks.

About the icon generator scripts:

• Since v1.2.0, the scripts/ folder has included both Python and Shell scripts for generating platform-specific app icons and splash screens from source images in the Content/ folder.
• Python scripts are recommended because they are cross-platform and have always worked correctly. Shell scripts use the macOS sips command and are intended for macOS only; however, they were broken from v1.2.0 through v1.2.5 due to path resolution issues. This was fixed in v1.2.7 and later.
• For usage instructions, see Script Usage Instructions. Shell scripts will be removed in v2.0.0 and later.

A multi-platform game template built with VB.NET and MonoGame, featuring the demo game Seed-Scape: Forest Planting Quest and a blank starter template for creating new projects.

The 1.x line is now in its final release phase, and version 1.2.12 is the current recommended release. It mitigates the enemy 180° direction-flip bug and polishes documentation and respawn logic, keeping the 1.x line stable for existing projects. Version 1.2.11 remains the previous recommended release with the exit-flow fix, the iOS platform check, and the high-score save path resolution.

Version 2.0.0, which will introduce the new demo game Mending Garden, is planned but currently paused while the author prepares for the Postgraduate Entrance Exam. See Roadmap → Version 2.0.0 for details.

Starting from version 1.2.0, all assets are fully licensed and attribution-ready:

• Main character sprite adapted from CC0-licensed art
• Original graphics created in Aseprite (published to Open Game Art)
• All audio assets are CC0-licensed from Open Game Art
• Font properly licensed for commercial use
• Blank template available from version 1.2.4 for starting your own projects

🚨 Important Notice: Versions prior to 1.2.0 have been unlisted and should not be used due to potential copyright concerns with included assets. Always use version 1.2.0 or later for production projects.

---

Overview

• Project Name: PacDessert1436.MonoGame.StartKitVB
• Template Short Name: mg2dstartkitvb
• Game Name: Seed-Scape: Forest Planting Quest

PacDessert1436.MonoGame.StartKitVB is a production-ready game template demonstrating modern MonoGame development practices using VB.NET.

Designed as a VB.NET alternative to the original C# MonoGame StartKit (mg2dstartkit), this template enables VB.NET developers — especially those transitioning from vbPixelGameEngine — to leverage MonoGame's powerful game development capabilities.

This package uses C# platform hosting projects for Android compatibility (required by MonoGame's Android binding source generators), while keeping the game logic and core implementation in VB.NET. The repository includes two template variants:

1. Complete Demo Game: Seed-Scape: Forest Planting Quest — an arcade game where players collect seeds to grow a forest while dodging patrolling insects.
2. Blank Template (mgblank2dstartkitvb): a clean starting point for your own MonoGame projects (available from version 1.2.4).

Versions 1.2.0 through 1.2.3 had template ID collisions that made the blank template unavailable; the demo-game template (mg2dstartkitvb) remained available across all these versions. Additionally, v1.2.3 marks the final gameplay polish for the v1.x series (see Version History for details).

New to MonoGame? Check out BEGINNER_GUIDE.md for a comprehensive guide to transitioning from vbPixelGameEngine to MonoGame.

Release Status and Chronology

The 1.x line is now in its final release phase. The current recommended version is 1.2.12, which is the latest edge-case fix — another patch release that keeps the line stable while mitigating the enemy 180° direction-flip bug and polishing XML documentation and respawn logic. This patch release also completes and corrects the XML documentation in SpriteSheet.vb and simplifies the enemy respawn logic by centralizing position resetting through Enemy.RespawnAt(). No other parts of the game logic are affected.

• Version 1.2.12 mitigates the enemy 180° direction-flip bug by adjusting Actor.ValidDirections() in Actor.vb so the opposite direction is never offered as a valid choice; enemies may only continue forward or turn sideways.
• Version 1.2.11 includes a small exit-flow fix in GameManager.vb so the game closes through the normal MonoGame shutdown path rather than relying on the abrupt Environment.Exit(0) fallback. It is a conservative patch release for existing projects.
• Version 1.2.10 includes the iOS adapter fix in GameMain.vb, which was the last major cleanup pass for the 1.x line, along with high-score save path resolution in v1.2.9.
• Version 1.2.8.3 is the performance-focused release. It improves runtime efficiency, reduces overhead in the renderer and actor loop, and includes a small internal cleanup pass, but it does not include the project-specific high-score storage fix.
• Version 2.0.0 is planned for a new demo game, Mending Garden, but development is currently paused while the author focuses on exam preparation. Updates will resume after the exam.

Note: If you want to avoid high-score save path collisions between different projects using this template, upgrade to version 1.2.9 or later.

Earlier 1.2.8 and 1.2.7 updates

The 1.2.8.x line also introduced:

• real-time high score display in the demo game
• safer exception handling around scheduled events and high-score load/save paths
• a dependency update to ModuleEventRaiser.Generator 1.2.5.1

The 1.2.7.x line improved the blank template experience with letterboxing, tap/click input, cleaner rendering flow, iOS hosting support, shell-script fixes, and broader gamepad support.

Script Usage Instructions

Python Scripts (Recommended for All Platforms)

# Install dependencies (one-time setup)
pip install -r scripts/requirements.txt

# Generate Android icons and splash screens
python3 scripts/android-icons-generator.py

# Generate iOS icons
python3 scripts/ios-icons-generator.py

# Generate macOS icons
python3 scripts/mac-icons-generator.py

Shell Scripts for macOS Only (Will Be Removed in Version 2.x)

# Make scripts executable (one-time setup)
chmod +x scripts/*.sh

# Generate Android icons and splash screens
./scripts/android-icons-generator.sh

# Generate iOS icons
./scripts/ios-icons-generator.sh

# Generate macOS icons
./scripts/mac-icons-generator.sh

Note: Shell scripts require the macOS sips command. Python scripts are recommended for cross-platform use because they provide better portability and more predictable behavior on Windows and Linux.

Important Notes on GameManager.vb

Version 1.2.11 already includes a safer exit flow for GameManager.vb if you're upgrading from an earlier 1.x release. To patch older code manually, make these changes and then ensure GameMain.vb passes Me into the GameManager constructor:

' In GameManager.vb:
Private ReadOnly _game As GameMain

Public Sub New(game As GameMain)
    HighScore = LoadHighScore()
    InitializeGame()
    _game = game
End Sub

Private Sub ExitGame()
    _game.Exit()
End Sub

Public Sub HandleInput()
    ' Replace any direct `Environment.Exit(0)` calls with `ExitGame()`.
End Sub

' Then update `Initialize()` in GameMain.vb with this line:
_gameManager = New GameManager(Me)

Additionally, because the button rendering in Renderer.vb is separate from input handling in GameManager.vb, keep shutdown and menu controls centralized in HandleInput() whenever you add or change buttons.

---

Project Status

Core Architecture

• ✅ Clean Architecture Pattern: Proper separation of concerns with dedicated managers
• ✅ Event-Driven Design: Comprehensive event system for game state management
• ✅ True OOP Implementation: Polymorphic actor system with base Actor class
• ✅ Memory Management: Complete IDisposable pattern implementation

Game Systems

• ✅ GameManager: Centralized game state management with collision detection
• ✅ Renderer: Advanced 2D rendering with sprite sheets and animations
• ✅ SoundManager: Fully functional audio playback support
• ✅ VirtualJoystick: Cross-platform input handling (touch, mouse, keyboard)

Entity System

• ✅ Actor Framework: Base class with Player, Enemy, and Seed subclasses
• ✅ Enemy Movement: Random patrolling behavior with direction changes
• ✅ Enemy Respawn Mechanics: Fully implemented and tested
• ✅ Progression System: Multiple seed types (Acorn, Berry, Nut) and enemy types (Beetle, Caterpillar) working seamlessly
• ✅ Forest Growth: Sapling-to-tree transformation when seeds are collected

Platform Support

• ✅ WindowsDX: Primary platform with full feature support
• ✅ Android: Touch input fully functional and tested
• ⚠️ iOS: Compatibility in progress (untested)
• ✅ DesktopGL: Now functional, though high DPI mode is unavailable (the game window may exceed screen height)

---

Project Structure

Blank Starter Template (mgblank2dstartkitvb)

Blank2DStartKitVB/
├── Blank2DStartKitVB.Core/        # Shared VB.NET game logic
│   ├── GameMain.vb                # Main game class
│   └── scripts/                   # Icon generator scripts
│       ├── android-icons-generator.py
│       ├── android-icons-generator.sh
│       ├── ios-icons-generator.py
│       ├── ios-icons-generator.sh
│       ├── mac-icons-generator.py
│       ├── mac-icons-generator.sh
│       └── requirements.txt
├── Blank2DStartKitVB.WindowsDX/   # Windows desktop launcher (C# host)
├── Blank2DStartKitVB.Android/     # Android mobile launcher (C# host)
├── Blank2DStartKitVB.iOS/         # iOS mobile launcher (C# host)
└── Blank2DStartKitVB.DesktopGL/   # Cross-platform OpenGL launcher (C# host)

Full Demo Game Template (mg2dstartkitvb):

MonoGameStartKitVB/
├── MonoGameStartKitVB.Core/         # Shared VB.NET game logic
│   ├── Actor.vb                     # Entity framework (Player, Enemy, Seed)
│   ├── Essentials.vb                # Constants, enums, events, utilities
│   ├── GameMain.vb                  # Main game class
│   ├── GameManager.vb               # Game state and logic
│   ├── Renderer.vb                  # Graphics rendering
│   ├── SoundManager.vb              # Audio management
│   ├── SpriteSheet.vb               # Sprite and animation system
│   ├── VirtualJoystick.vb           # Input handling
│   └── scripts/                     # Icon generator scripts
│       ├── android-icons-generator.py
│       ├── android-icons-generator.sh
│       ├── ios-icons-generator.py
│       ├── ios-icons-generator.sh
│       ├── mac-icons-generator.py
│       ├── mac-icons-generator.sh
│       └── requirements.txt
├── MonoGameStartKitVB.WindowsDX/    # Windows desktop launcher (C# host)
├── MonoGameStartKitVB.Android/      # Android mobile launcher (C# host)
├── MonoGameStartKitVB.iOS/          # iOS mobile launcher (C# host)
└── MonoGameStartKitVB.DesktopGL/    # Cross-platform OpenGL launcher (C# host)

Key Components

Component	Responsibility	Status
GameMain	Initializes game systems, coordinates Update/Draw cycles	✅ Complete
GameManager	Manages game state, collision detection, level progression	✅ Working
Renderer	Handles all rendering, animations, and HUD display	✅ Working
SoundManager	Plays background music and sound effects	✅ Working
Actor	Base class for all game entities with inheritance	✅ Working

Note: On version 1.2.9 and later, the GameMain class uses the Viewport constructor defaults for MinDepth (0.0) and MaxDepth (1.0) on Android - no need to explicitly write With {.MinDepth = 0.0, .MaxDepth = 1.0}.

---

Getting Started

Prerequisites

• Visual Studio 2026, Visual Studio Code, or another .NET-compatible IDE
• .NET SDK 10.0 or later
• MonoGame 3.8.5 installation (see Getting Started in the MonoGame documentation)
• Essential tools and extensions for VB.NET development

Using the NuGet Template

Install the template via NuGet:

dotnet new install PacDessert1436.MonoGame.StartKitVB

Create a new project with the demo game:

dotnet new mg2dstartkitvb -n YourGameName

Create a new project with the blank template:

dotnet new mgblank2dstartkitvb -n YourGameName

Building and Running from Source Code

1. Clone or download the project repository
2. Open the solution in your preferred .NET IDE
3. Restore NuGet packages if prompted
4. Set the startup project based on your target platform:

• WindowsDX: For Windows desktop development (recommended)
• Android: For mobile development and testing
• iOS: For Apple mobile development (requires macOS)
• DesktopGL: Cross-platform testing (high DPI mode unavailable)

5. Build and run the project

---

Game Features (Seed-Scape: Forest Planting Quest)

Core Gameplay

• Player Movement: Smooth 4-directional movement with responsive controls
• Seed Collection: Gather seeds to grow trees and earn points
• Enemy Movement: Patrolling insects with dynamic direction changes
• Pesticide Power-Up: Temporarily makes enemies vulnerable
• Forest Growth: Saplings transform into mature trees as seeds are collected
• Level Progression: Increasing difficulty with new enemy types as you advance

Input Support

• Keyboard: WASD or arrow keys for movement
• Touch: Optimized virtual joystick for mobile devices (fully tested and functional)
• Mouse: Click-based controls for menus and virtual joystick interaction

Visual Features

• Sprite Animations: Smooth, fluid animations for all game entities
• Dynamic HUD: Real-time display of score, lives, level, and high score
• Multiple Game States: Title screen, in-game, paused, game over, and level cleared screens

---

Platform Support Status

✅ WindowsDX (DirectX)

• Status: Fully Supported
• Features: All game features work correctly
• Performance: Optimal for Windows desktop systems
• Recommendation: Primary development platform

✅ Android

• Status: Fully Supported
• Features: Touch input with virtual joystick (tested and working seamlessly)
• Deployment: Ready for testing on Android devices
• Notes: Touch controls have been thoroughly tested and function properly

⚠️ iOS

• Status: Included in the blank template solution; device validation remains pending
• Features: Basic project scaffolding and platform support are in place
• Notes: Requires macOS for development and would benefit from additional real-device verification

✅ DesktopGL (OpenGL)

• Status: Functional
• Features: All assets load correctly, and the game is fully playable
• Notes: High DPI mode is unavailable, which may cause the game window to exceed screen height on some displays

---

Roadmap

Completed Features in 1.2.x

• ✅ Enhanced sound effects and music system
• ✅ High score saving with JSON serialization
• ✅ DesktopGL build fix (FFMPEG pipeline resolution)

Known Issues in 1.2.x

• DesktopGL high DPI mode unavailable (game window may exceed screen height)
• iOS compatibility untested on physical devices
• (Mitigated in 1.2.12 — see Version History) Previous 1.x releases allowed enemies to make a 180° turn via two fast consecutive direction switches. This is no longer possible as the opposite direction is now excluded from ValidDirections; enemies may only continue forward or turn sideways.

Version 2.0.0: Mending Garden (Upcoming - Development Paused)

Important Note: Development will be paused starting from August 1st 2026, since I focus on preparing for the Postgraduate Entrance Exam. This pause will continue until the end of 2026, when the exam is complete. Updates will resume afterward, though plans for this new game template may evolve depending on my focus at that time. Thank you for your understanding!

Mending Garden (version 2.0.0) is a farming simulation game deeply rooted in the theme of Plant Protection, set on a charming Chinese countryside farm:

• 🌱 Crop Planting: Cultivate regionally significant crops like corn, cotton, and wheat
• 🍃 Seasonal Cycle: Follow the natural rhythm of Spring planting → Summer growth → Autumn harvest
• ⏰ Timed Care: Tend to crops at specific intervals to maintain their health and promote growth
• 🐛 Pest Defense: Protect your harvest from insects using fast-paced "Duck Hunt" style gameplay
• 🏆 Harvest System: Collect mature crops and earn rewards for successful farming
• 🎨 Authentic Visuals: Hand-drawn art style inspired by Chinese rural landscapes and farming culture

---

Technical Notes

Event Scheduling System

The game uses the latest version of ModuleEventRaiser.Generator to schedule events, providing a robust event-driven architecture:

• GameStateChanged - Fired when the game state transitions
• PlayerScoreChanged - Fired when the player collects items
• SeedCollected - Fired when a seed is collected
• EnemyKilled - Fired when an enemy is defeated
• LevelCleared - Fired when all seeds in a level are collected

Content Pipeline

All assets are processed through the MonoGame Content Pipeline:

• Sprites: PNG format, loaded via the SpriteSheet class
• Audio: WAV format for sound effects
• Fonts: SpriteFont format for text rendering

---

Version History

Version 1.2.12 (Definitive Patch Release)

• Enemy 180° direction-flip mitigation: Adjusted Actor.ValidDirections() in Actor.vb so the opposite direction is excluded from the valid set; enemies may only continue forward or turn sideways. This prevents two consecutive same-frame direction changes from producing an apparent 180° reversal.
• XML documentation cleanup in SpriteSheet.vb: Completed missing <summary> entries for public fields (FrameWidth, FrameHeight, FrameCount, FrameDuration) and both constructors, corrected the duplicated summary on Animation.SpriteSheet (was mislabeled as a frame index), and documented edge-case behavior such as frameIndex clamping, empty frameIndices fallback to frame 0, and frameDuration minimum of 0.001 s.
• Enemy respawn logic simplification: Removed the duplicated position-reset math from Enemy.Die() in Actor.vb and now rely entirely on Enemy.RespawnAt(SpawnPoint) (called automatically at the end of the respawn timer, and also from GameManager.ResetPositionsAfterDeath()), centralizing position/state reset into one method.

Version 1.2.11

• Patch release: Previous recommended 1.x version, kept as a stable reference for projects upgraded before 1.2.12.
• Exit-flow cleanup: Adjusted the shutdown path in GameManager.vb so the game closes through the normal MonoGame exit flow instead of relying on the abrupt Environment.Exit(0) fallback.

Version 1.2.10

• Final 1.x cleanup: This was the last major 1.x release and includes the iOS compatibility fix, along with the earlier high-score save path work.
• iOS compatibility fix: Added the OperatingSystem.IsIOS() check in GameMain.vb for both templates.

Version 1.2.9

• High-score save path fix: Stabilized the 1.x line and improved project reuse by resolving shared high-score save path collisions, so the template can be reused safely across different projects.

Version 1.2.8.3

• Performance-focused release: Reduced per-frame overhead, improved renderer and actor-loop efficiency, and performed a small internal cleanup pass.

Version 1.2.8.2

• HUD and save reliability: Improved the HUD with real-time high score updates, highlighted new records in the display, upgraded the event generator dependency, and added logging for high-score load/save failures.

Version 1.2.8.1

• Hotfix: Addressed an exception-swallowing issue in the scheduled-event generator by upgrading the dependency to ModuleEventRaiser.Generator 1.2.5.1.

Version 1.2.7

The 1.2.7 line improved the blank template experience with letterboxing, tap/click input, cleaner rendering flow, iOS hosting support, shell-script fixes, and broader gamepad support.

Version 1.2.6 (Deprecated)

This release only corrected packaging notes in the README and is effectively the same as 1.2.7.

Version 1.2.5.x

The 1.2.5 line polished input and stability across desktop and mobile scenarios, including joystick handling, null-reference protections, and cross-platform verification.

Version 1.2.4

This release fixed the blank-template identity collision and made the template usable for new projects.

Version 1.2.3

The game received gameplay and visual polish, including audio timing fixes, animation adjustments, and a purple enemy blink effect.

Version 1.2.2

This update improved maze generation, level and score safety limits, and the documentation around the actor system.

Version 1.2.1

This release updated the blank template viewport handling and refreshed the event generator dependency.

Version 1.2.0

The project became a more complete template with fully licensed assets, a new blank template, improved audio and UI, and high-score persistence.

Version 1.1.x and earlier

These early releases established the first playable prototype, Android touch support, and the initial architecture before the DesktopGL pipeline issue surfaced.

---

Asset Credits

Graphics

• player_sheet.png - Adapted from Forest Boy: Platformer Animated Character (CC0, public domain)
• All original sprites (seeds, trees, beetles, caterpillars, UI elements) - Created in Aseprite, published to Open Game Art with CC0 & OGA-BY licenses
  • See: Assets of Seed-Scape: Forest Planting Quest

Fonts

• GameFont.spritefont - 12px Monospace variant of Fusion Pixel Font by TakWolf (SIL Open Font License 1.1)

Music & Sound Effects

All audio assets are CC0-licensed (public domain), sourced from Open Game Art:

Asset	Description	Source
BGM/main_theme.mp3	Dark Forest Waltz	10-Track Modern Chiptune Demo by IndieDevs
level_cleared.wav	New Thing Get!	congusbongus
game_start.wav	Difference (first 4 seconds)	Chasersgaming
game_over.wav	Shutdown Sound #1	512 Sound Effects (8-Bit Style) by SubspaceAudio
enemy_killed.wav	Impact Sound #13	512 Sound Effects (8-Bit Style) by SubspaceAudio
enemy_respawn.wav	Neutral Sound #11	512 Sound Effects (8-Bit Style) by SubspaceAudio
seed_packet.wav	Coin Sound (Double #1)	512 Sound Effects (8-Bit Style) by SubspaceAudio
life_gained.wav	Powerup Sound #12	512 Sound Effects (8-Bit Style) by SubspaceAudio
life_lost.wav	Human Death Scream #12 (0.5x speed)	512 Sound Effects (8-Bit Style) by SubspaceAudio
pesticide.wav	Coin Sound (Cluster #3)	512 Sound Effects (8-Bit Style) by SubspaceAudio
at_next_level.wav	Fanfare Sound #3 (0.25x speed)	512 Sound Effects (8-Bit Style) by SubspaceAudio

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.