State — per-target state machines

state gives a target a state machine — idle → walk → jump → fall — that advances on the stage tick, chooses which motion / tween plays in each state, and transitions on conditions, input, timers, or collision events. It is what turns "play this animation" into "behave."

Status: design. Not built yet.

What it is

An entity's behaviour is states and transitions. state attaches a machine to a target: each state has an enter (usually start a motion or tween — play the walk cycle, fade in), an optional per-tick update, and an exit; each transition says "from this state, on this trigger, go to that one." The active state drives the animation; the transitions drive the logic.

The model

• states — { name, enter, update, exit }, enter typically firing a motion / tween;
• transitions — { from, to, when }, where when is a condition, an input action, a timer, or a named event;
• one active state per machine; transitions are checked each tick and the first that fires wins (a fixed order, for determinism).

Pairs with the family

Transitions read the same signals everything else emits: an input pressed("jump") → the jump state; a collision enter on a hazard → the hurt state; a timer → idle → wander. So state is the glue that makes the movement siblings react — it decides which motion/tween to play, they do the playing.

On the stage

state advances each target's machine per tick (checking transitions, running the active update), and drives the other siblings by starting their sequences on enter — it writes no target position itself. Transitions are pure functions of state + inputs + events in a fixed order, so behaviour is deterministic and replayable.

Clients

• Luau — require("state"): define machines, set states, add transitions.
• AntBASIC — a STATE … ENDSTATE block per entity, states as labels with WHEN transitions.

Related

• motion / tween — what each state plays · input / collision — what triggers transitions · stage — the tick
• luau_state — the Luau API