Add implementation plan

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.