Stateful Object Spec Oracle

Jump to: navigation, search


See also: States System

The Stateful Object Spec Oracle is used in conjunction with the Asset Library's ability to run a command on the instantiation of an asset, to create "stateful objects".


Stateful objects are object(s) that have a corresponding state (such as "open" or "closed") that manipulates them in some way. Once a developer establishes a Stateful Object Spec, a game's designers can easily (as simple as a right-click menu) loosely couple stateful objects and stateful systems to each other, to achieve complex interactions without requiring a single line of code.

As implied by the system's name, the Stateful Object Spec Oracle uses the Spec System to create the template for a specific type of stateful object. Where possible, the GUI for working with Stateful Object Specs mimics that of the State Editor GUI (see States System).

What problem(s) does this solve?

What problems(s) does this not solve?


Stateful Object Spec

The Stateful Object Spec represents a generic definition of a stateful object, which may be used from an Asset Library command for a particular asset (or asset grouping) to give the instantiations a state. The spec uses tokens in place of what are normally hard-coded values, such as a GUID which is of course an unknown until an instantiation is made.


The Stateful Object Spec supports the inclusion of tokens that are dynamically replaced when the Asset Library command runs.

There are two types of tokens, differentiated by the symbol preceding the token name, # or ? .

Token Prefixes
number sign (#
Tokens preceded by a number sign (#) are meant for literal replacement by the Token's Value specified by the Library Command.
Example: #foo='bar' will replace occurrances of #foo in the stateful object spec with bar
question mark (?
Tokens preceded by the question mark (?) are meant to search the instantiations created by the Library for a match on the Token's Value to the asset FQN (i.e. pathfindingnode.pfn, Optionally, the libraryIndex may be specified instead of the assetFQN. Once a match is found, that instantiation's GUID is used to replace the Token.
Example: ?foo='pathfindingnode.pfn' will replace all occurrances of ?foo with the GUID for the pathfinding node created.

Most Tokens are placed in the state action definitions, but there are a few tokens implicitly supported by the Stateful Object Spec system.

Built-in tokens

There are a number of tokens which are built into the Stateful Spec Oracle system.

Token required/optional Usage Example
?guids required This token is used to insert a list of IDs from the Library using a built-in token supported by the Library($GUIDS). ?guids='$GUIDS'
?statefulobject required This is used to locate the instantiation in the $GUIDS list that is the "statefulObject". The statefulObject may be identified either by the libraryIndex or by the FQN of the instance's asset. The libraryIndex is the number displayed beside the instance's FQN when you hover over the library entry. ?statefulobject='1' or ?statefulobject='sphere.hgm'
#spec required Specifies the spec key of the stateful object spec that should be used to factory the state for the particular library command. #spec='1'
#statetype required Used to specify which concrete implementation of the states system this object should use. By default there is only one concrete implementation which is the "_areaStates" system. #statetype='_areaStates'
#statefulobjectclass optional Used to specify the base class to be applied to the node identified by the ?statefulobject token. The specified class must inherit from the clean engine class _statefulObject. #statefulobjectclass='yourClass'
#secondarystatefulobjectclass optional Used to specify the base class to be applied to the nodes other than the node indentified by the ?statefulobject token. The specified class must inherit from the clean engine class _secondarystatefulobject. #secondarystatefulobjectclass='yourClass'
#statename optional The state created for a stateful object may have a name specified by the library command using the #statename token. The system then munges the specified name if necessary to create a unique name. State names should not be confused with the idea of the current value of a state. #statename='bar'
#glom optional This optional token allows the specification of 1 or more nodes to which one or more classes should be glommed. GlomOperations are semicolon (;) delimited with each operation defined by an identifier (<libraryIndex|FQN|all>) separated by a colon (:) from a comma (,) delimited list of classes to glom onto the node(s). #glom='1:classX;all:classY;sphere.hgm:classZ

Stateful Objects

For the purposes of this system, stateful objects are those objects that have a state created by the States System. During instantiation from the Library, the "stateful object" has the class _statefulObject (or a designated child class) GLOMmed onto it. Any other objects instantiated at the same time as the "stateful object" have the class _secondaryStatefulObject (or a designated child class) GLOMmed onto them.

Library index numbers

When multiple items are grouped together to create a library object, they are added in the order in which they were selected with the selection tool. When a library icon is clicked to add those objects to the world, they are recreated in the same order. You may use the index of an object in that ordered list to specific a particular instance.


Asset Library commands

Stateful Objects Specifications are primarily used in conjunction with /commands run by HeroBlade's Asset Library. This allows for the creation of stateful objects during their instantiation from the Library.

Sample Library Command:
/hestates ?guids='$GUIDS' #statetype='_areaStates' #spec='_DOOR' ?statefulobject='gate_large_ironbound_inner_door.hgm' ?pathFindingNode='pathfinding.pfn'

Sample Library Command using Library Index Numbers:
/hestates ?guids='$GUIDS' #statetype='_areaStates' #spec='_DOOR' ?statefulobject='2' ?pathFindingNode='3'


Invoking the Stateful Object Spec Editor

Invoke Stateful Object Spec Editor

Like all Spec Oracles, the list view of existing specifications may be invoked by opening the HotSpot Menu (CTRL-SHIFT-click in the top left corner of the render window) and selecting the _statefulObjectSpecOracle option from the menu (left).

NOTE: On version HeroBlade, after opening the Hot Spot Menu, select the Tools tab and from there, Stateful Object under the Spec Oracles collapse menu.

List View

Once the list view is displayed, you may edit an existing spec by selecting it and clicking the Edit button or via a double-click on the row. A new specification may be created by clicking the Add button which will create a spec with a "default" name, which you may then edit (right).

Setting Up a New Stateful Object Spec

The creation of a new stateful object spec requires a number of steps:

Unlike the "State Editor GUI", the fields of a stateful object specification are strings allowing for the addition of tokens in place of literal values. Consequently, the stateful object specification GUI is lacking in the dropdowns and other GUI elements that constrain values to only those that are "valid" for a given field. This requires a modest amount of care be taken to ensure that you define the various elements appropriately.

Edit Properities

Edit Properties

A newly created stateful object spec will have several default values set that may be updated using the Properties Sheet located in the editor GUI.

There are three fields to consider here:

Display Name
The display name is the name used by the Library command to identify a spec.
Categories are simply used for organizational purposes, you might have all stateful door specs organized in a DOOR category.
The value which should be considered to be the default value for states instantiated from this spec. (note: the default value must be added to the list of values see below)

Once you have edited the properties, click OK to create the spec and set its default tokens. Then reselect the new spec, click Edit to open it, and select the Tokens tab to continue. You might be tempted to click on the Tokens tab without first clicking OK and re-opening the spec, but in HeroBlade that won't work.

Add Tokens

Add New Token
Several default tokens are added whenever a new stateful object spec is created (#spec, #statetype, ?guids, and ?statefulobject), additional tokens may be added by clicking the Add(left) button resulting in a new token with a default name being created. Editing the default token is accomplished by either double-clicking or selecting the token's row and clicking the Edit button.
Edit Token

Generally, the only fields available for editing using the "Token Editor"(right) is the _statefulObjectTokenName which should be set to the name of your token (remember your token should have either # or ? prefacing it) and a _statefulObjectTokenHint which is used in the generation of a sample Library command to make the "arcane" syntax something easily edited after cut/paste into the Library's Edit Command dialog.

For example, if a stateful object always instantiates a mesh file, and that mesh is always a "door" mesh of some kind, you might want to change the hint text for the ?statefulobject token. To do this, highlight ?statefulobject, click Edit, highlight _statefulObjectTokenHint in the new window, click in the Value column to place the edit cursor, change the hint text to:

?statefulobject='door_assetname.hgm' and click OK.

For a list of tokens, see the Built-In Tokens chart above.

Add Values

Two values are automatically added to all states and need not be included in the stateful object specification's list of values, they are; * and NOTSET. Remember to add the default value you specified on the "Properties Sheet" for the stateful object specification. The namespace for values is local to a particular state, meaning you may use a value "CLOSED" to mean two different things for two different states.

Add New Value
The values that will be valid for a given stateful object specification should be added using the Add button located on the "Values Tab" (left).
Edit Value
Clicking the Add button will add a new value with a default display name, you can edit the default value by double-clicking on it or by selecting it and clicking the Edit button to invoke the "Value Editor" (right).

The value created when the Add button was clicked should be edited using the "Value Editor" to have a meaningful name replacing the default name (defaultValue + (optionally) a number of uniqueness).

For example, if the default value is CLOSED, add this value by selecting the Values tab, clicking Add to open the Value Editor, clicking the _statefulObjectValidValue row, left clicking in the Value column to position the edit cursor, changing the value to CLOSED, and clicking OK.

In HeroBlade the new value will show up initially with the name defaultValue instead of with the name CLOSED. Click on that row, select Edit, and click OK to dismiss the Value Editor, and the name will update to CLOSED.

Repeat this sequence to add each of the possible state variable values for your stateful object. You probably don't need separate values for transient states (e.g. OPENING and CLOSING for a door); use Transitions (below) instead.

Add Transitions

Add New Transition
A new transition may be added by clicking the Add button located on the "Transitions Tab"(left), which will result in a new transition being added to the list with default values set for the From, To and Action List to execute.
Edit Transition
Editing a Transition is accomplished by either double-clicking the transition or selecting the transition and clicking the Edit button to invoke the Transition Editor.

For each state change you want to allow, add a Transition and set _statefulObjectFromState and _statefulObjectToState to valid Values you defined in the previous step. Set _statefulObjectActionList to a name you'll use later to define what happens during the state change (for example, a transition from a door's CLOSED state to its OPENED state might use _statefulObjectActionList of OPENING; the name can be anything that makes sense to you).

In HeroBlade you can edit the default values at the time the transition is added, but the values will show up as NOTSET and NOTSET until you click on that row, select Edit, and click OK.

The "Transition Editor"(right) allows for the editing of the values for the From, To, and Action List to execute for a given transition. Remember, the From and To values should be added to the Values list (see Add Values above) and the Action List should be added to the list of action lists (see Add Action Lists below)

Add Action Lists

The Spec Editor does not automatically create Action Lists entries for the actions you defined in your Transitions; you have to add an Action Lists entry for each of these using the same name you used on the Transitions panel. For example, if you specified a transition that uses an action list of CLOSING, you need to explicitly add a CLOSING action list on the Action Lists panel.

Add New Action List
A new action list may be added by clicking on the Add button located on the Action Lists Tab(left), which will open the Action List Editor GUI and create a new action list with a default name.
Edit Action List
The Action List Editor GUI has two tabs, the Property Sheet and the Actions tabs. To change the name of the action list, click the Property Sheet tab, enter the desired name into the _statefulObjectActionListName field, and click OK.

In HeroBlade the name will show as DEFAULTACTIONLIST in the Spec Editor until you Edit the new spec again and click OK.

Add Actions

Add New Action
A new action may be added to an action list on the Actions tab of the Action List Editor GUI(left).
Choose Action Type
Clicking the Add button will invoke the State Action Type Chooser GUI, allowing you to select the type of action you wish to add (right).

The newly created action will have its value set to defaults which may be edited by either double-clicking the element or selecting it and clicking the Edit button to invoke the Action Editor for that state action type (see below)

In HeroBlade the changes you make to entries in an action list might not show up properly until you completely close the action list and then re-Edit the list and Edit / OK individual list items.

Caution: The stateful object actions by their nature accept whatever string specified for their field values, this allows for the use of tokens but eliminates any useful type of error checking that might be generically made. Consequently, the GUI does not protect you from inputting bad data.

Add New Action
The call script action calls the script specified, passing in the data from the field _statefulObjectActionData. The script call is performed in the specified local GOM (the client, current areaserver, or both).

Tokens may be placed in the following fields:


The PlayFX action is not currently implemented for stateful object specifications.

Add New Action
The PlaySound state action plays the sound segment specified in _statefulObjectActionData at a position of a target node.

Tokens may be placed in the following fields:

Add New Action
The SetField state action sets the field specified on a target node to a specified value. This action makes use of autoconversion and consequently the specified field's type must be one to which string will autoconvert.

Tokens may be placed in the following fields:

Add New Action
The SetProperty state action sets the Property specified on a target node to a specified value. Properties have specific formating for the different property types, you must ensure the value you specify is in the appropriate formating for the destination property (see the properties panel in HeroBlade)

Tokens may be placed in the following fields:

Add New Action
The SetState state action sets the State specified to a specified value. You must be careful to make sure the state name and value specified will exist at the time the stateful object is created.

Tokens may be placed in the following fields:

Need clarification: what is a state name? Doesn't each stateful object have only one state variable? If not, how are more created, and named, and initialized?

Add New Action
The Transform state action does an interpolation on the position/rotation/scale as offsets from their server values.

Tokens may be placed in the following fields:

Need clarification: are offsets relative to the original position or rotation of the object, or relative to its current position or rotation? For example, if a door swings open by a rotation transform of 90, does it close by a rotation transform of 0 or by a rotation transform of -90? It looks like 0 rather than -90 is correct.

Need clarification: how is _statefulObjectTransformIsReversible used? It appears to immediately reverse the transform once it reaches final position.

Add New Action
The UnmarshalData state action unmarshals a string created with the marshalUtils utility script to a specified target node in the specified local GOM. It is unlikely you would properly construct the marshal string properly formated by hand so you almost always need to copy paste the string produced into the editor.

Note: If HeroEngine is expanded to include field level reflection this state action may be totally unnecessary.

Tokens may be placed in the following fields:

Advanced usage

Create an Asset Library command for a Stateful Object Spec

You can add stateful objects to the Asset Library, simplifying future placement in areas. If you've started with Clean Engine and a stateful object is the first thing you're adding to the library, you might want to first add a library category for your game (call it YourGame for example). You might want to organize your stateful objects under a separate tab within each library category. The discussion below presupposes you have an asset library category set up, and a Stateful Objects tab created for that category.

Begin by adding your object or object grouping to the library under your Stateful Objects tab. To do this for a single mesh in the repository, select the tab and right click in the white space of the right-hand pane. Select Add Item... from the pop-up, and browse to your object's geometry in the repository, then click OK. The object will appear in the pane, with a "NO ICON" graphic. Although your object is now in the library, and organized under the Stateful Objects tab, it is not yet a stateful object.

Add Library Command
To make the library create a stateful object instead of just a mesh, add a command line to the object's library entry by right clicking on the object's icon (left).
Enter Command
Select Edit Command... from the pop-up menu to bring up the Enter Commands GUI (right).

The command for a stateful object will always be /hestates. The command is followed by 4 required tokens and their values as single quoted parameters (order does not matter) as well as any other tokens specified by the stateful object spec that is to be used. You can type this in manually, or copy and paste it using the Lib CMD button of the Stateful Object Spec Editor (see Generate Sample Library Command below).

Required tokens
The value for ?guids is always the Library's $GUIDS token, this causes the library to insert a list of IDs for the nodes generated. ex. ?guids='$GUIDS'
The value of the ?statefulobject token should be the file name of the "main" asset of an asset grouping, which is used to find the GUID of that asset and inserted in the token's place. ex. ?statefulobject='gate_large_ironbound_inner_door.hgm
The value of the #spec token may either by the specKey of a statefulobject spec, or the display name for the desired spec. ex. #spec='_DOOR'
The value for the #statetype token is normally going to be _areaStates, until such a time as another state system is created (then you will have an actual choice to make). ex. #statetype='_areaStates'

Any additional tokens (and optionally the advanced tokens) may be added to the command string, remembering that tokens prefaced by # are literal replacements and those prefaced by ? are replaced by the ID of the asset matching the specified file name.

Generate sample Library command

Spec Generated Sample Command
The Stateful Object Spec is capable of generating a sample library command. On the Tokens tab of the Stateful Object Spec Editor, click the Lib CMD button located in the bottom right corner to invoke the Library Command GUI with the generated command. This command may be copy/pasted into the Library's Edit Command dialog and then edited to update any parameter values that need to be changed.

In many cases, the generated command will need only the slightest modification the most common of which is replacing the ?statefulobject= token's value with the name of the proper asset. Under normal usage, the tokens #spec, #statetype and ?guids require no changes.

Example command

/hestates ?guids='$GUIDS' #statetype='_areaStates' #spec='1' ?statefulobject='gate_large_ironbound_inner_door.hgm' ?pathFindingNode='pathfinding.pfn'

A complex command:

/hestates ?guids='$GUIDS' #statetype='_areaStates' #spec='1' ?statefulobject='gate_large_ironbound_inner_door.hgm' ?pathFindingNode='pathfinding.pfn' #opensound='world\segment\demoland\resources\audio\sfx\Sfx_OpenChomper.sgt' #closesound='world\segment\demoland\resources\audio\sfx\Sfx_CloseChomper.sgt' #openrotationaloffset='(-45,0,0)' #openpositionaloffset='(0,0,0)' #openscaleoffset='(0,0,0)' #opentransformduration='0:00:05.000' #closetransformduration='0:00:05.000'

The States System

A Stateful Object Specification is absolutely useless without the states system backing it up mechanically. Consequently, users of the Stateful Object Specification system should have a passing familiarity with the States System.

Personal tools