godot-genre-racing

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

物理与操控

• 绝对不要使用刚性相机附件；务必采用带 lerp() 的平滑跟随模式，以防晕动症。
• 绝不要把真实性置于乐趣之上；务必提高重力比例（2x-3x），并保持较高摩擦力，以获得灵敏的街机操控感。
• 绝不要对卡丁车使用 VehicleBody3D 默认设置；务必使用射线检测或自定义弹簧／阻尼器模型重写悬架。
• 绝不要直接对质量施加转向扭矩；务必使用结合横向速度的转向曲线。
• 绝不要在没有阻尼器模型的情况下计算悬架；务必加入阻尼，以防持续振荡（弹跳）。
• 绝不要忽略质心属性；务必将其向下偏移，确保高速转弯时的稳定性。
• 绝不要将引擎力乘以 delta；它是在物理求解器中积分的力。
• 绝不要依赖 is_action_pressed() 进行手动换挡；务必使用 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 - 专业竞速 AI，使用 Path3D 预测转向和橡皮筋逻辑。

模块化组件

• 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 - 根据转速合成音高，用于引擎轰鸣和换挡音效。
• skid_mark_emitter.gd - 有条件地生成轮胎打滑轨迹，提供持久的视觉反馈。
• minimap_icon_projector.gd - 在 3D 与 2D 之间转换，将赛车投影到局部 UI 上。
• 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
容易翘起 / 翻车	降低质心（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 补间动画

高级竞速元系统

不要粘贴 DriftBoost / Ghost 内联示例，应扩展脚本：

1. 漂移加速 / 小涡轮 — 必须：使用 arcade_vehicle_physics.gd 中的漂移钩子（is_drifting、drift_friction_slip）；蓄力后在释放时调用 apply_central_impulse；通过短暂的 Camera FOV 补间动画营造加速感。
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.