Scripting: Difference between revisions

From Archon Wiki
Jump to navigation Jump to search
(Created page with "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 s...")
 
No edit summary
Line 1: Line 1:
Scripting
Archon scripting is a much expanded iteration on the original STUB scripting.  The original documentation is included/updated below.


Archon scripting is as much expanded iteration on the original STUB scripting.  The original documentation is included/updated below.
== Script Syntax ==
 
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.
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.
Line 21: Line 19:


FUNCTION Tick( side )  
FUNCTION Tick( side )  
{
}
or
FUNCTION Process( TType data )
{
{
}
}
Line 31: Line 35:
Note that a call to return will skip any further processing in the function and exit with the value immediately.
Note that a call to return will skip any further processing in the function and exit with the value immediately.


Macros
=== Macros ===


You can define macros - textual substitutions - in the same way as for C.  Note that #/## notations are not supported.  E.g.
You can define macros - textual substitutions - in the same way as for C.  Note that #/## notations are not supported.  E.g.
Line 78: Line 82:
{
{
<execute if condition true>
<execute if condition true>
}
else if( <condition 2> )
{
<execute if condition 2 true>
}
}
else
else
{
{
<execute if condition false>
<execute if neither condition false>
}
}


Line 115: Line 123:


+ There is no concept of ELSE IF(…) in the language. You can only pair a single ELSE with any IF statement.
+ 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.
+ 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:
+ Single line IF and FOR result expressions are not allowed:
Line 159: Line 154:
filename as provided
filename as provided


Singletons
=== 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.
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.
Line 165: Line 160:
int gArray[3][2]={0,1,2,3,4,5} ;
int gArray[3][2]={0,1,2,3,4,5} ;


The char Type
=== The char Type ===


You can define and use arrays of chars as strings.  This functionality is still under constructionAnd example is:
You can define and use arrays of chars as strings.  Versions of the sprintf and strcpy functions existThese functions are safe, in that they cannot exceed the bounds of their output strings.


char name[32] ;
char name[32] ;
char work[32] ;
int someValue ;


name[0] = 48 ;
someValue = 99 ;
name[0] = 'A' ;
PrintStringLiteral( name ) ;
PrintStringLiteral( name ) ;
sprintf( work, "%d", someValue ) ;
strcpy( name, work ) ;


Limitations to note:
Limitations to note:


char arrays must be multiples of 4 in size
char arrays must be multiples of 4 in size
multidimensional string arrays are not supported (possible they may be)
multidimensional string arrays are not supported (possible they may be).
character notation (e.g. ‘A’) is not implemented, but will be.

Revision as of 16:05, 22 October 2015

Archon scripting is a 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 ) { }

or

FUNCTION Process( TType data ) { }

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.

  1. 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 if( <condition 2> ) { <execute if condition 2 true> } else { <execute if neither 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.

+ All atomic variables are signed integers.

+ 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. Versions of the sprintf and strcpy functions exist. These functions are safe, in that they cannot exceed the bounds of their output strings.

char name[32] ; char work[32] ; int someValue ;

someValue = 99 ; name[0] = 'A' ; PrintStringLiteral( name ) ; sprintf( work, "%d", someValue ) ; strcpy( name, work ) ;

Limitations to note:

char arrays must be multiples of 4 in size multidimensional string arrays are not supported (possible they may be).