API
API|
@babylonjs/core|
PhysicsCharacterController

Class PhysicsCharacterController

Character controller using physics

Index
constructor
acceleration characterMass characterStrength dynamicFriction footOffset keepContactTolerance keepDistance maxAcceleration maxCastIterations maxCharacterSpeedForSolver maxSlopeCosine maxStepHeight onTriggerCollisionObservable penetrationRecoverySpeed staticFriction up
shape shapeOptions
calculateMovement calculateMovementToRef checkSupport checkSupportToRef dispose getPosition getVelocity integrate moveWithCollisions setPosition setShapeOptions setVelocity
acceleration: number = 0.05

Acceleration factor. A value of 1 means reaching max velocity immediately

characterMass: number = 0

character mass default 0

characterStrength: number = 1e38

Strength when pushing other bodies default 1e38

dynamicFriction: number = 1

friction with dynamic surfaces default 1

footOffset: number

Distance from the body's position to the character's foot along up. Used by maxStepHeight to measure how high a contact sits above the foot. Defaults to half the capsule height passed at construction. Override when supplying a custom collision shape whose center is not at half-height.

keepContactTolerance: number = 0.1

maximum distance to keep contact default 0.1

keepDistance: number = 0.05

minimum distance to make contact default 0.05

maxAcceleration: number = 50

maximum acceleration in world space coordinate

maxCastIterations: number = 10

maximum number of raycast per integration starp default 10

maxCharacterSpeedForSolver: number = 10.0

character maximum speed default 10

maxSlopeCosine: number = 0.5

cosine value of slope angle that can be climbed computed as Math.cos(Math.PI * (angleInDegree / 180.0)); default 0.5 (value for a 60deg angle)

maxStepHeight: number = 0

Maximum height the character can automatically step up onto a walkable surface. When greater than 0 the controller enforces this as a strict cap on step climbing, independent of the collision shape's geometry:

  • Obstacles whose top is at most maxStepHeight above the character's foot are climbed (either rolled over naturally by the capsule, or snapped up via the step-up sweep when the simplex would otherwise be blocked).
  • Obstacles taller than maxStepHeight are blocked, even ones the capsule's rounded bottom would otherwise glide over.

This is enforced by demoting any "walkable" contact that sits more than maxStepHeight above the foot into an extra horizontal wall constraint, so the step-height limit does not depend on the capsule radius. As a documented side effect, slopes whose contact rises above maxStepHeight (roughly when capsuleRadius * (1 - cos(slopeAngle)) > maxStepHeight) are also treated as walls. Pick maxStepHeight large enough to clear the slope angles you want to remain walkable, or rely on maxSlopeCosine alone (with maxStepHeight = 0) when the rounded-capsule riding behavior is acceptable.

Step-up only triggers against STATIC and ANIMATED bodies. Dynamic bodies fall through to normal contact resolution and pushing behavior.

Thin walls / fences with floor behind them are not considered steppable: the landing must be measurably higher than the starting position along up.

The foot is computed as position - up * footOffset. Override footOffset if you supply a custom collision shape whose center is not at half-height.

Assumes up is a unit vector.

default 0 (disabled)

onTriggerCollisionObservable: Observable<ICharacterControllerCollisionEvent> = ...

Observable for trigger entered and trigger exited events

penetrationRecoverySpeed: number = 1.0

speed when recovery from penetration default 1.0

staticFriction: number = 0

friction with static surfaces default 0

up: Vector3 = ...

up vector

  • Helper function to calculate velocity based on surface informations and current velocity state and target

    Parameters

    • deltaTime: number

      frame delta time in seconds. When using scene.deltaTime divide by 1000.0

    • forwardWorld: Vector3

      character forward in world coordinates

    • surfaceNormal: Vector3

      surface normal direction

    • currentVelocity: Vector3

      current velocity

    • surfaceVelocity: Vector3

      velocity induced by the surface

    • desiredVelocity: Vector3

      desired character velocity

    • upWorld: Vector3

      up vector in world space

    Returns Vector3

    a new velocity vector

  • Helper function to calculate velocity based on surface informations and current velocity state and target

    Parameters

    • deltaTime: number

      frame delta time in seconds. When using scene.deltaTime divide by 1000.0

    • forwardWorld: Vector3

      character forward in world coordinates

    • surfaceNormal: Vector3

      surface normal direction

    • currentVelocity: Vector3

      current velocity

    • surfaceVelocity: Vector3

      velocity induced by the surface

    • desiredVelocity: Vector3

      desired character velocity

    • upWorld: Vector3

      up vector in world space

    • result: Vector3

      resulting velocity vector

    Returns boolean

    boolean true if result has been computed

  • Set new shape options and rebuild the collision shape accordingly. When the options provide an explicit shape, it is used directly; otherwise a capsule is created from the capsuleHeight / capsuleRadius values. The resulting shape is assigned through the shape setter, which releases the previously owned shape.

    Parameters

    • characterShapeOptions: CharacterShapeOptions

      character physics shape options

    • preserveFootPosition: boolean = true

      when true (default), the controller position is adapted so the world-space foot position (center - up * footOffset) is kept fixed as the height changes; when false, the position is left unchanged.

    Returns void