PhysX Vehicle getting started

This chapter gets a car moving with the shortest path: enable the Gem, assemble a chassis, apply a template, add optional drive input, then verify speed in play mode.

Prerequisites

• The PhysXVehicle Gem is enabled in your project (Project Manager or project.json).
• Dependencies PhysX5, PhysXCommon, and LmbrCentral are already enabled.
• Restart the Editor if needed so editor components appear under PhysX Vehicle in the Add Component menu.

Minimal loop (five steps)

1 Enable the Gem
 → 2 Create chassis entity (RB + collider)
 → 3 Apply Sedan template + set mass
 → 4 Add Drive (or script control)
 → 5 Enter play mode and verify

1. Enable the Gem

Enable PhysXVehicle in Project Manager (or add it to the Gem list in project.json). Confirm PhysX5 / PhysXCommon remain enabled. Restart the Editor if the PhysX Vehicle components do not appear.

2. Create the chassis entity

Create an entity and add:

1. PhysX Dynamic Rigid Body
2. PhysX Collider — box or convex hull with reasonable ground clearance (the collider is the chassis shell; wheels do not add separate colliders)
3. PhysX Vehicle Chassis (EditorVehicleChassisComponent)

Recommended hierarchy:

Car (Entity)
├── PhysX Rigid Body + Collider
├── PhysX Vehicle Chassis
├── PhysX Vehicle Drive (optional, step 4)
├── Mesh (body visuals, optional)
├── WheelVisual_FL … RR (optional child meshes)

3. Apply a template and set mass

On PhysX Vehicle Chassis:

1. Choose Template → Sedan (or Off-road / Truck).
2. Click Apply Template. This replaces the chassis configuration (wheels, drive, Ackermann, and related fields).
3. On the PhysX Rigid Body, set Mass to the template intent:

Fine-tune wheel anchors to match your mesh. Default anchors assume O3DE forward = +Y, up = +Z.

If you leave the wheel list empty on a wheeled chassis, EnsureDefaultWheels() builds a default 4-wheel layout at activate time.

Assign each visual wheel entity to the matching wheel’s Wheel Entity Id so the solver can sync suspension compression, steer angle, and spin.

4. Drive it

Option A — PhysX Vehicle Drive (same entity):

Drive has an optional Steer scale (default 1) and an Enabled toggle.

Option B — script / AI (skip Drive): write VehicleControlRequestBus addressed by the chassis entity id. See Scripting and control.

#include <PhysXVehicle/VehicleControlBus.h>
#include <PhysXVehicle/VehicleStateBus.h>

PhysXVehicle::VehicleControlRequestBus::Event(
 chassisEntityId, &PhysXVehicle::VehicleControlRequests::SetGear, 1);
PhysXVehicle::VehicleControlRequestBus::Event(
 chassisEntityId, &PhysXVehicle::VehicleControlRequests::SetThrottle, 1.0f);

A sample Lua driver ships at Gems/PhysXVehicle/Assets/Scripts/VehicleDriveExample.lua (StartingPointInput events: vehicle_throttle / vehicle_brake / vehicle_steer / vehicle_handbrake).

5. Enter play mode and verify

1. Place the vehicle above a PhysX-collidable ground.
2. Enter play mode.
3. Throttle forward; the chassis should accelerate without falling through.
4. Optionally read state:

float speed = 0.0f;
PhysXVehicle::VehicleStateRequestBus::EventResult(
 speed, chassisEntityId, &PhysXVehicle::VehicleStateRequests::GetSpeed);

If nothing moves, open Debugging (Gem missing, collider buried, rays miss ground, wrong mass).

Tracked variant (summary)

For a tank: apply Chassis Tank template, add PhysX Vehicle Track → Apply Tank Track Preset, set rigid-body mass ≈ 35000 kg. Full steps: Tracked vehicles.

Next steps

• Core concepts — why rays and sub-steps matter.
• Wheeled vehicles — templates and tuning.
• Scripting and control — buses and Lua.