Functions

Templates

templates are the coolest recommended way of creating calico's state machines

calico_template()

calico_template() -> Struct.CalicoTemplate

Creates a template, essentially a scaffolding for a state machine.

The following methods are methods of Struct.CalicoTemplate, which are used to set up the template.

.init()

template.init(name) -> template
name: string | real

Sets the initial state. When the state machine is created later, this state will be the state machine's initial state.

.state()

template.state(name) -> template
name: string | real

Creates a new state with a given name, at the current level.

/// ...
.state("idle")
.state("walk")

In which the example template now has two states: idle and walk.

.child()

template.child(name) -> template
name: string | real

Pushes the hierarchy a level down, then creates a new state in that level with the given name. Kinda like "push".

/// ...
.state("top")
   .child("middle")
      .child("bottom")

in which top is the highest of the hierarchy, middle is top's child, and bottom is middle's child.

.back()

template.back() -> template

Pulls the hierarchy a level higher. Kinda like "pop".

/// ...
.state("top")
   .child("middle")
      .child("bottom")
      .back()
   .state("middle2")

in which top is the highest of the hierarchy, middle is top's child, and bottom is middle's child. middle2 is top's child.

.onenter()

template.onenter(callback) -> template
callback: function(Struct.Calico)

Sets the onenter trigger for the last created state in the current level, to the given callback. onenter triggers when the state machine changes into the state.

When triggered, the callback will have the running state machine passed into it.

// ...
.state("idle")
   .onenter(function() { show_debug_message("idle") })
.state("walk")
   .onenter(function() { show_debug_message("walk") })

.onleave()

template.onleave(callback) -> template
callback: function(Struct.Calico)

Exactly the same as .onenter(), but sets the onleave trigger.

.on()

template.on(name, callback) -> template
name: string | real
callback: function(Struct.Calico)

Similar to .onenter() or .onleave(), except used for custom triggers.

/// ...
.state("idle")
   .on("step", function() { show_debug_message(current_time) })
   .on("draw", function() { show_debug_message("doodling") })

See calico_run()

.add()

template.add(data) -> template
data: Struct { name: function }

Sugar for .on(), .onenter(), and .onleave(). Each member of the struct will be added as separate triggers. If a member is named either "onenter" or "onleave", the associated triggers will be set automatically.

// ...
.onenter(function() {})
.on("step", function() {})
.on("draw", function() {})

is exactly the same as

// ...
.add({
   onenter: function() {},
   step: function() {},
   draw: function() {}
})

General

calico_create()

calico_create([template], [context = self]) -> Struct.Calico
template: Struct.CalicoTemplate
context: Instance.Id

Creates a new state machine, optionally using a previously created template.

If using a template, the context argument will automatically rebind all the triggers to the new self. This can be disabled by passing in undefined instead.

calico_run()

calico_run(source, event)
source: Struct.Calico
event: string | real

A state machine records its current state. This function will run a trigger within that current state.

calico_run(machine, "step")
calico_run(machine, "draw")

calico_child()

calico_child(source)
source: Struct.Calico

If run outside a trigger, this does nothing.

When run inside a trigger, it will start running the state's child trigger. This is where the "reverse inheritance" comes from.

template = calico_template()
.init("bottom")
.state("top")
   .on("run", function (_machine) {
      calico_child(_machine)
      show_debug_message("top")
   })
   .child("bottom")
      .on("run", function() {
         show_debug_message("bottom")
      })

machine = calico_create(template)
calico_run(template, "run")

Because of .init("bottom"), the bottom state is machine's initialized state. When calico_run() is called, because top is bottom's parent, top's trigger is run first. calico_child() is then called, which delegates execution to bottom.

All together, "bottom" then "top" are printed, in that order, to the console.

calico_change()

calico_change(source, state)
source: Struct.Calico
state: string | real

Switches the state machine's current state to a new one. If available, the previous state's onleave trigger will run, then the new state's onenter trigger will run.

If this is run while a trigger is running, then the state will not change until the trigger is finished.

Alternative signature:

calico_change(alias)
alias: Struct.CalicoAlias

Exactly the same, but uses an alias created with calico_get() to switch to a new state.

calico_get()

calico_get(source, state) -> Struct.CalicoAlias
source: Struct.Calico
state: string | real

Creates an alias of a state. Sometimes useful.

calico_is()

calico_is(source, state) -> bool
source: Struct.Calico
state: string | real

Checks if the state machine is in the given state.

This may give unexpected results inside a trigger, as calico_change() waits until a trigger has fully completed before actually changing the state.

Alternative signature:

calico_is(alias) -> bool
alias: Struct.CalicoAlias

Exactly the same, but using an alias created with calico_get().

Mutation

These functions are for modifying a state machine after it has been created.

calico_mutate_init()

calico_mutate_init(source, state)
source: Struct.Calico
state: string | real

Sets the state machine's current state to the given state, without triggering onenter or onleave.

calico_mutate_state()

calico_mutate_state(source, state, [parent])
source: Struct.Calico
state: string | real
parent: string | real

Initializes a new state of a given name in the state machine. Optionally can have a parent.

calico_mutate_onenter()

calico_mutate_onenter(source, state, callback)
source: Struct.Calico
state: string | real
callback: function(Struct.Calico)

Sets the onenter trigger for a given state machine's state.

calico_mutate_onleave()

calico_mutate_onleave(source, state, callback)
source: Struct.Calico
state: string | real
callback: function(Struct.Calico)

Sets the onleave trigger for a given state machine's state.

calico_mutate_on()

calico_mutate_on(source, state, trigger, callback)
source: Struct.Calico
state: string | real
trigger: string | real
callback: function(Struct.Calico)

Sets the a custom trigger of a given name for a given state.