Getting Started
Felix is a small, fast, fully typed finite state machine for Roblox and Luau.
- States with
OnEnter/OnExitcallbacks - Transitions fired by named triggers, with optional Conditions (guards) and Effects (actions)
- Event data sent with triggers, and a shared Context table, both available to every callback
- Predictable ordering: Exit → Effects → Enter
- Safe re-entrancy: sending a trigger from inside a callback is queued until the current transition finishes
- Strict-mode types for everything, exported from the package
Built for combat, all optional (see the Combat guide):
- Scopes that clean up hitboxes, connections and timers when a state is left, however it's left
- Timed states (
Duration/Next),OnUpdate, and time in state, driven bymachine:Update(dt) - Any-state transitions for interrupts like stuns and death
- Priority and Resistance for armor, uncancellable frames and cancel windows
- Input buffering with
machine:Buffer(trigger, window) - Hierarchical states, tags, history,
CanSend, aRejectedsignal, andSnapshot/ForceStatefor networking
Installation
With Wally, add Felix to your wally.toml:
[dependencies]
Felix = "3b-6/felix@0.1.0"
Then run wally install and require it:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Felix = require(ReplicatedStorage.Packages.Felix)
Felix has no dependencies and works anywhere Luau runs: on the client, on the server, and in Lune.
Quick start
A character that can idle, walk and jump:
--!strict
local Felix = require(ReplicatedStorage.Packages.Felix)
-- 1. Create the states
local idle = Felix.State.new("Idle")
local walk = Felix.State.new("Walk")
local jump = Felix.State.new("Jump")
idle.OnEnter = function()
print("Standing still")
end
jump.OnEnter = function()
print("Jumping!")
end
jump.OnExit = function()
print("Landed")
end
-- 2. Connect them with transitions. A transition goes in the Transitions list of the state it leaves.
table.insert(idle.Transitions, Felix.Transition.new({
From = "Idle",
Target = "Walk",
Triggers = { "Move" },
}))
table.insert(walk.Transitions, Felix.Transition.new({
From = "Walk",
Target = "Idle",
Triggers = { "StopMoving" },
}))
-- One transition can listen for several triggers
for _, state in { idle, walk } do
table.insert(state.Transitions, Felix.Transition.new({
From = state.Name,
Target = "Jump",
Triggers = { "Jump", "DoubleTap" },
}))
end
table.insert(jump.Transitions, Felix.Transition.new({
From = "Jump",
Target = "Idle",
Triggers = { "Land" },
}))
-- 3. Create the machine: an ID, the name of the starting state, options, and the states
local character = Felix.new("Character", "Idle", nil, { idle, walk, jump })
-- 4. Start it and send triggers
character:Start() --> Standing still
character:Send("Move") -- Idle -> Walk
character:Send("Jump") --> Jumping!
character:Send("Move") -- ignored: Jump has no "Move" transition
character:Send("Land") --> Landed, Standing still
print(character.Current and character.Current.Name) --> Idle
Next, read the Usage guide, the Combat guide, or jump to the API reference.