Log inGet started
Package

Locomotion.component

Newest version

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 landTime seconds.

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