Locomotion.component
This package holds more than this page lists. See all of its files in its world.
README.md
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. The strafe angle is the signed angle from the body's facing to
its velocity, positive toward the body's right (forward x up): the R
clips sit at +90, the L clips at -90 and the B clips at 180. 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.
Once every clip has bound, the component hands the graph to the engine
(AnimGraph:runNatively): the engine measures the root's velocity from its
position, turns the body toward it, damps the speed and angle and evaluates
the blend space every frame, and the component's update is held. A body
the sync moves (another peer's avatar), an NPC and the local player's own
body all walk with no script running for their pose. The component takes
the graph back when one of its fields changes or another component changes
the graph (a layer spliced over it), and runs it in script while the graph
holds a node the engine does not run, a clip that drives blend shapes, or
the body has no MovementState. component.get("Locomotion"):stats()
reads { native, handle?, frames?, refusal? }: where the graph runs, and
why not in the engine when it does not.
Jumping, falling and landing
jumpAnim, fallAnim and landAnim are the air poses: the take-off and
rise, the fall, and the landing. With any of them set (the synty preset sets
all three, and the built-in humanoid avatar uses it) the blend space and those
clips sit under one Mixer, and the body moves between four states by the
motion of its root:
- ground: the locomotion blend plays.
- rise: the body is off the ground and moving up faster than 1 m/s. The take-off clip plays from its start.
- fall: the body is off the ground and moving down faster than 1 m/s (a walk off a ledge), or its rise has stopped. The fall clip loops.
- land: the ground is under the body again. The landing clip plays from its
start and fades into the locomotion blend over
landTimeseconds.
The body is off the ground while nothing stands within 5 cm below its feet
across its footprint. The footprint is the disc its CharacterController
stands on, its radius less its skinWidth (0.25 m without one), and the
5 cm are counted from the ground the feet stand a skinWidth above, so a body
standing on the edge of a ledge, or with a wide skin, reads the ground its
controller stands on. A sphere of the footprint's radius is swept down past
the colliders the character carries, far enough to reach an edge at the rim
of the footprint, and the surface it meets counts where the sphere touched it.
A change of the controller's radius or skinWidth reaches the sweep on the
next frame (the controller calls footingChanged()). A body on nothing that
moves neither up nor down (a preview, a mannequin) keeps the locomotion blend.
Each pose's weight moves toward its state's at
1 / airBlendTime a second. A slot left nil, or whose clip failed to bind, is
stood in for: the take-off by the fall, the fall by the take-off, and the
landing by the locomotion blend. A clip that failed to bind keeps the graph in
script, and stats().refusal names the clip.
The engine runs the air states with the rest of the graph, so the local player, an NPC and another player's body the sync moves all jump, fall and land the same way with no script running for their pose.
local loco = entity(id).component.get("Locomotion")
loco.jumpAnim = asset.resolve("A_Jump_Running_Masc", "animation")
loco.landTime = 0.2