The easiest way to find out the syntax of a script element for an action is to run CommandSim, execute the action, and look at the resulting XML (see How to Create Scenario Scripts).

This article gives a list of the acceptable elements and specific syntax instructions.

CommandSim recognizes scripts by enclosing information within an XML script tag (element),  for example

<script name="My Script">
     Script tags go here
</script>

The script tag has an optional attribute, comment, in which you can place a text comment.  This is useful for when you preview your script--you can give the instructor a synopsis of the actions, or otherwise indicate what needs special attention:

<script name="My Script" comment="Put synopsis here">
     Script tags go here
</script>

Within the script tags (i.e., between <script> and </script> ), there are the following elements, and must be in the following order:

Specifying the list of Units

Participating units you want CommandSim to list when an instructor previews a script should be listed within a start units tag (<units>) and a close units tag (</units>), for example,

<units comment="This is a unit comment">
     <unit name="MEDIC 6"/>
     <unit name="RESCUE 10"/>
</units>

Put each unit on its own line, within its own <unit> tag.  Use the attribute name

You'll notice you can include an optional comment as well as an attribute of the units tag.  The comment will be printed in the script preview.

Important: The listing of units is solely for the instructor to see who the designer has said is relevant for the script.  CommandSim ignores this list for the purpose of assigning and executing actions.

Specifying Timeline Elements

The timeline elements are the most important part of a script.  Timeline elements do not necessarily have to be in chronological order in the XML file--CommandSim will sort them by time when it reads in the actions.  The possible elements are:

• stateChange. Tells CommandSim to change the scenario state at the given time.  Example:
  <stateChange stateName="Normal" state="0" time="00:00:01"/>
  the stateName attribute value is the text name of the state.  The state attribute gives the numeric index (starting from 0) of the state.  CommandSim uses the index to determine which state to switch to, not the name--the name is used to show only in the instructor's timeline view.  State indexes are assigned based on the order states appear in the XML file (0 being the first).  The time attribute gives the time (in hours:minutes:seconds format) at which the state should be changed.
• moveUnit. This tells CommandSim to move the specified participant to a specific location at a specific time.  Example:
  <moveUnit toNodeName="N8" toNodeIndex="9" player="TRUCK 10" time="00:00:08"/>
  The attribute toNodeName gives the target location ("node") name, and the toNodeIndex gives the target location's index (starting from 0). Node (location) indexes are assigned based on the order the nodes appear in the XML file (0 being the first). The time attribute gives the time (in hours:minutes:seconds format) at which the move should occur.
• overlayChange. This tells CommandSim to show a custom overlay to a specific participant at a given time.  Example:
  <overlayChange overlayName="Multigas" overlayIndex="0" player="EMS3" time="00:00:00"/>
  The overlayName attribute gives the text name of the overlay (used in the Timeline view for the instructor), but CommandSim uses the overlayIndex (numeric index) to decide which overlay to actually use.  Overlays are assigned numeric indexes based on the order they appear in the XML file, with 0 being the first.  The player attribute tells which player should receive the overlay. The time attribute gives the time (in hours:minutes:seconds format) at which the overlay should appear (or disappear, in the case of none).
• overlayCancel. This tells CommandSim to remove a custom overlay from a specific participant at a given time.  Example:
  <overlayCancel overlayName="Multigas" overlayIndex="0" player="EMS3" time="00:00:00"/>
• instrMoveUnit.  This is like moveUnit, but is the result of an instructor-initiated participant movement.  In a script, whether the participant moves or the instructor is of no consequence, unless the move was delayed (see the instrMoveUnitDelay element, next).  Here's an example:
  <instrMoveUnit wasDelayedMove="false" toNodeName="N0" toNodeIndex="0" player="EMS2" time="00:00:03"/>
  The wasDelayedMove attribute says this move is not the result of a delayed movement--it is an immediate participant move.  CommandSim ignores script actions that occur as a result of delayed movements (when wasDelayedMove="true"). The toNodeName attribute value is the text name of the target node (location), and the toNodeIndex is the numeric index of the target node.  CommandSim uses the name to show instructors in the Timeline view, but uses the numeric index in making the change.  The player attribute gives the name of the participant to move. The time attribute gives the time (in hours:minutes:seconds format) at which the move should occur.
• instrMoveUnitDelay. Use this tag to schedule a delayed move, for example, a unit responding the scene.  An example is
  <instrMoveUnitDelay dSec="30" dMin="0" dHr="0" toNodeName="N7" toNodeIndex="8" player="Squirt2" time="00:00:27"/>
  The attributes give the amount of delay: seconds (dSec), minutes (dMin), and hours (dHr) from the time at which the action is executed (time).  The target node (location) is given by its name (toNodeName) and its index (toNodeIndex), as described in other script tags.  When you run an exercise in CommandSim with a delayed movement, CommandSim will add a script tag instrMoveUnit when the delayed time elapses.  You can safely delete that tag from your script, as CommandSim's script processing ignores it because it will have an attribute wasDelayedMove="true".
• setEnvironVar. Use this tag to change the value of an environment variable.  Environment variables allow you to create conditions that the instructor can change dynamically.  The node visuals (SWF files) must be programmed to respond to environment variable changes (see the article on "Adding Environment and Participant Variables").  An example is
  <setEnvironVar value="3" id="XFireWind" time="00:02:15"/>
  In this example, the environment variable with identifier (id) XFireWind is set to the value of 3, at 2 minutes and 15 seconds.
• setPlayerVar. Use this tag to change the value of a participant ("player") variable.  CommandSim maintains a set of variables for each participant.  The variable values can be different for each participant.  The instructor can then change the values dynamically, either through the Scenario States & Variables panel, or through scripts.  The node visuals (SWF files) must be programmed to respond to participant variable changes (see the article on "Adding Participant Variables").  An example is
  <setPlayerVar value="13" id="SCBATankAir" player="V" time="00:05:10"/>
  In this example, player V's participant variable  with identifier (id) SCBATankAir is set to the value of 13, at 5 minutes and 10 seconds.
• playerVarChg. This tag is generated whenever a player variable changes not due to the instructor.  For example, you might program a piece of equipment to have some value that decays over time, such as air in an SCBA tank.  If you want to change a value via a script, however, we recommend using setPlayerVar.

Here is an example of a well-defined script (though meaningless in terms of content):

<?xml version="1.0"?>
<script name="[Ex01]/Giordanos" comment="This is a comment.">
   <units comment="This is a unit comment">
      <unit name="VV"/>
      <unit name="RESCUE 10"/>
   </units>
   <timeline comment="This is a timeline comment">
      <stateChange stateName="Normal" state="0" time="00:00:01"/>
      <instrMoveUnit wasDelayedMove="false" toNodeName="N0" toNodeIndex="0" player="VV" time="00:00:03"/>
      <moveUnit toNodeName="N8" toNodeIndex="9" player="VV" time="00:00:08"/>
      <instrMoveUnit wasDelayedMove="false" toNodeName="N4" toNodeIndex="5" player="VV" time="00:00:17"/>
      <instrMoveUnitDelay dSec="30" dMin="0" dHr="0" toNodeName="N7" toNodeIndex="8" player="VV" time="00:00:27"/>
      <instrMoveUnit wasDelayedMove="true" toNodeName="N7" toNodeIndex="8" player="VX" time="00:00:30"/>
      <overlayChange overlayName="Multigas" overlayIndex="0" player="VV" time="00:00:00"/>
      <overlayChange overlayName="none" overlayIndex="1" player="VV" time="00:00:25"/>
   </timeline>
   <objectives/>
</script>

What is the "objectives" tag for?

This is unused in the current version.