# Maya Character Controller Guide

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.
