Eve library

Maya Character Controller Guide

Guide

Revision 1

On this page

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:

ts
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:

  • createPlatformerCharacterController
  • createRealisticFpsCharacterController
  • createArcadeCharacterController
  • createVrCharacterController

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.