FixedUpdateFSM

A module singleton (global functions only, no handle) that attaches a Lua-driven finite state
machine to a scene-graph GameObject, ticked on the fixed-step update. The state machine’s
template is inferred from the script’s top-level state sub-tables: any key whose value is a table
and that is not a known lifecycle/module key (on_create, on_enable, on_disable,
on_destroy, OnClickRelease, update, late_update) becomes a state. For the UI-object variant,
see FSM.

Inside state handlers, self.object is the attached GameObject. The Lua Attach binding injects
no other context fields — the per-instance self.<param> fields that the FSM system can carry are
populated only by the YAML scene-installer path, which this call does not reach.

Template limits. At most 256 states, and each state’s data carries up to 8 named f32
parameters (MAX_STATES / MAX_STATE_PARAMS).

Functions

FixedUpdateFSM.Attach( GameObject object, string scriptPath, string initialState ) : boolean or nil
Loads the FSM module script at scriptPath (resolved relative to the script base directory),
builds the template from its state-table keys, and attaches a FixedUpdateFSM component to
object starting in initialState. Returns true on success, or nil on failure — an
empty/non-UTF-8 script path or initial-state string, a script that fails to load or does not return
a table, a template with no states, an initialState that is not one of those states, a full
script/template cache, or a failed component add. (Prerequisites not yet ready — the Lua VM or
script cache uninitialized — also return nil.)

FixedUpdateFSM.Detach( GameObject object ) : void
Destroys the FixedUpdateFSM component on object, firing its on_disable → on_destroy
callbacks. No-op if the object has no such component.

FixedUpdateFSM.State( GameObject object ) : string or nil
Returns the current state’s name, or nil if the object has no FixedUpdateFSM component, the
component has no data or active instance, its template pointer is null, or the current state is
null.

Example

-- Attach a patrol/chase/attack FSM to an enemy and query its current state.
-- The script must define patrol/chase/attack as state sub-tables and return the module.
local ok = FixedUpdateFSM.Attach(enemy, "scripts/enemy_fsm.lua", "patrol")
if not ok then
    print("enemy FSM attach failed")
end

local state = FixedUpdateFSM.State(enemy)
if state == "chase" then
    -- ...
end

-- Later, when the enemy is removed:
FixedUpdateFSM.Detach(enemy)