PacDessert1436.MonoGame.StartKitVB 1.2.9

MonoGame 2D StartKit VB.NET

⚠️ Special Reminders

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 stage after dozens of edge-case fixes, and version 1.2.8.3 is the performance-focused release of the line. Version 1.2.9 is the truly definitive polish release, focusing on a small improvement that resolves high-score save path collisions, so the template is easier to reuse across different projects.

Version 2.0.0, which will introduce the new demo game known as Mending Garden, is planned but currently paused while the author prepares for the Postgraduate Entrance Exam. See Roadmap → Version 2.0.0 for more 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 100% complete with the last edge-case resolved. The current recommended version is 1.2.9, which is the final 1.x release and the only version that resolves the shared high-score save path conflict.

• Version 1.2.8.3 is the prior 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 until the exam period is over.

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

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 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.

---

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, 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

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.9

This is the real final polish release of the 1.x series. It keeps the release line stable while making the template easier to reuse, especially by storing high-score data in a project-specific folder instead of a shared template-wide location.

Version 1.2.8.3

This is the performance-focused release of the 1.x line. It reduces per-frame overhead, improves rendering and actor-loop efficiency, and includes a small internal cleanup pass.

Version 1.2.8.2

This patch 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

This hotfix addressed the exception-swallowing flaw in the scheduled-event generator by upgrading the dependency to 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.