MagicBox

Labels and Values

Labels are sample simulation data model elements, and are defined as strings.  A complete list of valid labels can be found on the Simulation Data Model Elements Page.

Each label has a value.  Values can be one of three types:

• Boolean, either true or false
• Number, integer or floating-point
• String, a sequence of characters delimited by a double-quote (") character

In addition to the specific value types listed above, some statements and clauses allow the use of special keywords. 

Comments

Comments are strings that are removed by the rules engine and/or sequencer prior to processing.

There are two types of comments:

• Block comments, strings delimited with /* and */
• Line comments, which begin with // and continue until the end of the line

Statements and Whitespace

Storyboard instructions are defined by a series of statements.  Statements are in many forms, but all statements must be terminated with a semicolon (;).

With the exception of line comments, extraneous whitespace (space and tab characters, line feeds) is ignored.  This means that you can use blank lines, or break a statement across multiple lines, to help organize your storyboard logic.  Whitespace within a quoted string is used as-is.

Conditions

A condition is a logical clause or phrase that is either true or false.  Conditions are used in many statements, and are specified as follows:

(label relation value);

Where relation is a logical relationship between label and value, and can be one of the following:

In addition to the regular values, conditions allow the keyword any to be used as a value.  Conditions using the any keyword will always evaluate to true.

Examples:

• (x = 2);
• (main_power = true);
• (radio_station = "KBBL");

Commands

A command is a control statement.  The following commands are supported:

• freeze;   // sets simulation freeze on
• unfreeze; // sets simulation freeze off
• reset;    // resets the simulation state

Set Statements

A set statement sets a simulation label to a specific value.  Set statements are of the form:

set label = value;

Examples:

• set main_power = true;
• set swing_angle = 20;
• set radio_station = "KBBL";

Advance Conditions

Advance conditions identify simulation conditions that must be met for the storyboard to be considered complete.  Advance conditions are of the form:

advance when condition;

Examples:

• advance when (swing_angle >= 30);
• advance when (main_power = true);
• advance when (selected_gear = "D");

Allowed Actions

Allowed actions identify user actions that should be permitted without remediation.  Allowed actions are of the form:

allow condition;

Examples:

• allow (swing_angle >= 30);
• allow (main_power = any);

Alternate Actions

Alternate actions identify simulation state changes that should be made along with, or instead of, a user action.  Alternate actions are of the forms:

do set label = value instead of condition;

do set label = value when condition;

Multiple alternate actions specified for a single condition are all processed, in top-to-bottom order.  In addition to the standard values for value, the phrase user value can be used.  When user value is specified, it indicates to the rules engine that the value specified by the user action is to be used for the set portion of the statement.

Examples:

• do set left_throttle = user value when (right_throttle = any);
• do set throttle = 50 instead of (throttle >= 45);
• do set station_id = "KBBL-DT" instead of (station_id = "Channel Ocho");

Remediation Statements

Remediation statements specify the message to display for an incorrect user action.  Remediation statements are of the forms:

remediate using message when condition;

remediate using message;

Where message is a string delimited by double-quotes (").  If the when condition clause is not present, this statement is considered to be the default remediation, and will be used when a more specific remediation statement is not available for the user action.  Statement with the when condition clause are called specific remediations.

Examples:

• remediate using "That is the right throttle."
  when (right_throttle = any);
   
• remediate using "That is not the left throttle.";

Initial Sequencing

When a simulation storyboard is loaded, the set statements and commands specified in the initial sequence field are processed in top-to-bottom order.

Once the initial sequence is complete, the rules data is loaded.  If any set statements or commands are specified in the rules data, the are processed in top-to-bottom order before rules monitoring begins.

After all simulation set processing is complete, the rules engine begins monitoring the simulation state and the user actions.

User Actions

When a user performs a specific action, the simulation rules engine analyzes the action and determines the response to perform in the following order:

1. If a specific remediation exists for the action, the action will be cancelled and the remediation message will be displayed.  Otherwise,
2. If an alternate action exists for the action, the action will be modified as defined in the statement(s) before being passed to the simulation.  Otherwise,
3. If the action is part of the advance conditions, the action is passed to the simulation.  Otherwise,
4. If the action is part of the allowed actions, the action is passed to the simulation.  Otherwise,
5. The action is cancelled and the default remediation (if defined) is displayed.