Graph Editor expressions

An expression is a short Luau-like formula that reads graph parameters and returns a value, such as math.clamp((MovementSpeed + 0.5) / MaxSpeed, 0, 1). Use expressions to drive a node property or a state machine transition. Expressions keep parameter transformations and animation decisions in your graph, close to the nodes they drive.

Prerequisites

Before you create an expression, familiarize yourself with the Animation Graph Editor, including how to open it and create an animation graph.

Create an expression

This example uses an expression to drive the Position property of an Blend1DNode. Configure the node with an idle animation at position 0 and a run animation at position 1. The expression converts the character's movement speed into the 0-to-1 range that the node uses to blend between those animations.

1. Add MovementSpeed and MaxSpeed Number graph parameters.

   

2. Drag a connection from the Position property pin of the Blend1DNode and select New Expression.

   

3. Enter the following expression:

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

   

4. Click outside the expression box to refresh it. As MovementSpeed rises toward MaxSpeed, the Blend1DNode receives a value from 0 to 1 and blends from the idle animation to the run animation.

After you load the graph onto an AnimationTrack, update MovementSpeed and MaxSpeed from your gameplay script with AnimationTrack:SetParameter(). The following example uses the MoveDirection and WalkSpeed properties of a Humanoid:

game:GetService("RunService").Stepped:Connect(function()
    animationTrack:SetParameter("MovementSpeed", humanoid.MoveDirection.Magnitude * humanoid.WalkSpeed)
    animationTrack:SetParameter("MaxSpeed", humanoid.WalkSpeed)
end)

The expression evaluates as the parameter values change. For the parameter workflow, see API integration.

What is supported

Expression support includes arithmetic and comparison operations, logical and conditional expressions, calls to functions in the math library, construction and member access for CFrame, Vector2, Vector3, and Color3 values, and string concatenation. The following sections list the supported syntax and functions.

Arithmetic and comparisons

Use standard arithmetic and comparison operations, with the usual order of operations. For example, // divides and rounds down.

Speed * 2.0 + Offset
(Health / MaxHealth) * 100
DamageMultiplier ^ 2
Count % 3
10 // 3
Speed < 1
Health >= MaxHealth

Comparison operators work with numbers. Use == and ~= to compare numbers, booleans, or strings.

Logic and short-circuiting

and, or, and not follow Luau truthiness and short-circuit evaluation. Only false and nil are considered false.

IsGrounded and GroundSpeed or AirSpeed
not IsDisabled

If-then-else expressions

Use Luau's conditional expression form to branch within a single expression:

if Speed > 10 then "sprint" elseif Speed > 2 then "run" else "idle"

Math library

Use the math library. Graph expressions don't yet support math.frexp(), math.noise(), or math.randomseed(). math.modf() currently returns only the integer portion.

math.clamp(Speed / MaxSpeed, 0, 1)
math.sin(Time * 2 * math.pi)
math.atan2(Direction.Y, Direction.X)
math.max(A, B, C)

Vector construction and member access

Construct Vector2 and Vector3 values, perform vector arithmetic, and access vector members such as Magnitude and Unit.

Vector3.new(math.cos(Time), math.sin(Time), 0)
Vector2.new(InputX, InputY)
MoveDirection.Magnitude * 2.0
Position.X + Offset
Vector3.zero

Color3 construction and member access

Construct Color3 values and access their color channels.

Color3.fromRGB(255, 128, 0)
Color.R

CFrame construction, member access, and operations

Construct CFrame values, access CFrame members, and combine them with CFrames or Vector3 values.

CFrame.new(Position, LookAtPosition)
CFrame.Angles(RotationX, RotationY, RotationZ)
CFrame.identity
Transform.LookVector
Transform.Position + Vector3.new(0, 1, 0)

String concatenation

Use .. to concatenate two strings:

"state_" .. CurrentState

Local variables and multi-line expressions

Use a multi-line expression to break a formula into named steps. A multi-line expression supports local declarations, return, if/elseif/else, and standalone expressions. Inside an if or else body, use only return or a standalone expression; nested if statements and local declarations aren't supported.

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