The Maya character controller is a kinematic capsule controller layered on top
of PhysicsWorld. It owns gameplay movement decisions while using existing
physics bodies, colliders, and AABBs for world queries.
Setup#
Create a controller with createMayaCharacterController(world, config). By
default it creates a kinematic capsule body with the player collision group. You
can also pass an existing body ID to
new MayaCharacterController(world, config, bodyId) when the runtime has
already spawned a body.
World bodies can include userData.mayaCharacter metadata:
world.createBody({
type: BodyType.Static,
position: vec3(0, -0.5, 0),
userData: {
mayaCharacter: {
groundNormal: vec3(0, 1, 0),
movingPlatformVelocity: vec3(1, 0, 0),
climbable: false,
},
},
colliders: [{ shape: ColliderShape.Box, halfExtents: vec3(10, 0.5, 10) }],
});
Movement Loop#
Call controller.update(input) once per gameplay tick. The input includes a
movement vector, optional look direction, jump/crouch/prone/climb flags, delta
time, and an optional prediction sequence number.
The returned frame contains position, velocity, movement mode, stance, ground probe, step probe, ledge probe, platform state, and contacts.
Supported Gameplay Features#
- Swept capsule movement and AABB depenetration against blocking colliders.
- Ground checks with slope angle calculation and walkable/steep classification.
- Slope sliding for surfaces steeper than
maxWalkableSlopeDeg. - Step climbing for obstacles under
maxStepHeight. - Ledge detection with optional movement prevention.
- Moving-platform velocity inheritance through
movingPlatformVelocity. - Swimming/floating through water volumes or water body metadata.
- Ladder/climbable surfaces through explicit climbable volumes or body metadata.
- Standing, crouching, and prone stances with stand-up clearance checks.
- Character-character overlap pushing through
resolveCharacterCollisions. - Normal, low, zero, and variable gravity modes.
- Client prediction records and server reconciliation.
- Debug state for capsule, ground, step, ledge, contacts, platform, and history.
Presets#
Use preset factories for common tuning profiles:
createPlatformerCharacterControllercreateRealisticFpsCharacterControllercreateArcadeCharacterControllercreateVrCharacterController
Presets only override config values, so projects can still pass final overrides for radius, height, speed, slope limits, step height, or gravity.
Debugging#
Use getDebugState() to draw the capsule, ground normal, step target, ledge
probe point, collision normals, and prediction history. In editor builds, show
the current mode/stance and probe results near the character inspector.