Debugwarts

A C# / MonoGame arcade game about catching software bugs with a magical debugging field. A match starts with 60 seconds. Watch for Nuxie's cue, open the field, and keep the moving bug inside your bar long enough to catch it.

The game uses the artwork and audio already included in Debugwarts/Content. No new game assets were added during the refactor.

Build and play

Requirements:

• .NET 9 SDK for the game.
• .NET 8 runtime for the pinned MonoGame content tools.
• A desktop with OpenGL support. Linux also needs SDL2 and OpenAL available.
• Internet access for the first NuGet/tool restore, unless those packages are cached.

Run these commands from the folder containing Debugwarts.sln:

dotnet restore Debugwarts.sln
dotnet build Debugwarts.sln
dotnet run --project Debugwarts

MonoGame packages and content tools are pinned to 3.8.4.1, the version used by the original project. The build restores the local content tools automatically. Generated bin/ and obj/ folders are ignored by Git.

The original compiled font is kept in Debugwarts/Content/Prebuilt/File.xnb, so building does not require Arial to be installed. File.spritefont remains as the editable font definition. See assets and content before rebuilding that font.

Controls

Control	Action
Enter	Start from the title screen; retry from results
Space or left click	Dismiss the tutorial; respond when ! appears
Hold Space or left mouse button	Push the catching bar upward
Release	Let gravity pull the bar downward
P	Pause or resume, including during the tutorial/countdown
Tab	Return to the title screen from results
Escape	Quit

Leaving the game window pauses the match. Press P after returning to resume it.

Gameplay

• Bug patterns: Syntax Error changes direction, Memory Leak sinks and jumps, Runtime Error moves in bursts, and Floating Exception follows a drifting wave. Harder patterns appear as time runs down.
• Traits: Fast and Aggressive speed up movement; Heavy slows it down; Tiny is a smaller target; Slippery drains lost catch progress faster.
• Catching: First contact gives a 30% head start. Stay overlapped to fill the remaining progress. Brief gaps have a 0.15-second grace period; losing all progress lets the bug escape.
• Scoring: Every fifth consecutive catch raises the multiplier. A catch that never drains progress earns a further 50% bonus and displays CLEAN!. Ignoring a cue or losing a bug resets the streak.
• Power-ups: Hold the bar over a pickup for 0.7 seconds. Green adds five seconds; blue freezes bugs for two seconds; gold enables faster catching for four seconds. Effect durations tick throughout the active match and stop while paused.
• Results: See your score, catches, misses, best streak for the match, and saved personal best. An unfinished encounter at timeout is not counted as an additional miss.

Code map

Start with GameScene.cs. It connects the pieces below; it no longer owns every gameplay rule and drawing operation.

Folder	Responsibility
Debugwarts/	Entry point, window settings, content and tool manifest
GameLib/Scenes/	Title, match and results screens; scene lifetime
GameLib/Gameplay/	Match state, score rules, catching, spawning, bar physics and power-ups
GameLib/Entities/	Bug movement patterns and pickup behavior
GameLib/Presentation/	World rendering, HUD, tutorial, countdown and audiovisual feedback
GameLib/Effects/	Particles, screen shake and floating text
GameLib/Data/	Player statistics and save-file handling
GameLib/Graphics/	Reusable sprite, animation, atlas and tile helpers
GameLib/Input/, GameLib/Audio/	Shared input and audio utilities
Tests/	Automated regression checks without a game window

Read the architecture guide for update flow, ownership and examples of where to make changes.

Verification

dotnet run --project Tests
dotnet format Debugwarts.sln --verify-no-changes --no-restore
dotnet build Debugwarts.sln -c Release

Tests is an executable regression runner with a nonzero exit code on failure; use dotnet run --project Tests, not dotnet test. It needs no additional test-framework package and does not read or write the player's real save.

See testing notes for coverage and the manual play checklist.

Saved progress

High score, total catches and best streak are saved to Debugwarts/save.json under the operating system's local application-data folder. On Windows this is normally %LOCALAPPDATA%/Debugwarts/save.json; on Linux it is normally ~/.local/share/Debugwarts/save.json (or under XDG_DATA_HOME).

The game reads the old save.json beside the executable if a new-location save does not exist. Writes use a temporary file before replacing the old save. Missing or malformed saves start with empty statistics; write failures do not crash the game and are reported on the results screen. Progress also saves when leaving a match.

Contributing

Use the four-space C# formatting in .editorconfig. Keep comments short and explain the reason behind a rule or calculation. Put new rules in Gameplay, visual responses in Presentation, and movement patterns in Entities. Add regression checks when changing scoring, timing, saving or state transitions.

Use the existing content unless the project owner explicitly approves additional assets. No repository license or asset attribution manifest was present in the supplied project; this refactor does not assign a license or invent credits. The project owner can add the intended license and verified asset credits before sharing the repository.