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");