godot-genre-rhythm

NEVER Do (Expert Anti-Patterns)

Audio Sync & Logic

• NEVER use Time.get_ticks_msec() / Time.get_ticks_usec() as the song clock; strictly use AudioStreamPlayer.get_playback_position() + AudioServer.get_time_since_last_mix() - AudioServer.get_output_latency() (see [rhythm_conductor.gd](scripts/rhythm_conductor.gd)).
• NEVER process song logic in _process(); strictly use _physics_process() or a conductor loop to ensure deterministic timing regardless of render frames.
• NEVER use _process() to capture hit inputs; strictly use _input(event) to record the exact timestamp of the button press event.
• NEVER scale engine time_scale for song speed; strictly use AudioStreamPlayer.pitch_scale to adjust speed and avoid globally breaking physics logic.
• NEVER neglect Audio Latency calibration; strictly provide a tool for players to adjust for hardware/Bluetooth delays (~30-100ms) to prevent "unplayable" sync issues.
• NEVER use _process delta as the song clock; strictly read the conductor's get_song_time() (playback + mix − output latency).
• NEVER move thousands of note sprites on the CPU; strictly use a Shader-Based Highway (UV scrolling) to offload track movement to the GPU.
• NEVER use yield or await for beat timing; strictly use a sample-accurate Delta Accumulator tied to the audio clock.
• NEVER assume a constant BPM; strictly build your conductor to handle a Tempo Map for complex track changes.

Feedback & Performance

• NEVER judge inputs based on world position (pixels); strictly judge against the Song's Elapsed Time (ms) to ensure consistency across resolutions.
• NEVER play hit sounds with static pitch; strictly add ±5% Random Pitch Variation to hit sounds to avoid the "machine gun" effect.
• NEVER use tight timing windows (e.g., <25ms) for all players; strictly use Wider Windows for Beginners to prevent immediate frustration.
• NEVER instantiate note nodes every beat; strictly use Object Pooling to recycle note instances and prevent GC spikes during dense tracks.
• NEVER use standard Area2D signals for rhythmic hits; strictly Poll Inputs in the conductor loop to compare against target timestamps.
• NEVER calculate FFT for visualization on the main thread; strictly use AudioEffectSpectrumAnalyzerInstance for optimized engine-side analysis.
• NEVER allow note spamming/mashing; strictly penalize misses or break combos to maintain the game's integrity.
• NEVER use load() dynamically during gameplay; strictly use ResourceLoader.load_threaded_request() to avoid thread stalling.
• NEVER forget to pause the conductor/ highway; strictly sync with the audio player's pause state to prevent notes from scrolling while the music is stopped.

---

🛠 Expert Components (scripts/)

> MANDATORY reads before implementing the matching system:

> 1. [rhythm_conductor.gd](scripts/rhythm_conductor.gd) — canonical audio clock

> 2. [input_judge_logic.gd](scripts/input_judge_logic.gd) — time-window judging

> 3. [note_object_pool.gd](scripts/note_object_pool.gd) — pooled notes (no per-beat instantiate)

> 4. [latency_calibrator.gd](scripts/latency_calibrator.gd) — player hardware offset

Original Expert Patterns

• [rhythm_conductor.gd](scripts/rhythm_conductor.gd) - Song time = playback_position + mix − output latency.
• [input_judge_logic.gd](scripts/input_judge_logic.gd) - ms windows vs song time (not pixel position).
• [note_object_pool.gd](scripts/note_object_pool.gd) - Recycle note instances under dense charts.
• [latency_calibrator.gd](scripts/latency_calibrator.gd) - Calibration UI offset applied on the conductor.

Modular Components

• [note_orchestrator.gd](scripts/note_orchestrator.gd) - Spawn/schedule notes from chart data.
• [rhythm_scoring_system.gd](scripts/rhythm_scoring_system.gd) - Score aggregation from judgments.
• [score_combo_manager.gd](scripts/score_combo_manager.gd) - Combo / break rules.
• [rhythm_ui_feedback.gd](scripts/rhythm_ui_feedback.gd) - Hit sparks / judgment labels.
• [beat_synced_animator.gd](scripts/beat_synced_animator.gd) - Visuals locked to conductor beats.
• [note_lane_manager.gd](scripts/note_lane_manager.gd) - Multi-lane layout helpers.
• [dynamic_bpm_handler.gd](scripts/dynamic_bpm_handler.gd) - Tempo map / BPM changes.
• [audio_spectrum_analyzer.gd](scripts/audio_spectrum_analyzer.gd) - Spectrum visuals (not the clock).

> Do NOT load unused lanes: skip [audio_spectrum_analyzer.gd](scripts/audio_spectrum_analyzer.gd) unless building reactive viz; skip [dynamic_bpm_handler.gd](scripts/dynamic_bpm_handler.gd) for constant-BPM tracks.

---

> Script map: Baseline MusicConductor samples → [rhythm_conductor.gd](scripts/rhythm_conductor.gd); JudgmentSystem → [input_judge_logic.gd](scripts/input_judge_logic.gd); chart spawn → [note_orchestrator.gd](scripts/note_orchestrator.gd) + [note_object_pool.gd](scripts/note_object_pool.gd).

Core Loop

1. Calibrate latency → 2. Conductor clock → 3. Spawn pooled notes → 4. _input judge → 5. Score/combo UI

Decision Trees

Clock (one recipe)

| Need | Action |

|------|--------|

| Song position | MANDATORY [rhythm_conductor.gd](scripts/rhythm_conductor.gd) get_song_time() |

| Visual highway | Position from song time / beats — never _process delta integration as truth |

| Hit timestamp | Capture in _input / _unhandled_input, compare to note target time |

Systems

| Need | Action |

|------|--------|

| Judgment windows | [input_judge_logic.gd](scripts/input_judge_logic.gd) |

| Scoring / combo | [rhythm_scoring_system.gd](scripts/rhythm_scoring_system.gd) + [score_combo_manager.gd](scripts/score_combo_manager.gd) |

| Chart spawn | [note_orchestrator.gd](scripts/note_orchestrator.gd) + pool |

| Juice | [rhythm_ui_feedback.gd](scripts/rhythm_ui_feedback.gd) / [beat_synced_animator.gd](scripts/beat_synced_animator.gd) |

Do not re-inline MusicConductor / NoteHighway / JudgmentSystem / RhythmScoring classes in this skill — load the scripts.

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. Audio | godot-audio-systems | Stream clock + latency |

| 2. Input | godot-input-handling | Timestamped hits |

| 3. UI | godot-ui-containers | Highway / HUD |

| 4. Perf | pooling / shaders | Dense charts |

| 5. Balance | godot-monte-carlo-balancer | Window difficulty bands |

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| Time.get_ticks_* conductor | Use playback + mix − latency |

| Judge in _process | _input + song time |

| Instantiate per note | [note_object_pool.gd](scripts/note_object_pool.gd) |

> MANDATORY for depth beyond decision trees and script catalog: [rhythm-systems-deep.md](references/rhythm-systems-deep.md). Do NOT Load on first-pass wiring — use bundled scripts/ first.

Godot-Specific Tips

1. Audio latency: Calibrate with AudioServer and custom offset
2. Input polling: Use _input not _process for precise timing
3. Shaders: UV scrolling for note highways
4. Particles: Use GPUParticles2D for hit effects

3. Hardware-Synced Latency Calibration

Calculate precise offsets by compensating for OS/Hardware latency.

## Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

### Official Documentation
- [Sync the gameplay with audio and music](https://docs.godotengine.org/en/stable/tutorials/audio/sync_with_audio.html) — Playback-position helpers (`get_time_since_last_mix`, output latency) that every BPM conductor and judgment window must use.
- [Audio streams](https://docs.godotengine.org/en/stable/tutorials/audio/audio_streams.html) — AudioStreamPlayer roles, pitch_scale for song speed, and how music reaches buses without breaking sync.
- [Audio buses](https://docs.godotengine.org/en/stable/tutorials/audio/audio_buses.html) — Route Music / HitSFX / UI so judgment SFX never fight the track bus.
- [Importing audio samples](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_audio_samples.html) — WAV vs Ogg/MP3 tradeoffs for charts, hit clicks, and calibration tones.
- [AudioServer](https://docs.godotengine.org/en/stable/classes/class_audioserver.html) — Mix/output latency APIs and bus-effect instances used by conductors and spectrum visuals.
- [AudioStreamPlayer](https://docs.godotengine.org/en/stable/classes/class_audiostreamplayer.html) — Non-positional music/hit player API (`get_playback_position`, `pitch_scale`, pause) for the highway clock.
- [AudioEffectSpectrumAnalyzer](https://docs.godotengine.org/en/stable/classes/class_audioeffectspectrumanalyzer.html) — Engine-side FFT effect for reactive highways without main-thread FFT work.
- [Using InputEvent](https://docs.godotengine.org/en/stable/tutorials/inputs/inputevent.html) — `_input` / action press timing for lane hits instead of polling in `_process`.
- [CanvasItem shaders](https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/canvas_item_shader.html) — UV scroll patterns for GPU note highways that avoid moving thousands of sprites on CPU.
- [Tween](https://docs.godotengine.org/en/stable/classes/class_tween.html) — Judgment splash, receptor pulse, and beat-synced scale pops without frame-tied lerps.
- [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html) — Threaded chart/audio preload so dense tracks never stall the first note.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — Audio latency project settings, bus layout names, and input map lane actions must exist before the conductor runs.
- [godot-audio-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-audio-systems/SKILL.md) — Buses, stream players, spectrum instances, and sync-with-audio helpers this genre skill consumes for BPM clocks.
- [godot-input-handling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-input-handling/SKILL.md) — Action maps, `_input` vs `_unhandled_input`, and event timestamps for lane press/release and anti-spam.
- [godot-gdscript-mastery](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-gdscript-mastery/SKILL.md) — Typed Resources for NoteData/charts, signals for beat/judgment events, and deterministic timing loops.

#### Complements
- [godot-tweening](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-tweening/SKILL.md) — Judgment labels, receptor flashes, and beat pulses should be Tween-driven, not per-frame scale hacks.
- [godot-shaders-basics](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-shaders-basics/SKILL.md) — Shader highways and spectrum-driven uniforms keep dense charts off the CPU.
- [godot-particles](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-particles/SKILL.md) — Hit sparks and combo flourishes via GPUParticles2D without instantiating VFX every Perfect.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — Score/combo HUD, calibration sliders, and lane receptor layout as Control trees.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — Persist A/V offset, scroll speed, and difficulty windows across sessions.
- [godot-autoload-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-autoload-architecture/SKILL.md) — Conductor / scoring / pool owners are typically Autoloads with a clear boot order.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — Beat, judgment, combo-break, and chart-finished signals need owner boundaries so UI never owns the clock.

#### Downstream / consumers
- [godot-performance-optimization](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-performance-optimization/SKILL.md) — Escalate when note pools, highway draw calls, or mix callbacks still hitch after pooling and shader scroll.
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — Simulate timing-window width, scroll speed, and miss penalties against clear rates before shipping difficulty tiers.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross-cutting rhythm concern.