hmotine
Real-Time hierarchical (in)finite state machine framework.
The states are hierarchical, the state transition can happen in timed manner.
Install hmotine
npm install hmotine
Using hmotine
Registering states
Register as many states as you want. A state is defined by:
- State name, a valid Javascript identifier
- State advance function, a function that implements the transition logic for the state. It accepts one parameter, the pointer to hmotine machine object. Through this pointer, advance function can access utility functions provided by the machine.
- State object, an object containing variables and functions that can be accessed from state's advance function, or from child state's advance functions.
- Parent state name. Any already defined state can be the parent of a newly defined state. This is why the order of state definitions matters.
Advance function
Advance function of a state will be invoked when machine is in that state.
The advance function can access its own object and objects of its parents,
and it can update the object variables with new values. Advance function
in the end of its execution has to instruct the machine what will be the next state.
Advance function takes one parameter, the hmotine machine. In the rest of this
chapter we assume that the name of that parameter is m
.
Accessing state variables
The hmotine machine provides the method for advance function to access the state. It will first look at state's own properties, and if not found it will look at state's parent's properties and so on, up the chain of parent-child relationship.
The methods to access and modify the state are m.get()
and m.set()
.
State transition
In the end of its execution flow, advance function should instruct the machine what to do. Possible options:
- Stay in the current state:
return m.keep()
- Go to other state:
return m.goto("NEXT_STATE")
- Stop the machine:
return m.end()
Timing of the state transition
Functions for state transition keep
, goto
and end
, that are used to finish
the advance function can have additional parameter which says in how many
milliseconds should execute the advance function next time.
For example, if advance function is finished by return m.goto("NEXT_STATE, 200)
,
the advance function of NEXT_STATE
will be invoked after 200-x milliseconds, where
x is the number of milliseconds taken by previous advance function.
Debug mode
Use machine.debugOn()
to enable debug mode. In debug mode, hmotine will log to the
console the current state and all state variables
Code example
var machine = require("hmotine");
machine.addState("root", function(m) {}, {c: 0});
machine.addState("up", function(m) {
m.set("c", m.get("c") + 1);
console.log(m.get("c"));
if (m.get("c") < 10) {
return m.keep(500);
} else {
return m.goto("down", 2000);
}
}, {}, "root");
machine.addState("down", function(m) {
m.set("c", m.get("c") - 1);
console.log(m.get("c"));
if (m.get("c") > 0) {
return m.keep(500);
} else {
return m.goto("up", 2000);
}
}, {}, "root");
machine.start("up");