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.