makepad/libs/model/VEHICLE_API.md

Editable vehicles

Build the actual car geometry and materials with model operations, then bind four separate tire objects. These operations use ordinary transactional model.apply; the source document, undo history and published GLB preserve them.

{"op":"vehicle_wheel","object":"front_left_tire",
 "connection":"wheel_front_left","pivot":[0,0,0],"radius":0.35,"width":0.22}

delete_vehicle_wheel {object} removes a binding without deleting its mesh. vehicle_wheel replaces that object's existing binding. The four distinct connections are wheel_front_left, wheel_front_right, wheel_rear_left, and wheel_rear_right. An object can have one binding, with at most four per document. Ordinary assets with no wheel bindings compile normally; a vehicle with any bindings requires all four before compilation/publication.

Author in metres with Y up, the nose towards +Z, and the driver's left towards +X. Front anchors must be ahead of their rear anchors in Z; left anchors must have larger X than right anchors. The vehicle runtime rotates this model by 180 degrees around Y into its driving direction, engine -Z.

Each wheel's rotation axle is object-local X. The cylinder primitive's axle is Y, so rotate its geometry onto X using a mesh transform before binding. For example, the row-major matrix [[0,-1,0,0],[1,0,0,0],[0,0,1,0],[0,0,0,1]] rotates a cylinder onto X. Place it with object_node translation and optionally parent it to the body. Wheel node world transforms support translation and positive uniform scale; rotated or nonuniform node bases are refused. Use geometry transforms for the axle orientation. Wheel descendants may contain additional rigid rim geometry, but cannot contain another wheel binding.

pivot is the wheel centre in object-local coordinates. Export computes its model-space anchor through the object hierarchy. radius and width are positive model-space metre measurements, at most 10,000; update them after scaling geometry. Pivot edits preserve the anchor. The wheel object must have exported faces. Skin skeletons and driven wheel bindings cannot be combined. Geometry remains editable; tire UVs and material layers use the ordinary paths.

Export writes the runtime contract directly on the wheel's glTF node: extras: {kind:"vehicle_wheel",connection,pivot,anchor,radius,width}. The renderer separates that geometry from the static body stream. Sandbox fits its four suspension probes to the declared anchors/radii, then renders steering, spin, suspension travel and detached wheels through the same binding. A generic named socket is an attachment marker and does not animate a tire.

For headlights, use actual light operations attached to the body. Place them near the +Z nose. A spot emits along its local -Z, so use rotation [0,1,0,0] to aim it towards the car's +Z front. Example:

{"op":"light","name":"headlight_left","attachment":{"object":"body"},
 "transform":{"translation":[0.6,0.15,2.0],"rotation":[0,1,0,0]},
 "kind":"spot","inner":0.12,"outer":0.4,
 "color":[1,0.9,0.7],"intensity":150,"range":30}

Intensity is candela, range metres, cone half-angles radians. The full car instance transform places both mesh and emitters; model scale does not change light intensity or range. Use an emissive material for a visibly glowing lamp surface as well. For a daylight game, start the lens around emissive strength 0.1 and compare its highlights and beam against the sun before increasing it. Keep lens color, metallic and roughness explicit when using surface_material: omitted factors reset to defaults, including emissive RGB zero. Authored lights remain independent of the gameplay command that toggles generic entity headlights. The host automatically suppresses its two generic headlights when the installed exterior has authored emitters; independent script lights remain available.

Publish the finished asset and use its returned reference for the actual car spawn, with explicit chassis dimensions matching the authored exterior length. The chassis remains the physics body; model length determines the common visual/wheel scale. Seats use the existing vehicle seat count/placement. Named seat sockets and door meshes can be authored, but do not automatically replace gameplay seat placement or supply an opening-door interaction.

Visual steering and suspension

vehicle_wheel accepts optional visual:{steer_gain:0.55,steer_max:0.32,compression:0.08,droop:0.10}. All fields are required together: gain 0..1, angle cap 0..1.2 radians, compression/droop 0..5 model metres. Display steering is clamp(physical steering*gain, -cap, cap); display suspension is clamped to -droop..compression. This affects only visible geometry. Turning radius, tire forces, physical suspension, anchors, radii and spin are unchanged. Without visual metadata, existing motion and source serialization remain unchanged.

The authored limits travel with the shared asset and are used by both the game renderer and model.render. Preserve the intended body silhouette, select an appropriate display range, and verify real clearance within that range. Do not grow giant fenders solely to pass the legacy diagnostic pose.