CharacterController

Explained in Your first game, Rigid bodies.

class CharacterController

import { CharacterController } from '@driftengine/physics';

Constructor

`new`

constructor(options?: ControllerOptions)

Parameter	Type	Description
`options?`	`ControllerOptions`

Properties

Name	Type	Description
`x`	`number`
`y`	`number`
`z`	`number`
`velX`	`number`
`velY`	`number`
`velZ`	`number`
`state`	`ControllerState`
`groundX`	`number`	The surface normal under the feet, meaningful when grounded or sliding.
`groundY`	`number`
`groundZ`	`number`
`upX`	`number`	Which way is up for this body, as a unit vector. World up unless a caller says otherwise. More The whole of this class used to assume one axis, and none of it was wrong for doing so. `velY` was the only representation of vertical velocity, `gravity` was a scalar applied to it, `slopeCos` was measured against world Y, `stepHeight` was a height only because up was fixed, and the three states were decided by a downward probe. That is a complete and correct controller for a body on a floor, and it cannot represent one on a wall at all. A consumer needing one had to reimplement the sweep, the step-over, the slope test and the ground probe — roughly nine hundred lines that would not share this file's contact code, so the two would drift. It is not a gecko's problem: it is every wall-crawler, every arbitrary-gravity level and every walker on the inside of a rotating station. Settable per tick, because a body walking around a corner changes frame continuously and the alternative is rebuilding the controller. Read through `setUp`, which normalises, so the dot products below can assume unit length.
`upY`	`number`
`upZ`	`number`
`groundBody`	`number`	Which body is being stood on, or −1.
`shape`readonly	`ConvexShape`
`foot`readonly	`ConvexShape`	A ball the size of the capsule's foot, swept down to find ground. More A single ray from the capsule's axis is not enough, and the failure is specific: a character balanced on the lip of a step has its axis over open air, the ray misses, it is reported airborne, and stepping is disabled — so it stalls on the edge of the very step it was climbing. A ball finds ground under any part of the foot. It is slightly smaller than the capsule so a wall pressed against the side cannot be mistaken for a floor.
`radius`readonly	`number`
`halfHeight`readonly	`number`
`stepHeight`readonly	`number`
`slopeCos`readonly	`number`
`maxSpeed`readonly	`number`
`acceleration`readonly	`number`
`deceleration`readonly	`number`
`airControl`readonly	`number`
`jumpSpeed`readonly	`number`
`jumpCutoff`readonly	`number`
`gravity`readonly	`number`
`coyoteTicks`readonly	`number`
`jumpBufferTicks`readonly	`number`
`slideBoost`readonly	`number`
`pushStrength`readonly	`number`
`filter`readonly	`QueryFilter \| undefined`

Accessors

Name	Type	Description
`speedAlongUp`get	`number`	This body's speed along its own up. What `velY` was when up was always world Y.

Methods

`setUp`

setUp(x: number, y: number, z: number): void

Point this body's up at a direction, normalising it.

Parameter	Type	Description
`x`	`number`
`y`	`number`
`z`	`number`

A zero-length vector is refused rather than normalised into a NaN frame, because every dot product below would then answer NaN and the states would read as a body that is nowhere. It keeps the frame it had, which is the defined state the two-backends rule asks for in the renderer and is the right answer here for the same reason.

`setGravityDirection`

setGravityDirection(x: number, y: number, z: number): void

Point the fall direction somewhere other than up, and stop it following.

Parameter	Type	Description
`x`	`number`
`y`	`number`
`z`	`number`

The sign convention is up's: gravity is negative, so this is the direction a rise goes and gravity is applied against it. That is the same arithmetic as before — velY += gravity * dt with a gravity of −20 is an acceleration along −Y — generalised rather than reversed.

`teleport`

teleport(x: number, y: number, z: number): void

Place the character, clearing whatever it was doing.

Parameter	Type	Description
`x`	`number`
`y`	`number`
`z`	`number`

`move`

move(world: PhysicsWorld, dt: number, input: ControllerInput): void

Advance one fixed tick.

Parameter	Type	Description
`world`	`PhysicsWorld`
`dt`	`number`
`input`	`ControllerInput`