godot-genre-racing

絶対に避けるべきこと（エキスパート向けアンチパターン）

物理と操作

• 酔いを防ぐため、カメラを剛体に固定してはいけません。必ず lerp() を使った スムーズな追従 パターンを使用してください。
• リアリティを楽しさより優先してはいけません。アーケードらしい反応の良さを実現するため、必ず 重力スケール を上げ（2〜3倍）、摩擦を高く保ってください。
• カートに VehicleBody3D のデフォルト設定を使用してはいけません。必ずレイキャストまたはカスタムのスプリング／ダンパーモデルを使ってサスペンションを書き換えてください。
• 質量に対して直接ステアリングトルクを適用してはいけません。必ず横方向の速度を考慮したステアリングカーブを使用してください。
• ダンパーモデルなしでサスペンションを計算してはいけません。永続的な振動（バウンス）を防ぐため、必ず減衰を含めてください。
• 重心 プロパティを無視してはいけません。高速コーナリング時の安定性を確保するため、必ず重心を下げてください。
• エンジン出力に delta を掛けてはいけません。これは物理ソルバーで積分される力です。
• マニュアルのギアシフトに is_action_pressed() を使用してはいけません。1回のタップを正確に検出するため、必ず is_action_just_pressed() を使用してください。

AIと競争

• AIの速度を固定してはいけません。プレイヤーとの距離に応じてレースの競争性を保つ ラバーバンディング を必ず使用してください。
• AIのパスファインディングを毎フレーム、トラック全体に対して実行してはいけません。必ずスプライン／パス上の「先読み」ポイントを使用してください。
• レースの チェックポイント を無視してはいけません。トラックのショートカットを防ぐため、必ず Area3D による順次検証を実施してください。
• プレイヤーが真後ろにいることを確認する 内積 のチェックなしで、スリップストリームに標準の Area3D を使用してはいけません。

ビジュアルとオーディオ

• 「速度感」の演出を省略してはいけません。必ず 視野角の動的な拡大縮小、モーションブラー、高速走行時のカメラシェイクを実装してください。
• _process() で静的要素のミニマップ上の変換を更新してはいけません。必ず動的なレーサーのみを更新してください。
• ゴーストカーを大量のトランスフォームのリストとしてシリアライズしてはいけません。必ず一定間隔で位置／クォータニオンを保存してください。
• エンジン音のピッチを一定にしてはいけません。必ずRPMまたはエンジン負荷を pitch_scale に対応付けてください。
• スキッドマーク用のパーティクルを毎フレーム生成してはいけません。低コストで軌跡を持続させるため、必ず Trail3D またはプロシージャルなストリップを使用してください。
• 路面の検出に標準の String を使用してはいけません。必ず StringName（例：&"asphalt"）を使用してください。

---

🛠 エキスパート向けコンポーネント（scripts/）

エキスパート向けのオリジナルパターン

• arcade_vehicle_physics.gd - カスタム重力、空中制御、摩擦とスリップを利用したドリフトを備えた、高性能なアーケード向けハンドリングです。
• spline_ai_controller.gd - Path3D による予測ステアリングとラバーバンディングのロジックを使用した、プロ仕様のレーシング AI です。

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

• arcade_vehicle_controller.gd - 物理演算を使わないカート向けの、レイキャストベースのタイトな代替車両移動モデルです。
• raycast_vehicle_controller.gd - シャープなアーケードシミュレーション向けの、RigidBody3D と RayCast サスペンションです。
• lap_checkpoint_manager.gd - 順序付きチェックポイントとラップを管理します。
• spline_track_spawner.gd - AI の走行ライン向けに Path3D のトラック骨組みを作成します。
• slipstream_handler.gd - 相対的な内積チェックによってスピードブーストを発生させる、スリップストリームゾーンです。
• lap_tracker.gd - 順序付きチェックポイントロジックを備えた高精度なラップ管理です。
• ghost_recorder.gd - 軽量なゴーストカー再生向けのバイナリ形式のトランスフォームシリアライズです。
• engine_audio_controller.gd - エンジンの回転音やギアチェンジ向けに、RPM をピッチに変換して音声を合成します。
• skid_mark_emitter.gd - 視覚的なフィードバックを持続させる、条件付きタイヤスリップトレイルシステムです。
• minimap_icon_projector.gd - レーサーをローカライズされた UI に投影する、3D から 2D へのブリッジです。
• force_feedback_router.gd - 地形や衝突に基づいてハプティクスと振動を管理します。
• raycast_suspension.gd - 設定可能な剛性を備えた、レイキャストホイール向けのスプリング／ダンパーモデルです。
• racing_checkpoint.gd - トラックを使ったラップ進行を管理する、インデックス付きトリガーゲートです。

---

コアループ

1. レース：プレイヤーがトラック上の車両を操作します。
2. 競争：プレイヤーが対戦相手を追い越すか、タイムに挑みます。
3. アップグレード：プレイヤーが通貨／ポイントを獲得し、パーツや車を購入します。
4. チューニング：プレイヤーが車両のステータス（グリップ、加速）を調整します。
5. 熟達：プレイヤーがトラックのレイアウトと最適な走行ラインを習得します。

関連スキル（構築順）

Reference → Related Skills の体系を使用してください。スキル ID を独自に作成しないでください。

1. 前提条件 — godot-project-foundations、godot-physics-3d、godot-input-handling
2. 補完スキル — godot-camera-systems、godot-ai-navigation、godot-particles、godot-ui-containers、godot-raycasting-queries
3. 後続スキル — godot-save-load-systems、godot-economy-system

判断ツリー — 車両モデル

操作感	選択肢	必須
VehicleBody3D のアーケードスタイル（トルク／ホイールスリップ）	組み込みホイール＋重力／摩擦の調整	arcade_vehicle_physics.gd
カスタムサスペンション／カートのシャープな操作感	RigidBody3D＋RayCast スプリング	raycast_vehicle_controller.gd（＋raycast_suspension.gd）

最低限の VehicleBody3D のサンプルをそのまま貼り付けないでください。まず、選択したスクリプトを読んでください。任意の入力シム：arcade_vehicle_controller.gd。

ゴールデンパス（スクリプトの順序）

1. 車両 — 上記の物理スクリプトを選択します。
2. チェックポイント／ラップ — racing_checkpoint.gd → lap_checkpoint_manager.gd / lap_tracker.gd。
3. AI — spline_track_spawner.gd → spline_ai_controller.gd。
4. ゴースト — ghost_recorder.gd。

必要に応じて、次のスクリプトも接続します：slipstream_handler.gd、skid_mark_emitter.gd、engine_audio_controller.gd、force_feedback_router.gd、minimap_icon_projector.gd。

ふわつく物理挙動／操作感 — フォールバック表

症状	調整項目	場所
車が浮く／接地力が弱い	gravity_scale を上げます（約2～3倍）。生のリアリズムより楽しさを優先します	arcade_vehicle_physics.gd
簡単に転倒／横転する	COM を低くします（center_of_mass_mode とオフセット）	VehicleBody3D / RigidBody3D
アイススケートのように横滑りする	wheel_friction_slip / normal_friction_slip を上げます。ドリフト中のみドリフトスリップを下げます	arcade_vehicle_physics.gd
レイキャスト式カートの跳ねすぎ	spring_stiffness / spring_damping / tire_grip を調整します	raycast_vehicle_controller.gd、raycast_suspension.gd
カメラの挙動が悪い／硬すぎる	Marker3D と lerp による追従を使います。シャーシに直接親子付けしないでください	godot-camera-systems
視野が狭い／速度を把握できない	速度に応じて FOV を調整します。シェイク、風のライン、モーションブラーも任意で追加できます	Camera3D + Environment。ブースト時に FOV を tween します

高度なレーシングのメタシステム

インラインの DriftBoost／Ghost サンプルを貼り付けないでください。スクリプトを拡張します。

1. ドリフトブースト／ミニターボ — 必須：arcade_vehicle_physics.gd のドリフトフック（is_drifting、drift_friction_slip）を使用します。チャージし、リリース時に apply_central_impulse を適用します。ブーストの感覚を出すため、カメラの FOV を短時間 tween します。
2. タイヤスモーク／スキッド痕 — 必須：skid_mark_emitter.gd を get_skidinfo() で制御し、godot-particles と組み合わせます。物理フレームごとにパーティクルを生成しないでください。
3. バイナリー形式のリプレイゴースト — 必須：変換のシリアライズには ghost_recorder.gd を使用し、godot-save-load-systems で永続化します。

意思決定ツリーやスクリプトカタログを超えて深く掘り下げる場合は、必ず racing-systems-deep.md を参照してください。最初の配線作業では 読み込まないでください。まず同梱の scripts/ を使用します。

アーキテクチャの概要

1. 車両コントローラー

移動の物理挙動を処理します。

## Godot-Specific Tips

*   **VehicleBody3D**: Godot's built-in node for vehicle physics. It's decent for arcade, but for sims, you might want a custom RayCast suspension.
*   **Path3D / PathFollow3D**: Excellent for simple AI traffic or fixed-path racers (on-rails).
*   **AudioBus**: Use the `Doppler` effect on the AudioListener for realistic passing sounds.
*   **SubViewport**: Use for the rear-view mirror or minimap texture.

## Common Pitfalls

1.  **Floaty Physics**: Cars feel like they are on ice. **Fix**: Increase gravity scale (2x-3x) and adjust wheel friction. Realism < Fun.
2.  **Bad Camera**: Camera is rigidly attached to the car. **Fix**: Use a `Marker3D` with a `lerp` script to follow the car smoothly with a slight delay.
3.  **Tunnel Vision**: No sense of speed. **Fix**: Increase FOV as speed increases, add camera shake, wind lines, and motion blur.

## 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
- [VehicleBody3D](https://docs.godotengine.org/en/stable/classes/class_vehiclebody3d.html) — built-in chassis forces, steering, and engine_force integration for arcade/sim hybrids.
- [VehicleWheel3D](https://docs.godotengine.org/en/stable/classes/class_vehiclewheel3d.html) — per-wheel friction_slip, suspension, and skidinfo used by drift and tire-smoke logic.
- [Rigid body](https://docs.godotengine.org/en/stable/tutorials/physics/rigid_body.html) — RigidBody3D force/impulse discipline for custom raycast vehicles and drift-boost impulses.
- [Ray-casting](https://docs.godotengine.org/en/stable/tutorials/physics/ray-casting.html) — RayCast3D suspension, ground contact, and look-ahead probes without full nav mesh queries.
- [Path3D](https://docs.godotengine.org/en/stable/classes/class_path3d.html) — racing-line curves that spline AI and track spawners sample each physics tick.
- [Curve3D](https://docs.godotengine.org/en/stable/classes/class_curve3d.html) — baked samples and up-vectors for banked track props and look-ahead steering points.
- [Area3D](https://docs.godotengine.org/en/stable/classes/class_area3d.html) — checkpoint gates and slipstream draft volumes with body_entered ownership.
- [Camera3D](https://docs.godotengine.org/en/stable/classes/class_camera3d.html) — FOV and follow transforms that sell sense-of-speed without rigid mount sickness.
- [Controllers, gamepads, and joysticks](https://docs.godotengine.org/en/stable/tutorials/inputs/controllers_gamepads_joysticks.html) — analog steer/throttle deadzones and force-feedback routing for racing pads.
- [Audio streams](https://docs.godotengine.org/en/stable/tutorials/audio/audio_streams.html) — pitch_scale / player setup for RPM-mapped engine loops and Doppler pass-bys.
- [Environment and post-processing](https://docs.godotengine.org/en/stable/tutorials/3d/environment_and_post_processing.html) — motion blur and camera attributes that reinforce high-speed FOV ramps.
- [Binary serialization API](https://docs.godotengine.org/en/stable/tutorials/io/binary_serialization_api.html) — compact ghost/replay transform storage via FileAccess store_var.

### Related Skills

#### Prerequisites
- [godot-project-foundations](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-project-foundations/SKILL.md) — scene tree, InputMap actions, and Project Settings physics layers before wiring VehicleBody3D tracks.
- [godot-physics-3d](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-physics-3d/SKILL.md) — RigidBody3D/VehicleBody3D integration, collision layers, and gravity scale patterns racing handling depends on.
- [godot-input-handling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-input-handling/SKILL.md) — analog axes, just-pressed gear/drift taps, and gamepad deadzone curves for steering authority.

#### Complements
- [godot-camera-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-camera-systems/SKILL.md) — smooth follow, FOV ramps, and shake that sell speed without rigid camera mounts.
- [godot-audio-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-audio-systems/SKILL.md) — bus layout, Doppler, and layered engine/tire loops beyond a single pitch_scale mapping.
- [godot-raycasting-queries](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-raycasting-queries/SKILL.md) — suspension rays, surface probes, and look-ahead casts shared with custom kart controllers.
- [godot-ai-navigation](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ai-navigation/SKILL.md) — when spline rubber-banding is not enough and opponents need NavigationAgent3D detours around blockers.
- [godot-particles](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-particles/SKILL.md) — tire smoke, sparks, and trail meshes gated by skidinfo instead of per-frame GPUParticles spam.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — lap_completed, checkpoint, and race-state signals without cross-scene ownership loops.
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — speedometer, lap timer, and minimap HUD layout that stays readable at race pace.

#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — sample rubber-band curves, drift-boost windows, and AI look-ahead knobs for competitive fairness.
- [godot-economy-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-economy-system/SKILL.md) — post-race currency and part upgrades that consume lap/placement outcomes from this genre loop.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — persist ghost binaries, best laps, and unlock state built on race recordings.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — library router and mirrored module entry for cross-skill discovery.