zfxaction26_1/CODE.md

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