PhysX Vehicle debugging
Use per-vehicle debug settings on the chassis, optionally override them with a CVar, and work through the troubleshooting table when the vehicle does not move or grip.
Per-vehicle debug settings
On PhysX Vehicle Chassis → Debug (VehicleDebugSettings):
| Field | Purpose |
|---|---|
| Enabled | Master switch for this vehicle’s debug draw / panel |
| Draw suspension | Ray from anchor to contact (colored by hit) |
| Draw contacts | Contact sphere and surface normal |
| Draw tire forces | Longitudinal (blue) / lateral (red) force vectors |
| Draw friction circle | Combined-force point in the contact plane |
| Draw wheels | Wheel disc at the visual wheel center |
| Show ImGui | Telemetry panel when ImGui is available |
| Force scale | Meters drawn per Newton (default 0.0005) |
Debug geometry is submitted on TickBus via DebugDisplayRequestBus. Solving still runs on physics sub-steps—draw is visualization only.
CVar: vehicle_DebugDraw
| Value | Meaning |
|---|---|
0 | Use each vehicle’s Debug → Enabled |
1 | Force debug draw on for all vehicles |
-1 | Force debug draw off for all vehicles |
The CVar is marked DontReplicate. Prefer chassis Debug for single-vehicle work; use 1 when comparing several cars in one scene.
ImGui telemetry
When Show ImGui is on and the ImGui Gem is present (build with PHYSXVEHICLE_IMGUI_ENABLED), the panel shows speed / RPM / gear and per-wheel telemetry. If the panel never appears, confirm the ImGui Gem and that Debug → Enabled is on (or vehicle_DebugDraw = 1).
What to look for
| Draw | Healthy sign | Problem sign |
|---|---|---|
| Suspension rays | Hit ground under each wheel / road wheel | Rays miss or start underground |
| Contacts | Stable points under the chassis | Flicker / none while collider intersects ground |
| Tire / track forces | Forward push under driven contacts when throttling | Huge forces + spin, or zero force with throttle |
| Friction circle | Combined demand inside the circle | Saturation every frame → lower torque or raise friction |
Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| Vehicle does nothing | Gem / chassis / rigid body missing | Enable Gem; confirm dynamic RB + collider + Chassis on same entity |
| Falls through / no grip | Collider buried or rays miss ground | Raise chassis; check anchors and rest length + radius reach the ground |
| Tips over easily | High CoM or light anti-roll | Lower CoM offset Z; set rigid-body mass correctly; add anti-roll |
| Wheels spin, no motion | Low friction or excess torque | Raise tire friction; lower peak torque |
| Visual wheels frozen | No Wheel Entity Id | Assign child mesh entities on each wheel config |
| Tracked acts like a car | No Track component / wrong kind | Apply Tank chassis template + Track preset |
| Jitter on pivot turn | High track gains | Lower long / lat gain; keep physics fixed step stable |
| Script input ignored | Drive still writing / wrong entity id | Disable Drive; address buses with chassis id |
| Bounce / porpoise | Stiffness / damping mismatch | Raise damping ratio; lower stiffness or revisit auto-stiffness target rest ratio |
| ImGui missing | ImGui Gem / define off | Enable ImGui; confirm PHYSXVEHICLE_IMGUI_ENABLED |
Related checks outside the Gem
- Ground must have PhysX collision (static or dynamic) that scene queries can hit.
- Collider ground clearance should leave room for suspension rays; a collider that sits on the ground can fight the ray forces.
- Fixed physics step stability matters for tracked pivot turns—avoid extreme sub-step sizes when debugging jitter.
Next steps
- Components — Debug field defaults.
- Reference — limits and design docs.