1 /**
  2  * @class stateControl
  3  * @extends component
  4  * @description
  5  * Adds a state machine mechanism to the entity.
  6  *
  7  * Each StateControl instance is effectively a dynamic state machine.
  8  * After desgnating what states exist within the machine using
  9  * CreateState(), the machine can be run using Execute(). Using each state's
 10  * StepFunc, the states will transition until an invalid state is returned. Referring
 11  * to an invalid state halts the state machine.
 12  *
 13  * It is also entirely valid to modify the state machine mid-execution.
 14  *
 15  * 
 16  */ 
 17 function stateControl() {
 18 
 19     /**
 20      * Sets this array of functions as the only one associated 
 21      * with the state of the given name.
 22      *
 23      * During each state, different logic is disgnated to run to control
 24      * what happens during this state and when the state should be altered.
 25      * The step function of the state loop is is meant to hold the bulk of the logic, but 
 26      * it also returns what state should be transitioned to. If the state is to be 
 27      * kept the same, the StepFunc should simply return the empty string. The draw function of the array
 28      * can be used to produce visual effects associated with the state, but
 29      * may not change the current state.
 30      *
 31      * If the state tag returned by the StepFunc does not refer to a valid 
 32      * state part of stateControl, the execution state of the stateControl halts.
 33      * After being halted, the state machine will remain idle until the next
 34      * execute() is called. 
 35      * 
 36      *
 37      * @param {String} name Name of the state.
 38      * @param {Function} onInit The function to call when entering a state 
 39      * @param {Function} onStep The function to call during the step phase of the component when in this state
 40      * @param {Function} onDraw The function to call during the draw phase of the component when in this state
 41      */
 42     this.createState = function(){};
 43 
 44     /**
 45      * Removes the state.
 46      *
 47      * No action is taken if the tag does not refer to a valid state.
 48      * @param {String} name
 49      */
 50     this.removeState = function(){};
 51 
 52     /**
 53      * Begins the state machine execution loop from the given state.
 54      *
 55      * If begin state does not refer to a valid state, no action is taken.
 56      * If done in the middle of a state loop function, any queued 
 57      * function calls are cancelled.
 58      * @param {String} name
 59      */
 60     this.execute = function(){};
 61 
 62     /**
 63      * stops all current execution.
 64      *
 65      * If done during a state loop, all remaining state loop functions 
 66      * that would have executed are cancelled.
 67      */
 68     this.halt = function(){};
 69 
 70 
 71 
 72     /**
 73      * Returns the current state tag. If no execution state is active, the empty string is returned.
 74      * @type {String}
 75      */
 76     this.state = "";
 77 
 78     /**
 79      * Returns whether or not the machine is in a halted state.
 80      * @type {Boolean}
 81      */
 82     this.halted = false;
 83 
 84 
 85 
 86 
 87 
 88     return this;
 89 }
 90