Machine
A state machine, created by Felix.new. It holds a list of States, is in at most one of them at a time (plus that state's parents, see State.Parent), and moves between them when you Machine:Send a trigger that one of the current state's Transitions listens for.
C is the type of the machine's Machine.Context. It defaults to any.
Fields starting with an underscore (_Queue, _Transitioning, …) are internal and may change between versions.
Properties
Current
This item is read only and cannot be modified. Read OnlyMachine.Current: State?
The state the machine is in, or nil when it isn't running. In a hierarchical machine this is the innermost
active state; use Machine:Is to also match its parents.
Previous
This item is read only and cannot be modified. Read OnlyMachine.Previous: State?The state the machine was in before the last transition, or nil right after Machine:Start.
Active
This item is read only and cannot be modified. Read OnlyMachine.Active: booleanWhether the machine is running: true between Machine:Start and Machine:Stop.
Context
Machine.Context: C
A table shared by every callback, for data like health, ammo or a target. It's the same table passed as
Context in Felix.Details, or an empty table if none was passed.
Clock
This item is read only and cannot be modified. Read OnlyMachine.Clock: number
Machine time in seconds: the sum of every dt passed to Machine:Update. State.Duration, Scope:Delay,
Machine:Buffer windows and Machine:GetTimeInState all use it.
AnyTransitions
Transitions that can fire from any state, for interrupts like getting stunned or dying. They're checked after
the current state's own transitions and its parents', so a state can handle a trigger its own way.
Their From must be "*", and their Except lists states they don't fire from.
table.insert(fighter.AnyTransitions, Felix.Transition.new({
From = "*",
Target = "Dead",
Triggers = { "Die" },
Priority = math.huge,
Except = { "Dead" },
}))
ID
This item is read only and cannot be modified. Read OnlyMachine.ID: anyThe id passed to Felix.new. Used in error messages.
Default
This item is read only and cannot be modified. Read OnlyMachine.Default: stringThe name of the state entered by Machine:Start.
StateChanged
This item is read only and cannot be modified. Read OnlyMachine.StateChanged: Signal
Fires with (newState, oldState, ...) whenever Machine.Current changes: after a state's OnEnter runs,
and after OnExit when the machine stops. ... is the event data passed to Machine:Send.
newState is nil on Machine:Stop, and oldState is nil on Machine:Start; neither has event data.
A Machine:Send made from a handler is queued like one made from any other callback.
Handlers run on their own thread. If a handler yields, the machine may have moved on by the time it resumes,
so use the newState argument rather than reading Machine.Current after a yield.
local connection = machine.StateChanged:Connect(function(newState, oldState, ...)
print(oldState and oldState.Name, "->", newState and newState.Name, ...)
end)
connection:Disconnect()
Rejected
This item is read only and cannot be modified. Read OnlyMachine.Rejected: Signal
Fires with (trigger, reason, ...) when a Machine:Send doesn't transition. reason is a Felix.RejectReason.
Triggers retried by Machine:Buffer don't fire it.
fighter.Rejected:Connect(function(trigger, reason)
warn(`{trigger} rejected: {reason}`) --> Parry rejected: Resisted
end)
Functions
Send
Machine:Send(trigger: string,--
The trigger name
...: any--
Event data, passed after the machine to the Conditions, the old state's OnExit, the Effects and the new state's OnEnter
) → boolean--
true if the machine transitioned
Sends a trigger. The machine looks for a transition listening for trigger in the current state's
Transitions (in the order they were inserted), then in each parent's, then in Machine.AnyTransitions.
The first one whose Priority meets the current State.Resistance and whose Conditions all pass fires.
If none does, nothing happens, Machine.Rejected fires, and Send returns false.
A Send made from inside a callback is queued and runs after the current transition has fully finished,
so it returns false. Errors thrown by callbacks are rethrown from Send.
If a callback yields (for example with task.wait()), the transition isn't finished until it resumes, so
every Send in the meantime is queued. That's rarely what you want in combat: use Scope:Delay to wait
instead. Set CatchYields (or DebugMode) in Felix.Details to turn a yield into an error, which stops the
callback where it yielded.
player:Send("Hit", 25, "Zombie")
Buffer
Machine:Buffer(trigger: string,window: number,--
How long to keep retrying, in machine time
) → boolean--
true if it transitioned right away
Like Machine:Send, but if the trigger can't fire now it's kept for window seconds and retried after every
transition and every Machine:Update, until it fires or expires. For input buffering: an attack pressed just
before the current one ends still comes out.
Buffering a trigger that's already buffered replaces it, so mashing a button buffers one press.
UserInputService.InputBegan:Connect(function(input)
if input.UserInputType == Enum.UserInputType.MouseButton1 then
fighter:Buffer("Attack", 0.2)
end
end)
ClearBuffer
Machine:ClearBuffer(trigger: string?--
Only clear this trigger. Clears everything when omitted.
) → ()Drops buffered triggers. Machine:Stop clears the buffer too.
CanSend
Machine:CanSend(trigger: string,...: any--
Event data, passed to the Conditions
) → (RejectReason?--
Why not, when it wouldn't
)Checks a trigger without sending it, for UI and AI ("can I dodge right now?"). It runs the Conditions, so keep them free of side effects.
local canDodge, reason = fighter:CanSend("Dodge")
Update
Machine:Update(dt: number--
Seconds since the last Update
) → ()
Advances machine time by dt, then, in order: fires due Scope:Delay timers, moves on from states whose
State.Duration ran out, calls each active state's State.OnUpdate, and retries buffered triggers.
Call it every frame:
RunService.Heartbeat:Connect(function(dt)
fighter:Update(dt)
end)
Nothing time-based happens without it. Machines that don't use time don't need it.
Errors
| Type | Description |
|---|---|
| "Can't Update during a transition." | Called from inside a callback |
Start
Machine:Start() → ()Enters the default state (and its parents, and its State.Initial children). Calling it on a running machine exits the current state and starts over.
Before entering anything, Start checks the machine's setup, so typos fail at setup instead of mid-game: state
names are unique, the default state exists, every transition's Target names one of the machine's states and
its From matches the state it's in, and every Parent, Initial, Next and Except names a real state.
Errors
| Type | Description |
|---|---|
| "Default State not Defined." | The default state isn't one of the machine's states |
| "... has a Transition to ..., which Doesn't Exist." | A transition targets a state the machine doesn't have |
| "Can't Start during a transition." | Called from inside a callback |
Stop
Machine:Stop() → ()Exits the current state (and its parents) and stops the machine, cleaning up every Scope and clearing buffered triggers. Triggers sent while stopped are ignored. Call Machine:Start to run it again.
Called from inside a callback, it waits until the current transition finishes, then discards any queued triggers.
Destroy
Machine:Destroy() → ()Stops the machine and releases its states and details. Like Machine:Stop, it waits for the current transition to finish when called from inside a callback.
ForceState
Machine:ForceState(name: string,--
The state to move to
elapsed: number?--
How long the machine has already been in it. Defaults to 0.
) → ()
Moves straight to a state, skipping Conditions, Effects and State.Resistance (exits and enters still run).
If the machine is already in that state, only its time is changed. For applying a server's Machine:Snapshot
on a client, or resetting a fighter at round start. Scope:Delay timers aren't shifted by elapsed.
-- Client: snap to the server's state when prediction was wrong
remote.OnClientEvent:Connect(function(snapshot)
if snapshot.State and not fighter:Is(snapshot.State) then
fighter:ForceState(snapshot.State, snapshot.Time)
end
end)
Errors
| Type | Description |
|---|---|
| "Isn't Active." | The machine isn't running |
| "Can't ForceState during a transition." | Called from inside a callback |
Snapshot
The current state's name and how long the machine has been in it, as plain data to send to clients. Apply it with Machine:ForceState. Machine.Context isn't included.
Is
Machine:Is(name: string) → boolean--
Whether the machine is in name, or in a child of it
if fighter:Is("Attacking") then -- true in Attacking's children too
IsAny
GetTag
Machine:GetTag(tag: string) → any--
The tag's value in the innermost active state that sets it, or nil
Reads State.Tags. A child's value overrides its parent's.
HasTag
Lets damage, movement and UI code ask about the state instead of checking state names:
if not target:HasTag("Invulnerable") then
target:Send("Hit", damage)
end
GetScope
Machine:GetScope(name: string?--
An active state. Defaults to the state whose callback is running, or Machine.Current.
) → Scope
The Scope for the current stay in a state: everything added to it is cleaned up when the machine leaves
that state. Inside OnEnter, OnExit, OnUpdate and Scope:Delay callbacks, machine:GetScope() is the
scope of the state the callback belongs to.
Errors
| Type | Description |
|---|---|
| "... isn't active." | The state isn't active (for example, from inside an Effect, between states) |
GetTimeInState
Machine:GetTimeInState() → number--
Machine time since the state was entered, or 0 if it isn't active
-- A Condition: only cancel into a dodge after the attack's first 0.2s
function(machine)
return machine:GetTimeInState() >= 0.2
end
GetHistory
The names of the last states the machine was in. Keeps Felix.Details HistorySize entries (8 by default).
Cleared by Machine:Start, which is also when a changed HistorySize takes effect. Returns a new table each call.
-- Back to whatever stance we were in before getting hit
local history = fighter:GetHistory()
local before = history[#history - 1]
Refresh
Machine:Refresh() → ()
Rebuilds the machine's lookup tables. Inserting transitions or states after Machine:Start is picked up
automatically; call this after replacing or removing them, or after changing a transition's Triggers.