Fighting_Rthythm_game/docs/superpowers/plans/2026-07-02-godot-architecture-refactor.md

Godot Architecture Refactor Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Refactor Fighting_Rthythm_game to match the provided architecture: EventBus communication, thin Main, componentized Player, SkillData resources, UI subscenes, Stage/ActorsContainer ownership, and named 2D layers.

Architecture: Keep the game runnable at each increment. Cross-system communication goes through autoload/event_bus.gd; parent-to-child orchestration uses typed references; child-to-parent requests use signals. Player becomes a coordinator over child components, while skill definitions move to .tres resources loaded by InputResolver.

Tech Stack: Godot 4.6 GDScript, .tscn scenes, .tres resources, headless SceneTree tests.

---

Task 1: Architecture Guard Tests

Files:

• Create: tests/test_architecture_refactor.gd

• Modify: project.godot

• Step 1: Write failing tests

Add tests that assert EventBus is autoloaded, Main no longer hand-wires UI with has_method/has_signal, Player has child components, Player does not use raw KEY_*, skills load as SkillData, Stage owns ActorsContainer, UI exists as a separate scene, and project 2D layers are named.

• Step 2: Run test to verify it fails

Run: /Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_architecture_refactor.gd

Expected: FAIL because the current project lacks EventBus, component nodes, resource skills, UI subscenes, and Stage boundaries.

Task 2: EventBus And Rhythm Decoupling

Files:

• Create: autoload/event_bus.gd

• Modify: project.godot

• Modify: scenes/rhythm/rhythm_conductor.gd

• Modify: scenes/characters/player.gd

• Add EventBus signals for rhythm requests, beats, judgements, skills, health, energy, charge, combo, damage, and projectile requests.

• Register EventBus as a game autoload.

• Make RhythmConductor listen for rhythm action requests and emit EventBus judgement/beat signals.

• Remove Player's get_first_node_in_group("rhythm_conductor") fallback and treat missing judgement as a miss.

Task 3: Player Components

Files:

• Create: scenes/components/input_component.gd

• Create: scenes/components/combo_tracker.gd

• Create: scenes/components/energy_component.gd

• Create: scenes/components/health_component.gd

• Create: scenes/components/damage_emitter.gd

• Create: scenes/components/damage_receiver.gd

• Create: scenes/components/state_machine.gd

• Modify: scenes/characters/player.gd

• Modify: scenes/characters/player.tscn

• Modify: project.godot

• Move raw input handling into InputComponent using only InputMap actions.

• Move combo slot storage and clear timing into ComboTracker.

• Move energy/health state into components that emit EventBus updates.

• Add DamageEmitter and DamageReceiver Area2D components with collision-layer-based targeting.

• Keep Player as a typed coordinator over components.

Task 4: SkillData Resources

Files:

• Create: resources/skill_data.gd

• Create: resources/skills/*.tres

• Modify: scenes/combat/input_resolver.gd

• Modify: scenes/characters/player.gd

• Define SkillData extends Resource.

• Convert each hard-coded skill pattern into a .tres resource.

• Make InputResolver load resources and return SkillData.

• Move animation, energy cost/reward, projectile flags, clear-window behavior, and displacement into resources.

Task 5: UI Subscenes And Thin Main

Files:

• Create: scenes/ui/main_ui.tscn

• Create: scenes/ui/main_ui.gd

• Create: scenes/ui/rhythm_track.tscn

• Create: scenes/ui/rhythm_track.gd

• Create: scenes/ui/combo_window_hud.tscn

• Create: scenes/ui/combo_window_hud.gd

• Create: scenes/ui/energy_bar.tscn

• Create: scenes/ui/energy_bar.gd

• Modify: scenes/main/main.gd

• Modify: scenes/main/main.tscn

• Move rhythm track animation into RhythmTrack.

• Move combo slot rendering into ComboWindowHud.

• Move energy/health/charge display into UI nodes that subscribe to EventBus.

• Reduce Main to typed child references and scene setup only.

Task 6: Stage And ActorsContainer

Files:

• Create: scenes/stage/stage.tscn

• Create: scenes/stage/stage.gd

• Create: scenes/stage/actors_container.gd

• Create: scenes/combat/player_projectile.tscn

• Modify: scenes/combat/player_projectile.gd

• Modify: scenes/characters/player.gd

• Modify: scenes/main/main.tscn

• Put ground and Player under Stage/ActorsContainer.

• Make Player emit projectile requests instead of adding children to the scene tree.

• Make ActorsContainer instantiate projectiles, own them, and group them.

Task 7: Verification

Files:

• Modify: tests as needed to target public component interfaces instead of Player internals.

• Run every tests/*.gd with Godot headless.

• Confirm architecture guard tests cover every explicit objective item.

• Inspect key source files to ensure raw key matching, group conductor lookup, Player projectile spawning, and Main has_method/has_signal probing are gone.