Syntax Summary
==============

program:
--------
statement_list

statement_list:
---------------
statement statement ... statement

statement:
----------
identifier event_parameter_list :
case integer event_parameter_list :
case identifier event_parameter_list :
compound_statement
if prim_expr statement
if prim_expr statement else statement
while prim_expr statement
for ( statement ; expr ; statement_list ) statement
try compound_statement catch compound_statement
switch prim_expr compound_statement
break
continue
identifier event_parameter_list
nonident_prim_expr identifier event_parameter_list
nonident_prim_expr = expr
nonident_prim_expr += expr
nonident_prim_expr -= expr
nonident_prim_expr ++
nonident_prim_expr --
;

compound_statement:
-------------------
{ statement_list }

expr:
-----
expr && expr
expr || expr
expr & expr
expr | expr
expr ^ expr
expr == expr
expr != expr
expr < expr
expr > expr
expr <= expr
expr >= expr
expr + expr
expr - expr
expr * expr
expr / expr
expr % expr
nonident_prim_expr
func_prim_expr

func_prim_expr:
---------------
identifier event_parameter_list
nonident_prim_expr identifier event_parameter_list
- func_prim_expr
~ func_prim_expr
! func_prim_expr
identifier :: prim_expr
nonident_prim_expr :: prim_expr

event_parameter_list:
---------------------
prim_expr prim_expr ... prim_expr

prim_expr:
----------
nonident_prim_expr
identifier_prim
prim_expr :: prim_expr

nonident_prim_expr:
-------------------
$ prim_expr
nonident_prim_expr . identifier
nonident_prim_expr . size
nonident_prim_expr [ expr ]
string
integer
float
( number number number )
game
level
local
parm
self
group
( expr )
- nonident_prim_expr
~ nonident_prim_expr
! nonident_prim_expr
NULL
NIL

number:
-------
float
integer


Automatically started scripts
=============================

1) maps/mapname.scr
A level script is associated with each map, and is loaded and started at the start of that map (and not for subsequent starts from a saved game). This script is used for triggering all map related dynamic objects such as doors, elevators, AI, etc. maps/mapname.scr corresponds to maps/mapname.bsp. A level script is optional.

2) maps/mapname_precache.scr
A level precache script is associated with each map, and is loaded and started whenever the map is loaded (even from a saved game). This script is used for precaching map specific resources. maps/mapname_precache.scr corresponds to maps/mapname.bsp. A level precache script is optional.

3) Scripts in the anim directory are executed to carry out animation behavior of AI characters. Which script is executed is determined by internal AI state or scripts such as global/shoot.scr.

Threads
=======

A thread executes commands in a script one at a time in order. Multiple threads can exist. The automatically started scripts start execution with a single thread at the start of the file.

All threads belong to a group of threads, denoted "group". The current thread is denoted "local". The group of threads that a thread belongs to will be discussed in the next section.

Methods of creation of threads
------------------------------

1) Automatic
The new thread initially is the only thread in its group.

2) Command: thread label
The new thread belongs to the same group of threads as the original thread.

3) Command: thread filename::label
The new thread initially is the only thread in its group.

4) Command: object thread label
The new thread initially is the only thread in its group.

5) Command: object thread filename::label
The new thread initially is the only thread in its group.


Predefined object references
============================

1) game
Refers to the unique game object which maintains its state across levels. Only primitive values (integers/floats/strings/vectors) will persist across levels.

2) level
Refers to the unique level object which maintains its state for the duration of a level.

3) local
Refers to the thread executing the current command.

4) parm
Refers to the unique parm object which can be used to pass parameters to new threads.
Note that any use of this variable could be coded "better" by using parameters in the creation of new threads.

5) self
Refers to the object that the thread is processing for. This object is the same for all threads in a group of threads.

6) group
Refers to the object representing the group of threads the thread executing the current command belongs to.


self object
===========

The "self" object has its value set at the creation of a group of threads. The following are some such situations:

1) Automatically started scripts
self is NULL for level scripts. self is the character for animation scripts.

2) Command: thread label
Since the new thread has the same group as the original thread, self in the new thread is equal to self in the original thread.

3) Command: thread filename::label
self in the new thread is set equal to self in the original thread.

4) Command: object thread label
self in the new thread is set equal to object.

5) Command: object thread filename::label
self in the new thread is set equal to object.

6) If a thread is initiated in response to an event of an object, then self is set equal to this object.


switch (selection) statement
============================

Standard usage
--------------

switch (expr)
{
label1:
statement
...
statement
break

label2:
statement
...
statement
break

case 0:
statement
...
statement
break

case 1:
statement
...
statement
break

default:
statement
...
statement
break
}

The expression expr is evaluated and cast to a string. Code execution tranfers to the matching label or to the optional default label if there is no match. The case prefix is required for integers, and optional for strings. The break command makes the switch statement finish.


if (conditional) statement
==========================

Standard usage
--------------

if (expr)
statement

if (expr)
statement
else
statement

if (expr)
{
statement
...
statement
}

if (expr)
{
statement
...
statement
}
else
{
statement
...
statement
}

arithmetic binary operators
===========================

precedence
----------

The operators are listed in order of later evaluation to sooner evaluation:

||
&&
|
^
&
== !=
< > <= >=
+ -
* / %

descriptions
------------

|| logical or (outputs 0 or 1)

&& logical and (outputs 0 or 1)

| bitwise or (outputs integer)

^ bitwise exclusive or (outputs integer)

& bitwise and (outputs integer)

== equality (outputs 0 or 1)

!= inequality (outputs 0 or 1)

< less than (outputs 0 or 1)

> gretaer than (outputs 0 or 1)

<= less than or equal (outputs 0 or 1)

>= greater than or equal (outputs 0 or 1)

+ plus (numeric or string types)

- minus

* multiply

/ divide

% modulus (remainder after division by integer)


while statement
===============

Standard usage
--------------

while (expr)
statement

while (expr)
{
statement
...
statement
}

At the start of a cycle of the loop the expression expr is evaluated and cast to boolean (true or false). While the expression evaluates to true the statement(s) are executed.
A continue placed inside such a loop will move the code execution point to the end of the current cycle of the loop.
A break placed inside such a loop will terminate execution of the loop (code execution will continue sfter the loop).

Example
-------

local.n = 1
while (local.n <= 10)
{
println local.n
local.n++
}


for statement
=============

Standard usage
--------------

for ( statement1 ; expr ; statement2 )
statement

for ( statement1 ; expr ; statement2 )
{
statement
...
statement
}

At the start of execution of this entire statement, statement1 is executed. At the start of a cycle of the loop the expression expr is evaluated and cast to boolean (true or false). While the expression evaluates to true the statement(s) are executed. At the end of each cycle of the loop, statement2 is executed.
A continue placed inside such a loop will move the code execution point to the end of the current cycle of the loop.
A break placed inside such a loop will terminate execution of the loop (code execution will continue after the loop).

Example
-------

for (local.n = 1; local.n <= 10; local.n++)
{
println local.n
local.n++
}

Vectors (coordinates)
=====================

Standard usage
--------------

( number number number )

Example
-------

(1.1 23.2 -15.5) is preferable to "1.1 23.2 -15.5" since the latter is a string which would be cast to a vector each time it is interpretted as a vector.

Note
----

Due to a parsing deficiency, vectors like (-1 2 3) should be written ( -1 2 3). That is, a space must be between the "(" and the "-".

Targetname operator $
=====================

The targetname operator $ converts a string to the object with targetname equal to that string.

Examples
--------

$my_targetname // object with targetname "my_targetname"

local.t = "my_targetname2"
$(local.t) // object with targetname "my_targetname2"

Variables
=========

Any object in the game can have variables in its variable list.

Examples
--------

game.a // variable a for game object

level.b // variable b for level object

local.c // variable c for local object

parm.d // variable d for parm object

self.e // variable e for self object

group.f // variable f for group object

$my_targetname.g // variable g for object with targetname "my_targetname"

self.enemy.health // for this to make sense self.enemy would be an object and self.enemy.health would be the health variable of this object


Arrays
======

Standard usage
--------------

nonident_prim_expr [ expr ]

nonident_prim_expr is a non-identify primitive expression and expr is an arbitrary expression.
nonident_prim_expr [ expr ] interprets nonident_prim_expr as an array and accesses the element at the position at which expr evaluates to.
Indexing of arrays can be by integers or strings.

Types of arrays
---------------

1) Constant array
Created by expression of the form entry_1::entry_2::entry_3:: ... :: entry_n
Constant arrays start their indexing at 1.
Once created a constant array can not be changed but it can be read for its values.

2) Hash table array
Unitialised entries evaluate to NIL. Any new entry can be set.

3) Targetname array
Created by the $ targetname operator if more than one entity exists for that targetname.
For example, $player is an array if more than one player is in the game.
Targetname arrays start their indexing at 1.

Examples
--------

println local.n[10] // prints the element at position 10 of the local.n array

local.n[1][3] = 10 // sets the element at position (1, 3) of the local.n array equal to 10 (Hash table array)

local.n = hello::world::this::is::a::test::123 // consant array
println local.n[1] // prints hello
println local.n[7] // prints 123
println local.n[8] // results in Script Error: const array index '8' out of range
println local.n[hello] // results in Script Error: const array index '0' out of range

local.n[hello][world][5] = 23
local.a = local.n[hello]
local.b = local.a[world]
println local.b[5] // prints 23

for (local.n = 1; local.n <= 10; local.n++)
println game.stats[game.stats_name[local.n]] // print out element in game.stats array at position game.stats_name[local.n]

local.a = (a::b)::c
println local.a[1][1] // prints a
println local.a[1][2] // prints b
println local.a[2] // prints c


Vector Examples
---------------

Vectors are accessed like arrays in the indices 0, 1, 2.
A vector could be set like
local.my_vector = (10 -2 60.1)

Then this vector could be accessed like:
println local.n[2]
which would print 60.1 to the console.

Example
-------
$player.origin += (5 6 7) // offset the player's origin by (5 6 7).


Make Array Example
------------------

local.Path1 = makeArray
t1 300 10 200
t2
t3
t4
t5
t6
t7 NIL 10 200
t8
t9
t10
t11
t12
t13
t14 0 10 200
endArray

println local.Path1[1][2]
println local.Path1[1][3]
println local.Path1[1][4]
println local.Path1[1][5]
println local.Path1[14][1]
println local.Path1[15][1]
end

results in:

300
10
200
NIL
t14
NIL

printed to console.


Automatic casting
=================

If a parameter in a statement is required to be of some type, then an automatic cast will be attempted.

Accessing characters of a string
================================

Characters of a string are accessed by the [] array operator. Indexing starts at 0.
For example, "abc"[2] evaluates to the string "c".
There is no character type, so characters are just strings of length 1.[/]