characterController system

Self-contained character controller + locomotion package. Install on any entity to give it a third-person camera, WASD ground movement, and skeletal animation driven by a Locomotion blend space — without hand-wiring the underlying components. The player's controls drive the character once it is bound as the local player's body (layers.active.players.localPlayer.avatar = entity(id)); any other character moves on what writes its CharacterController input bus.

Layout

systems/characterController/
  characterController.module/   -- public API (install / uninstall / preset)
    init.luau                   -- surface used by tools and custom code
    physics.module/             -- raycast helpers (ground / walls / ceiling)
    movement.module/            -- velocity integration + collision resolve
    data.module/                -- default config presets (standard, platformer, ...)

  presets/                      -- (Task 16) shipped controller + animation
                                --   presets (synty, default humanoid, ...)
  files/                        -- (Task 17) bundled assets pulled in by
                                --   the shipped presets (synty rig, anims)
  demo/                         -- (Task 20) showcase scene exercising the
                                --   install -> tweak -> preset loop

tools/characterController.toolbox/
                                -- user-facing tools (install, uninstall,
                                --   apply-preset). Lives here until runtime
                                --   VFS-driven toolbox discovery lands
                                --   (see #1220); the colocated
                                --   `.toolbox/` is the long-term home.

documentation/                  -- long-form reference
  01-overview.md                -- what the package is, when to use it
  02-install.md                 -- characterController.install(id, opts)
                                --   recipe and the components it touches
  03-presets.md                 -- shipped presets and how to author your own
  04-customize.md               -- overriding components, swapping the
                                --   camera, custom blend spaces

Flow

                  ┌────────────────────┐
   user / agent ──┤ characterController│
                  │  .toolbox          │
                  └────────────────────┘
                                          │
                                          ▼
                                ┌──────────────────────┐
              custom code ──────┤ characterController  │── install /
              (require)         │  .module (API)       │   uninstall / preset
                                └──────────────────────┘
                                          │
                                          ▼
                              ┌────────────────────────┐
                              │ CharacterController    │
                              │ + Locomotion           │
                              │ + MovementState        │
                              │ + AnimDebug            │
                              │ (+ third-person cam)   │
                              └────────────────────────┘
                                          │
                                          ▼
                         WASD-driven character with animation
                         on any entity, no hand wiring required.

characterController.install(entity, opts) is the only thing most callers need — it adds the controller, the locomotion graph, the movement-state mirror, and (optionally) a third-person camera child. The package is self-contained: it depends only on standard utility modules and on the animation graph engine, never on game-specific code.

Documentation

• documentation/01-overview.md — what this package is and when to reach for it.
• documentation/02-install.md — the characterController.install(id, opts) recipe.
• documentation/03-presets.md — shipped presets (synty, default humanoid) and authoring your own.
• documentation/04-customize.md — overriding components, swapping the camera, custom blend spaces.