godot-genre-rhythm

绝对不要做（专家级反模式）

音频同步与逻辑

• 绝对不要使用 Time.get_ticks_msec() / Time.get_ticks_usec() 作为歌曲时钟；必须使用 AudioStreamPlayer.get_playback_position() + AudioServer.get_time_since_last_mix() - AudioServer.get_output_latency()（参见 rhythm_conductor.gd）。
• 绝对不要在 _process() 中处理歌曲逻辑；必须使用 _physics_process() 或指挥器循环，确保无论渲染帧数如何，时序都具有确定性。
• 绝对不要使用 _process() 捕获击打输入；必须使用 _input(event) 记录按钮按下事件的准确时间戳。
• 绝对不要通过缩放引擎的 time_scale 来调整歌曲速度；必须使用 AudioStreamPlayer.pitch_scale 调整速度，避免全局破坏物理逻辑。
• 绝对不要忽略 音频延迟 校准；必须提供工具，让玩家能够调整硬件 / 蓝牙延迟（约 30-100ms），避免出现“无法游玩”的同步问题。
• 绝对不要将 _process 的 delta 用作歌曲时钟；必须读取指挥器的 get_song_time()（播放位置 + 混音时间 − 输出延迟）。
• 绝对不要在 CPU 上移动数千个音符精灵；必须使用基于着色器的轨道（UV 滚动），将轨道移动交给 GPU 处理。
• 绝对不要使用 yield 或 await 计时节拍；必须使用与音频时钟关联、采样精确的增量累加器。
• 绝对不要假设 BPM 恒定；必须构建能够处理复杂曲目变化的速度图。

反馈与性能

• 绝对不要根据世界位置（像素）判断输入；必须根据**歌曲经过时间（ms）**进行判断，确保不同分辨率下的一致性。
• 绝对不要以固定音高播放击打音效；必须为击打音效添加 ±5% 的随机音高变化，避免产生“机关枪”效果。
• 绝对不要对所有玩家都使用严格的时序窗口（例如 <25ms）；必须为初学者设置更宽的窗口，避免他们立即受挫。
• 绝对不要每拍都实例化音符节点；必须使用对象池回收音符实例，避免密集曲目中出现 GC 峰值。
• 绝对不要使用标准 Area2D 信号进行节奏击打；必须在指挥器循环中轮询输入，并与目标时间戳进行比较。
• 绝对不要在主线程上计算 FFT 进行可视化；必须使用 AudioEffectSpectrumAnalyzerInstance，进行经过优化的引擎侧分析。
• 绝对不要允许刷音符 / 连击；必须惩罚漏击或打断连击，以维护游戏的完整性。
• 绝对不要在游戏过程中动态使用 load()；必须使用 ResourceLoader.load_threaded_request()，避免线程卡顿。
• 绝对不要忘记暂停指挥器 / 轨道；必须与音频播放器的暂停状态保持同步，防止音乐停止时音符仍在滚动。

---

🛠 专家组件（scripts/）

实现匹配系统前，必须阅读：

1. rhythm_conductor.gd — 标准音频时钟
2. input_judge_logic.gd — 时间窗口判定
3. note_object_pool.gd — 池化音符（不逐拍实例化）
4. latency_calibrator.gd — 玩家硬件偏移

原创专家模式

• rhythm_conductor.gd - 歌曲时间 = 播放位置 + 混音时间 − 输出延迟。
• input_judge_logic.gd - 以歌曲时间（而非像素位置）计算 ms 时间窗口。
• note_object_pool.gd - 在密集谱面中回收音符实例。
• latency_calibrator.gd - 应用于指挥器的校准界面偏移量。

模块化组件

• note_orchestrator.gd - 根据谱面数据生成／安排音符。
• rhythm_scoring_system.gd - 根据判定汇总分数。
• score_combo_manager.gd - 连击／断连规则。
• rhythm_ui_feedback.gd - 击中特效／判定标签。
• beat_synced_animator.gd - 与节拍器节拍同步的视觉效果。
• note_lane_manager.gd - 多轨道布局辅助工具。
• dynamic_bpm_handler.gd - 速度图／BPM 变化。
• audio_spectrum_analyzer.gd - 频谱视觉效果（不负责计时）。

不要加载未使用的轨道：除非要构建响应式视觉效果，否则跳过 audio_spectrum_analyzer.gd；对于 BPM 恒定的曲目，跳过 dynamic_bpm_handler.gd。

---

**脚本映射：**基准 MusicConductor 采样 → rhythm_conductor.gd；JudgmentSystem → input_judge_logic.gd；谱面生成 → note_orchestrator.gd + note_object_pool.gd。

核心循环

1. 校准延迟 → 2. 节拍器时钟 → 3. 生成对象池中的音符 → 4. _input 判定 → 5. 分数／连击 UI

决策树

时钟（一种方案）

需求	操作
歌曲位置	必须使用 rhythm_conductor.gd get_song_time()
视觉轨道	根据歌曲时间／节拍计算位置——绝不能用 _process 增量积分作为基准
击中时间戳	在 _input / _unhandled_input 中捕获，并与音符目标时间比较

系统

需求	操作
判定窗口	input_judge_logic.gd
计分／连击	rhythm_scoring_system.gd + score_combo_manager.gd
谱面生成	note_orchestrator.gd + 对象池
表现效果	rhythm_ui_feedback.gd / beat_synced_animator.gd

不要在此技能中重新内联 MusicConductor / NoteHighway / JudgmentSystem / RhythmScoring 类——请加载脚本。

技能链

阶段	技能	用途
1. 音频	godot-audio-systems	音频流时钟 + 延迟
2. 输入	godot-input-handling	带时间戳的击中
3. UI	godot-ui-containers	轨道／HUD
4. 性能	对象池／着色器	密集谱面
5. 平衡	godot-monte-carlo-balancer	判定窗口难度区间

必须阅读 rhythm-systems-deep.md，以获取超出决策树和脚本目录范围的深入内容。首次接线时不要加载——先使用内置的 scripts/。

Godot 专属提示

1. 音频延迟：使用 AudioServer 和自定义偏移进行校准
2. 输入轮询：精确计时时使用 _input，而不是 _process
3. 着色器：使用 UV 滚动实现音符轨道
4. 粒子：使用 GPUParticles2D 实现击中特效

3. 硬件同步延迟校准

通过补偿操作系统／硬件延迟，计算精确偏移量。

## 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.