StatefulComponent - acrimi/Raven GitHub Wiki

StatefulComponent is an abstract component meant to be implemented by other components that represent a sequence of states. It cannot be applied directly to an entity, it can only be inherited from. By default it contains two states, "inactive" and "active", but additional states can be configured to take place between those two. Requesting the component to activate or deactivate will cause it progress through the states until it reaches the appropriate "active" or "inactive" state, respectively. Each state can have a duration that will cause it to move to the next state after enough time has elapsed. States with an infinite duration will remain active until the component is manually moved to the next state.

Transitions between states will fire events of the format "{componentName}{StateName}". The "active" and "inactive" states additionally provide support for alias event names that will be fired in addition to the standard events. There are also two special events that are fired when exiting either the "active" or "inactive" states of the format "{componentName}Exit" and "{componentName}Enter", respectively. These events will fire even if no enter or exit states are configured.

Configuration

When used inside the components block, the initial state of the component can be configured with the following parameters:

Key	Type	Description
duration	float	The duration, in seconds, of the "active" state for this component. Defaults to -1, which is treated as infinite duration.
enterStates	(string|object)[]	An array of states that will be passed through when going from the "inactive" state to the "active" state. Each state can be defined as either an object with a single key value pair corresponding the state's name and duration, or as a string representing the state name. States defined as a string will have an infinite duration. The array values can be heterogenous.
[stateName]	float	The key represents the name of this state and the value is the duration, in seconds. For infinite duration, use a value of -1
exitStates	(string|object)[]	An array of states that will be passed through when going from the "active" state to the "inactive" state. Each state can be defined as either an object with a single key value pair corresponding the state's name and duration, or as a string representing the state name. States defined as a string will have an infinite duration. The array values can be heterogenous.
[stateName]	float	The key represents the name of this state and the value is the duration, in seconds. For infinite duration, use a value of -1
initialState	string	The state the component will start in. Must be one of "inactive", "active", or any of the custom states provided via enterStates or exitStates. By default, the component will start in the "inactive" state. Setting a different initial state will not cause events to fire for entering that state.
isActive	boolean	Equivalent to passing "active" to initialState. Defaults to false.

Examples:

"StatefulComponent": {
  "duration": 1.8,
  "enterStates": [
    {
      "enterTransition": 0.5
    },
    "preActive"
  ],
  "exitStates": [
    {
      "exitTransition": 1
    },
    "preInactive"
  ],
  "initialState": "enterTransition"
}

"StatefulComponent": {
  "isActive": true
}

Properties

The following properties are readable by property accessors (eg render state and persistence definitions):

Key	Type	Description
isActive	boolean	Whether or not the current state is "active"
isInactive	boolean	Whether or not the current state is "inactive"
state	string	The name of the current state
progress	float	The percentage, from 0 to 1, of how much time has elapsed for the current state relative to its duration (elapsedTime / duration). If the current state has an infinite duration, this value is always 0.