Roblox Animation Graph Editor: Blends and State Machines

One clip is easy. Our animation guide covers it start to finish: key it, publish it, LoadAnimation it, set its priority. The trouble starts with the second, third and tenth clip. A character that blends idle into run by speed, waves with its upper body while it walks, and plays a landing before it moves again turns into a pile of Play, Stop, AdjustWeight and priority calls that are hard to follow for anyone but their author. Roblox's own launch post describes that state plainly: "getting animations to blend smoothly together required writing custom Luau code."

The Animation Graph Editor moves that logic out of scripts and into an asset. It left beta on July 15, 2026, the day graphs started running in live games. On October 8, Roblox added State Machine nodes and Luau-style Expressions as a Studio beta, three weeks after its Fall roadmap had dated them "Mid 2027."

This guide covers how a graph loads, what each of the 15 node types does, the three AnimationTrack methods that connect your scripts to it, what the new beta features can and cannot do yet, and which machine runs the graph under each authority mode.

A graph is an animation, as far as your code knows

The July release post makes the key design point: "Both clips and graphs share the same animation asset definition. You can swap a clip and a graph in your code, and they will function identically in the engine." The engine's API dump agrees. It lists AnimationGraphDefinition as a subclass of AnimationClip.

So the pipeline is the one you already use. When you create a graph, the editor makes an AnimationGraphDefinition that holds your nodes, connections and parameters. You publish it, get an asset ID, and load it through an Animator. One code snippet in the July post loads it with Humanoid:LoadAnimation(), which is deprecated. The documentation's own sample uses the Animator, and so should you.

Three methods on the returned AnimationTrack do the rest:

A player-character setup, for a game on the default authority mode (more on that below):

-- LocalScript in StarterCharacterScripts (Workspace.AuthorityMode = Automatic)
local RunService = game:GetService("RunService")

local character = script.Parent
local humanoid = character:WaitForChild("Humanoid")
local animator = humanoid:WaitForChild("Animator")

local graph = Instance.new("Animation")
graph.AnimationId = "rbxassetid://0" -- your published graph's asset ID

local track = animator:LoadAnimation(graph)
track:Play()

-- Print what the graph expects you to drive
for name, default in track:GetParameterDefaults() do
	print(name, default)
end

local connection = RunService.Heartbeat:Connect(function()
	track:SetParameter("Speed", humanoid.MoveDirection.Magnitude * humanoid.WalkSpeed)
end)

humanoid.Died:Connect(function()
	connection:Disconnect()
end)

Roblox's samples drive parameters from Stepped in the documentation and from Heartbeat in the October announcement, and neither page says one is required. Our Heartbeat vs RenderStepped guide covers what each loop costs. Rigs without a Humanoid are covered too: the July post's feature list includes support for AnimationController targets, and asked about it in the July thread, a Roblox staff member said AnimationControllers "should be capable of playing AnimationGraph via the LoadAnimation API on Animators."

Build the walk-and-wave starter graph

The documentation's starter graph layers a wave on top of a walk with four nodes: two Clips, an Add and the Graph Output. Condensed:

1. Add a rig: Avatar tab ⟩ Character ⟩ My Avatar.
2. Open Graph Editor from the same Avatar tab, select the rig, then Graph ⟩ New.
3. Right-click the canvas ⟩ Insert Node ⟩ Clip. In its Animation ID dropdown, click Import and enter 507777826, Roblox's default walk.
4. Add a second Clip node with 507770239, the default wave.
5. Right-click ⟩ Add. Wire the walk clip to the Base port and the wave clip to Additive.
6. Wire the Add node's output to the Pose port on Graph Output, then press the editor's play button.

Roblox publishes two places worth copying from: the Animation Graph Editor Simple Demo, linked from the main documentation page, and a state machine demo holding the full JumpFallLandRunExample graph. On October 8 a developer reported they had no animation permission for the state machine demo, and a Roblox staff member replied the same day that the permissions had been updated.

The node set, all 15 types

Enum.AnimationNodeType lists 15 node types plus InvalidNode, the unassigned default. Here is what each one does, from the enum reference's node-by-node entries and, for State Machine, its own documentation page:

Nodes are nestable: a Blend1D can feed an Over node, which can be one state of a state machine, which feeds Graph Output.

Parameters: how gameplay reaches the graph

Parameters are the graph's variables. The July post lists Number, String, Boolean and Enum types, and the One Shot node's documentation adds a Trigger parameter, which "automatically resets to false one frame after being set to true."

Any property with a green pin can be driven by one. Drag from the pin to empty canvas and the editor creates a parameter node wired to it. The Parameters pane in the top left edits values during preview, and your script edits them at runtime with SetParameter.

Two uses that are easy to miss:

• Swapping a clip at runtime. In July, a developer asked how to put a player's equipped UGC idle animation into a Blend1D slot. Roblox shipped runtime ID switching in August, and when the same developer asked for the API on August 19, the staff answer was: "You can wire AnimationId on a clip node to a parameter and set it via SetParameter like other node properties." That takes a String parameter, and Clip's AnimationId takes the usual rbxassetid:// form.
• Gameplay state the graph can't see. Expressions, covered below, read only graph parameters. Roblox's FAQ is direct about anything else: "Use SetParameter() to pass anything else in."

-- "IdleAnim" is a String parameter wired to the idle Clip node's AnimationId pin
track:SetParameter("IdleAnim", "rbxassetid://0") -- the player's chosen idle

One known issue from the October 8 post: adding a parameter "will always add a green parameter node to the graph even if you don't wire it to something." Roblox says a fix is coming. Until then, delete the stray nodes.

Transitions: two curves, two timings

Select, Priority Select, Sequence and Random Sequence share one set of transition settings. These control the blend when the active input changes:

Two details shape how a graph feels.

Only two curves work. The documentation says transitions "currently only" support Linear and CubicV2. That is narrower than the five keyframe easing styles in the Animation Editor that our animation guide lists, so don't expect Elastic or Bounce on a graph transition. If you see the older Cubic value, skip it: the PoseEasingStyle reference deprecates it because it "has a bug where the direction is reversed between the editor and runtime."

BeforeFinished overlaps the ending. With BeforeFinished, the blend starts one transition duration early, so a 0.2-second transition begins in the final 0.2 seconds of the outgoing clip. There is one exception to the override rule: a BeforeFinished transition uses the outgoing input's overrides. As of October 8, Sequence and Random Sequence support BeforeFinished too.

Blend1D and Blend2D: phase sync and whose footsteps fire

A Blend1D node "linearly interpolates between the two animation poses closest to the current input position." Put idle at 0, walk at 8 and run at 16, feed it speed, and it crossfades for you. Past either end of the range, it "extrapolates using the two nearest inputs." Since July that is deliberate behaviour, not a bug, so a speed boost beyond your run position will push the run past its authored pose. If you don't want that, clamp the value before it reaches the node.

PhaseSync is what makes the blend look right. With the default, Synced, the node computes a "virtual duration" from the weighted average of its active inputs and adjusts each input's time step so "animations of different lengths" stay "in lockstep." That is what keeps a short run cycle and a longer walk cycle in step while the node blends between them. Unsynced lets each clip run at its own rate.

Blend2D adds a second axis. In Cartesian mode, X and Y are grid coordinates, which suits strafing with forward/back on one axis and left/right on the other. In Polar mode, X is a direction in radians and Y is a magnitude. The docs note that direction "is weighted more heavily" there, so inputs at similar angles but different speeds blend more smoothly than inputs at different angles. As of October 8 it also accepts negative Y values.

The detail that saves a debugging session is events. Markers you place in clips bubble up the graph, and those that reach the top fire through AnimationTrack:GetMarkerReachedSignal(), the same call our animation guide recommends for impact frames. Blend nodes filter them: "Only events from the highest-weight active input propagate, scaled by its blend weight. Events from the secondary input are silenced." Put a Footstep marker in both the walk and the run clip, and a half-blend fires one set of footsteps, from whichever clip carries more weight, not two. Under the global rules, an event whose weight reaches zero anywhere on the way up is dropped.

Layering: Over, Add, Mask and One Shot

Upper-body actions over locomotion are the second classic use. Roblox's July post gives the canonical example: a Mask node "isolates joints to specific bones (for example, waving only the upper body)."

• Over puts the Over pose on top of Base. Combined with a Mask, "masked-out joints in the Over pose reveal the Base pose entirely." That is the arms-wave, legs-run setup.
• Mask holds a weight per joint, which allows partial "feathering" rather than an on/off split. Populate it from HumanoidRigDescription for standard humanoids or with the Picker for any rig. A mask can live by reference on another instance and be shared across nodes, and Invert reuses it as 1 - weight.
• Add and Subtract do pose arithmetic. Subtract computes A - Weight * B to turn an ordinary animation into an additive one, and Add layers that onto a base. Both weights are unclamped.

The One Shot node arrived after the July release; Roblox lists it among the fixes and additions in the October 8 post. It covers "the common 'fire an animation on an event' case (waves, punches, emotes, additive flourishes) in a single node." Before it, the same job meant composing an Over/Add/Subtract node with a Priority Select and resetting a trigger every frame.

Bind Trigger to a Trigger parameter, not a Boolean. The docs explain why: it resets itself, so a player spamming the key re-fires only on a fresh edge, and no script has to clear it:

-- "Wave" is a Trigger parameter wired to a One Shot node's Trigger pin
local UserInputService = game:GetService("UserInputService")

UserInputService.InputBegan:Connect(function(input, processed)
	if not processed and input.KeyCode == Enum.KeyCode.G then
		track:SetParameter("Wave", true) -- resets to false a frame later
	end
end)

For a game that ships on console and touch too, bind the action through the Input Action System instead of a raw key check.

State machines: the October 8 Studio beta

Read the two limits first, because they decide whether you can use any of this today:

• Enable it in Studio: File ⟩ Beta Features ⟩ Animation Graphs State Machines.
• Not in live games yet. The announcement's FAQ: "Can I use State Machines and Expressions in live games during the beta? No. They only work in Studio at the moment."

So this is a feature to prototype with, not to ship, until Roblox moves it to full release. The announcement calls it "an early beta" and says the design will be adjusted "based on what you report."

Why Priority Select was not enough

Roblox's announcement explains the gap with a sword combo. A character may go from Swing 1 to Swing 2, but not from Idle straight to Swing 2. Priority Select "checks all of its conditions every frame," so the condition meant to move Swing 1 to Swing 2 "could also fire while the character is still in Idle." Developers worked around that by tracking the state in Luau and feeding it into a Select node. A state machine keeps track of the current state itself, so a transition only fires from the states you wire it from.

The pieces:

• States. Each state is an input on the State Machine node and can be "a clip, a blend node, or another state machine." The input name has to match the state name.
• (Entry) marks the state the machine starts in.
• (Any) transitions "can fire from every other state," such as the announcement's example of going to Holster when IsEquipped == false, mid-combo.
• Transitions fire either on an expression (Wait For set to Expression, which is AnimationNodeWaitFor.Trigger underneath) or when the source state is Finished.

Roblox's pages disagree on one priority detail. The documentation says that when two true transitions share a priority, "it selects one transition at random." The announcement says "each priority value has to be unique within the state machine." Giving every competing transition its own value satisfies both.

Jump, fall, land in three transitions

The documentation's worked example uses three states from JumpFallLandRunExample: Locomotion (an idle/run Blend1D), Fall and LandIdle (both clips set to OnceAndHold), plus a Boolean Grounded parameter. Entry goes to Locomotion, then:

Besides Speed for the locomotion blend, your script's new job is to keep Grounded honest. A Humanoid's FloorMaterial reads Air when it isn't standing on anything, which gives you a one-liner inside the loop from the first sample:

track:SetParameter("Grounded", humanoid.FloorMaterial ~= Enum.Material.Air)

The FloorMaterial reference adds two caveats: the character has to be able to collide with the floor to detect it, and the property can't tell you whether the Humanoid is swimming.

Two limits from the announcement. A state machine does not replace Humanoid states: jumping or dying "still come from the Humanoid or your own scripts," and you pass them in as parameters. And in the editor, "you can't manually set a state or trigger a transition" yet, so you test by changing parameters during preview. Priority Select isn't going away; Roblox's answer to "Should I stop using Priority Select?" was "No." Use the state machine when a transition should only apply from certain states.

Expressions: Luau-shaped, parameters only

An expression is "a short Luau-like formula that reads graph parameters and returns a value." It can drive a node property, such as a Blend1D's Position, or a state machine transition condition. To add one, drag a wire from a property pin and choose the expression option.

The documentation's worked example converts speed into the 0-to-1 range of a Blend1D set up with idle at position 0 and run at position 1:

math.clamp(MovementSpeed / MaxSpeed, 0, 1)

Multi-line expressions can use local and return:

local normalizedSpeed = Speed / MaxSpeed
local eased = math.clamp(normalizedSpeed, 0, 1)
return eased

One quirk: math.modf() "currently returns only the integer portion." Per the announcement, each expression "is parsed once when the graph loads and is evaluated when a node uses it," and it is serialized with the graph asset rather than living in a script. If one fails to parse or evaluate during preview or a playtest, the error shows up in the Output window.

The payoff is fewer parameters and less glue code. One developer in the announcement thread reported that expressions let them cut 4 of 11 parameters from their graph and delete roughly 70 lines of animation code. One documentation wrinkle as of October 11: the state machine page's links to the Expressions page lead to a 404 on the Creator Hub. The page itself is live at create.roblox.com/docs/animation/graph-editor-expression, the address the October 8 announcement links to.

Who runs the graph: replication and Server Authority

The documentation states that "Animation graph parameters and internal node state replicate automatically," and which machine drives them depends on Workspace.AuthorityMode when the Animate script is created. You get that script from Graph ⟩ Create Animate script, which builds an Animate ModuleScript with a RunClient LocalScript, a RunServer Script, or both beneath it, depending on the case in the table below. It goes in StarterCharacterScripts for player characters, or on the rig for NPCs.

Three consequences:

• In Automatic mode you don't need a RemoteEvent for animation parameters. Several SetParameter calls in one frame are "coalesced (last-writer-wins)," and other clients see the change after "one send interval plus network latency." Damage and other consequences still belong on the server, as our RemoteEvents guide covers. Only the animation state syncs itself.
• Server mode replicates everything. That includes "elapsed time, current selections, transition progress, loop counts, and RNG seeds," so all clients see identical animation. The owning client's RunClient script switches on PredictionMode on the Animator, so the local player sees smooth animation that reconciles with the server if they disagree. Roblox's security docs still describe Server Authority as "currently in beta," the same status our collision summaries guide notes.
• Studio previews use the unpublished graph. The generated script carries a PreviewInStudio attribute. When true (the default), playtests load your local, unpublished graph, so you can iterate without publishing. It is "currently not supported" in Server mode.

One gap to check yourself. The StarterCharacterScripts reference says a LocalScript named Animate replaces the default animation script. The generator produces a ModuleScript named Animate, and the graph documentation doesn't say how the two interact. After generating, play-test and look under your character in the Explorer before assuming the default Animate script is gone.

Graph or AnimationTrack code?

Your existing animation code doesn't have to go anywhere. The July FAQ: "Your existing LoadAnimation scripts will continue to function." Asked in October about overhead, a Roblox staff member called the graph "an alternative to the AnimationTrack-based logic" and said it "should not interfere with performance of your games if you don't use it."

What is dated next for graphs

Roblox's Fall 2026 roadmap (September 18) names Animation Graphs in two items and lists root motion alongside them:

Roblox has not said whether "Mid 2027" now means the full release of state machines and expressions. Separately, the RDC 2026 recap dates a new default avatar movement system "that includes motion matching and root motion" to Early 2027. If you are rebuilding a character controller around graphs, those two dates are the ones to plan around.

Quick Action Checklist

• Build graphs from Avatar ⟩ Graph Editor, publish them, and load them with Animator:LoadAnimation(), the same as a clip. Avoid the deprecated Humanoid:LoadAnimation() in the July post's snippet.
• Call GetParameterDefaults() once to see what the graph expects, then drive it with SetParameter(); NaN and inf become 0.
• Use Linear or CubicV2 for transitions; no other curve applies.
• Keep PhaseSync on Synced for locomotion blends, and clamp Position if you don't want Blend1D to extrapolate.
• Put footstep markers in every locomotion clip; a blend fires only the dominant clip's events.
• Use Over plus Mask for upper-body layers, and a One Shot with a Trigger parameter for emotes and punches.
• Swap animations at runtime by wiring a clip's AnimationId to a String parameter.
• Turn on Animation Graphs State Machines under File ⟩ Beta Features to try state machines and expressions, and don't ship them: Roblox says they only work in Studio during the beta.
• Give every competing state machine transition its own Priority.
• Generate the Animate script with Graph ⟩ Create Animate script after setting Workspace.AuthorityMode, and call SetParameter from the client (Automatic), the server (NPCs), or both (Server mode).
• After generating, check in a playtest whether the default Animate script still runs.