Log inGet started
Package

AnimGraph.module

Newest version

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; layout defaults 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 slot id and 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 over duration, 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 of base (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.shapeRoot names where to look, opts.shapeAliases adds names per shape). A mesh with shapes and no skin gets a layout of its shapes alone.

  • AnimGraph.shapesUnder(rootId, aliases?) — the shapeOrder / shapeSlots / shapeTargets of every mesh at or under rootId.

  • 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; :tick calls 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 evaluate is called; otherwise the return value is nil.
  • crossfade collapses 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 of evaluate borrow the returned buffer — do NOT destroy it.
  • removeNode frees the slot id and calls :destroy() on the node; the next addNode may reuse the same id.