Scripting
Scripting
Archon scripting is as much expanded iteration on the original STUB scripting. The original documentation is included/updated below.
Script Syntax
CScript is a simple scripting language, based on the basic C syntax. It provides a simple framework to hook it up to an application, effectively the function call handling.
Even if you have not had experience with scripting languages before, you can begin to add or alter your custom scripts using just a simple text editor (see the Tools section for details on how to help make editing better with syntax highlighting and other useful features).
The team recommend taking a look at the existing scripts to begin to see the way the scripting works. Beginning by tweaking existing scripts is a great way to see something onscreen quickly.
All scripting must be part of a function. A function has the form:
FUNCTION <name>( [<param>], [<param>], ...) { <function body> }
For example
FUNCTION Tick( side ) { }
There is a limit of 12 parameters that can be passed to a given function.
All functions return a value, although you do not have to use it, nor use the return should you decide not to. To return a value use:
return <value> ; Note that a call to return will skip any further processing in the function and exit with the value immediately.
Macros
You can define macros - textual substitutions - in the same way as for C. Note that #/## notations are not supported. E.g.
- define MAX_UNITS 256
Structures
You can define structures in a similar way to C. The format is:
struct <typename> { <contents> }
For example
struct TPos { int x ; int y ; }
struct TObject { int type ; TPos position ; int orders[4] ; }
Access is as per standard C syntax:
TObject obj ;
obj.type = 5 ; obj.orders[0] = 0 ; obj.position.x = 9 ;
Control
You have 2 ways to control the flow of a function. The IF statement, and the FOR statement. All code executed by an IF or FOR statement must be enclosed in a block (within a { } pair).
An IF statement has the form:
if( <condition> ) { <execute if condition true> } else { <execute if condition false> }
Note that the else keyword and following code is optional. Where the condition can be made up of various logical operators such as && (and) and || (or). So an example statement would be:
if( ( a == 10) || ( b == 5 ) ) { }
A FOR statement has the form:
for(<start>; <condition>; <delta>) { }
<start> is a statement initialising the loop variable, <condition> is a check where the loop will continue so long as it is true, and the <delta> statement is a simple expression incrementing (or decrementing) the loop variable. So the statement:
for( i=0; i<10; i++ ) { }
would repeat the code inside the block with i having values of 0 to 9 inclusive, before moving onto any following code.
Key Differences with C
+ There is no operator priority. Brackets are supported and their use recommended.
+ IF statements can can use only a single && or || statement pair when expressions are not contained in brackets. That is:
if( a == 0 && b == 0 && c == 0 ) is invalid
if( (a == 0) && (b == 0) && (c == 0) ) is valid
+ There is no concept of ELSE IF(…) in the language. You can only pair a single ELSE with any IF statement.
+ FOR statements do not allow bracketed terms in the increment (3rd) expression. That is:
for( a = 0 ; a < 10 ; a += (10 – c ) ) is invalid
+ All atomic variables are signed integers.
+ There is no implicit typing of arrays.
int big[10][10] ; int small[10] ;
small = big[3] is invalid
+ String expressions are only allowed as input to function calls. There is currently very limited support for string functionality (see below).
+ Single line IF and FOR result expressions are not allowed:
if(a == 0) is invalid a = 10 ;
if(a == 0) is valid { a = 10 ; }
+ All structures are passed by reference to functions (e.g. any changes to a passed in struct in a function will affect the passed in variable in the calling function). Including Files
You can include other files in your scripts. These can contain useful utility functions, either of your own, or from the game. The syntax for including a file is:
include "filename.bsf"
(note that #include will work also)
The script system will look for the file in the following places in the following order:
same folder as the initial file <campaign folder>/DATA/BATTLE/SCRIPTS <campaign folder>/DATA/SCRIPTS DATA/BATTLE/SCRIPTS DATA/SCRIPTS filename as provided
Singletons
Any variables defined outside a function are considered to be global, singleton variables. These variables are a single instance across all scripts that access them. You can also initialise singletons (but not local variables) this initialiser lists. These should exactly match the number of entries, and do not support sub-lists. E.g.
int gArray[3][2]={0,1,2,3,4,5} ;
The char Type
You can define and use arrays of chars as strings. This functionality is still under construction. And example is:
char name[32] ;
name[0] = 48 ; PrintStringLiteral( name ) ;
Limitations to note:
char arrays must be multiples of 4 in size multidimensional string arrays are not supported (possible they may be) character notation (e.g. ‘A’) is not implemented, but will be.