AnimGraph.module
- .metadata17 B
- Node.module
- README.md4.1 KB
- init.luau53.0 KB
- rigResolve.module
This package holds more than this page lists. See all of its files in its world.
README.md
AnimGraph
DAG of animation nodes implemented in pure Luau. Nodes are stored in
a slot vector; freed slots are reused on the next addNode (mirrors
the legacy Rust crate's Vec<Option<AnimNode>> pattern). An AnimGraph
has exactly one designated "output" node. Each frame the engine calls
graph:update(dt) followed by graph:evaluate(), which recursively
walks reachable nodes and returns the pose buffer for the output node.
The module re-exports the Node hierarchy on the returned table so
callers can reach AnimGraph.Clip.new(...), AnimGraph.Mixer.new(...),
etc. without separate requires.
Exports
-
AnimGraph.new(opts: { layout: Layout? }?) -> AnimGraph— construct a new graph;layoutdefaults to a sensible default. -
AnimGraph:addNode(node: Node) -> number— insert a node, return its slot id (reuses freed slots). -
AnimGraph:removeNode(id: number)— free the node at slotidand call:destroy()on it. -
AnimGraph:setOutput(id: number)— designate which node is the graph's final output. -
AnimGraph:update(dt: number)— advance every reachable node. -
AnimGraph:evaluate() -> TypedBuffer?— return the output node's pose buffer (caller MUST NOT destroy). -
AnimGraph:crossfade(from: number, to: number, duration: number)— sugar that wires a temporary Mixer between two nodes, ramps weights overduration, then collapses to the new output when the ramp completes. -
AnimGraph.Clip,AnimGraph.Mixer,AnimGraph.BlendSpace2D,AnimGraph.Layer,AnimGraph.Additive,AnimGraph.Node— re-exports of the node constructors.Additive.new(layout, base)turns and moves named bones on top ofbase(or of the layout's rest pose)::setRotation(bone, q),:setPosition(bone, p),:clear(); it is how an avatar's animator bends bones over the locomotion playing beneath it. -
AnimGraph.layoutForEntity(body, opts?)— the layout for a body: its bones, rig and rest pose, and the blend shapes of the meshes around it (opts.shapeRootnames where to look,opts.shapeAliasesadds names per shape). A mesh with shapes and no skin gets a layout of its shapes alone. -
AnimGraph.shapesUnder(rootId, aliases?)— theshapeOrder/shapeSlots/shapeTargetsof every mesh at or underrootId. -
AnimGraph.shapeIndex(layout, name)/AnimGraph.shapeMask(layout, spec)/AnimGraph.poseLength(layout)— find a shape by name or alias, build a Layer's shape mask ("face", a shape name, an array or a map), and size a pose buffer. -
AnimGraph:applyShapes(pose)— write the shapes a pose covers into the body's meshes;:tickcalls it.
A pose buffer carries, after its bone records, one weight per shape of the layout's shapeOrder and then one coverage per shape: 1 where a clip's weight track drives the shape, 0 where it holds its rest weight. Mixers lerp both, a Layer takes the overlay's shapes by its shape mask (Layer.new(layout, base, overlay, mask, shapeMask)), Additive:setShape(name, weight) holds a shape over the base, and :tick writes every covered shape to the meshes' MorphWeights.
Types:
Layout = { ... }— pose layout used by the graph and its nodes.
Usage
local AnimGraph = require("@builtin::systems.anim.AnimGraph")
local graph = AnimGraph.new({ layout = myLayout })
local idle = graph:addNode(AnimGraph.Clip.new("idle"))
local walk = graph:addNode(AnimGraph.Clip.new("walk"))
graph:setOutput(idle)
graph:crossfade(idle, walk, 0.25) -- blend to walk over 250ms
-- Each frame:
graph:update(dt)
local pose = graph:evaluate()
Notes
- The output node MUST be set before
evaluateis called; otherwise the return value isnil. crossfadecollapses the temporary mixer when the ramp completes, so long-running graphs don't accumulate orphan mixers.- Buffer ownership: nodes own their internal buffers and free them in
:destroy(). Callers ofevaluateborrow the returned buffer — do NOT destroy it. removeNodefrees the slot id and calls:destroy()on the node; the nextaddNodemay reuse the same id.