Fighting_Rthythm_game/docs/superpowers/plans/2026-07-02-chart-layer.md

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:

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:

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:

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:

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:

show_accent_marker
enemy_prepare_attack
enemy_attack_active
enemy_recovery
camera_pulse

Event payload examples:

{
	"lane": "enemy",
	"color": "ff3355",
	"label": "ATK"
}

{
	"shake": 0.35,
	"duration_beats": 0.25
}

Recommended first test chart:

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:

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:

/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():

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:

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:

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:

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:

/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:

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:

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:

/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:

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:

/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:

/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:

[ext_resource type="Script" path="res://scenes/chart/chart_runner.gd" id="6_chart_runner"]

Add this node between Stage and UI:

[node name="ChartRunner" type="Node" parent="."]
script = ExtResource("6_chart_runner")

The intended main scene tree becomes:

Main
  ├─ Stage
  ├─ ChartRunner
  └─ UI

• Step 2: Update scene architecture test

In tests/test_rhythm_scene.gd, add an assertion that main scene has ChartRunner:

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:

/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:

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:

[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:

@onready var chart_marker_container: Control = $ChartMarkerContainer

var chart_markers: Array[Control] = []

Connect chart signals in _ready():

bus.connect("chart_event_upcoming", _on_chart_event_upcoming)
bus.connect("chart_event_triggered", _on_chart_event_triggered)

Add these methods:

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:

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:

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:

/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:

/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:

PASS chart layer
PASS rhythm action architecture

• Step 2: Run player input/action tests

Run:

/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:

PASS input component intents
PASS combo window
PASS action controller flow
PASS player combo input

• Step 3: Run UI tests

Run:

/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:

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:

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.