From 47a0104357d25e11691471c92fba166e9baf41c9 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Tue, 21 Apr 2026 18:21:39 +0200 Subject: [PATCH] Add implementation plan --- CODE.md | 624 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 624 insertions(+) create mode 100644 CODE.md diff --git a/CODE.md b/CODE.md new file mode 100644 index 0000000..59682a0 --- /dev/null +++ b/CODE.md @@ -0,0 +1,624 @@ +# Side-Scrolling Shooter Implementation Plan + +This document describes the implementation order for the game jam vertical slice and the supporting tools needed to test each feature quickly while building. `DESIGN.md` remains the system design source. This file is the coding plan for turning that design into a playable Godot 4 .NET game with fast iteration loops. + +The guiding rule is: every feature should be reachable in seconds from a test scene, debug shortcut, or timeline jump. A one-month jam cannot afford long manual setup before testing a weapon, cluster, boss phase, pickup, difficulty setting, or mission transition. + +## Working Principles + +- Build one thin playable path first, then widen systems. +- Keep gameplay rules in plain C# classes where possible. +- Keep Godot node scripts focused on scene wiring, input, visuals, audio, and signals. +- Make definitions data-driven before adding many content variants. +- Add debug controls with the feature, not later. +- Make every new system testable in isolation and inside the real mission loop. +- Prefer deterministic test data and seeded randomness. +- Commit after each small, working slice. + +## Target Vertical Slice + +The first complete slice should contain: + +- A bootable Godot .NET project. +- A menu with start, controls, and difficulty selection. +- A shop where the player chooses one special weapon. +- One mission with intro, gameplay, boss intro, boss fight, boss destruction, outro, and highscore/end state. +- One fixed camera path with speed changes. +- One repeating background layer and one repeating foreground layer. +- One interactive layer with enemy spawns and boss content. +- One hero with movement, shield charges, retries, points, level, primary weapon slots, secondary weapon, special weapon ammo, and squadron mates. +- One primary weapon, one secondary weapon, and one special weapon. +- Two normal enemy types: one serial behavior and one parallel movement/firing behavior. +- One enemy cluster with completion reward. +- One point collectible and one squadron mate collectible. +- One boss placeholder with phases and destruction sequence. +- Debug tools that can jump directly to the mission, cluster, weapon range, boss, and end states. + +## Folder Layout + +Use this layout unless the project already establishes a better local convention: + +- `scenes/bootstrap/` for startup and root scene. +- `scenes/menu/` for menu, controls, difficulty selection, and highscore screens. +- `scenes/shop/` for pre-mission special weapon selection. +- `scenes/mission/` for the mission runner and test mission scene. +- `scenes/level/` for parallax, camera path, and interactive layer scenes. +- `scenes/hero/` for hero and squadron mate scenes. +- `scenes/enemies/` for enemy and boss scenes. +- `scenes/weapons/` for projectile, beam, explosion, and special weapon scenes. +- `scenes/collectibles/` for pickup scenes. +- `scenes/debug/` for test harness scenes and debug UI. +- `scripts/game/` for run state, scene flow, and services. +- `scripts/content/` for definition classes and sample data. +- `scripts/level/` for camera path, parallax, timeline, and mission runner code. +- `scripts/hero/` for hero controller, inventory, level, shields, retries, and squadron mates. +- `scripts/weapons/` for weapon runtime, projectile runtime, targeting, and collision rules. +- `scripts/enemies/` for enemy actor, behavior tracks, clusters, and boss phases. +- `scripts/collectibles/` for pickup runtime and pickup application rules. +- `scripts/debug/` for debug overlay, shortcuts, spawners, and test harnesses. +- `tests/` for C# rule tests and any Godot scene smoke tests. + +## Slice 1: Project Shell + +Create the Godot .NET project shell, root scene, and buildable solution before gameplay code. + +Implement: + +- `project.godot`. +- A root scene that can load menu, shop, mission, debug scenes, and end screens. +- Basic input actions for movement, primary fire, secondary fire, special fire, pause, debug overlay, and quick restart. +- A tiny smoke scene that displays the hero placeholder and exits cleanly in headless mode. +- A build command path using `.\godot --headless --path . --build-solutions`. + +Testing and iteration support: + +- Add a `DebugBootMode` setting that can start directly in menu, mission, weapon range, cluster sandbox, boss sandbox, or end-state sandbox. +- Add one command-line or exported setting for deterministic seed. +- Add a visible build/version label in debug mode. + +Acceptance: + +- Godot opens the project. +- The C# solution builds. +- The root scene can load at least one playable scene and one debug scene. + +## Slice 2: Core Data Definitions + +Implement the definition layer before content grows. Definitions should be small plain C# types or Godot resources, whichever is faster to edit and safer to serialize. + +Implement: + +- `MissionDefinition`. +- `DifficultyDefinition`. +- `CameraPathDefinition`. +- `LevelLayerDefinition`. +- `EnemyTypeDefinition`. +- `EnemyBehaviorDefinition`. +- `EnemyClusterDefinition`. +- `CollectibleDefinition`. +- `WeaponDefinition`. +- `SpecialWeaponDefinition`. +- `SquadronMateTypeDefinition`. +- Sample definitions for the first mission. + +Testing and iteration support: + +- Add a content registry that exposes definitions by stable id. +- Add a debug content browser that lists loaded missions, enemies, weapons, collectibles, difficulties, clusters, and boss phases. +- Add validation methods that report missing ids, invalid timings, invalid multipliers, empty weapon slots, and broken mission references. + +Acceptance: + +- The test mission loads from definitions. +- Invalid sample data produces clear validation errors before gameplay starts. + +## Slice 3: Debug Foundation + +Build shared debug tools early so every later feature can plug into them. + +Implement: + +- Toggleable debug overlay. +- Pause, resume, frame-step, and time-scale controls. +- Reload current scene. +- Restart current mission. +- Switch difficulty in test contexts. +- Set deterministic seed. +- Spawn actor by definition id. +- Jump to mission timeline marker. +- Toggle collision shapes and gameplay bounds. +- Toggle invulnerability. +- Toggle infinite special ammo. +- Toggle no enemy fire. + +Testing and iteration support: + +- Debug shortcuts should work with keyboard and clickable debug UI. +- Every debug command should be callable from C# so tests and future automation can use the same hooks. +- Debug overlay should show current scene, mission time, camera progress, difficulty, hero state, enemy count, projectile count, cluster id, boss phase, and random seed. + +Acceptance: + +- A developer can enter a test scene, pause time, spawn a target, fire, reset, and repeat without returning to the editor. + +## Slice 4: Hero Runtime + +Implement the hero as the first real gameplay actor. + +Implement: + +- Camera-relative movement bounds. +- Movement input. +- Shield charges. +- Retry count. +- Damage and death rules. +- Points and level-up thresholds. +- Primary weapon slots and current slot selection. +- Secondary weapon slot. +- Special weapon slot and ammo. +- Mission-persistent inventory state. +- Death state that clears collectibles and squadron mates. + +Testing and iteration support: + +- Add a hero sandbox scene with bounds visible. +- Add debug controls for damage, heal, kill, add points, set level, add shield, remove shield, set retries, and clear inventory. +- Add a quick toggle for invulnerability. +- Add a small text panel showing all hero state changes. + +Acceptance: + +- The hero can move inside bounds. +- Damage, shields, retries, death, rebirth, points, and level-up can be exercised without enemies. + +## Slice 5: Weapon Test Range + +Implement projectile infrastructure and the first weapon set in a dedicated range before wiring the full mission. + +Implement: + +- Projectile actor. +- Projectile ownership. +- Projectile lifetime. +- Projectile collision categories. +- Primary fire loop. +- Secondary fire loop. +- Special fire loop. +- Basic ballistic projectile. +- Basic forward secondary projectile. +- One special weapon projectile. +- Dummy enemy target. +- Dummy enemy projectile. + +Testing and iteration support: + +- Create `WeaponRange` scene with hero, dummy targets, enemy projectile emitters, and clear reset zones. +- Add debug controls to switch primary weapon, secondary weapon, special weapon, hero level, squadron count, and ammo. +- Add spawn buttons for stationary target, moving target, enemy projectile stream, and dense projectile wall. +- Add damage numbers or hit counters in debug mode. +- Add projectile count and collision count to overlay. + +Acceptance: + +- The player can test each weapon behavior within seconds. +- Projectile consumption rules can be verified in the range before enemies exist. + +## Slice 6: Collectibles + +Implement pickups after hero inventory and before enemy drops. + +Implement: + +- Collectible actor. +- Pickup collision. +- Pickup application service. +- Points pickup. +- Primary weapon pickup rule. +- Secondary weapon pickup rule. +- Shield charge pickup. +- Special ammo pickup. +- Squadron mate pickup rule. +- Clear screen pickup hook. + +Testing and iteration support: + +- Add pickup injector controls in the hero sandbox and mission debug overlay. +- Add a collectible test lane where pickups drift toward the hero. +- Add one-button spawn for every collectible type. +- Show before/after inventory state when a pickup is collected. + +Acceptance: + +- Every pickup type can be spawned and collected without enemy setup. +- Inventory state updates are visible immediately. + +## Slice 7: Squadron Mates + +Implement squadron mates once hero firing and pickups exist. + +Implement: + +- Mate spawning and despawning. +- Maximum mate count. +- Type switching. +- Hug formation. +- Orbit formation. +- Line formation. +- V formation. +- Follow formation. +- Mate primary and secondary firing. +- Enemy projectile consumption by mates. + +Testing and iteration support: + +- Extend `WeaponRange` with mate controls. +- Add controls for mate count, mate type, spacing, orbit speed, and follow target. +- Add projectile wall emitters to test consumption. +- Add formation ghost markers in debug mode. + +Acceptance: + +- All formations can be switched live. +- Mate projectile consumption and firing can be tested without a mission. + +## Slice 8: Enemy Behavior System + +Implement enemies and behavior tracks after weapons can damage targets. + +Implement: + +- Enemy actor with composed sprite parts. +- Health and damage handling. +- Score value. +- Drop table hook. +- Serial behavior track runner. +- Parallel behavior track runner. +- Movement path event. +- Orientation path event. +- Wait event. +- Fire projectile event. +- Enable/disable hitbox event. +- Spawn child event. +- VFX/SFX hook. + +Testing and iteration support: + +- Create `EnemySandbox` scene. +- Add dropdown or shortcuts to spawn enemy by type id. +- Add controls to restart behavior, scrub behavior time, slow time, and freeze movement while firing continues. +- Draw behavior path, current target point, fire mounts, hitboxes, and hurtboxes. +- Show behavior track names and active event names in overlay. + +Acceptance: + +- One enemy can run a serial movement sequence. +- One enemy can move and fire in parallel. +- Both can be killed by hero weapons in the sandbox. + +## Slice 9: Enemy Clusters + +Implement cluster scheduling once individual enemies work. + +Implement: + +- Cluster runtime state. +- Spawn schedule. +- Spawn anchors relative to screen, camera, world path, or marker. +- Cluster membership tracking. +- Destroyed, escaped, and resolved states. +- Completion reward. +- Difficulty-aware spawn interval multiplier. + +Testing and iteration support: + +- Create `ClusterSandbox` scene. +- Add cluster replay button. +- Add jump to cluster by id. +- Add one-button kill all, escape all, and complete all. +- Add timeline scrub and time-scale controls. +- Show cluster state, remaining enemies, escaped enemies, next spawn time, and reward status. + +Acceptance: + +- A cluster can be played repeatedly without restarting the full mission. +- Reward behavior can be verified for destroyed and escaped enemies. + +## Slice 10: Level Runner + +Implement the real mission stage after hero, weapons, enemies, clusters, and pickups can be tested alone. + +Implement: + +- Mission timeline. +- Fixed camera path. +- Speed curve. +- Camera-relative hero bounds. +- Background parallax group. +- Foreground parallax group. +- Interactive layer. +- Layer repetition. +- Layer transition hook. +- Spawn markers. +- Mission timeline markers. +- Music cue hooks. + +Testing and iteration support: + +- Add `TestMission` with short timeline sections: intro, normal cluster, transition, second cluster, boss marker, outro marker. +- Add jump controls for every timeline marker. +- Add camera speed override and freeze camera. +- Draw camera path, current progress, spawn markers, layer bounds, and hero bounds. +- Add a marker list UI for quick jumps. + +Acceptance: + +- The test mission can be played normally or jumped to any section. +- Parallax, camera speed, enemy spawns, and hero bounds remain coherent after jumps. + +## Slice 11: Mission Flow + +Wire the playable loop after the mission stage works in isolation. + +Implement: + +- Logo placeholder. +- Skippable intro choreography. +- Menu. +- Controls screen. +- Difficulty selection. +- Shop. +- Mission intro. +- Fade to gameplay. +- Boss intro transition. +- Mission outro. +- Rebirth retry state. +- Game over state. +- Normal victory state. +- Secret victory hook. + +Testing and iteration support: + +- Add debug boot modes for every flow state. +- Add skip choreography shortcut. +- Add force result shortcuts: retry, game over, normal victory, secret victory. +- Add a flow state overlay showing current state and allowed transitions. +- Add quick start with selected difficulty and selected special weapon. + +Acceptance: + +- The full route from menu to mission to end state works. +- Every choreographed or transitional state can be skipped or booted directly for testing. + +## Slice 12: Boss Slice + +Implement boss behavior after mission flow can reach the boss marker. + +Implement: + +- Boss actor based on enemy behavior runtime. +- Boss composed parts. +- Boss phase controller. +- Phase health or shared health. +- Boss projectile pattern hook. +- Boss intro. +- Boss destruction VFX hook. +- Boss music cue hook. +- Boss reward and mission completion trigger. + +Testing and iteration support: + +- Create `BossSandbox` scene. +- Add phase jump controls. +- Add damage boss, kill part, kill phase, and kill boss buttons. +- Add boss attack pattern selector. +- Add invulnerable boss toggle for pattern testing. +- Show boss health, part health, active phase, active pattern, and next phase trigger. + +Acceptance: + +- Boss phases can be tested without replaying the mission. +- The real mission can jump directly to boss intro and continue through victory. + +## Slice 13: Difficulty + +Implement difficulty after baseline systems exist, then apply it consistently. + +Implement: + +- Difficulty selection before run start. +- Active difficulty stored in run state. +- Difficulty applied to hero starting shields and retries. +- Difficulty applied to enemy health. +- Difficulty applied to enemy projectile speed. +- Difficulty applied to enemy fire cadence. +- Difficulty applied to cluster spawn intervals. +- Difficulty applied to boss health and phase timing. +- Difficulty applied to collectible drop rates. +- Difficulty applied to special weapon ammo. +- Difficulty applied to score. +- Optional mission overrides by difficulty. + +Testing and iteration support: + +- Add difficulty switcher to all sandbox scenes. +- Show active modifiers in debug overlay. +- Add compare mode that restarts the same cluster or boss phase under another difficulty with the same seed. +- Add validation that every difficulty has visible menu copy and all required multipliers. + +Acceptance: + +- A developer can replay the same cluster, enemy, weapon range, or boss phase on each difficulty quickly. +- The menu clearly communicates the active difficulty. + +## Slice 14: Highscore And Run End + +Implement end states once scoring and difficulty are stable. + +Implement: + +- Score accumulation. +- Score multiplier from difficulty. +- Highscore entry. +- Stored score table. +- Mission reached. +- Difficulty in score record. +- Victory type. +- Retry and game over flow. + +Testing and iteration support: + +- Add debug buttons to add score, clear local highscores, force highscore entry, and force each victory type. +- Add highscore sandbox with seeded sample scores. +- Show score event log in debug overlay. + +Acceptance: + +- Scores are recorded with difficulty and mission reached. +- Retry, game over, normal victory, and secret victory can each be reached directly and through gameplay. + +## Slice 15: Content Expansion Pass + +After the vertical slice works, expand content only where the systems are already easy to test. + +Implement: + +- More primary weapon variants. +- More secondary weapon variants. +- Remaining special weapons. +- More enemy behavior events if needed. +- More clusters. +- More layer transition styles. +- More boss attacks. +- More collectible visuals. +- More mission definitions. + +Testing and iteration support: + +- Every new weapon must be added to `WeaponRange`. +- Every new enemy must be added to `EnemySandbox`. +- Every new cluster must be added to `ClusterSandbox`. +- Every new boss attack must be reachable in `BossSandbox`. +- Every new mission section must get a timeline marker. + +Acceptance: + +- New content can be tested from a sandbox before being placed in the mission. + +## Automated Tests + +Use automated tests for pure rules and brittle integration points. Do not rely on automation for every visual or feel decision during the jam. + +Implement C# tests for: + +- Definition validation. +- Difficulty modifier application. +- Hero shield, retry, death, and rebirth rules. +- Point thresholds and level-up. +- Primary weapon pickup replacement rules. +- Secondary weapon replacement rules. +- Special ammo pickup rules. +- Squadron mate type and count rules. +- Cluster destroyed, escaped, and completed states. +- Score multiplier application. +- Highscore sorting. + +Implement scene smoke tests when practical: + +- Root scene loads. +- Menu loads. +- Shop confirms selection. +- Test mission loads. +- Weapon range loads. +- Enemy sandbox loads. +- Cluster sandbox loads. +- Boss sandbox loads. + +The fast local loop should be: + +1. Run the smallest relevant C# rule tests. +2. Run the relevant sandbox scene. +3. Use debug controls to test edge cases. +4. Run full build before commit. + +## Manual Debug Recipes + +Each feature should have a short repeatable manual recipe in this file or a later `DEBUG.md`. + +Examples: + +- Weapon collision: boot `WeaponRange`, spawn projectile wall, set primary to projectile-consuming shot, hold primary fire, watch consumed count. +- Cluster reward: boot `ClusterSandbox`, select cluster id, replay, kill all enemies, verify reward; replay, let one escape, verify no reward. +- Boss phase: boot `BossSandbox`, jump to phase 2, enable invulnerable hero, run pattern for 30 seconds, then kill phase. +- Mission transition: boot `TestMission`, jump to layer transition marker, freeze camera, step frames, verify parallax swap. +- Difficulty compare: boot `ClusterSandbox`, select Normal, replay; switch Hard with same seed, replay; compare spawn timing and projectile speed. + +## Debug Controls To Keep Through The Jam + +Keep these controls available in non-release builds: + +- Toggle debug overlay. +- Reload scene. +- Restart run. +- Pause. +- Frame step. +- Time scale 0.25x, 0.5x, 1x, 2x, 4x. +- Toggle invulnerability. +- Toggle infinite special ammo. +- Toggle no enemy fire. +- Add points. +- Damage hero. +- Kill hero. +- Rebirth. +- Spawn collectible by id. +- Spawn enemy by id. +- Spawn enemy projectile stream. +- Replay cluster. +- Jump to mission marker. +- Jump to boss phase. +- Kill boss phase. +- Force mission victory. +- Force game over. + +Remove or hide them only for release exports. + +## Commit Cadence + +Each commit should leave the project buildable and should include one small useful increment. Good commit boundaries: + +- Project shell builds. +- Debug overlay boots. +- Definitions validate. +- Hero sandbox works. +- Weapon range works. +- Collectibles work. +- Squadron mates work. +- Enemy sandbox works. +- Cluster sandbox works. +- Test mission works. +- Mission flow works. +- Boss sandbox works. +- Difficulty works. +- Highscore works. + +Before each commit: + +1. Run relevant rule tests. +2. Run relevant scene manually or through a smoke test. +3. Run `.\godot --headless --path . --build-solutions`. +4. Run `jb cleanupcode --build=False` for touched C# files. +5. Update documentation for changed behavior. + +## Priority Rules During The Jam + +If time gets tight: + +- Keep the full mission loop working. +- Keep one polished weapon better than many half-working weapons. +- Keep debug jumps and sandboxes working. +- Prefer data tweaks over new systems. +- Cut optional special weapons before cutting boss, shop, difficulty, or retry flow. +- Cut secret victory implementation before cutting normal victory and highscore. +- Cut additional enemy types before cutting cluster replay tooling. +- Cut visual polish only after preserving readable collisions and feedback. + +The goal is a complete, testable side-scrolling shooter foundation that can be themed quickly when the jam topic is known.