controller.mount

A camera that rides a body: it stands at a point of the body's own frame, faces an orientation in that frame, and moves with the body where it is drawn each frame, so it stays on its seat as the body drives, turns, pitches and rolls, smooth whatever the physics tick rate and the frame rate. A driver's seat, a hood or bumper view, a helmet, a turret sight, a boat's bridge, a coaster car, a mech's cockpit.

local cam = entity.spawn("cockpit")
local camera = cam.component.add("Camera", { fov = 70 })
camera.behavior = asset.ref("@builtin::controller.mount", "component")
camera.follow = car

local mount = cam.component.get("@builtin::controller.mount")
mount.offset = { x = -0.35, y = 0.9, z = 0.2 }   -- the driver's eye, in the car's frame
mount.headMotion = 0.04                           -- the head moves with braking and cornering

A key that switches between this view and a chase view behind the car writes the Camera's behavior (@builtin::controller.chase reads the same Camera.follow):

camera.behavior = asset.ref("@builtin::controller.chase", "component")  -- behind the car
camera.behavior = asset.ref("@builtin::controller.mount", "component")  -- back in the seat

A hood view is the same rig with offset on the bonnet; a rear view turns it round with mountYaw = 180; a turret sight puts follow on the turret's own entity, which the rig reads the drawn pose of like any body.

Fields

Field	Default	Notes
follow	empty	The body to ride. Empty takes the Camera's follow slot. Any entity: a body, or an entity parented under one (a seat, a turret), read where it is drawn.
offset	{0, 1.2, 0}	Where the camera stands: metres along the body's own axes, x right, y up, z back (a car's forward is its local -Z).
mountYaw	0	Degrees the view is turned right of the body's forward.
mountPitch	0	Degrees the view is tilted up from the body's forward.
lookSensitivity	0.3	Degrees per unit of the look control.
lookYawLimit	120	Degrees the look turns either side of the mount's direction.
lookPitchMin, lookPitchMax	-45, 45	Degrees the look tilts down and up.
lookReturnDelay	0.6	Seconds after the look is let go before the view comes back. Negative holds the look.
lookReturnTime	0.25	Seconds (time constant) of the view coming back.
invertY	false	Forward on the look control looks up unless this is on.
headMotion	0	Metres the eye moves against each g of acceleration along the body's forward and side axes; the view leans with it, dipping under braking and swaying out of a turn. 0.04 is a belted driver.
headLag	0.12	Seconds (time constant) the head takes to follow a change of acceleration.
inputMap	@builtin::inputMaps.cameraRig	The map look is read from. The camera-rig map stays live while a vehicle holds the player's controls. A write on a live rig takes up the new map.

How it moves

The rig reads Physics.drawnPose of its body every frame: the pose the frame draws the body at, blended between physics ticks. A camera placed from the body's transform (entity.position) would move in whole ticks while the body is drawn between them, and the cabin would shake on screen.

Head motion reads a motion probe the rig places at the mount point (Physics.probeMotion) on the rigid body that carries follow: the followed entity's own body, or for a seat or a turret entity the body it is parented under. The probe reads the acceleration a rider there feels, which the rig turns into the followed entity's own axes. A body this peer does not simulate gives the probe nothing to read, and the head holds still on it.

The camera entity stands unparented: the rig writes its world pose every frame.

Controls

• Look: right-button drag, the right stick, or a drag on the right of a touch screen (the camera-rig map). The view returns to the mount's direction once the control is let go.

For mouse look with no button held, point inputMap at a map of the world's own in the camera group that declares look with pointerLock = true: the camera group stays live while a vehicle holds the player's controls.