TransitionCondition Script Protocol

Overview

TransitionCondition scripts provide custom logic for evaluating whether a State Machine transition should fire. The evaluate function is called each frame and returns true to allow the transition or false to block it.

When to use TransitionCondition scripts:

• Complex transition conditions that depend on multiple inputs
• Conditions that require script-level computation (math, comparisons)
• Time-based or physics-based transition logic
• Threshold checks against ViewModel data

---

Type Definition

export type TransitionCondition<T> = {
    init:     ((self: T, context: Context) -> boolean)?,
    evaluate: (self: T) -> boolean,
} & T

---

Protocol Methods

Function	Signature	Required	Description
init	(self: T, context: Context): boolean	No	One-time initialization
evaluate	(self: T): boolean	Yes	Returns whether the transition should fire

evaluate(self) — REQUIRED

Called each frame to determine if the transition should be taken. Return true to allow the transition, false to block it.

function evaluate(self: MyCondition): boolean
    if self.score then
        return self.score.value >= self.threshold
    end
    return false
end

init(self, context) — Optional

Called once when the condition is created. Use for setup and caching ViewModel property references.

function init(self: MyCondition, context: Context): boolean
    local vm = context:viewModel()
    if vm then
        self.score = vm:getNumber("score")
    end
    return true
end

---

Template

export type ScoreGate = {
    threshold: Input<number>,
    score: Property<number>?,
}

function init(self: ScoreGate, context: Context): boolean
    local vm = context:viewModel()
    if vm then
        self.score = vm:getNumber("score")
    end
    return true
end

function evaluate(self: ScoreGate): boolean
    if self.score then
        return self.score.value >= self.threshold
    end
    return false
end

return function(): TransitionCondition<ScoreGate>
    return {
        threshold = 100,
        init = init,
        evaluate = evaluate,
    }
end

---

How to Apply

1. Create a TransitionCondition script in the Assets panel
2. In the State Machine editor, select a transition between states
3. Add the script as a condition on the transition
4. The evaluate function will be checked each frame

---

Key Differences from Other Scripts

Feature	Node Script	TransitionCondition
Lifecycle	init, advance, update, draw	init, evaluate
Rendering	Has draw() and Renderer access	No rendering
Return semantics	advance returns whether to continue	evaluate returns whether to transition
When it runs	Every frame	Every frame (while transition is possible)

---

Practice Exercise

Exercise 1: Score Gate Condition ⭐

Premise

TransitionCondition scripts let you gate transitions with custom logic. This exercise builds a threshold gate using a ViewModel number property.

Goal

By the end of this exercise, you will allow a transition only when score >= threshold and print an ANSWER: line when the gate opens.

Starter Code

export type ScoreGate = {
    threshold: Input<number>,
    score: Property<number>?,
    hasLoggedOpen: boolean,
}

function init(self: ScoreGate, context: Context): boolean
    local vm = context:viewModel()
    if vm then
        self.score = vm:getNumber("score")
    end
    return true
end

function evaluate(self: ScoreGate): boolean
    -- TODO 1: Return false if score property is missing
    if not self.score then
        return false
    end

    -- TODO 2: Gate transition with score >= threshold
    local open = self.score.value >= self.threshold

    -- TODO 3: Print once when gate first opens
    if open and not self.hasLoggedOpen then
        print("ANSWER: gate-open")
        self.hasLoggedOpen = true
    end

    return open
end

return function(): TransitionCondition<ScoreGate>
    return {
        init = init,
        evaluate = evaluate,
        threshold = 100,
        score = nil,
        hasLoggedOpen = false,
    }
end

Assignment

1. Create/bind a ViewModel number property named score
2. Attach this script to a transition condition
3. Increase score to at least threshold and confirm transition unlocks
4. Copy the ANSWER: line from Console

Verify Your Answer

Verify Your Answer

Paste your console output (must include the ANSWER: line):

---

Knowledge Check

Q:What must evaluate(self) return?

Q:Which callback is required in TransitionCondition scripts?

See Also: ListenerAction Protocol, Script Types Overview

Next Steps

• Return to Script Types Overview
• Need a refresher? Review Quick Reference