Vehicle

Vehicle is the runtime API for deterministic vehicle entities.

Vehicles are not generic nodes. They are dynamic simulation entities with:

• handling/config
• state
• inputs
• driver occupancy

Status

Partially implemented.

Implemented now on the server:

• Vehicle.Create
• Vehicle.Destroy
• Vehicle.Get
• Vehicle.GetAll
• Vehicle.SetFrozen
• Vehicle.AssignDriver
• Vehicle.ClearDriver

Implemented now on shared/client:

• Vehicle.Get
• Vehicle.GetAll

Shared/client queries read from the built-in authoritative replica mirror.

Function List

Function	Description	Scope
Vehicle.Create	Spawn a deterministic vehicle.	S
Vehicle.Destroy	Remove a deterministic vehicle.	S
Vehicle.Get	Read one runtime vehicle.	S
Vehicle.GetAll	List runtime vehicles.	S
Vehicle.SetFrozen	Freeze/unfreeze a deterministic vehicle.	S
Vehicle.AssignDriver	Assign a player as the vehicle driver.	S
Vehicle.ClearDriver	Clear the current vehicle driver.	S

Events

Current script-facing lifecycle events:

• vehicle:spawned
• vehicle:despawned
• vehicle:driver_changed

Vehicle.Create

S Server Only

local vehicleId, err = Vehicle.Create(definition, transform, options)

Parameters:

• definition (string): vehicle config/archetype id
• transform (table):
• position (x, y, z)
• rotation (x, y, z, w)
• options (table, optional)

Returns:

• vehicleId (number | nil)
• err (nil | string)

Vehicle.Destroy

S Server Only

local ok, err = Vehicle.Destroy(vehicleId)

Returns:

• ok (boolean | nil)
• err (nil | string)

Vehicle.Get

S Shared

local vehicle, err = Vehicle.Get(vehicleId)

Returns:

• vehicle (table | nil)
• err (nil | string)

Current fields:

• vehicleId
• definition
• tick
• position
• rotation
• linearVelocity
• angularVelocity
• grounded
• frozen
• driverPlayerId (server)
• controlled (shared/client)
• spawnConfirmed (shared/client)

Vehicle.GetAll

S Shared

local vehicles, err = Vehicle.GetAll()

Returns:

• vehicles (table | nil)
• err (nil | string)

Vehicle.AssignDriver

S Server Only

local ok, err = Vehicle.AssignDriver(vehicleId, playerId)

Returns:

• ok (boolean | nil)
• err (nil | string)

Vehicle.SetFrozen

S Server Only

local ok, err = Vehicle.SetFrozen(vehicleId, frozen)

Parameters:

• vehicleId (number)
• frozen (boolean)

Returns:

• ok (boolean | nil)
• err (nil | string)

Vehicle.ClearDriver

S Server Only

local ok, err = Vehicle.ClearDriver(vehicleId)

Returns:

• ok (boolean | nil)
• err (nil | string)

Relationship To Other APIs

• Node remains the graph API for map/world objects
• Map owns static baked world content
• Environment owns world visual state

Vehicles should interact with the deterministic world query layer, not directly with Godot physics.

In the current runtime direction there is no on-foot player flow. A player is either:

• unassigned
• assigned as the driver of a vehicle

Vehicle spawn/despawn and driver assignment/clearing are intentionally separate operations.

Configuration Direction

Vehicles should spawn by stable vehicleId, backed by registered vehicle config data.

Planning reference:

• Docs/Vehicle_Config_Schema_v1.md
• Docs/Deterministic_Numeric_Representation_v1.md
• Docs/Vehicle_Registry_And_Spawn_Validation_v1.md
• Docs/Vehicle_Replication_And_Snapshots_v1.md
• Docs/Vehicle_Transport_Events_v1.md