Specification of TangoSim Script Language (Last update: Tue Jan 28 12:16:02 EST 1997)

1. Purpose of the script language

The TangoSim script language and applciation protocols are used to describe
C2 demo that consists of C2 participants such as Command Control (CC), Radar
Operator (RO) and Weather Station (WS) and represents a command and control
scenario defined by VRI. It is together used with a simulation engine and a Tango runtime
system where the simulation engine parses and schedules the script execution and
Tango runtime facilitates the event communication among distributed participants 
and applications running on different workstations over a network.
Further detailed description about the demo execution platform
and architecture is given in a separate document. The script language is the 
interface that separates the scenario description and event execution.
With the scripting language, a script writer can describe a C2 scenario simulation
in a more abstract and flexible way so that no execution and platform details are necessary 
to make up a simulation.

2. The Scripting Language

TangoSim Script language consists of a sequence of command lines (separated by '\n'):
In addition, a command line can also span more than one lines by using the continuation
character '\' before '\n':

<script file> ::= <command line>\n
	      <command line>\n
	      ...
	      <command line>\n

A command line is the basic language unit that describes an event
to be interpreated by the simulation engine and eventually to be
sent to the application that understands the protocol it defines
and executes the event.

<command line> ::= <timestamp>:<statement>
<command line> ::= <label>

<lablel> ::= :<identifier>

An <identifier> consists of a sequence of characters, 
where no space and ',' is allowed in the sequence>.

<timestamp> is an non-negative integer that represents the elapsed time in seconds
relative to the time when the most recent statement was executed or relative to the starting
time of the simulation (thread) if it is the first statement to execute.

A statement consists of the main script language syntax:
<statement> ::= <variable definition>|<branching statement>|<new thread statement>|<application statement>

Variable definition statement defines or undefines a untyped variable that will be used
in a branch statement.

<variable definition> ::= [define|undefine] <variable name>
<variable name> ::= <identifier>

A branching statement checks the existance of a variable to decide if an additional thread of
(other than the current one) a sequence of command lines needs to be started. It is usually
used together with a new thread statement to mimic a if-then-else branching.

<branching statement> ::= [ifdef|ifndef] <variable name> <statement>

New thread statement starts another thread of a sequence of command lines, to run simultaneously
with the current thread that starts the new thread. By default, the first line in a script file
starts a default main thread without the use of a new thread statement. 

Note the use of a new thread statement inside a branching statement is not exactly as
the if-then-else or goto statement found in most programming languages. Even a new thread is started, 
the thread that started the new thread will continue to execute until a thread label or end-of-file
is encountered.

<new thread statement> ::= start <identifier> 
<new thread statement> ::= start <identifier> , <timestamp>

The first form of new thread statement immediate starts command at the label <identifier>,
while the second one starts it in <timestamp> seconds from the time when this statment is
executed.

Application statement identifies what application will recieve the current
event to be sent by the simulation engine.

<application statement> ::= <identifier>,<application protocol>

where <identifier> is the application name that uniquely identifies the application
that will execute the event.

<application protocol> is the convention that the particular application defines.
It is the application's responsibility to define the event protocol that the application
can understand and execute. The simulation engine will only be responsible to 
send whatever defined (in string) to the receiving application.

3. Application Protocols

Each application defines its own event protocol to be carried out by the script language.
Currently we have total three applications that are scriptable. They are
GIS, MMail and Chat. More applications are planned. This section only
describes GIS, MMail and Chat.

1). GIS

For 2D GIS applet to be run on RO workstation:
<application name> ::= RO2D
For 2D GIS applet to be run on CC workstation:
<application name> ::= CC2D

For 3D GIS application to be run on RO workstation:
<application name> ::= RO3D

Currently there are five objects used in GIS:
   plane, radar, airbase, ship, map

For plane, there are seven types of events:
newplane,name,[plane|helo],description
     - create a new plane object named 'name' whose type is
	either figter plane ('plane') or a helicopter. 'description'
        specifies any textual description of the object that
        is usually to be displayed as table content.

plane,name,update,position,course,speed,altitude,classification
     - update for the named plane object the current position, course,
       speed, altitude and classification

plane,name,update,position
     - update for the named plane object the current position only, while
       keep other attributes (course, speed, altitude and classification) unchanged

plane,name,update,classification
     - update for the named plane object the current classification only, while
       keep other attributes (position, course, speed and altitude) unchanged

plane,name,hide
     - make the named plane object disappear from the GIS GUI

plane,name,show
     - make the named plane object visible on the GIS GUI

plane,name,remove
     - remove the named plane object from the application

where:
names - a sequence of characters not containing ',' character, leading and 
      	terminating whitespaces will be stripped.
position- determines the geographical position of the 
	plane in the format: nnn nn' nn"[N|S] nnn nn' nn"[E|W]
        where the first nnn nn' nnn" represents the Latitude in degree, minute and second
        and the second one is for Longitude. N/S/E/W reprsents the map direction in 
        north/south/east/west.
        
course  - a floating point number in degrees, ranging 
	from 0 to 360 counting from north direction (clock-wise) to
        represent the heading.

Speed   - a floating point speed in mph to represent the current speed of the plane

altitude - an integer number in feet to represent the plane altitude

classification - friend|foe|UFO for civiliar, enemy and unidentified plane type.

Note 2D and 3D GIS use the same event protocol.

The rest events for GIS are:

newbase,basename,position,description
    - create a new air base object with specified position
newship,shipname,position,description
    - create a new ship object with specified position
newradar,radarname,position,range,description
    - create a new radar object with specified position and detecting range
map,setscale,n
    - set the scale of current map
map,center,position
    - postion the current map
	
2). Media Mail (MMail)
MMail delivers multi-media data on participant's screen. The current
media types that MMail can play/display include: text, image, audio, video.
<application name> ::= MessageBox

<MMail event protocol> ::= [!,][CC][RO][WS],[text|image|audio|video],name,<file location>

Where 

if ! is given, it represents the media will be played immediately, otherwise
it will be placed in an archive list from which the user can manually select to play later.
A played media is always archived in the list for future replay.

CC/RO/WS represent particular participants in the demo. It is usually assumed
that MMail applet will run on all the three stations. The [CC][RO][WS]
field is used to filter out on which workstation(s) the media will be played.

'name' is the text used in the archive list.

<file location> ::= <absolute file path>|<URL>

<absolute file path> is the file path on the local machine where the applet runs,
while URL gives the URL from which the media file can be downloaded via HTTP. 
Due to security reason in NEtscape browser, the URL must be on the same Web server
as the MMail applet is downloaded from.

3). Chat

<application name> ::= CHAT

<CHAT event protocol> ::= <any string>

The Chat applet simply displays whatever given in the string.


4. Examples
 Ask Konrad for examples