characterController

# AnimDebug Demo component for inspecting character-controller animation state during the character controller demo.

# CharacterController Kinematic mover. Integrates velocity against gravity, walls, ceilings and ground, and writes the result to the entity's position every frame. ## Driving it The character moves on a public input bus: `inputX`, `inputZ` and `inputJump`. Each frame the controller reads the bus, moves on what it found, and then refills it for the next frame. **Only the local player's body answers the player's controls.** The character the local player is bound to (`layers.active.players.localPlayer.avatar`) refills its bus from the `move` axis and the `sprint` / `jump` actions of its input map, so the map drives it whenever nothing else does. Every other character holds no map and refills its bus with no movement: an NPC, a mannequin, a preview or another player's body stands where it is until something writes its bus. The player's spawn binds the body for you; to hand the controls to a character you made, bind it: ```luau layers.active.players.localPlayer.avatar = entity(bodyId) ``` The character takes the map up on the frame after the bind and gives it back when the binding moves to another body. Anything else takes the character over by writing those three fields from its own `update()` — an AI brain, a networked peer, a replay, or gameplay code that wants the character committed during an attack. The write works from **any** `executionOrder`, because the refill happens after the read: whatever is in the bus when the controller next reads it is what the character does. - A writer ahead of the controller (`executionOrder` below `-100`) is acted on the same frame. - A writer behind it is acted on the next frame. - Stop writing, and the character stops one frame later; on the local player's body the map has it back instead. - Pausing gameplay empties the bus, so a character frozen mid-stride stands where it was paused and a writer that had it committed says so again. `inputX` / `inputZ` are a world-space velocity in units per second — the controller applies them as they are, so scale them yourself rather than expecting `moveSpeed` to. `inputJump` asks for one jump and the next update consumes it. A component that walks the character due north, whatever the input map says: ```lua -- Northbound.component/init.luau declare { executionOrder = 50 } -- anywhere works; 50 runs after the controller public = { speed = Field.number(4.0, Sync), } function update(_dt: number) local cc = public.entity.component.get("CharacterController") if cc == nil then return end cc.inputX = 0 cc.inputZ = -public.speed end ``` `WASDInput` is the same pattern shipped as a component: it reads an input map of its own and writes the bus of whatever component `targetComponent` names, which is how a mover that reads no controls of its own gets driven. On a CharacterController — which reads `move`, `sprint` and `jump` from its own `inputMap` — a WASDInput writes the bus every frame at its own `speed`, and that is the speed the character walks at. `CharacterController.install` adds one when `input = true` asks for it. ## The control scheme `inputMap` is the scheme the character answers to. It reads three controls from it, each on its own: - `move` — an axis2, projected against the active viewport camera so "forward" is into the screen. - `sprint` — held, multiplies `moveSpeed` by `sprintMultiplier`. - `jump` — pressed, asks for one jump. A map declaring only some of the three drives the character with those: a scheme with no `sprint` holds one gait, a scheme with no `jump` stays on the ground. The character logs which controls the map left out and names the map, so a game with three verbs ships a three-control scheme. A field naming no map leaves the character answering nothing, and logs that too. **Repointing it on a live character takes on the next frame.** The map the character was holding is stood down — its controls leave the live set and its touch buttons leave the screen — and the map named here is taken up in its place: ```luau entity(bodyId).component.get("CharacterController").inputMap = asset.resolve("mygame.input.run", "inputMap") ``` Assigning the map the character already holds changes nothing, so re-stating the scheme leaves the live set where it is. While gameplay is paused the character holds no map at all (the editor's camera has the controls), and it takes whatever `inputMap` names when play resumes. A character that is not the local player's body holds no map either, and takes whatever `inputMap` names when it is bound as that body. ## Telemetry These read back what the mover did on the frame just simulated: - `grounded` — standing on ground no steeper than `maxSlopeAngle`. - `falling` — in the air and descending. - `sliding` — on ground too steep to stand on, being carried down it. - `blocked` — the character asked to move horizontally and the wall pass left it with none of that movement: pressed into a wall, or wedged where two surfaces meet. This is what tells a character standing still apart from one whose walk is being refused. - `slopeAngle` — the angle, in degrees, of the ground under it. - `velocityX` / `velocityY` / `velocityZ` / `horizontalSpeed` — its velocity. - `jumpCount` — jumps used since it last landed.

# Locomotion Blend-space-driven locomotion for entities running the characterController package. Reads horizontal velocity from a sibling `MovementState` (or, as a fallback, `CharacterController`) component on the parent and feeds a single 2D blend space (strafe-angle on X, speed on Y) with idle / walk-{F,L,R,B} / run-{F,L,R,B} / sprintF clips. Each clip's point sits at the speed the clip carries this body at: its retarget bake measures how fast the ground passes under the stance foot on this body's legs, so the feet move with the ground at whatever speed the body moves. A clip that plays without a measured speed sits at its gait's `walkSpeed` / `runSpeed` / `sprintSpeed`. Pair on the same entity (or a parent of) a `SkinnedModel`. The component creates the AnimGraph, polls for the SkinnedModel child once start() has run, registers the clips as blend-space points and plays the graph. `update()` damps speed + angle and writes them to the active blend space each frame. This supersedes the older FSM-based Locomotion controllers (crouch / jump / fall / land / turn-in-place state machine). Those behaviours can be added back as separate layered graphs once the blend-space driver has settled.

# MovementState Component that exposes movement state for controller-driven animation and gameplay consumers.

# characterController Physics-based character controller — capsule movement with ground / wall / ceiling detection. A kinematic controller using raycasts for collision; handles gravity, jumping, slope traversal, step climbing, wall sliding, coyote time, and moving platforms. The module owns a per-entity registry; attach once, call `move` / `jump` each frame, then drive a per-frame `update(dt)`. The `install` / `uninstall` / `preset` surface wires up the standard set of components (CharacterController + Locomotion + MovementState + optional WASDInput and third-person camera child) in one call. Require it to use the surface: ```luau local CharacterController = require("@builtin::systems.characterController.characterController") ``` ## Exports - `CC.attach(entityId: string, userConfig: Config?)` — register an entity, merge user overrides over `Defaults.standard`. - `CC.detach(entityId: string)` — drop the registry entry. - `CC.move(entityId: string, direction: Vec3)` — set per-frame world-space movement input (`y` is ignored). - `CC.jump(entityId: string)` — request a jump; honours coyote time and jump buffer. - `CC.getState(entityId: string) -> State` — snapshot copy of grounded / falling / velocity / etc. - `CC.getVelocity(entityId: string) -> (number, number, number)` — current `vx, vy, vz`. - `CC.setGravity(entityId: string, gravity: number)` — update gravity at runtime. - `CC.setMaxSlope(entityId: string, degrees: number)` — update max walkable slope angle. - `CC.setConfig(entityId: string, key: string, value: any)` — update a single config key. - `CC.getConfig(entityId: string) -> Config` — config copy. - `CC.update(entityId: string, dt: number)` — advance one frame (resolve movement, write position, tick state machine). `dt` is clamped to 0.1. - `CC.isAttached(entityId: string) -> boolean` — whether the entity has a registration. - `CC.install(entityId: string, opts: InstallOpts?) -> InstallResult` — high-level wire-up (components + optional camera / mesh / WASDInput). - `CC.uninstall(entityId: string) -> UninstallResult` — remove everything `install` added. - `CC.preset(entityId: string, presetName: string) -> PresetResult` — apply a preset to an already-installed character in place. Types: - `Vec3 = { x: number, y: number, z: number }` - `Config = { height?, radius?, maxSlopeAngle?, stepHeight?, gravity?, jumpForce?, coyoteTime?, jumpBuffer?, maxJumps?, airControlFactor?, groundSnapDistance?, skinWidth?, moveSpeed? }` - `State = { grounded, falling, sliding, wallContact, wallNormal, velocity, groundNormal, slopeAngle, jumpCount, timeSinceGrounded, timeSinceWallContact, onMovingPlatform, platformEntity? }` - `BundleRef = { guid?, __ref?, identity?, path?, name? }` - `InstallOpts = { preset?, camera?, input?, mesh?, overrides? }` - `InstallResult = { entityId, cameraId?, meshHostId? }` - `UninstallResult = { entityId, despawned }` - `PresetResult = { entityId, preset, applied }` ## Usage ```luau local CharacterController = require("@builtin::systems.characterController.characterController") -- Low-level: manual attach + per-frame drive. CharacterController.attach(entityId, { gravity = -15, jumpForce = 7 }) CharacterController.move(entityId, { x = 1, y = 0, z = 0 }) CharacterController.update(entityId, dt) -- High-level: one-call wire-up. CharacterController.install(entityId, { preset = "humanoid_default", camera = true, overrides = { jumpForce = 8 }, }) ``` ## Notes - `attach` merges user config over `Defaults.standard`; passing unknown keys is allowed (they survive into the config table). - `update` clamps `dt` to 0.1s to prevent capsule tunnelling on lag spikes. - `getState` and `getConfig` return shallow copies — mutating the result does not affect the controller. The returned `velocity` / `wallNormal` / `groundNormal` are also shallow copies. - `install` is idempotent per component — re-running on an already wired entity adds nothing new. `uninstall` removes the components and any third-person-camera child that targets this entity. - `preset` mutates fields in place and never adds or removes components — call `install` first.