State

A State is an object with a unique id that represents one possible state of a parent StateMachine. A state can be associated with only one machine (its parent), and its id must be unique within its machine. When the parent machine has entered a state, that state is considered active until it leaves the state.

States can be constructed, added and cleaned up manually, or they may be created through StateMachine:newState. For manually-constructed states, it's helpful to add the state as a task to the machine's maid so it is cleaned up

Event-based Usage

local sm = StateMachine.new()

-- Create some states
local stateGame = sm:newState("game")
local stateShop = sm:newState("shop")
stateShop.onEnter:connect(function ()
    print("Welcome to the shop!")
end)
stateShop.onLeave:connect(function ()
    print("Come back soon.")
end)

-- Make some transitions
sm:transition("game")
sm:transition("shop") --> Welcome to the shop!
sm:transition("game") --> Come back soon.

Subclass Usage

local CounterState = setmetatable({}, State)
CounterState.__index = CounterState

function CounterState.new(...)
    local self = setmetatable(State.new(...), CounterState)

    -- Tracks number of times it has been transitioned to
    self.transitionCount = 0

    return self
end

function CounterState:enter(...)
    State.enter(self, ...) -- call super
    self.transitionCount = self.transitionCount + 1
end

Usage

local sm = StateMachine.new()
sm.StateClass = CounterState -- StateMachine:newState now uses CounterState

local firstState = sm:newState("first")
sm:newState("second")
sm:newState("third")

sm:transition("first")
sm:transition("second")
sm:transition("first")

print("Transitions: " .. firstState.transitionCount) --> Transitions: 2

Constructors

State.new(StateMachine machine, string id[, function onEnterCallback])

Construct a new state given the StateMachine it should belong to, its unique id within this machine, and optionally a function to immediately connect to the onEnter event.

This is called by StateMachine:newState, automatically providing the machine to this constructor.

Fields

StateMachine State.machine

The parent StateMachine which owns this state and can transition to it.

string State.id

The unique string that identifies this state in its machine

Maid State.maid

A Maid invoked upon cleanup

Functions

State:__tostring()

Returns a string with this state's id.

State:cleanup()

Clean up resources used by this state.

Careful, this function doesn't remove this state from the parent machine!

State:enter(...)

Called when the parent machine enters this state, firing the onEnter event with all given arguments.

If this state has any sub-machines, they will transition to the "Active" state.

State:leave(...)

Called when the parent machine leaves this state, firing the onLeave event with all given arguments.

If this state has any sub-machines, they will transition to the "Inactive" state.

boolean State:isActive()

Returns whether the parent machine is currently in this state.

State:transition()

Orders the parent machine to transition to this state.

Events

State.onEnter(State prevState)

Fires when the parent machine transitions into this state.

State.onLeave(State nextState)

Fires when parent machine transitions out of this state.