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 を使用し、物理演算のロジック全体に影響が及ぶのを避けてください。
• オーディオ遅延のキャリブレーションを怠らないでください。ハードウェアや Bluetooth による遅延（約 30～100ms）を調整できるツールを必ず用意し、「プレイできない」ほどの同期問題を防いでください。
• 曲のクロックとして _process の delta を使用しないでください。必ずコンダクターの get_song_time()（再生位置 + ミックス − 出力遅延）を読み取ってください。
• 数千個のノートスプライトを CPU 上で動かさないでください。トラックの移動処理を GPU に委ねるため、必ず シェーダーベースのハイウェイ（UV スクロール）を使用してください。
• ビートのタイミングに 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 - キャリブレーション UI のオフセットをコンダクターに適用します。

モジュール式コンポーネント

• 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

判断ツリー

クロック（1 つの方法）

必要なもの	操作
曲の再生位置	必須 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	判定ウィンドウの難易度帯

よくある落とし穴

落とし穴	解決策
コンダクターで Time.get_ticks_* を使う	再生位置 + ミックス − レイテンシーを使用します
_process で判定する	_input + 曲の再生時間を使用します
ノートごとにインスタンス化する	note_object_pool.gd

判断ツリーやスクリプト一覧を超える詳細が必要な場合は、rhythm-systems-deep.md が必須です。初回の配線では読み込まないでください。まず同梱の scripts/ を使用してください。

Godot 固有のヒント

1. オーディオレイテンシー：AudioServer とカスタムオフセットを使って調整します
2. 入力ポーリング：正確なタイミングには _process ではなく _input を使用します
3. シェーダー：ノートハイウェイのスクロールには UV スクロールを使用します
4. パーティクル：ヒットエフェクトには GPUParticles2D を使用します

3. ハードウェア同期レイテンシー調整

OS／ハードウェアのレイテンシーを補正して、正確なオフセットを計算します。

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