PacDessert1436.MonoGame.StartKitVB 1.3.0

MonoGame 2D StartKit VB.NET

⚠️ Special Reminders

If you are using version 1.3.0 or later, all of the fixes below are already included — no manual patching is required.

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). 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 and GameMain.vb: See Important Notes on Code Patching for concise guidance on safe shutdown and input handling in GameManager.vb. The GameMain.vb in the demo game also requires special handling, especially regarding the LoadContent method call.

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. 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 save/load 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.3.0 is the current recommended release. It moves game system initialization to the LoadContent phase, updates the MonoGame dependency to 3.8.5.1, and polishes the BEGINNER_GUIDE documentation. Version 1.2.12 is deprecated — its mitigation attempt made the enemy direction-flip more likely; upgrade straight to 1.3.0. See below for details.

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. Note: v1.2.3 was 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, and the next update will be on 2.0.0. The current recommended version is 1.3.0, which moves game system initialization to the LoadContent phase, updates the MonoGame dependency to 3.8.5.1, and polishes the BEGINNER_GUIDE documentation. Version 1.2.12 is deprecated since its ValidDirections-only attempt made the flip worse; upgrade directly to 1.3.0.

• Version 1.2.13 hardens Enemy.ChangeDirection() in Actor.vb: after picking a candidate, it compares the pick against the opposite of both Direction and _previousDirection, falling back to _previousDirection when a cross-frame reversal would occur. This greatly reduces the same-frame two-step direction flip that 1.2.12's ValidDirections change actually made more common — though rare edge cases still allow the direction flip.
• 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, along with high-score save path resolution from 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 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 Code Patching

Version 1.2.11 and later already include a safer exit flow for GameManager.vb. 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

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.

As for content loading in GameMain.vb, doing the game system initialization in Initialize may appear to work because _graphics.ApplyChanges is called first, but it doesn't necessarily work on all devices. Therefore, it is recommended to do the initialization in LoadContent:

Protected Overrides Sub LoadContent()
    _gameManager = New GameManager(Me)
    _renderer = New Renderer(GraphicsDevice, Content)
    _soundManager = New SoundManager(Content)

    MyBase.LoadContent()
End Sub

---

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 relies on 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.1 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: Device Validation 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

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

Known Issues

• DesktopGL high DPI mode unavailable (game window may exceed screen height)
• iOS compatibility untested on physical devices
• Enemy 180° direction flip via two fast direction switches
  • Frequency is greatly reduced in 1.2.13 by the dual-opposite guard in ChangeDirection(), but rare edge cases still allow it.
  • Do not use 1.2.12 — its ValidDirections-only change made the flip more likely.

Version 2.0.0: Mending Garden (Upcoming - Development Paused)

Important Note: Development will be paused starting from September 2026, as the author is focusing 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 the author's 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. Key events include:

• 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.3.0 (Ultimate 1.x Release)

This version is the definitive, recommended 1.x release with a critical edge-case fix, the MonoGame dependency update, and BEGINNER_GUIDE documentation polishing. The next update of this NuGet package will be on 2.0.0.

• Move game system initialization to LoadContent in the demo game: The game system initialization is now done in LoadContent, which is called after the entire Initialize phase. The 1.2.x series could work thanks to the _graphics.ApplyChanges call, but that doesn't necessarily work on all devices.
• MonoGame dependency update: Both the blank template and the demo game now have MonoGame packages pinned to version 3.8.5.1, which is the latest stable version as of this release. MonoGame.Framework.Native is now introduced in both templates.
• BEGINNER_GUIDE documentation polishing: Improved the clarity and completeness of the beginner guide, adding more details on project structure, rendering concepts, and common pitfalls.

<ItemGroup>
  
  <PackageReference Include="MonoGame.Framework.Native" Version="3.8.5.1">
    <PrivateAssets>All</PrivateAssets>
  </PackageReference>
</ItemGroup>

Version 1.2.13

• Reduces enemy 180° direction-flip frequency: Enemy.ChangeDirection() now checks a candidate pick against the opposite of both Direction and _previousDirection, keeping _previousDirection if a cross-frame reversal would occur. This greatly cuts down on same-frame double flips — though rare edge cases remain.
• XML documentation cleanup in SpriteSheet.vb: Completed <summary> entries for public fields (FrameWidth, FrameHeight, FrameCount, FrameDuration) and both constructors, corrected the mislabeled Animation.SpriteSheet summary, and documented edge cases: frameIndex clamping, empty frameIndices fallback to frame 0, and frameDuration minimum of 0.001 s.
• Enemy respawn logic simplification: Removed duplicated position-reset math from Enemy.Die() and rely entirely on Enemy.RespawnAt(SpawnPoint) (called at respawn-timer end and from GameManager.ResetPositionsAfterDeath()), centralizing position and state reset in one method.

⚠️ Version 1.2.12 (Deprecated — DO NOT USE)

• Attempted to fix the 180° flip by removing the opposite direction from Actor.ValidDirections().
• Deprecated reason: The ValidDirections-only change backfired — it did not prevent the two-step flip and made it more likely to occur.
• The doc cleanup and respawn simplification planned for this release were preserved and shipped in 1.2.13.

Version 1.2.11

• Patch release: 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

• iOS compatibility fix: Added the OperatingSystem.IsIOS() check in GameMain.vb for both templates.
• High-score save path: Included the high-score save path resolution from v1.2.9.

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 display, 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: Fixed 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 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, added level and score safety limits, and improved 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. Versions prior to 1.2.0 have been unlisted due to potential copyright concerns with included assets.

Version 1.1.x and earlier

These early releases established the first playable prototype, Android touch support, and the initial architecture.

---

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.