Refactor rhythm action architecture
This commit is contained in:
wxm
1319
docs/2026-07-02-action-intent-phase-fix-plan.md
Normal file
1319
docs/2026-07-02-action-intent-phase-fix-plan.md
Normal file
File diff suppressed because it is too large
Load Diff
992
docs/superpowers/plans/2026-07-02-chart-layer.md
Normal file
992
docs/superpowers/plans/2026-07-02-chart-layer.md
Normal file
@@ -0,0 +1,992 @@
|
||||
# Chart Layer 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:** Add a thin, testable Chart Layer that turns beat-indexed battle data into upcoming and triggered chart events for UI, enemies, hazards, and future boss patterns.
|
||||
|
||||
**Architecture:** Keep `RhythmManager` as the only music clock and rhythm judgement service. Add chart resources plus a scene-owned `ChartRunner` that reads `RhythmManager.song_position()`, emits chart events once, and mirrors those events through `EventBus` for UI/world listeners. Do not make `ChartRunner` an autoload; a chart belongs to a song, room, or encounter, not to the whole app.
|
||||
|
||||
**Tech Stack:** Godot 4.6, GDScript, Resource `.tres` data model, existing `EventBus`, existing `RhythmManager`, existing headless Godot test scripts.
|
||||
|
||||
---
|
||||
|
||||
## Current Project Reading
|
||||
|
||||
The project already has a good player-side rhythm action foundation:
|
||||
|
||||
- `RhythmManager` is an autoload clock and judgement provider: `autoload/rhythm_manager.gd`.
|
||||
- `EventBus` broadcasts rhythm, judgement, skill, projectile, damage, player resource, and combo UI events: `autoload/event_bus.gd`.
|
||||
- `InputComponent` creates timestamped `InputIntent` objects: `scenes/components/input_component.gd`.
|
||||
- `ActionController` owns intent judgement, combo recording, action phase timing, pending intent replacement, and startup/active/recovery flow: `scenes/components/action_controller.gd`.
|
||||
- `ComboWindow` keeps explicit inputs and explicit `Ø` Miss placeholders; it does not auto-fill empty beats: `scenes/components/combo_window.gd`.
|
||||
- `ActionData` resources and `ActionResolver` already make player actions data-driven: `resources/action_data.gd`, `resources/actions/*.tres`, `scenes/combat/action_resolver.gd`.
|
||||
- `RhythmTrack` currently reacts to `beat_ticked` and `action_judged`, but it has no knowledge of future chart events: `scenes/ui/rhythm_track.gd`.
|
||||
- `ActorsContainer` currently manages spawned projectiles only; there is not yet a real enemy container or enemy behavior layer: `scenes/stage/actors_container.gd`.
|
||||
|
||||
The Chart Layer should therefore avoid touching the player input/action pipeline. It should add a parallel world-timeline pipeline.
|
||||
|
||||
## The Actual Problem Chart Layer Solves
|
||||
|
||||
Right now the project has a clock, but not a battle timeline.
|
||||
|
||||
Current flow:
|
||||
|
||||
```text
|
||||
RhythmManager
|
||||
-> beat_ticked(beat_index)
|
||||
-> UI / BurstComponent / future enemies listen directly
|
||||
```
|
||||
|
||||
This works while the game is only a player combo sandbox. It becomes fragile when enemies, hazards, boss patterns, camera hits, accents, and tutorial prompts need to happen on specific beats.
|
||||
|
||||
Without Chart Layer, each future system will likely write its own beat math:
|
||||
|
||||
```gdscript
|
||||
func _on_beat_ticked(beat_index: int) -> void:
|
||||
if beat_index % 4 == 2:
|
||||
show_warning()
|
||||
elif beat_index % 4 == 3:
|
||||
attack()
|
||||
```
|
||||
|
||||
That creates four problems:
|
||||
|
||||
1. **Battle timing is scattered.** Enemy scripts, UI scripts, stage scripts, and boss scripts all become tiny schedule owners.
|
||||
2. **UI cannot reliably preview future danger.** A `beat_ticked` signal tells listeners what just happened, not what will happen one beat from now.
|
||||
3. **Warning and attack can drift apart.** If UI and enemy each compute their own beat offsets, one can show a warning while another opens hitboxes on a different beat.
|
||||
4. **Encounter tuning becomes code editing.** Changing "attack at beat 16" to "warning at 15.5, attack at 16, recover at 17" should be data work, not enemy-script surgery.
|
||||
|
||||
Chart Layer centralizes that schedule.
|
||||
|
||||
New flow:
|
||||
|
||||
```text
|
||||
RhythmManager.song_position()
|
||||
-> ChartRunner.update_for_song_time(song_time)
|
||||
-> BeatChart / ChartTrack / ChartEvent
|
||||
-> chart_event_upcoming(event, time_to_event)
|
||||
-> chart_event_triggered(event)
|
||||
-> EventBus mirrors both signals
|
||||
-> RhythmTrack / EnemyBeatPlanner / Hazard / Camera listen
|
||||
```
|
||||
|
||||
Player input remains independent:
|
||||
|
||||
```text
|
||||
InputIntent
|
||||
-> RhythmManager.judge(timestamp)
|
||||
-> ActionController
|
||||
-> ComboWindow
|
||||
-> ActionResolver
|
||||
-> ActionExecutor
|
||||
```
|
||||
|
||||
Chart Layer must not force the player to press a specific key on a specific beat.
|
||||
|
||||
## Scope for This Plan
|
||||
|
||||
This plan implements the smallest useful Chart Layer:
|
||||
|
||||
- Data resources:
|
||||
- `ChartEvent`
|
||||
- `ChartTrack`
|
||||
- `BeatChart`
|
||||
- Runtime node:
|
||||
- `ChartRunner`
|
||||
- Event bus signals:
|
||||
- `chart_event_upcoming`
|
||||
- `chart_event_triggered`
|
||||
- `chart_reset`
|
||||
- Main scene integration:
|
||||
- A `ChartRunner` child under `Main`
|
||||
- UI integration:
|
||||
- `RhythmTrack` listens to upcoming/triggered chart events and can render simple future markers.
|
||||
- Tests:
|
||||
- Resource loading
|
||||
- event ordering
|
||||
- upcoming events fire once
|
||||
- triggered events fire once
|
||||
- EventBus mirrors runner events
|
||||
- existing player rhythm/action tests still pass
|
||||
|
||||
This plan intentionally does not implement a full enemy AI system. It creates event hooks that a future `EnemyBeatPlanner` can consume.
|
||||
|
||||
## Event Model
|
||||
|
||||
First version event types:
|
||||
|
||||
```text
|
||||
show_accent_marker
|
||||
enemy_prepare_attack
|
||||
enemy_attack_active
|
||||
enemy_recovery
|
||||
camera_pulse
|
||||
```
|
||||
|
||||
Event payload examples:
|
||||
|
||||
```gdscript
|
||||
{
|
||||
"lane": "enemy",
|
||||
"color": "ff3355",
|
||||
"label": "ATK"
|
||||
}
|
||||
```
|
||||
|
||||
```gdscript
|
||||
{
|
||||
"shake": 0.35,
|
||||
"duration_beats": 0.25
|
||||
}
|
||||
```
|
||||
|
||||
Recommended first test chart:
|
||||
|
||||
```text
|
||||
beat 4 show_accent_marker
|
||||
beat 6 enemy_prepare_attack target_id=test_enemy lead_beats=1
|
||||
beat 7 enemy_attack_active target_id=test_enemy lead_beats=1
|
||||
beat 8 enemy_recovery target_id=test_enemy lead_beats=0.5
|
||||
beat 12 camera_pulse
|
||||
beat 16 show_accent_marker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
Create:
|
||||
|
||||
- `resources/chart_event.gd`
|
||||
One scheduled event on a beat or subdivision.
|
||||
|
||||
- `resources/chart_track.gd`
|
||||
A named collection of related events, such as `accent`, `enemy`, `camera`, or `hazard`.
|
||||
|
||||
- `resources/beat_chart.gd`
|
||||
A chart resource that owns tracks and exposes all events in sorted order.
|
||||
|
||||
- `scenes/chart/chart_runner.gd`
|
||||
Scene-owned runner that reads the current song time and emits upcoming/triggered events.
|
||||
|
||||
- `tests/test_chart_layer.gd`
|
||||
Headless test for resources, runner timing, and EventBus mirroring.
|
||||
|
||||
Modify:
|
||||
|
||||
- `autoload/event_bus.gd`
|
||||
Add chart signals.
|
||||
|
||||
- `scenes/main/main.tscn`
|
||||
Add a `ChartRunner` node as a sibling of `Stage` and `UI`.
|
||||
|
||||
- `scenes/ui/rhythm_track.gd`
|
||||
Listen to chart events and maintain simple future markers.
|
||||
|
||||
- `scenes/ui/rhythm_track.tscn`
|
||||
Add a `ChartMarkerContainer` node under `RhythmTrack`.
|
||||
|
||||
- `tests/test_rhythm_action_architecture.gd`
|
||||
Add architecture assertions that the chart resource scripts and runner load.
|
||||
|
||||
Optional runtime data after the scripts compile:
|
||||
|
||||
- `resources/charts/test_song_chart.tres`
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Add Failing Chart Layer Architecture Test
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/test_chart_layer.gd`
|
||||
- Modify: `tests/test_rhythm_action_architecture.gd`
|
||||
|
||||
- [ ] **Step 1: Create the focused chart test**
|
||||
|
||||
Create `tests/test_chart_layer.gd`:
|
||||
|
||||
```gdscript
|
||||
extends SceneTree
|
||||
|
||||
var failures: Array[String] = []
|
||||
|
||||
|
||||
func _init() -> void:
|
||||
_run.call_deferred()
|
||||
|
||||
|
||||
func _run() -> void:
|
||||
await process_frame
|
||||
_check_resources_load()
|
||||
await _check_runner_upcoming_and_triggered_once()
|
||||
await _check_event_bus_mirroring()
|
||||
_finish()
|
||||
|
||||
|
||||
func _check_resources_load() -> void:
|
||||
_expect(load("res://resources/chart_event.gd") != null, "ChartEvent script should load")
|
||||
_expect(load("res://resources/chart_track.gd") != null, "ChartTrack script should load")
|
||||
_expect(load("res://resources/beat_chart.gd") != null, "BeatChart script should load")
|
||||
_expect(load("res://scenes/chart/chart_runner.gd") != null, "ChartRunner script should load")
|
||||
|
||||
|
||||
func _make_event(beat: int, event_type: StringName, target_id := &"", lead_beats := 1.0):
|
||||
var event_script: Script = load("res://resources/chart_event.gd")
|
||||
var event: Resource = event_script.new()
|
||||
event.set("beat_index", beat)
|
||||
event.set("event_type", event_type)
|
||||
event.set("target_id", target_id)
|
||||
event.set("lead_beats", lead_beats)
|
||||
return event
|
||||
|
||||
|
||||
func _make_chart() -> Resource:
|
||||
var chart_script: Script = load("res://resources/beat_chart.gd")
|
||||
var track_script: Script = load("res://resources/chart_track.gd")
|
||||
var chart: Resource = chart_script.new()
|
||||
var track: Resource = track_script.new()
|
||||
chart.set("chart_id", &"test_chart")
|
||||
track.set("track_id", &"enemy")
|
||||
track.set("track_type", &"enemy")
|
||||
track.set("events", [
|
||||
_make_event(2, &"enemy_prepare_attack", &"test_enemy", 1.0),
|
||||
_make_event(3, &"enemy_attack_active", &"test_enemy", 1.0),
|
||||
])
|
||||
chart.set("tracks", [track])
|
||||
return chart
|
||||
|
||||
|
||||
func _make_runner(chart: Resource) -> Node:
|
||||
var runner_script: Script = load("res://scenes/chart/chart_runner.gd")
|
||||
var runner: Node = runner_script.new()
|
||||
runner.set("beat_time_override", 0.5)
|
||||
runner.call("set_chart", chart)
|
||||
root.add_child(runner)
|
||||
return runner
|
||||
|
||||
|
||||
func _check_runner_upcoming_and_triggered_once() -> void:
|
||||
var runner := _make_runner(_make_chart())
|
||||
var upcoming: Array[StringName] = []
|
||||
var triggered: Array[StringName] = []
|
||||
runner.connect("chart_event_upcoming", func(event: Resource, _time_to_event: float) -> void:
|
||||
upcoming.append(StringName(str(event.get("event_type"))))
|
||||
)
|
||||
runner.connect("chart_event_triggered", func(event: Resource) -> void:
|
||||
triggered.append(StringName(str(event.get("event_type"))))
|
||||
)
|
||||
|
||||
runner.call("update_for_song_time", 0.49)
|
||||
_expect(upcoming == [&"enemy_prepare_attack"], "Prepare upcoming should fire at lead window")
|
||||
_expect(triggered.is_empty(), "No event should trigger before event time")
|
||||
|
||||
runner.call("update_for_song_time", 1.0)
|
||||
runner.call("update_for_song_time", 1.1)
|
||||
_expect(triggered == [&"enemy_prepare_attack"], "Prepare triggered should fire once")
|
||||
|
||||
runner.call("update_for_song_time", 1.49)
|
||||
runner.call("update_for_song_time", 1.50)
|
||||
runner.call("update_for_song_time", 1.80)
|
||||
_expect(upcoming.count(&"enemy_attack_active") == 1, "Attack upcoming should fire once")
|
||||
_expect(triggered.count(&"enemy_attack_active") == 1, "Attack triggered should fire once")
|
||||
runner.queue_free()
|
||||
await process_frame
|
||||
|
||||
|
||||
func _check_event_bus_mirroring() -> void:
|
||||
var bus_script: Script = load("res://autoload/event_bus.gd")
|
||||
var bus: Node = bus_script.new()
|
||||
bus.name = "EventBus"
|
||||
root.add_child(bus)
|
||||
|
||||
var mirrored_upcoming := 0
|
||||
var mirrored_triggered := 0
|
||||
bus.connect("chart_event_upcoming", func(_event: Resource, _time_to_event: float) -> void:
|
||||
mirrored_upcoming += 1
|
||||
)
|
||||
bus.connect("chart_event_triggered", func(_event: Resource) -> void:
|
||||
mirrored_triggered += 1
|
||||
)
|
||||
|
||||
var runner := _make_runner(_make_chart())
|
||||
runner.call("update_for_song_time", 0.49)
|
||||
runner.call("update_for_song_time", 1.0)
|
||||
_expect(mirrored_upcoming == 1, "ChartRunner should mirror upcoming events to EventBus")
|
||||
_expect(mirrored_triggered == 1, "ChartRunner should mirror triggered events to EventBus")
|
||||
|
||||
runner.queue_free()
|
||||
bus.queue_free()
|
||||
await process_frame
|
||||
|
||||
|
||||
func _expect(condition: bool, label: String) -> void:
|
||||
if not condition:
|
||||
failures.append(label)
|
||||
|
||||
|
||||
func _finish() -> void:
|
||||
if failures.is_empty():
|
||||
print("PASS chart layer")
|
||||
quit(0)
|
||||
else:
|
||||
for failure: String in failures:
|
||||
push_error(failure)
|
||||
quit(1)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run the focused test and verify it fails for missing files**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_chart_layer.gd
|
||||
```
|
||||
|
||||
Expected: FAIL because `resources/chart_event.gd`, `resources/chart_track.gd`, `resources/beat_chart.gd`, and `scenes/chart/chart_runner.gd` do not exist yet.
|
||||
|
||||
- [ ] **Step 3: Extend architecture test**
|
||||
|
||||
In `tests/test_rhythm_action_architecture.gd`, add a new function `_check_chart_layer()` and call it from `_run()` after `_check_autoloads()`:
|
||||
|
||||
```gdscript
|
||||
func _check_chart_layer() -> void:
|
||||
for path: String in [
|
||||
"res://resources/chart_event.gd",
|
||||
"res://resources/chart_track.gd",
|
||||
"res://resources/beat_chart.gd",
|
||||
"res://scenes/chart/chart_runner.gd",
|
||||
]:
|
||||
_expect(load(path) != null, "%s should load" % path)
|
||||
var bus_script: Script = load("res://autoload/event_bus.gd")
|
||||
_expect(bus_script != null, "EventBus should load for chart signal checks")
|
||||
if bus_script != null:
|
||||
var bus: Node = bus_script.new()
|
||||
_expect(bus.has_signal("chart_event_upcoming"), "EventBus should expose chart_event_upcoming")
|
||||
_expect(bus.has_signal("chart_event_triggered"), "EventBus should expose chart_event_triggered")
|
||||
_expect(bus.has_signal("chart_reset"), "EventBus should expose chart_reset")
|
||||
bus.free()
|
||||
```
|
||||
|
||||
Expected: architecture test fails until the scripts and EventBus signals are added.
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Add Chart Resource Types
|
||||
|
||||
**Files:**
|
||||
- Create: `resources/chart_event.gd`
|
||||
- Create: `resources/chart_track.gd`
|
||||
- Create: `resources/beat_chart.gd`
|
||||
- Test: `tests/test_chart_layer.gd`
|
||||
|
||||
- [ ] **Step 1: Create `ChartEvent`**
|
||||
|
||||
Create `resources/chart_event.gd`:
|
||||
|
||||
```gdscript
|
||||
class_name ChartEvent
|
||||
extends Resource
|
||||
|
||||
@export var event_id: StringName = &""
|
||||
@export var beat_index := 0
|
||||
@export var subdivision := 0
|
||||
@export var subdivisions_per_beat := 1
|
||||
@export var event_type: StringName = &""
|
||||
@export var target_id: StringName = &""
|
||||
@export var payload: Dictionary = {}
|
||||
@export var lead_beats := 1.0
|
||||
|
||||
|
||||
func beat_position() -> float:
|
||||
var safe_subdivisions := maxi(1, subdivisions_per_beat)
|
||||
return float(beat_index) + float(subdivision) / float(safe_subdivisions)
|
||||
|
||||
|
||||
func time_seconds(beat_time: float) -> float:
|
||||
return beat_position() * maxf(0.001, beat_time)
|
||||
|
||||
|
||||
func key() -> StringName:
|
||||
if not event_id.is_empty():
|
||||
return event_id
|
||||
return StringName("%s:%s:%d:%d" % [event_type, target_id, beat_index, subdivision])
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create `ChartTrack`**
|
||||
|
||||
Create `resources/chart_track.gd`:
|
||||
|
||||
```gdscript
|
||||
class_name ChartTrack
|
||||
extends Resource
|
||||
|
||||
@export var track_id: StringName = &""
|
||||
@export var track_type: StringName = &""
|
||||
@export var events: Array[ChartEvent] = []
|
||||
|
||||
|
||||
func sorted_events() -> Array[ChartEvent]:
|
||||
var result: Array[ChartEvent] = []
|
||||
for event: ChartEvent in events:
|
||||
if event != null:
|
||||
result.append(event)
|
||||
result.sort_custom(func(a: ChartEvent, b: ChartEvent) -> bool:
|
||||
return a.beat_position() < b.beat_position()
|
||||
)
|
||||
return result
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Create `BeatChart`**
|
||||
|
||||
Create `resources/beat_chart.gd`:
|
||||
|
||||
```gdscript
|
||||
class_name BeatChart
|
||||
extends Resource
|
||||
|
||||
@export var chart_id: StringName = &""
|
||||
@export var total_beats := 0
|
||||
@export var tracks: Array[ChartTrack] = []
|
||||
|
||||
|
||||
func all_events() -> Array[ChartEvent]:
|
||||
var result: Array[ChartEvent] = []
|
||||
for track: ChartTrack in tracks:
|
||||
if track == null:
|
||||
continue
|
||||
for event: ChartEvent in track.sorted_events():
|
||||
result.append(event)
|
||||
result.sort_custom(func(a: ChartEvent, b: ChartEvent) -> bool:
|
||||
if is_equal_approx(a.beat_position(), b.beat_position()):
|
||||
return str(a.event_type) < str(b.event_type)
|
||||
return a.beat_position() < b.beat_position()
|
||||
)
|
||||
return result
|
||||
|
||||
|
||||
func is_empty() -> bool:
|
||||
return all_events().is_empty()
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run the focused test and verify it still fails at `ChartRunner`**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_chart_layer.gd
|
||||
```
|
||||
|
||||
Expected: FAIL because `scenes/chart/chart_runner.gd` and EventBus chart signals are not implemented yet.
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Add Chart Signals to EventBus
|
||||
|
||||
**Files:**
|
||||
- Modify: `autoload/event_bus.gd`
|
||||
- Test: `tests/test_chart_layer.gd`
|
||||
- Test: `tests/test_rhythm_action_architecture.gd`
|
||||
|
||||
- [ ] **Step 1: Add chart signals**
|
||||
|
||||
In `autoload/event_bus.gd`, add these signals after the existing rhythm/judgement signals:
|
||||
|
||||
```gdscript
|
||||
signal chart_event_upcoming(event: Resource, time_to_event: float)
|
||||
signal chart_event_triggered(event: Resource)
|
||||
signal chart_reset(chart_id: StringName)
|
||||
```
|
||||
|
||||
The top of the file should become:
|
||||
|
||||
```gdscript
|
||||
extends Node
|
||||
|
||||
signal rhythm_action_requested(action_name: StringName)
|
||||
signal beat_ticked(beat_index: int)
|
||||
signal judgement_made(quality: StringName, offset_ms: float)
|
||||
signal action_judged(action_name: StringName, rating: Dictionary)
|
||||
signal chart_event_upcoming(event: Resource, time_to_event: float)
|
||||
signal chart_event_triggered(event: Resource)
|
||||
signal chart_reset(chart_id: StringName)
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run architecture test**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_action_architecture.gd
|
||||
```
|
||||
|
||||
Expected: still FAIL until `ChartRunner` exists, but EventBus chart signal assertions should pass.
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Implement ChartRunner
|
||||
|
||||
**Files:**
|
||||
- Create: `scenes/chart/chart_runner.gd`
|
||||
- Test: `tests/test_chart_layer.gd`
|
||||
|
||||
- [ ] **Step 1: Create the chart directory and runner script**
|
||||
|
||||
Create `scenes/chart/chart_runner.gd`:
|
||||
|
||||
```gdscript
|
||||
class_name ChartRunner
|
||||
extends Node
|
||||
|
||||
signal chart_event_upcoming(event: ChartEvent, time_to_event: float)
|
||||
signal chart_event_triggered(event: ChartEvent)
|
||||
signal chart_reset(chart_id: StringName)
|
||||
signal chart_finished(chart_id: StringName)
|
||||
|
||||
@export var chart: BeatChart
|
||||
@export var rhythm_manager_path: NodePath
|
||||
@export var beat_time_override := 0.0
|
||||
@export var auto_run := true
|
||||
|
||||
var running := true
|
||||
var _upcoming_keys: Dictionary = {}
|
||||
var _triggered_keys: Dictionary = {}
|
||||
|
||||
|
||||
func _ready() -> void:
|
||||
running = auto_run
|
||||
|
||||
|
||||
func _physics_process(_delta: float) -> void:
|
||||
if not running or chart == null:
|
||||
return
|
||||
var rhythm := _rhythm_manager()
|
||||
if rhythm == null or not rhythm.has_method("song_position"):
|
||||
return
|
||||
update_for_song_time(float(rhythm.call("song_position")))
|
||||
|
||||
|
||||
func set_chart(next_chart: BeatChart) -> void:
|
||||
chart = next_chart
|
||||
reset()
|
||||
|
||||
|
||||
func reset() -> void:
|
||||
_upcoming_keys.clear()
|
||||
_triggered_keys.clear()
|
||||
var chart_id := &""
|
||||
if chart != null:
|
||||
chart_id = chart.chart_id
|
||||
chart_reset.emit(chart_id)
|
||||
var bus := _event_bus_or_null()
|
||||
if bus != null:
|
||||
bus.emit_signal("chart_reset", chart_id)
|
||||
|
||||
|
||||
func update_for_song_time(song_time: float) -> void:
|
||||
if chart == null:
|
||||
return
|
||||
var beat_time := _beat_time()
|
||||
for event: ChartEvent in chart.all_events():
|
||||
var event_time := event.time_seconds(beat_time)
|
||||
var time_to_event := event_time - song_time
|
||||
var lead_time := maxf(0.0, event.lead_beats) * beat_time
|
||||
var event_key := event.key()
|
||||
if not _upcoming_keys.has(event_key) and time_to_event > 0.0 and time_to_event <= lead_time:
|
||||
_upcoming_keys[event_key] = true
|
||||
_emit_upcoming(event, time_to_event)
|
||||
if not _triggered_keys.has(event_key) and song_time >= event_time:
|
||||
_triggered_keys[event_key] = true
|
||||
_emit_triggered(event)
|
||||
|
||||
|
||||
func pause() -> void:
|
||||
running = false
|
||||
|
||||
|
||||
func resume() -> void:
|
||||
running = true
|
||||
|
||||
|
||||
func _emit_upcoming(event: ChartEvent, time_to_event: float) -> void:
|
||||
chart_event_upcoming.emit(event, time_to_event)
|
||||
var bus := _event_bus_or_null()
|
||||
if bus != null:
|
||||
bus.emit_signal("chart_event_upcoming", event, time_to_event)
|
||||
|
||||
|
||||
func _emit_triggered(event: ChartEvent) -> void:
|
||||
chart_event_triggered.emit(event)
|
||||
var bus := _event_bus_or_null()
|
||||
if bus != null:
|
||||
bus.emit_signal("chart_event_triggered", event)
|
||||
|
||||
|
||||
func _beat_time() -> float:
|
||||
if beat_time_override > 0.0:
|
||||
return beat_time_override
|
||||
var rhythm := _rhythm_manager()
|
||||
if rhythm != null:
|
||||
return float(rhythm.get("beat_time"))
|
||||
return 0.5
|
||||
|
||||
|
||||
func _rhythm_manager() -> Node:
|
||||
if not is_inside_tree():
|
||||
return null
|
||||
if not rhythm_manager_path.is_empty():
|
||||
return get_node_or_null(rhythm_manager_path)
|
||||
return get_tree().root.get_node_or_null("RhythmManager")
|
||||
|
||||
|
||||
func _event_bus_or_null() -> Node:
|
||||
if not is_inside_tree():
|
||||
return null
|
||||
return get_tree().root.get_node_or_null("EventBus")
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run focused chart test**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_chart_layer.gd
|
||||
```
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
- [ ] **Step 3: Run architecture test**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_action_architecture.gd
|
||||
```
|
||||
|
||||
Expected: PASS after `_check_chart_layer()` assertions are satisfied.
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Add Runtime ChartRunner Node
|
||||
|
||||
**Files:**
|
||||
- Modify: `scenes/main/main.tscn`
|
||||
- Optional create after scripts compile: `resources/charts/test_song_chart.tres`
|
||||
- Test: `tests/test_rhythm_scene.gd`
|
||||
|
||||
- [ ] **Step 1: Add `ChartRunner` to `Main` scene**
|
||||
|
||||
Modify `scenes/main/main.tscn`.
|
||||
|
||||
Add an external resource:
|
||||
|
||||
```ini
|
||||
[ext_resource type="Script" path="res://scenes/chart/chart_runner.gd" id="6_chart_runner"]
|
||||
```
|
||||
|
||||
Add this node between `Stage` and `UI`:
|
||||
|
||||
```ini
|
||||
[node name="ChartRunner" type="Node" parent="."]
|
||||
script = ExtResource("6_chart_runner")
|
||||
```
|
||||
|
||||
The intended main scene tree becomes:
|
||||
|
||||
```text
|
||||
Main
|
||||
├─ Stage
|
||||
├─ ChartRunner
|
||||
└─ UI
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update scene architecture test**
|
||||
|
||||
In `tests/test_rhythm_scene.gd`, add an assertion that main scene has `ChartRunner`:
|
||||
|
||||
```gdscript
|
||||
var main_scene: PackedScene = load("res://scenes/main/main.tscn")
|
||||
var main := main_scene.instantiate()
|
||||
root.add_child(main)
|
||||
await process_frame
|
||||
if main.get_node_or_null("ChartRunner") == null:
|
||||
failures.append("Main should include ChartRunner for scene-owned chart playback")
|
||||
main.free()
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run scene test**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_scene.gd
|
||||
```
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
- [ ] **Step 4: Add a sample chart resource through the Godot editor**
|
||||
|
||||
After `ChartEvent`, `ChartTrack`, and `BeatChart` scripts compile, create `resources/charts/test_song_chart.tres` in the editor with:
|
||||
|
||||
```text
|
||||
BeatChart.chart_id = test_song_chart
|
||||
BeatChart.total_beats = 32
|
||||
|
||||
Track accent:
|
||||
beat 4 show_accent_marker
|
||||
beat 8 show_accent_marker
|
||||
beat 12 show_accent_marker
|
||||
beat 16 show_accent_marker
|
||||
|
||||
Track enemy:
|
||||
beat 6 enemy_prepare_attack target_id=test_enemy lead_beats=1.0
|
||||
beat 7 enemy_attack_active target_id=test_enemy lead_beats=1.0
|
||||
beat 8 enemy_recovery target_id=test_enemy lead_beats=0.5
|
||||
|
||||
Track camera:
|
||||
beat 12 camera_pulse target_id=main_camera lead_beats=0.5
|
||||
```
|
||||
|
||||
Assign this resource to `Main/ChartRunner.chart`.
|
||||
|
||||
The plan keeps runtime playable without this sample chart because tests construct chart resources in memory. The sample chart is for visual/manual verification.
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Let RhythmTrack Consume Chart Events
|
||||
|
||||
**Files:**
|
||||
- Modify: `scenes/ui/rhythm_track.tscn`
|
||||
- Modify: `scenes/ui/rhythm_track.gd`
|
||||
- Test: `tests/test_rhythm_ui.gd`
|
||||
- Test: `tests/test_ui_animation_regression.gd`
|
||||
|
||||
- [ ] **Step 1: Add marker container to scene**
|
||||
|
||||
In `scenes/ui/rhythm_track.tscn`, add:
|
||||
|
||||
```ini
|
||||
[node name="ChartMarkerContainer" type="Control" parent="."]
|
||||
layout_mode = 0
|
||||
offset_left = 0.0
|
||||
offset_top = 0.0
|
||||
offset_right = 1040.0
|
||||
offset_bottom = 128.0
|
||||
mouse_filter = 2
|
||||
```
|
||||
|
||||
Keep it behind `JudgementLabel` in the file order so text remains readable.
|
||||
|
||||
- [ ] **Step 2: Extend `RhythmTrack` script**
|
||||
|
||||
In `scenes/ui/rhythm_track.gd`, add:
|
||||
|
||||
```gdscript
|
||||
@onready var chart_marker_container: Control = $ChartMarkerContainer
|
||||
|
||||
var chart_markers: Array[Control] = []
|
||||
```
|
||||
|
||||
Connect chart signals in `_ready()`:
|
||||
|
||||
```gdscript
|
||||
bus.connect("chart_event_upcoming", _on_chart_event_upcoming)
|
||||
bus.connect("chart_event_triggered", _on_chart_event_triggered)
|
||||
```
|
||||
|
||||
Add these methods:
|
||||
|
||||
```gdscript
|
||||
func _on_chart_event_upcoming(event: Resource, time_to_event: float) -> void:
|
||||
var marker := Label.new()
|
||||
marker.text = _chart_marker_text(event)
|
||||
marker.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER
|
||||
marker.vertical_alignment = VERTICAL_ALIGNMENT_CENTER
|
||||
marker.add_theme_font_size_override("font_size", 14)
|
||||
marker.add_theme_color_override("font_color", _chart_marker_color(event))
|
||||
marker.custom_minimum_size = Vector2(54, 24)
|
||||
marker.position = _chart_marker_position(time_to_event)
|
||||
chart_marker_container.add_child(marker)
|
||||
chart_markers.append(marker)
|
||||
var tween := create_tween()
|
||||
tween.tween_property(marker, "modulate:a", 0.25, maxf(0.1, time_to_event))
|
||||
tween.tween_callback(marker.queue_free)
|
||||
|
||||
|
||||
func _on_chart_event_triggered(event: Resource) -> void:
|
||||
if StringName(str(event.get("event_type"))) == &"camera_pulse":
|
||||
center_flash.modulate = Color(1.0, 0.84, 0.26, 1.0)
|
||||
else:
|
||||
center_flash.modulate = _chart_marker_color(event)
|
||||
beat_flash = 1.0
|
||||
|
||||
|
||||
func _chart_marker_text(event: Resource) -> String:
|
||||
match StringName(str(event.get("event_type"))):
|
||||
&"show_accent_marker":
|
||||
return "ACC"
|
||||
&"enemy_prepare_attack":
|
||||
return "WARN"
|
||||
&"enemy_attack_active":
|
||||
return "ATK"
|
||||
&"enemy_recovery":
|
||||
return "REC"
|
||||
&"camera_pulse":
|
||||
return "CAM"
|
||||
return str(event.get("event_type")).to_upper()
|
||||
|
||||
|
||||
func _chart_marker_color(event: Resource) -> Color:
|
||||
match StringName(str(event.get("event_type"))):
|
||||
&"show_accent_marker":
|
||||
return Color("ffd84a")
|
||||
&"enemy_prepare_attack":
|
||||
return Color("ff7a33")
|
||||
&"enemy_attack_active":
|
||||
return Color("ff3355")
|
||||
&"enemy_recovery":
|
||||
return Color("8aa0ff")
|
||||
&"camera_pulse":
|
||||
return Color("ffffff")
|
||||
return Color("00f2ff")
|
||||
|
||||
|
||||
func _chart_marker_position(time_to_event: float) -> Vector2:
|
||||
var seconds_per_beat := 60.0 / maxf(1.0, bpm)
|
||||
var beat_distance := clampf(time_to_event / seconds_per_beat, 0.0, 4.0)
|
||||
var x := track_center.x + beat_distance * 92.0
|
||||
return Vector2(x - 27.0, track_center.y + 34.0)
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Add UI tests**
|
||||
|
||||
In `tests/test_rhythm_ui.gd`, assert the marker container exists:
|
||||
|
||||
```gdscript
|
||||
var track := ui.get_node_or_null("RhythmTrack")
|
||||
if track == null or track.get_node_or_null("ChartMarkerContainer") == null:
|
||||
failures.append("RhythmTrack should include ChartMarkerContainer")
|
||||
```
|
||||
|
||||
In `tests/test_ui_animation_regression.gd`, emit an upcoming event and assert a marker appears:
|
||||
|
||||
```gdscript
|
||||
var event_script: Script = load("res://resources/chart_event.gd")
|
||||
var event: Resource = event_script.new()
|
||||
event.set("event_type", &"enemy_attack_active")
|
||||
bus.emit_signal("chart_event_upcoming", event, 0.5)
|
||||
await process_frame
|
||||
var marker_container := ui.get_node("RhythmTrack/ChartMarkerContainer")
|
||||
_expect_bool(marker_container.get_child_count() > 0, true, "Chart upcoming event should create a rhythm marker")
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run UI tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_ui.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_ui_animation_regression.gd
|
||||
```
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Full Regression Run
|
||||
|
||||
**Files:**
|
||||
- No new files.
|
||||
|
||||
- [ ] **Step 1: Run chart and architecture tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_chart_layer.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_action_architecture.gd
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
```text
|
||||
PASS chart layer
|
||||
PASS rhythm action architecture
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run player input/action tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_input_component_intents.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_combo_window.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_action_controller_flow.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_player_combo_input.gd
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
```text
|
||||
PASS input component intents
|
||||
PASS combo window
|
||||
PASS action controller flow
|
||||
PASS player combo input
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run UI tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_ui.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_ui_layout.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_ui_animation_regression.gd
|
||||
```
|
||||
|
||||
Expected:
|
||||
|
||||
```text
|
||||
PASS rhythm ui
|
||||
PASS rhythm ui layout
|
||||
PASS ui animation regression
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Follow-Up After This Plan
|
||||
|
||||
After the thin Chart Layer lands, the next feature should be a chart-driven dummy enemy:
|
||||
|
||||
```text
|
||||
chart_event_upcoming(enemy_prepare_attack)
|
||||
-> EnemyWarningPresenter shows overhead warning
|
||||
|
||||
chart_event_triggered(enemy_attack_active)
|
||||
-> EnemyActionController opens enemy hitbox
|
||||
|
||||
chart_event_triggered(enemy_recovery)
|
||||
-> EnemyActionController closes enemy hitbox
|
||||
```
|
||||
|
||||
That should be a separate plan because it needs enemy scene structure, hitbox/hurtbox decisions, target IDs, and warning UI. Keeping it separate prevents the Chart Layer from becoming a hidden enemy-system rewrite.
|
||||
|
||||
## Important Non-Goals
|
||||
|
||||
- Do not move player input judgement into Chart Layer.
|
||||
- Do not make charts dictate required player keys.
|
||||
- Do not make `ChartRunner` an autoload.
|
||||
- Do not change `ComboWindow` empty-beat behavior.
|
||||
- Do not add full boss AI in this pass.
|
||||
- Do not use chart events to directly damage the player.
|
||||
|
||||
## Known Adjacent Risk
|
||||
|
||||
`RhythmManager.judge(input_timestamp_ms)` currently accepts an input timestamp in milliseconds and passes it to `get_rating_for_time(input_timestamp_ms / 1000.0)`. Chart Layer should not depend on this method; it should use `RhythmManager.song_position()` directly. A separate input-timing plan should verify whether `InputIntent.timestamp_ms` is being converted to song-relative time correctly.
|
||||
|
||||
## Self-Review
|
||||
|
||||
- Spec coverage: The plan covers chart data, runner behavior, EventBus mirroring, main scene integration, UI marker consumption, and regression tests.
|
||||
- Placeholder scan: The plan has no placeholder sections. Every task names exact files and expected commands.
|
||||
- Type consistency: Event resources are `ChartEvent`, tracks are `ChartTrack`, charts are `BeatChart`, and runner signals use `ChartEvent` locally plus `Resource` on `EventBus`.
|
||||
- Scope check: Enemy AI is intentionally excluded and captured as the next separate feature.
|
||||
- Current-project fit: The plan preserves the existing `RhythmManager`, `ActionController`, `ComboWindow`, `ActionResolver`, and player UI patterns.
|
||||
116
docs/superpowers/plans/2026-07-02-godot-architecture-refactor.md
Normal file
116
docs/superpowers/plans/2026-07-02-godot-architecture-refactor.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,202 @@
|
||||
# Rhythm Action 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 the project toward the architecture in `docs/架构方案.md`: global beat clock, four-slot combo window, ActionData resources, ActionResolver priority rules, Player execution components, and CombatManager formulas.
|
||||
|
||||
**Architecture:** Keep `EventBus` for decoupled broadcast, but add `RhythmManager` and `CombatManager` as first-class autoload services. Move domain logic out of `Player` into beat-aware components and data-driven resource files while preserving current gameplay tests.
|
||||
|
||||
**Tech Stack:** Godot 4.6 GDScript, `.tres` Resources, headless SceneTree tests.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Architecture Target Regression
|
||||
|
||||
**Files:**
|
||||
- Create: `tests/test_rhythm_action_architecture.gd`
|
||||
|
||||
- [x] **Step 1: Write the failing test**
|
||||
|
||||
Create one test that asserts the six requested architecture artifacts exist and expose their intended behavior:
|
||||
|
||||
```gdscript
|
||||
extends SceneTree
|
||||
|
||||
var failures: Array[String] = []
|
||||
|
||||
func _init() -> void:
|
||||
_run.call_deferred()
|
||||
|
||||
func _run() -> void:
|
||||
_check_autoloads()
|
||||
_check_action_data()
|
||||
_check_combo_window()
|
||||
_check_action_resolver()
|
||||
_check_player_components()
|
||||
_check_combat_manager()
|
||||
_finish()
|
||||
```
|
||||
|
||||
- [x] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_action_architecture.gd
|
||||
```
|
||||
|
||||
Expected: FAIL because `RhythmManager`, `CombatManager`, `ActionData`, `ActionResolver`, `ComboWindow`, `MotionExecutor`, and `BurstComponent` do not exist yet.
|
||||
|
||||
### Task 2: RhythmManager Autoload
|
||||
|
||||
**Files:**
|
||||
- Create: `autoload/rhythm_manager.gd`
|
||||
- Modify: `project.godot`
|
||||
- Modify: `scenes/rhythm/rhythm_conductor.gd`
|
||||
- Modify: `tests/test_rhythm_conductor.gd`
|
||||
|
||||
- [x] **Step 1: Implement `RhythmManager`**
|
||||
|
||||
Create an Autoload node with `beat_ticked`, `judgement_made`, and `action_judged` signals. It owns BPM, beat length, beat index, judgement scale, beat offset, fallback clock timing, and `judge_action(action_name)`.
|
||||
|
||||
- [x] **Step 2: Register autoload**
|
||||
|
||||
Add:
|
||||
|
||||
```ini
|
||||
[autoload]
|
||||
RhythmManager="*res://autoload/rhythm_manager.gd"
|
||||
```
|
||||
|
||||
- [x] **Step 3: Preserve `RhythmConductor` compatibility**
|
||||
|
||||
Keep `scenes/rhythm/rhythm_conductor.gd` loadable for old tests by delegating equivalent judging math to the same model or leaving it as a scene adapter.
|
||||
|
||||
- [x] **Step 4: Run rhythm tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_conductor.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_rhythm_action_architecture.gd
|
||||
```
|
||||
|
||||
Expected: rhythm conductor still passes; architecture test advances past autoload checks.
|
||||
|
||||
### Task 3: Four-Slot ComboWindow
|
||||
|
||||
**Files:**
|
||||
- Create: `scenes/components/combo_window.gd`
|
||||
- Modify: `scenes/characters/player.tscn`
|
||||
- Modify: `scenes/characters/player.gd`
|
||||
- Modify: `tests/test_combo_window.gd`
|
||||
|
||||
- [x] **Step 1: Implement `ComboWindow`**
|
||||
|
||||
`ComboWindow` extends `Node`, stores four slots, records `StringName` inputs, keeps `&"Ø"` only as an explicit Miss placeholder, clears on miss/full/action clear, and emits `combo_updated`/`combo_cleared`. It must not auto-append `&"Ø"` just because a beat passed without input.
|
||||
|
||||
- [x] **Step 2: Replace Player node**
|
||||
|
||||
Rename or replace `ComboTracker` with `ComboWindow` in `player.tscn`. Keep compatibility methods `get_slots()`, `get_pattern()`, `get_contiguous_pattern()`, `queue_clear()`, `flush_pending_clear()` so existing tests can continue running while behavior becomes component-based.
|
||||
|
||||
- [x] **Step 3: Run combo tests**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_combo_window.gd
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s res://tests/test_player_combo_input.gd
|
||||
```
|
||||
|
||||
Expected: existing combo behavior remains green, and the new architecture test confirms ComboWindow does not auto-append `&"Ø"` just because a beat passed without input.
|
||||
|
||||
### Task 4: ActionData and ActionResolver
|
||||
|
||||
**Files:**
|
||||
- Create: `resources/action_data.gd`
|
||||
- Create: `resources/actions/*.tres`
|
||||
- Create: `scenes/combat/action_resolver.gd`
|
||||
- Modify: `resources/skill_data.gd`
|
||||
- Modify: `scenes/combat/input_resolver.gd`
|
||||
- Modify: `scenes/characters/player.gd`
|
||||
- Modify: `tests/test_combo_window.gd`
|
||||
- Modify: `tests/test_architecture_refactor.gd`
|
||||
|
||||
- [x] **Step 1: Add full `ActionData`**
|
||||
|
||||
Create `ActionData extends Resource` with fields from `docs/架构方案.md`: `id`, `display_name`, `input_pattern`, `required_state`, `base_cost`, `damage_mult`, `move_mult_x`, `move_mult_y`, `action_beats`, `hit_type`, `range`, `target_type`, `armor_level`, `clear_window`, `can_chain`, `special`, plus compatibility fields `animation`, `energy_cost`, `energy_reward`, `spawns_projectile`, `projectile_scene`, and `displacement`.
|
||||
|
||||
- [x] **Step 2: Convert resources**
|
||||
|
||||
Create `resources/actions` equivalents for the current `resources/skills` files. After all tests and scripts use `ActionData`, remove the legacy `resources/skills` data.
|
||||
|
||||
- [x] **Step 3: Implement `ActionResolver`**
|
||||
|
||||
Load `resources/actions/*.tres`, expose `resolve(window, state_machine := null, context := {})`, `resolve_pattern(pattern, state_machine := null, context := {})`, `reload()`, and `clear_cache()`. Include an ordered rule pass for Space contexts before falling back to pattern matching.
|
||||
|
||||
- [x] **Step 4: Remove `InputResolver` after migration**
|
||||
|
||||
Move tests and runtime code to `ActionResolver` directly, then remove the legacy `InputResolver` adapter.
|
||||
|
||||
### Task 5: MotionExecutor and BurstComponent
|
||||
|
||||
**Files:**
|
||||
- Create: `scenes/components/motion_executor.gd`
|
||||
- Create: `scenes/components/burst_component.gd`
|
||||
- Modify: `scenes/characters/player.tscn`
|
||||
- Modify: `scenes/characters/player.gd`
|
||||
|
||||
- [x] **Step 1: Add `MotionExecutor`**
|
||||
|
||||
Expose `execute(action, direction, beat_time)` and `tick(delta)` to own action duration, lunge timing, and velocity output. Player calls it instead of hand-writing lunge windows.
|
||||
|
||||
- [x] **Step 2: Add `BurstComponent`**
|
||||
|
||||
Expose ready/active/cooldown state, beat-based duration, cost multiplier, damage multiplier, and judgement scale. It listens to `RhythmManager.beat_ticked` for duration and cooldown.
|
||||
|
||||
- [x] **Step 3: Move Player logic**
|
||||
|
||||
Replace direct charge/burst timing in `Player` with `BurstComponent`, and replace direct action displacement with `MotionExecutor`.
|
||||
|
||||
### Task 6: CombatManager
|
||||
|
||||
**Files:**
|
||||
- Create: `autoload/combat_manager.gd`
|
||||
- Modify: `project.godot`
|
||||
- Modify: `scenes/components/damage_emitter.gd`
|
||||
- Modify: `scenes/characters/player.gd`
|
||||
|
||||
- [x] **Step 1: Implement formulas**
|
||||
|
||||
`CombatManager` exposes `resolve_damage(base_attack, action, judgement, buffs := null, burst := null)`, `resolve_cost(action, burst := null)`, and `resolve_move(action, judgement, burst := null)`.
|
||||
|
||||
- [x] **Step 2: Wire damage and cost**
|
||||
|
||||
Player uses `CombatManager.resolve_cost` before action execution. `DamageEmitter` can accept an action context and asks `CombatManager.resolve_damage` rather than using scattered multipliers.
|
||||
|
||||
### Task 7: Verification and Gap Audit
|
||||
|
||||
**Files:**
|
||||
- Modify: tests as needed to cover exact behavior.
|
||||
|
||||
- [x] **Step 1: Run full suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
for test in tests/*.gd; do
|
||||
/Applications/Godot.app/Contents/MacOS/Godot --headless --path /Users/wxm/code/project/Fighting_Rthythm_game -s "res://$test" || exit 1
|
||||
done
|
||||
```
|
||||
|
||||
Expected: all tests exit `0`.
|
||||
|
||||
- [x] **Step 2: Search for architecture residue**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
rg -n "Timer|charge_duration|attack_lunge|InputResolver|SkillData|ComboTracker|PlayerProjectile\\.new\\(|get_first_node_in_group|has_method|\\.call\\(" autoload resources scenes tests
|
||||
```
|
||||
|
||||
Expected: any remaining hits are compatibility adapters, tests, or UI-only visual timing, not core gameplay architecture.
|
||||
182
docs/架构方案.md
Normal file
182
docs/架构方案.md
Normal file
@@ -0,0 +1,182 @@
|
||||
读完这份策划书,先说结论:前两轮的架构骨架(Autoload 总线 + 组件化 + Resource 数据驱动)完全适用,但策划书里有三个事实会**反过来修正**我之前的一些具体建议,先把它们摆清楚,因为整个架构都要围绕它们展开。
|
||||
|
||||
**第一,拍(Beat)是全游戏唯一的时间单位。** 动作持续用 ActionBeats,Buff 持续 8 拍,爆气 16 拍、冷却 4 拍,蓄力按拍分级,敌人每 N 拍行动,连段窗口是 4 拍。这意味着 RhythmManager 不只是"判定服务",它是**全局主时钟**,所有系统的计时都应该订阅它的 `beat_ticked`,而不是各自开 Timer 数秒——这样换 BPM 时整个游戏自动变速,这正是节奏游戏该有的性质。
|
||||
|
||||
**第二,我要收回上一轮"输入缓冲"的建议。** InputBuffer 是格斗游戏的手感工具,但在你这个设计里它是有害的:判定的本质是测量按键时刻与拍点的偏差,缓冲会把"提前按"偷偷延后消费,等于篡改了玩家的真实节奏。而且策划书的 Miss 机制天然解决了连打问题——乱按的人会大量 Miss,Miss 清空窗口、动作失败,惩罚是玩法自带的,不需要程序层再去限速。保留的只有 echo 过滤、去重和时间戳这些"让输入干净"的部分。
|
||||
|
||||
**第三,策划书 9.1 节其实已经替你把数据模型设计好了。** 那个统一技能字段表(inputPattern、requiredState、baseCost、各倍率、hitType、clearWindow、canChain……)就是 `ActionData extends Resource` 的字段清单,而且基础动作和技能同构——A 一段斩就是一个 cost=0、pattern=[A] 的 ActionData。全游戏 30 多个动作全部变成 `.tres` 文件,代码里没有任何一张硬编码技能表。
|
||||
|
||||
## 一、全局层:RhythmManager 作为节拍中枢RhythmManager(Autoload)的接口对应策划书 2.1 的全局单位表:
|
||||
|
||||
```gdscript
|
||||
# autoload/rhythm_manager.gd
|
||||
signal beat_ticked(beat_index: int)
|
||||
|
||||
var bpm: float
|
||||
var beat_time: float # 60.0 / bpm
|
||||
var beat_index: int
|
||||
var judgement_scale := 1.0 # 爆气时 > 1,放宽判定窗口
|
||||
|
||||
func song_position() -> float:
|
||||
return music.get_playback_position() \
|
||||
+ AudioServer.get_time_since_last_mix() \
|
||||
- AudioServer.get_output_latency()
|
||||
|
||||
func judge(input_timestamp_ms: float) -> Judgement:
|
||||
# 换算到歌曲时间,求与最近拍点的 BeatOffset
|
||||
# 与 RhythmConfig 中的阈值比较 → perfect / good / bad / miss
|
||||
# 阈值乘以 judgement_scale 实现爆气放宽
|
||||
```
|
||||
|
||||
判定阈值放进 `rhythm_config.tres` 资源(Perfect/Good/Bad 各自的偏差上限)——**策划书目前没有给这组数字**,这是要找策划补的第一个洞。爆气的"判定窗口适度放宽"通过 `judgement_scale` 一个字段实现,BurstComponent 进入爆气时改它,退出时还原。
|
||||
|
||||
CombatManager(Autoload)则是四条乘区公式的唯一归属地。策划书 2.3 的公式结构完全一致(基础值 × 动作乘区 × 节奏乘区 × Buff 乘区 × 爆气乘区),所以做一个统一的结算管线:
|
||||
|
||||
```gdscript
|
||||
# autoload/combat_manager.gd
|
||||
func resolve_damage(atk: float, action: ActionData, j: Judgement,
|
||||
buffs: BuffContainer, burst: BurstComponent) -> float:
|
||||
return atk * action.damage_mult * j.damage_mult \
|
||||
* buffs.damage_mult(action) * burst.damage_mult()
|
||||
|
||||
# resolve_move_x / resolve_move_y / resolve_cost 同构,只换字段
|
||||
```
|
||||
|
||||
各系统只负责"贡献自己的乘数"(比如强袭乐句 Buff 只对同方向技能生效,所以 `buffs.damage_mult(action)` 要传入动作),永远不要在 Player 或技能代码里手写 `damage * 1.25 * 1.2` 这种散落的乘法——否则第 4 条公式改一次你要全项目搜一遍。
|
||||
|
||||
## 二、数据层:ActionData 照抄策划书 9.1
|
||||
|
||||
```gdscript
|
||||
# resources/action_data.gd
|
||||
class_name ActionData extends Resource
|
||||
|
||||
@export var id: StringName
|
||||
@export var display_name: String
|
||||
@export var input_pattern: Array[StringName] # [&"A", &"A", &"space"]
|
||||
@export_enum("ground", "air", "guarding", "any") var required_state: String
|
||||
@export var base_cost := 0 # 基础动作恒为 0
|
||||
@export var damage_mult := 1.0
|
||||
@export var move_mult_x := 0.0
|
||||
@export var move_mult_y := 0.0
|
||||
@export var action_beats := 1.0 # W 为 2.0
|
||||
@export_enum("melee", "projectile", "circle", "counter") var hit_type: String
|
||||
@export var range := 0.0
|
||||
@export_enum("single", "area") var target_type: String
|
||||
@export var armor_level := 0
|
||||
@export var clear_window := true # 音刃前两段为 false
|
||||
@export var can_chain := false # 音刃族为 true
|
||||
@export var special: StringName # 破霸体、浮空等特效钩子
|
||||
```
|
||||
|
||||
A/D 三段、W、招架、下劈、W 派生、四个方向技能、三段音刃、反击音刃、三级蓄力——全部是这个类的 `.tres` 实例,放在 `res://resources/actions/` 下。第一版验收标准 17.4 里"A Space、AA Space、AAA Space 功能不同"这种需求,变成纯粹的资源文件差异。
|
||||
|
||||
## 三、玩家实体:组件划分随策划书调整
|
||||
|
||||
玩家场景树在上一轮基础上,按这份策划书的系统重新切分:
|
||||
|
||||
```
|
||||
Player (CharacterBody2D)
|
||||
├── Sprite / 骨骼动画
|
||||
├── StateMachine # 8 个状态,照抄 3.2 节
|
||||
│ └── ground / air / guarding / charging /
|
||||
│ bladeChain / burstCharge / bursting / hitstun
|
||||
├── InputComponent # 按下+松开事件、时间戳、长按检测
|
||||
├── ComboWindow # 四槽连段窗口,只记录显式输入/Miss,不自动补空拍
|
||||
├── ActionResolver # Space 优先级链 + 动作表匹配(纯逻辑)
|
||||
├── MotionExecutor # 把位移乘区结果变成 ActionBeats 内的实际位移
|
||||
├── EnergyComponent # 回能规则 + 空挥计数器
|
||||
├── BuffContainer # 四个 Buff 的触发、拍计时、乘区供给
|
||||
├── BurstComponent # 爆气条件、四态、效果开关
|
||||
├── DamageEmitter (Area2D)
|
||||
└── DamageReceiver (Area2D)
|
||||
```
|
||||
|
||||
几个组件值得单独说透。
|
||||
|
||||
**ComboWindow:它是连段窗口的领域对象,不是输入缓冲,也不负责空拍补位。** 这里按当前设计修正:ComboWindow 不订阅 `beat_ticked` 来自动补 Ø,某一拍没有输入就什么都不记录。它只记录两类内容:通过节奏判定的显式输入(A/D/W/S/Space),以及 Miss 时由裁决层显式写入的 Ø 占位。Miss 只是正常槽位输入,不因自身触发清空;满 4 槽清空;受击清空(监听 DamageReceiver);`clear_window == true` 的动作释放后清空;bladeChain 期间按专门规则决定是否保留窗口。识别连段时对外暴露过滤掉 Ø 的有效序列,但正常玩法里 Ø 只作为 Miss 反馈,不会因为空拍自动出现:
|
||||
|
||||
```gdscript
|
||||
# components/combo_window.gd
|
||||
class_name ComboWindow extends Node
|
||||
signal cleared(reason: StringName)
|
||||
var slots: Array[StringName] = []
|
||||
|
||||
func record(action: StringName) -> void: # 判定非 Miss 后调用
|
||||
slots.append(action)
|
||||
if slots.size() >= 4:
|
||||
clear(&"window_full")
|
||||
|
||||
func record_miss() -> void: # 仅 Miss 裁决显式调用
|
||||
slots.append(&"Ø")
|
||||
clear(&"miss")
|
||||
|
||||
func pattern() -> Array[StringName]: # 供 ActionResolver 匹配
|
||||
return slots.filter(func(s): return s != &"Ø")
|
||||
```
|
||||
|
||||
这样窗口的语义会更干净:连段只由玩家真实输入构成;Miss 是显式失败反馈并清空窗口;空拍不会污染连段,也不会制造需要额外解释的隐藏槽位。
|
||||
|
||||
**ActionResolver:Space 的六步优先级链是全项目最容易腐坏的逻辑,必须独立成模块。** 而且注意策划书 10.3 说反击音刃"优先级高于普通 S Space 音刃",但第 6 节的解析顺序里没写它——合并后的完整链条是七步:实现上把这七步写成一个有序规则数组,每条规则是"条件函数 + 产出动作",Resolver 逐条尝试、命中即返回。这样以后加 Q/E、装备技能替换(策划书 18 节的暂缓内容)只是往数组里插规则,不用动主干。
|
||||
|
||||
**InputComponent:长按检测暴露了一个策划书没定义的关键时序问题。** S Space 短按是音刃、长按是爆气——但按下的瞬间程序不可能知道玩家会不会长按,而策划书 4.1 又要求"按键时立刻判定"。这两条规则在 Space 上是冲突的,必须由程序定义结算时机。我建议的方案是**按下即判定、延迟结算**:
|
||||
|
||||
```gdscript
|
||||
# InputComponent 对 Space 的处理
|
||||
# 按下: 立即调用 RhythmManager.judge() 并暂存结果(pending)
|
||||
# 若在 hold_threshold(建议 0.3~0.5 拍,需策划确认)内松开:
|
||||
# → 按短按结算,使用按下那一刻的判定结果(节奏不失真)
|
||||
# 若超过阈值仍按住:
|
||||
# → 丢弃 pending,升级为 charging / burstCharge 状态
|
||||
# → 松开时重新判定(策划书 11.1 / 12.4 本来就要求松开判定)
|
||||
```
|
||||
|
||||
代价是短按的动作会比按键晚约三分之一拍才出招——对音刃这种远程投射物,可以让动画前段先演出、投射物在结算点生成来掩盖。这个点务必和策划当面对齐,它直接影响手感验收标准 17.1 的"按下后立即出动作"在 Space 上如何解释。
|
||||
|
||||
**StateMachine 直接照抄 3.2 节的八个状态**,每个 ActionData 的 `required_state` 字段由状态机门控(W 派生只在 air 状态可解析,招架结算只在 guarding)。charging、bladeChain、burstCharge 这三个状态的本质是"改变 Space 解析结果的模式",所以 ActionResolver 每次解析都要先问状态机当前状态——优先级链的①②③本质上就是状态查询。
|
||||
|
||||
**MotionExecutor 是这个游戏区别于普通横版的组件。** 玩家不能自由走路,意味着 Player 里**不存在**常规的"读方向键改 velocity"代码;所有位移都是动作的产物:接到一个动作的 `FinalMoveX/Y`(CombatManager 算好的乘区结果),在 `action_beats × beat_time` 的时长内用 tween 或速度曲线执行完,期间仍走 `move_and_slide` 保证碰撞。W 的 T0–T1 上升、T1 高点、T1–T2 下落也由它按拍切分,并在 T1 通知状态机开放空中派生窗口。
|
||||
|
||||
**资源三件套(Energy / Buff / Burst)全部是 EventBus 的订阅者。** EnergyComponent 的空挥限制需要一条此前没有的反馈链:DamageEmitter 命中时经 CombatManager 广播 `hit_confirmed`,EnergyComponent 据此区分"命中回能 100% / 有效位移未命中 50% / 连续三次空挥后归零"。BuffContainer 监听判定流水(合拍、完美律动看连击流)、连段事件(强袭乐句看 AAA 终结)、招架结果(守拍反击),持续时间订阅 `beat_ticked` 递减,并暴露一个 `ticking_paused` 开关给爆气用。BurstComponent 自己是个小状态机(off/ready/active/cooldown),每次能量或连击变化时检查 12.3 的三选一条件点亮 ready,激活时做四件事:改 CombatManager 乘区、把技能 cost 乘区归零、调 `RhythmManager.judgement_scale`、暂停 BuffContainer 计时,16 拍后统一还原并清资源。
|
||||
|
||||
## 四、世界层与敌人
|
||||
|
||||
Stage 负责装载关卡、把曲目和 BPM 交给 RhythmManager 开始播放。ActorsContainer 统一生成三种测试敌人和**音刃投射物**(音刃是远程投射物,正好落在上一轮"实体不自己 new 实体"的规则里)。敌人 = Character 基类 + DamageReceiver(带 ArmorLevel)+ 一个极简的 EnemyBrain:
|
||||
|
||||
```gdscript
|
||||
# EnemyBrain: 敌人和玩家订阅同一个时钟,这是设计对称性所在
|
||||
@export var data: EnemyData # beats_per_action、行为类型
|
||||
func _on_beat(i: int) -> void:
|
||||
if i % data.beats_per_action == 0:
|
||||
_act() # 接近 / 攻击 / 远程射击
|
||||
```
|
||||
|
||||
节奏型(1 拍、2 拍,以及未来的半拍、切分)就是 EnemyData 上的一个数字或节拍掩码,15.1 节的扩展方向零成本预留。破霸体走 DamageContext:W 派生的 ActionData 带 `armor_level` 和 `special = &"armor_break"`,Receiver 拿自己的 ArmorLevel 比较后决定是硬直、浮空还是只吃伤害。
|
||||
|
||||
UI 层强烈建议第一版就做**四槽窗口可视化**(四个格子实时显示 A/D/W/S/Space/Ø),它同时是玩家理解连段系统的核心界面和你调试 ComboWindow 的工具。这里的 Ø 只代表显式 Miss 反馈,不是空拍占位;UI 监听 ComboWindow 的信号即可。
|
||||
|
||||
## 五、目录结构与实施映射
|
||||
|
||||
```
|
||||
res://
|
||||
├── autoload/ # rhythm_manager.gd / event_bus.gd / combat_manager.gd
|
||||
├── resources/
|
||||
│ ├── actions/ # 30+ 个 ActionData .tres(基础动作与技能同构)
|
||||
│ ├── buffs/ # 4 个 BuffData
|
||||
│ ├── enemies/ # EnemyData(节奏型、数值)
|
||||
│ └── rhythm_config.tres
|
||||
├── components/ # input / combo_window / resolver / motion / energy / buff / burst / damage_*
|
||||
├── scenes/
|
||||
│ ├── characters/ # player.tscn、enemy 基类、三种测试敌人
|
||||
│ ├── stage/ # stage.tscn、actors_container.tscn
|
||||
│ ├── combat/ # 音刃投射物等
|
||||
│ └── ui/ # hud.tscn、combo_slots.tscn、energy_bar.tscn
|
||||
└── tests/ # 对 ComboWindow / Resolver / CombatManager 的纯逻辑单元测试
|
||||
```
|
||||
|
||||
对应策划书 16 节的五个阶段:阶段 1 = RhythmManager + RhythmConfig + InputComponent + ComboWindow(这四个是地基,而且全部可脱离画面单元测试);阶段 2 = StateMachine + MotionExecutor + 基础动作的 ActionData;阶段 3 = ActionResolver 优先级链 + 全部技能资源 + DamageEmitter/投射物 + ActorsContainer;阶段 4 = Energy/Buff/Burst 三组件 + 乘区管线补全;阶段 5 = EnemyBrain + 三种敌人。每个阶段结束,对应的验收标准(17 节)恰好都有明确的架构归属可以逐条勾选。
|
||||
|
||||
## 六、需要回去和策划确认的三个洞
|
||||
|
||||
架构做到这里,策划书有三处未定义的行为必须补上,否则程序只能自行拍板:一是**判定阈值的具体数字**(Perfect/Good/Bad 各多少毫秒或多少比例拍长),RhythmConfig 等着填;二是上面说的**长按阈值与短按结算时机**;三是**同一拍内的第二次输入**如何处理——ComboWindow 不再按拍自动补槽,但如果玩家在同一拍内按了两次,两次输入是否都独立判定、是否都进入窗口、第二次是否直接按 Miss 处理,仍需要定义。蓄力/爆气长按期间不补 Ø;这段时间窗口应冻结或在释放后按动作规则清空。
|
||||
|
||||
整体看,这份策划书和这套架构咬合得相当好——因为它本质上已经是一份"以拍为时基、以数据表驱动"的设计,你要做的就是让代码结构诚实地反映这个事实:一个时钟(RhythmManager)、一张表(ActionData 资源集)、一条链(Resolver 优先级)、一条管线(乘区结算),其余全是订阅者。如果你想,下一步我可以把阶段 1 的四个地基模块(含单元测试)完整写出来。
|
||||
Reference in New Issue
Block a user