Skip to main content

State

A state a Machine can be in. Created with Felix.State.new(name).

local jump = Felix.State.new("Jump")

jump.OnEnter = function(machine)
	print("Jumping!")
end

Properties​

Name​

State.Name: string

The state's name. Transitions target states by this name, so it must be unique within a machine.

Transitions​

State.Transitions: {Transition}

The transitions that can leave this state, checked in order when a trigger is sent. Add to it with table.insert.

OnEnter​

State.OnEnter: Callback?

Called with the machine and any event data when the machine enters this state.

OnExit​

State.OnExit: Callback?

Called with the machine and any event data when the machine leaves this state.

OnUpdate​

State.OnUpdate: UpdateCallback?

Called with the machine and dt on every Machine:Update while the machine is in this state (or in one of its children). Parents run before children.

Parent​

State.Parent: string?

The name of this state's parent, for hierarchical machines. While a child is active its parents are too: Machine:Is matches them, their transitions, State.Tags and State.Resistance apply, and they're only exited when a transition leaves them.

local combat = Felix.State.new("Combat")
local light = Felix.State.new("Light")
light.Parent = "Combat"

Initial​

State.Initial: string?

The child entered automatically when this state is entered, so a transition can target a parent.

Duration​

State.Duration: number?

Seconds of machine time after which the machine moves to State.Next on its own. Driven by Machine:Update. The move ignores Conditions and [State.Resistance]: it's the state ending, not an interrupt.

windup.Duration = 0.15
windup.Next = "Active"

Next​

State.Next: string?

The state entered when State.Duration runs out. Required when Duration is set.

Resistance​

State.Resistance: Resistance?

The minimum Transition.Priority needed to leave this state, or a function returning it. Defaults to the nearest parent's Resistance, or 0. A function is re-evaluated on every Send, which makes cancel windows easy:

-- Uncancellable for the first 0.25s, then anything goes
heavy.Resistance = function(machine)
	return if machine:GetTimeInState() < 0.25 then 10 else 0
end

Timeouts (State.Duration), Machine:ForceState and Machine:Stop ignore it.

Tags​

State.Tags: {[string]: any}?

Values that describe the state, read with Machine:HasTag and Machine:GetTag. A child's tag overrides its parent's.

dodge.Tags = { Invulnerable = true, CanMove = false }

Functions​

new​

State.new(
name: string--

The state's name, unique within its machine

) → State

Trigger​

State:Trigger(
trigger: string,
machine: Machine,
...: any--

Event data, passed to each Condition

) → Transition?--

The first transition listening for trigger whose Conditions all pass

Finds the transition in this state's own Transitions that a trigger would fire, without running it. It doesn't look at parents, the machine's AnyTransitions or State.Resistance; use Machine:CanSend for that.

Show raw api
{
    "functions": [
        {
            "name": "Trigger",
            "desc": "Finds the transition in this state's own `Transitions` that a trigger would fire, without running it.\nIt doesn't look at parents, the machine's `AnyTransitions` or [State.Resistance]; use [Machine:CanSend] for that.",
            "params": [
                {
                    "name": "trigger",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "machine",
                    "desc": "",
                    "lua_type": "Machine"
                },
                {
                    "name": "...",
                    "desc": "Event data, passed to each Condition",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "The first transition listening for `trigger` whose Conditions all pass",
                    "lua_type": "Transition?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 148,
                "path": "src/state.luau"
            }
        },
        {
            "name": "new",
            "desc": "",
            "params": [
                {
                    "name": "name",
                    "desc": "The state's name, unique within its machine",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "State"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 178,
                "path": "src/state.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Name",
            "desc": "The state's name. Transitions target states by this name, so it must be unique within a machine.",
            "lua_type": "string",
            "source": {
                "line": 24,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Transitions",
            "desc": "The transitions that can leave this state, checked in order when a trigger is sent. Add to it with `table.insert`.",
            "lua_type": "{ Transition }",
            "source": {
                "line": 30,
                "path": "src/state.luau"
            }
        },
        {
            "name": "OnEnter",
            "desc": "Called with the machine and any event data when the machine enters this state.",
            "lua_type": "Callback?",
            "source": {
                "line": 36,
                "path": "src/state.luau"
            }
        },
        {
            "name": "OnExit",
            "desc": "Called with the machine and any event data when the machine leaves this state.",
            "lua_type": "Callback?",
            "source": {
                "line": 42,
                "path": "src/state.luau"
            }
        },
        {
            "name": "OnUpdate",
            "desc": "Called with the machine and `dt` on every [Machine:Update] while the machine is in this state (or in one of\nits children). Parents run before children.",
            "lua_type": "UpdateCallback?",
            "source": {
                "line": 49,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Parent",
            "desc": "The name of this state's parent, for hierarchical machines. While a child is active its parents are too:\n[Machine:Is] matches them, their transitions, [State.Tags] and [State.Resistance] apply, and they're only\nexited when a transition leaves them.\n\n```lua\nlocal combat = Felix.State.new(\"Combat\")\nlocal light = Felix.State.new(\"Light\")\nlight.Parent = \"Combat\"\n```",
            "lua_type": "string?",
            "source": {
                "line": 63,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Initial",
            "desc": "The child entered automatically when this state is entered, so a transition can target a parent.",
            "lua_type": "string?",
            "source": {
                "line": 69,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Duration",
            "desc": "Seconds of machine time after which the machine moves to [State.Next] on its own. Driven by [Machine:Update].\nThe move ignores Conditions and [State.Resistance]: it's the state ending, not an interrupt.\n\n```lua\nwindup.Duration = 0.15\nwindup.Next = \"Active\"\n```",
            "lua_type": "number?",
            "source": {
                "line": 81,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Next",
            "desc": "The state entered when [State.Duration] runs out. Required when `Duration` is set.",
            "lua_type": "string?",
            "source": {
                "line": 87,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Resistance",
            "desc": "The minimum [Transition.Priority] needed to leave this state, or a function returning it. Defaults to the\nnearest parent's Resistance, or `0`. A function is re-evaluated on every Send, which makes cancel windows easy:\n\n```lua\n-- Uncancellable for the first 0.25s, then anything goes\nheavy.Resistance = function(machine)\n\treturn if machine:GetTimeInState() < 0.25 then 10 else 0\nend\n```\n\nTimeouts ([State.Duration]), [Machine:ForceState] and [Machine:Stop] ignore it.",
            "lua_type": "Resistance?",
            "source": {
                "line": 103,
                "path": "src/state.luau"
            }
        },
        {
            "name": "Tags",
            "desc": "Values that describe the state, read with [Machine:HasTag] and [Machine:GetTag]. A child's tag overrides its parent's.\n\n```lua\ndodge.Tags = { Invulnerable = true, CanMove = false }\n```",
            "lua_type": "{ [string]: any }?",
            "source": {
                "line": 113,
                "path": "src/state.luau"
            }
        }
    ],
    "types": [],
    "name": "State",
    "desc": "A state a [Machine] can be in. Created with `Felix.State.new(name)`.\n\n```lua\nlocal jump = Felix.State.new(\"Jump\")\n\njump.OnEnter = function(machine)\n\tprint(\"Jumping!\")\nend\n```",
    "source": {
        "line": 18,
        "path": "src/state.luau"
    }
}