godot-genre-racing

NEVER Do (Expert Anti-Patterns)

Physics & Handling

• NEVER use a rigid camera attachment; strictly use a Smooth Follow pattern with lerp() to prevent motion sickness.
• NEVER prioritize realism over fun; strictly increase Gravity Scale (2x-3x) and keep friction high for responsive arcade feel.
• NEVER use VehicleBody3D default settings for karts; strictly rewrite suspension using Raycasts or custom spring/damper models.
• NEVER apply steering torque directly to mass; strictly use a steering curve factored by lateral velocity.
• NEVER calculate suspension without a damper model; strictly include damping to prevent eternal oscillation (bouncing).
• NEVER ignore the Center of Mass property; strictly offset it downward to ensure stability during high-speed turns.
• NEVER multiply engine force by delta; it is an integrated force in the physics solver.
• NEVER rely on is_action_pressed() for manual gear shifting; strictly use is_action_just_pressed() for single-tap accuracy.

AI & Competition

• NEVER use static AI speeds; strictly use Rubber-Banding to keep races competitive based on player distance.
• NEVER run AI pathfinding across the entire track every frame; strictly use a "Look-Ahead" point on a spline/path.
• NEVER ignore racing Checkpoints; strictly enforce sequential Area3D validation to prevent track shortcuts.
• NEVER use standard Area3D for slipstreaming without a Dot Product check to ensure the player is directly behind.

Visuals & Audio

• NEVER skip "Sense of Speed" effects; strictly implement dynamic FOV scaling, motion blur, and high-speed camera shake.
• NEVER update minimap transforms for static elements in _process(); strictly update dynamic racers only.
• NEVER serialize ghost cars as mass transform lists; strictly store positions/quaternions at fixed intervals.
• NEVER use constant pitch for engine sounds; strictly map RPM or engine load to pitch_scale.
• NEVER spawn particles for skid marks every frame; strictly use Trail3D or procedural strips for low-cost persistence.
• NEVER use standard Strings for surface detection; strictly use StringName (e.g., &"asphalt").

---

🛠 Expert Components (scripts/)

Original Expert Patterns

• [arcade_vehicle_physics.gd](scripts/arcade_vehicle_physics.gd) - High-performance arcade handling with custom gravity, air control, and friction-slip drifting.
• [spline_ai_controller.gd](scripts/spline_ai_controller.gd) - Professional racing AI using Path3D predictive steering and rubber-banding logic.

Modular Components

• [arcade_vehicle_controller.gd](scripts/arcade_vehicle_controller.gd) - Alternative tight, raycast-based vehicle movement model for non-physics karts.
• [raycast_vehicle_controller.gd](scripts/raycast_vehicle_controller.gd) - RigidBody3D + RayCast suspension for crisp arcade sims.
• [lap_checkpoint_manager.gd](scripts/lap_checkpoint_manager.gd) - Sequential checkpoint / lap authority.
• [spline_track_spawner.gd](scripts/spline_track_spawner.gd) - Path3D track scaffolding for AI lines.
• [slipstream_handler.gd](scripts/slipstream_handler.gd) - Drafting zones with relative dot-product checks for speed boosts.
• [lap_tracker.gd](scripts/lap_tracker.gd) - High-precision lap management with sequential checkpoint logic.
• [ghost_recorder.gd](scripts/ghost_recorder.gd) - Binary transform serialization for lightweight ghost car playback.
• [engine_audio_controller.gd](scripts/engine_audio_controller.gd) - RPM-to-pitch audio synthesis for engine revving and gear shifts.
• [skid_mark_emitter.gd](scripts/skid_mark_emitter.gd) - Conditional tire-slip trail system for persistent visual feedback.
• [minimap_icon_projector.gd](scripts/minimap_icon_projector.gd) - 3D-to-2D bridge for projecting racers onto a localized UI.
• [force_feedback_router.gd](scripts/force_feedback_router.gd) - Haptic and rumble management based on terrain and collisions.
• [raycast_suspension.gd](scripts/raycast_suspension.gd) - Spring/damper model for raycast wheels with configurable stiffness.
• [racing_checkpoint.gd](scripts/racing_checkpoint.gd) - Indexed trigger gate for modular track-based lap progression.

---

Core Loop

1. Race: Player controls a vehicle on a track.
2. Compete: Player overtakes opponents or beats the clock.
3. Upgrade: Player earns currency/points to buy parts/cars.
4. Tune: Player adjusts vehicle stats (grip, acceleration).
5. Master: Player learns track layouts and optimal lines.

Related Skills (build order)

Use the Reference → Related Skills lattice — do not invent skill ids:

1. Prerequisites — godot-project-foundations, godot-physics-3d, godot-input-handling
2. Complements — godot-camera-systems, godot-ai-navigation, godot-particles, godot-ui-containers, godot-raycasting-queries
3. Downstream — godot-save-load-systems, godot-economy-system

Decision Tree — Vehicle Model

| Feel | Choose | MANDATORY |

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

| VehicleBody3D arcade (torque / wheel slip) | Built-in wheels + gravity/friction tweaks | [arcade_vehicle_physics.gd](scripts/arcade_vehicle_physics.gd) |

| Custom suspension / kart crispness | RigidBody3D + RayCast springs | [raycast_vehicle_controller.gd](scripts/raycast_vehicle_controller.gd) (+ [raycast_suspension.gd](scripts/raycast_suspension.gd)) |

Do not paste a bare VehicleBody3D sample — read the chosen script first. Optional input shim: [arcade_vehicle_controller.gd](scripts/arcade_vehicle_controller.gd).

Golden Path (script order)

1. Vehicle — pick physics script above.
2. Checkpoints / laps — [racing_checkpoint.gd](scripts/racing_checkpoint.gd) → [lap_checkpoint_manager.gd](scripts/lap_checkpoint_manager.gd) / [lap_tracker.gd](scripts/lap_tracker.gd).
3. AI — [spline_track_spawner.gd](scripts/spline_track_spawner.gd) → [spline_ai_controller.gd](scripts/spline_ai_controller.gd).
4. Ghost — [ghost_recorder.gd](scripts/ghost_recorder.gd).

Also wire as needed: [slipstream_handler.gd](scripts/slipstream_handler.gd), [skid_mark_emitter.gd](scripts/skid_mark_emitter.gd), [engine_audio_controller.gd](scripts/engine_audio_controller.gd), [force_feedback_router.gd](scripts/force_feedback_router.gd), [minimap_icon_projector.gd](scripts/minimap_icon_projector.gd).

Floaty Physics / Feel — Fallback Table

| Symptom | Knob | Where |

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

| Car floats / weak stick | Raise gravity_scale (≈2–3×); Fun > raw realism | [arcade_vehicle_physics.gd](scripts/arcade_vehicle_physics.gd) |

| Tips / rolls easily | Lower COM (center_of_mass_mode + offset) | VehicleBody3D / RigidBody3D |

| Ice-skating lateral slip | Raise wheel_friction_slip / normal_friction_slip; lower drift slip only while drifting | [arcade_vehicle_physics.gd](scripts/arcade_vehicle_physics.gd) |

| Raycast kart too bouncy | Tune spring_stiffness / spring_damping / tire_grip | [raycast_vehicle_controller.gd](scripts/raycast_vehicle_controller.gd), [raycast_suspension.gd](scripts/raycast_suspension.gd) |

| Bad / rigid camera | Marker3D + lerp follow; never hard-parent to chassis | godot-camera-systems |

| Tunnel vision / no speed read | Scale FOV with speed; optional shake, wind lines, motion blur | Camera3D + Environment; FOV tween on boost |

Advanced Racing Meta-Systems

Do not paste inline DriftBoost/Ghost samples — extend the scripts:

1. Drift-Boost / Mini-Turbo — MANDATORY: use drift hooks in [arcade_vehicle_physics.gd](scripts/arcade_vehicle_physics.gd) (is_drifting, drift_friction_slip); charge + apply_central_impulse on release; brief Camera FOV tween for boost feel.
2. Tire-Smoke / skids — MANDATORY: [skid_mark_emitter.gd](scripts/skid_mark_emitter.gd) gated by get_skidinfo(); pair with godot-particles — never spawn particles every physics frame.
3. Replay-Ghost binary — MANDATORY: [ghost_recorder.gd](scripts/ghost_recorder.gd) for transform serialization; persist via godot-save-load-systems.

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

Architecture Overview

1. Vehicle Controller

Handling the physics of movement.

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