Skip to main content

Locomotion

Idle, walk and run for a rig, blended from its real speed through the NPCAnimator, plus one-shots by name. On the server attach it to an agent after Build(); on the client attach it to a puppet Replica. It goes when its owner does. 

VluxyAI.Locomotion.Attach(agent)
-- in a state:
VluxyAI.Locomotion.Play(agent, "Attack")

-- client, a puppet replica:
VluxyAI.Locomotion.AttachReplica(replica, {
	Animations = { Idle = idle, Walk = walk, Run = run },
	WalkSpeed = 10,
	RunSpeed = 22,
})

Types​

LocomotionOptions​

</>
interface LocomotionOptions {
Animations: {[string]: AnimationInfo}?--

Tracks to load. Must include weighted Idle and Walk; a weighted Run is blended in above WalkSpeed. Default: Roblox's R15 idle, walk, and a one-shot Attack swing.

WalkSpeed: number?--

Studs per second the walk cycle is authored for. Default 16.

RunSpeed: number?--

Studs per second the run cycle is authored for; between WalkSpeed and this the walk crossfades into the run. Only used with a Run. Default 24.

MovingThreshold: number?--

Studs per second below which the rig idles. Default 0.5.

Fade: number?--

Seconds to blend between tracks. Default 0.15.

SpeedSmoothing: number?--

Seconds over which the measured speed settles; 0 uses each frame's raw speed. Default 0.1.

}

Functions​

Blend​

</>
Locomotion.Blend(
speed: number,--

Studs per second along the floor.

options: LocomotionOptions,--

WalkSpeed, RunSpeed and MovingThreshold are read; missing ones take their defaults.

hasRun: boolean--

Whether there is a run track to blend into.

) → LocomotionBlend

Types

​

interface LocomotionBlend {
Idle: number--

Weight of the idle track, 0 to 1.

Walk: number--

Weight of the walk track.

Run: number--

Weight of the run track; 0 without a run.

WalkPlayback: number--

Playback speed of the walk track.

RunPlayback: number--

Playback speed of the run track.

}

The weights and playback speeds for a speed. At or below MovingThreshold it idles; up to WalkSpeed it walks; with a run, the walk crossfades into the run between WalkSpeed and RunSpeed, and above that it runs. Each track plays at speed over the speed it is authored for. Pure.

Attach​

</>
Locomotion.Attach(
agent: Agent,
) → NPCAnimator--

Also kept at agent.Data.Locomotion.

Errors

TypeDescription
stringThe rig has no Animator, or the animations lack a weighted `Idle` or `Walk`.

AttachReplica​

</>
Locomotion.AttachReplica(
replica: Replica,--

Its Entity must be a Model with an Animator inside.

) → NPCAnimator--

Also kept at replica.Data.Locomotion.

Locomotion for a client rig a Replica moves: the blend follows the rig's own smoothed pivot motion, so it needs neither an agent nor physics (a puppet is usually anchored). Freeze, Play and Get take the replica as they take an agent. Undone when the replica is destroyed.

Errors

TypeDescription
stringThe entity is not a Model, has no Animator, or the animations lack a weighted `Idle` or `Walk`.

Freeze​

</>
Locomotion.Freeze(
agent: Agent | Replica,
isFrozen: boolean
) → boolean--

false when nothing is attached.

Holds every animation on the rig in its current pose (true), or lets them run again (false): the statue that stops mid-step the moment it is looked at. While frozen the blend is left alone, so the pose does not drift. Calling it with the state it is already in does nothing, so a sense may call it every tick.

Play​

</>
Locomotion.Play(
agent: Agent | Replica,
name: string--

A one-shot loaded by Attach or AttachReplica.

) → boolean--

false when nothing is attached or the name is unknown.

Plays a one-shot if locomotion is attached, so a state works with or without it. An unknown name is warned about once per owner and returns false; a weighted name is an error, as it is on the animator.

Get​

</>
Locomotion.Get(agent: Agent | Replica) → NPCAnimator?--

What Attach or AttachReplica made, if it was called.

Show raw api
{
    "functions": [
        {
            "name": "Blend",
            "desc": "The weights and playback speeds for a speed. At or below `MovingThreshold` it idles; up to\n`WalkSpeed` it walks; with a run, the walk crossfades into the run between `WalkSpeed` and\n`RunSpeed`, and above that it runs. Each track plays at `speed` over the speed it is authored\nfor. Pure.",
            "params": [
                {
                    "name": "speed",
                    "desc": "Studs per second along the floor.",
                    "lua_type": "number"
                },
                {
                    "name": "options",
                    "desc": "`WalkSpeed`, `RunSpeed` and `MovingThreshold` are read; missing ones take their defaults.",
                    "lua_type": "LocomotionOptions"
                },
                {
                    "name": "hasRun",
                    "desc": "Whether there is a run track to blend into.",
                    "lua_type": "boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "LocomotionBlend"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 132,
                "path": "lib/Animator/Locomotion.luau"
            }
        },
        {
            "name": "Attach",
            "desc": "",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "LocomotionOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "Also kept at `agent.Data.Locomotion`.",
                    "lua_type": "NPCAnimator"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "string",
                    "desc": "The rig has no Animator, or the animations lack a weighted `Idle` or `Walk`."
                }
            ],
            "source": {
                "line": 246,
                "path": "lib/Animator/Locomotion.luau"
            }
        },
        {
            "name": "AttachReplica",
            "desc": "Locomotion for a client rig a [Replica] moves: the blend follows the rig's own smoothed pivot\nmotion, so it needs neither an agent nor physics (a puppet is usually anchored). `Freeze`,\n`Play` and `Get` take the replica as they take an agent. Undone when the replica is destroyed.",
            "params": [
                {
                    "name": "replica",
                    "desc": "Its `Entity` must be a Model with an `Animator` inside.",
                    "lua_type": "Replica"
                },
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "LocomotionOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "Also kept at `replica.Data.Locomotion`.",
                    "lua_type": "NPCAnimator"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "string",
                    "desc": "The entity is not a Model, has no Animator, or the animations lack a weighted `Idle` or `Walk`."
                }
            ],
            "source": {
                "line": 290,
                "path": "lib/Animator/Locomotion.luau"
            }
        },
        {
            "name": "Freeze",
            "desc": "Holds every animation on the rig in its current pose (`true`), or lets them run again\n(`false`): the statue that stops mid-step the moment it is looked at. While frozen the blend is\nleft alone, so the pose does not drift. Calling it with the state it is already in does\nnothing, so a sense may call it every tick.",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent | Replica"
                },
                {
                    "name": "isFrozen",
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "returns": [
                {
                    "desc": "`false` when nothing is attached.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 329,
                "path": "lib/Animator/Locomotion.luau"
            }
        },
        {
            "name": "Play",
            "desc": "Plays a one-shot if locomotion is attached, so a state works with or without it. An unknown\nname is warned about once per owner and returns `false`; a weighted name is an error, as it\nis on the animator.",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent | Replica"
                },
                {
                    "name": "name",
                    "desc": "A one-shot loaded by `Attach` or `AttachReplica`.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "`false` when nothing is attached or the name is unknown.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 361,
                "path": "lib/Animator/Locomotion.luau"
            }
        },
        {
            "name": "Get",
            "desc": "",
            "params": [
                {
                    "name": "agent",
                    "desc": "",
                    "lua_type": "Agent | Replica"
                }
            ],
            "returns": [
                {
                    "desc": "What `Attach` or `AttachReplica` made, if it was called.",
                    "lua_type": "NPCAnimator?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 387,
                "path": "lib/Animator/Locomotion.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "LocomotionOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Animations",
                    "lua_type": "{ [string]: AnimationInfo }?",
                    "desc": "Tracks to load. Must include weighted `Idle` and `Walk`; a weighted `Run` is blended in above `WalkSpeed`. Default: Roblox's R15 idle, walk, and a one-shot `Attack` swing."
                },
                {
                    "name": "WalkSpeed",
                    "lua_type": "number?",
                    "desc": "Studs per second the walk cycle is authored for. Default `16`."
                },
                {
                    "name": "RunSpeed",
                    "lua_type": "number?",
                    "desc": "Studs per second the run cycle is authored for; between `WalkSpeed` and this the walk crossfades into the run. Only used with a `Run`. Default `24`."
                },
                {
                    "name": "MovingThreshold",
                    "lua_type": "number?",
                    "desc": "Studs per second below which the rig idles. Default `0.5`."
                },
                {
                    "name": "Fade",
                    "lua_type": "number?",
                    "desc": "Seconds to blend between tracks. Default `0.15`."
                },
                {
                    "name": "SpeedSmoothing",
                    "lua_type": "number?",
                    "desc": "Seconds over which the measured speed settles; `0` uses each frame's raw speed. Default `0.1`."
                }
            ],
            "source": {
                "line": 57,
                "path": "lib/Animator/Locomotion.luau"
            }
        },
        {
            "name": "LocomotionBlend",
            "desc": "",
            "fields": [
                {
                    "name": "Idle",
                    "lua_type": "number",
                    "desc": "Weight of the idle track, `0` to `1`."
                },
                {
                    "name": "Walk",
                    "lua_type": "number",
                    "desc": "Weight of the walk track."
                },
                {
                    "name": "Run",
                    "lua_type": "number",
                    "desc": "Weight of the run track; `0` without a run."
                },
                {
                    "name": "WalkPlayback",
                    "lua_type": "number",
                    "desc": "Playback speed of the walk track."
                },
                {
                    "name": "RunPlayback",
                    "lua_type": "number",
                    "desc": "Playback speed of the run track."
                }
            ],
            "source": {
                "line": 84,
                "path": "lib/Animator/Locomotion.luau"
            }
        }
    ],
    "name": "Locomotion",
    "desc": "Idle, walk and run for a rig, blended from its real speed through the [NPCAnimator], plus\none-shots by name. On the server attach it to an agent after `Build()`; on the client attach\nit to a puppet [Replica]. It goes when its owner does.\n\n```lua\nVluxyAI.Locomotion.Attach(agent)\n-- in a state:\nVluxyAI.Locomotion.Play(agent, \"Attack\")\n\n-- client, a puppet replica:\nVluxyAI.Locomotion.AttachReplica(replica, {\n\tAnimations = { Idle = idle, Walk = walk, Run = run },\n\tWalkSpeed = 10,\n\tRunSpeed = 22,\n})\n```",
    "source": {
        "line": 119,
        "path": "lib/Animator/Locomotion.luau"
    }
}