Lifecycle and Limitations

Explains configuration phases, validity, cleanup order and the native features intentionally not exposed by JoltVehicle.

A vehicle is a managed world-scoped resource dependent on its chassis. Its handle is opaque and generational; never interpret it as a pointer or Jolt BodyID.

Lifecycle#

Cleanup#

if (is_struct(car)) car.destroy();
// Or release every managed resource in dependency order:
jolt_stop();

• destroy() is idempotent through the managed wrapper.
• Native destruction removes the VehicleConstraint as a step listener and physics constraint.
• Destroying the chassis removes its dependent native vehicle; retain no assumption that the old wrapper remains usable.
• jolt_stop() destroys vehicles before constraints, bodies, world and runtime.

Current limitations#

• Only WheeledVehicleController is public; tracked vehicles and motorcycles are not implemented by the extension API.
• Wheels are virtual, not independently queryable rigid bodies.
• Custom tyre friction curves and engine torque curves are not exposed; safe multipliers and max torque are available.
• Configuration is immutable after build(); recreate the vehicle to change its structural setup.
• No car.update() exists; jolt_update() advances the native vehicle.
• Rendering remains caller-owned.

Safe error handling#

if (!car.set_inputs(throttle, steering, brake, handbrake)) {
    var error = jolt_get_error();
    show_debug_message(error.context + ": " + error.message);
}

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.