The basic process for creating scenarios involves defining a visual for each scenario state at each node.  This can add up to a large number of visuals fairly quickly.  In many cases, visual changes among states are minimal.  In other cases, the designer still may not to have the program load a completely new visual when a state changes, as a non-realistic visual disruption will occur.

To solve these problems, CommandSim has a mechanism in which the designer can create a visual (a Flash movie, or a "SWF") that understands how to react to a state change, rather than using the default mechanism that simply loads a new visual.  This minimizes visual discontinuities and allows designers not to have to repeat graphics when no visual has changed.

Whenever a visual for a state is loaded, it can access the current scenario state by calling a function _parent._parent.getStateIndex(). The value returned is the index (number) of the current state, starting with 0 for the first state. If you want the name of the current state, call the function _parent._parent.getStateName(). This returns the exact (string) name of the current state.

When the instructor changes the state, the participant panel looks up to see if there is a new visual for the current node and current state.  If there is a visual, the program loads that visual. 

Note: By default, a visual that knows it can handle multiple scenario states should, when loaded, call the _parent._parent.getStateIndex() function to get the current state and not to assume the visual should start with the first state.  This will ensure that the visual is displaying the correct scenario state for the current situation.

If there is no visual, it finds the state whose index (number) is closest but not exceeding the scenario state index.  For example, suppose you define visuals for states (indexes of) 0 and 3.  If the current state is index number 0, and the state is changed to the third state (index number 2), then CommandSim does not change the visual, it just informs the visual of the state change (through the mechanism defined below).  If the current state is 3 and the state is changed to 2, then CommandSim loads the visual for state 0, since there are no explicit visuals defined for states 1 or 2.  Therefore, in the extreme situation, you can have a visual for scenario state index 0, and none for other scenario states -- when the state is changed, the program will find the closest non-null visual and load that.

If a visual is present for a node and a state change occurs but there is no visual at that node for the new state (so the visual is already loaded), the participant application notifies the visual (SWF) through a method the scenario designer must define in the visual (SWF), called "csEventHandler".  This method takes two parameters.  First, a message name, and second, an optional value.  Here are the potential values for the message name:

Message	Value
stateChange	scenario state (firestate) index

To tell CommandSim that you want a visual to remain in place to handle more than a single state for that node, simply leave the state visual field blank in the corresponding text field for the node and scenario state (in the State Visuals Panel of the Scenario Designer application).

Important: If you have visuals in your scenario that use this mechanism, make sure to uncheck the STRICT MODE setting (State Visuals Panel in the Scenario Designer application).  Under strict mode, the Scenario Designer application will give you an error if a node is defined without an explicit file for the node visual.