Class PhysicsCharacterController
Constructors
constructor
-
new PhysicsCharacterController(
world: PhysicsWorld,
position: Vec3,
options: PhysicsCharacterControllerOptions,
): PhysicsCharacterControllerConstruct a controller. Prefer the createPhysicsCharacterController factory.
Parameters
- world: PhysicsWorld
- position: Vec3
- options: PhysicsCharacterControllerOptions
Returns PhysicsCharacterController
Properties
acceleration
Acceleration factor used by calculateMovement. Default 0.05.
character
Character mass used when reacting to gravity against dynamic bodies. Default 0.
character
Push strength applied to dynamic bodies the character contacts. Default 1e38.
dynamic
Dynamic-friction coefficient against surfaces. Default 1.
keep
Extra distance over which a contact is still tracked. Default 0.1.
keep
Minimum separation kept from surfaces, in metres. Default 0.05.
max
Maximum world-space acceleration used by calculateMovement. Default 50.
max
Maximum number of cast iterations per integration step. Default 10.
max
Upper bound on per-solve character speed. Default 10.
max
Cosine of the steepest slope the character can stand on. Default 0.5 (60°).
Readonlyon
Fires once per dynamic body the character pushes during a step, just before the reactive
impulse is applied. Mirrors Babylon.js' onTriggerCollisionObservable. Subscribe with
.add(cb); the returned disposer removes the subscription.
penetration
Speed at which penetrations are pushed out. Default 1.0.
static
Static-friction coefficient against surfaces. Default 0.
up
World up vector. Default (0, 1, 0).
Accessors
shape
-
The shape options used to build the collision capsule. Reflects the values passed at construction or the last call to setShapeOptions.
Returns PhysicsCharacterControllerOptions
Methods
calculate
-
calculateMovement(
deltaTime: number,
forwardWorld: Vec3,
surfaceNormal: Vec3,
currentVelocity: Vec3,
surfaceVelocity: Vec3,
desiredVelocity: Vec3,
upWorld: Vec3,
): Vec3Compute a target velocity from the current state, a desired velocity, and surface info — a helper for steering input into surface-aware motion.
Parameters
- deltaTime: number
Step duration in seconds.
- forwardWorld: Vec3
Character forward direction (world space).
- surfaceNormal: Vec3
Supporting surface normal.
- currentVelocity: Vec3
Current character velocity.
- surfaceVelocity: Vec3
Velocity induced by the surface.
- desiredVelocity: Vec3
Desired character velocity.
- upWorld: Vec3
Up vector (world space).
Returns Vec3
The new velocity vector.
- deltaTime: number
check
-
Probe the surface under the character along a direction (usually gravity) to classify support.
Parameters
- deltaTime: number
Step duration in seconds.
- direction: Vec3
Direction to probe, usually the gravity direction.
Returns CharacterSurfaceInfo
Support classification and averaged surface motion/normal.
- deltaTime: number
dispose
-
Release the controller's body, shape, and query collectors.
Returns void
get
-
Get the Havok body backing this character controller.
Returns PhysicsBody
get
-
Get the current character position (world space). The returned vector is owned by the controller.
Returns Vec3
get
-
Get the current character velocity (world space). The returned vector is owned by the controller.
Returns Vec3
integrate
-
Advance the controller using a velocity already chosen for this step (instead of a raw displacement). Mirrors Babylon.js'
integrate: it picks a cast direction from the current velocity and surface info, then runs the collide-and-slide.Parameters
- deltaTime: number
Step duration in seconds.
- surfaceInfo: CharacterSurfaceInfo
Surface info from a prior checkSupport call.
- gravity: Vec3
Gravity applied to the character this step.
Returns void
- deltaTime: number
move
-
Move the character by a displacement this physics step, sliding along any geometry it meets.
Parameters
- displacement: Vec3
Requested world-space displacement for this step.
Returns void
- displacement: Vec3
set
-
Teleport the character to a new position, clearing any swept motion.
Parameters
- position: Vec3
Returns void
set
-
Set new shape options and rebuild the collision capsule accordingly.
This is the supported way to change the capsule for common character features such as crouching, standing, crawling or sliding without recreating the controller (which would lose its position, velocity, support state and event subscriptions). The old Havok shape is released and replaced with a new one built from
options.capsuleHeight/options.capsuleRadius.Parameters
- options: PhysicsCharacterControllerOptions
New capsule dimensions.
- preserveFootPosition: boolean = true
When
true(default), the controller position is adapted so the world-space foot position (center - up * height/2) is kept fixed as the height changes; whenfalse, the position is left unchanged.
Returns void
- options: PhysicsCharacterControllerOptions
A physics-driven character controller. Create one with createPhysicsCharacterController; drive it each physics step with PhysicsCharacterController.moveWithCollisions and read back the resolved position with PhysicsCharacterController.getPosition.