559 lines
13 KiB
Text
559 lines
13 KiB
Text
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.
|