From f0366a49ad728dcee7f830c45a250258e2e2d4a1 Mon Sep 17 00:00:00 2001 From: Steven Koenig Date: Thu, 31 Jul 2008 11:29:45 +0000 Subject: [PATCH] ScriptingManual.xhtml: * Using CSS files of the readme for now, may be changed in later commits * Markup for 10/11 parts complete * Markup for the last one will take a while (~25 to 30 DIN A4 pages) git-svn-id: svn+ssh://svn.gna.org/svn/warzone/trunk@5718 4a71c877-e1ca-e34f-864e-861f7616d084 --- doc/ScriptingManual.xhtml | 4458 ++++++++++++++----------------------- 1 file changed, 1731 insertions(+), 2727 deletions(-) diff --git a/doc/ScriptingManual.xhtml b/doc/ScriptingManual.xhtml index f06d3eb67..bfd334651 100644 --- a/doc/ScriptingManual.xhtml +++ b/doc/ScriptingManual.xhtml @@ -6,2734 +6,1738 @@ - - Comments + + + + AI scripting language manual for Warzone 2100 -

Warzone2100. Script language notes.

- -

Original Author: Pumpkin Studios. 1999

- -

Last Author: $Author$

- -

Last update: $Date$, $Revision$, WRP

- -

Note from Pumpkin Studios: making any modifications to Warzone 2100 will void any technical support open to you. We will not answer questions or help you in any way if you have modified Warzone 2100. Pumpkin Studios and Eidos will not take responsibility for any damage resulting from modifcation of Warzone 2100.

- -

Contents:

- -

Introduction

- -

Comments

- -

Vlo files explained

- -

Slo files explained

- -

Event/trigger concept explained

- -

Triggers explained

- -

String Expressions

- -

Numeric Expressions

- -

Boolean Expressions

- -

Floating-point Expressions

- -

Assignment

- -

If Statements

- -

While Statements

- -

Casts

- -

Custom Functions

- -

Local Variables

- -

Data Types

- -

Script Functions

- -

Debugging Script Functions

- -

Script Function Constants

- -

Script Function Externals

- -

Script Function Callbacks

- -

Specific skirmish/multiplayer notes:

- -

Some of the file below doesn't apply to skirmish scripts! Make your changes to player0.slo and vlo -> player7.slo and vlo.

- -

Introduction

- -

In order for Warzone scripts to function properly two files are required: a file with a .sloextension and a file with a .vloextension.

- -

A .slo file is the main part of the script and holds executable instructions while the .vlo file holds additional variable declarations necessary for the .slo file to function properly.

- -

It is common for a script to deal with new or existing game components such as research topics, structures, unit bodies, propulsions, weapons etc. All these components are defined in appropriate text files like body.txt, structure.txt etc. If you want to use any of these components in your script - in your .slo file - like for example if you want to place certain structures on the map using scripts or enable certain research, you must first make these components available to your script by defining them in a .vlo file.

- -

Roughly said a .slo file is equivalent to a ".c" file and .vlo to a header file in C/C++.

- -

Comments

- -

There are two type of comment for the script language. A multi-line comment is started by the characters /* and finishes with */. A single line comment is started by //.

- -

Vlo Files Explained

- -

When writing a script it is usually known what data (as defined in data .txt files, located in 'stats' folder) will be used in the script, so it's a good idea to start writing the script with a .vlo file.

- -

Vlo files are structured as follows:

- -

script "myScript.slo"

- -

run

- -

{

- -

<variable_definitions>

- -

}

- -


- In the first line a .slo file is attached to this particular .vlo file. variable_definitions that resides inside the curly braces is the heart of every .vlo file, it contains definitions of the data that will be used in the main script part - the .slo file. Each variable definition starts on a new line and is structured as follows:

- -

<variable_name> <variable_type> <variable_value>

- -

NOTE: Available data types are covered later.

- -

For example if you want to have access to certain droid bodies, like "Python" in your script you have to define it in your .vlo file and assign it to a variable of type BODY with some descriptive name, like:

- -

myPythonBody BODY "Body11ABT"

- -

"Body11ABT" is an internal name of the "Python" body used by warzone, it is defined in the body.txt file. Since it is a string it must be put inside quotation marks. All components, be it some research, structure, droid template or a weapon is refered by its internal name in the game and are defined in the appropriate txt data files.

- -

Each variable definition in a .vlo file starts on the new line and ends at the end of the line.

- -

It is also possible to define arrays of some data type. For example if you want to use the following 3 research topics in your script you might want to define them like this:

- -

myResearch[0] RESEARCHSTAt "R-Vehicle-Body11"

- -

myResearch[1] RESEARCHSTAt "R-Vehicle-Prop-Tracks"

- -

myResearch[2] RESEARCHSTAt "R-Vehicle-Prop-Hover"

- -

This defines an array of size 3 of type RESEARCHSTAT.

- -

Slo Files Explained

- -

As already mentioned .slo file is the heart of every script, it is the place for the executable code. Slo files can be devided into 3 main parts:

- -

1.Variable declarations

- -

2.Event and function declaration

- -

3.Executable code

- -

Variables used throughout the script are defined in the Variable declarationspart, with exception of the local variables, which are explained later.

- -

For the .slo file to be able to access variables declared in the .vlo file they must be declared as public variables in the corresponding .slo file.

- -

Coming back to the two examples above you will have to add following lines to the .slo file:

- -

public BODy myPythonBody;

- -

public RESEARCHSTAT myResearch[3];

- -

Keyword publicsignals that the variable is defined in the corresponding .vlo files. Note that unlike in .vlo files variable declarations in .slo files end with a semicolon and unlike in .vlo files it is possible to declare more than one variable of the same type at once.

- -

More generally a variable declaration in a .slo file looks like this:

- -

<storage> <variable_type> <variable_name1> [, <variable_name2> , ...];

- -

storageis one of "public" or "private". Public means that the variable is declared and defined in the corresponding .vlo file.Private means the value is only used in the .slo file. Unlike local variables public and private variables are global variables that can be access from anywhere in the .slo file.

- -

NOTE: All variables are initialized to their default values when created. STRUCTURE/DROID/FEATURE variables are initialized to NULLOBJECT, STRINGs to "", FLOATs to 0.0, INTs to 0, BOOLs to FALSE etc.

- -

Event/Trigger Concept Explained

- -

In Warzone scripts executable code consists of events. An event is a list of instructions activated by some triggerattached to it. Event defines what to do, a trigger defines whento run an event, ie when to execute the code inside an event.

- -

All events are structured as follows:

- -

event <event_name>(<trigger>)

- -

{

- -

<code>

- -

}

- -

Example:

- -

event myFirstEvent(every, 50)

- -

{

- -

console("Hello world!");

- -

}

- -

This piece of code will output "Hello world!" to the game console every 5 seconds. Note that triggers are put inside the round braces after the event name while code that is to be executed resides inside the curly braces. The syntax of the executable code is very close to the C/C++ syntax.

- -

The only difference between a WZ event and a function as used in programming languages like C/C++ is that an event is not called or activated by another function, but rather by a trigger attached to it.

- -

It is always possible to interrupt execution of an event with the exitkeyword, which is a counterpart of the returnkeyword used for functions; exitkeyword does not deactivate an event.

- -

Example:

- -

event myEvent(every, 10) //run every second

- -

{

- -

console ( "this text will be printed every second" );

- -

if( (gameTime / 10) > 60) //did more than a minute pass?

- -

{

- -

exit; //anything that comes after 'exit' will not be executed

- -

console( "this text will only get printed in the first" );

- -

}

- -

}

- -

Events must be defined before they can be referenced. If event definition comes after the place where this event is referenced it is necessary to declare this event beforehand in the Event and function declaration section.

- -

Events are declared like this:

- -

event <event_name>;

- -

Such a declaration reserves identifier used as event name.

- -

Example:

- -

event myEvent; //declaration of the event

- -

...

- -

// another event that references myEvent

- -

event anotherEvent(wait, 10)

- -

{

- -

setEventTrigger(myEvent, inactive); //deactivate myEvent

- -

}

- -

...

- -

// myEvent is defined after being referenced by anotherEvent,

- -

// but it works, since we declared myEvent beforehand

- -

event myEvent(wait, 20)

- -

{

- -

console("It all compiles, because I was declared beforehand!");

- -

}

- -

If myEventwasn't declared before being referenced by anotherEventthen this example would not compile.

- -

Triggers Explained

- -

In WZ triggers are usually simple timers that repeartedly trigger execution of events, but triggers can also be callbacks (special events that occur in the game, like destruction of a building) that are listed and explained later.

- -

Here are avaiable trigger types:

- -

wait, <time>Run the event after delay <time>.

- -

every, <time>Run the event at every <time> interval.

- -

<callback>Run when callback occurs.

- -

<bool exp>, <time>Run the event if <bool exp> is true, checking every <time> interval.

- -

initRun the event when the script starts.

- -

inactiveDo not run the event until a trigger is assigned to it.

- -

NOTE: all time intervals are in 1/10 of a second.

- -

For example every, 10will trigger every second while wait, 50will only activate once: 5 seconds after the game has started. If an event has inactiveassigned as a trigger this event will never execute unless its trigger is reassigned by some other event with setEventTrigger(<event>, <trigger>)function.

- -

NOTE: complete function and callback listings are given below.

- -

A few examples:

- -

// 1. output text to game console every second

- -

event everySecond(every, 10)

- -

{

- -

console("The game has started " + gameTime/10 + " seconds ago");

- -

}

- -

// 2. Code inside this event will never execute unless its event is reassigned later

- -

event inactiveEvent(inactive)

- -

{

- -

console("Someone has just reactivated me!");

- -

}

- -

// 3. CALL_NEWDROID callback with parameters,

- -

event droidBuilt(CALL_NEWDROID, 5, ref newDroid, ref myFactory)

- -

{

- -

console("We got a new droid at coordinates " &

- -

newDroid.x & "-" & newDroid.y );

- -

}

- -

In the last example droidBuiltevent will be triggered everytime a factory belonging to player 5produces a new droid. newDroidvariable refers to the new droid thatb was just built and myFactoryto the factory that build this droid. This example assumes that newDroidand myFactorywere correctly defined in the Variable Declarationssection. For more callbacks see Script Function Callbacks.

- -

NOTE: refkeyword means that a pointer to the provided variable is passed to the interpreter, so that a callback can modify value of the variable.

- -

It is possible to reuse a trigger for more than one event if a trigger is declared in the Event and function declaration. Trigger declaration has following syntax:

- -

trigger <trigger_name> ( <trigger> );

- -

Example:

- -

trigger everySecond ( every, 10 ); //trigger declaration

- -

...

- -

event eventOne( everySecond ) // uses the trigger we declared above

- -

{

- -

...

- -

}

- -

event eventTwo( everySecond ) // uses the trigger we declared above

- -

{

- -

...

- -

}

- -

In this example everySecondtrigger is defined outside of an event. Such a trigger can be reused by its name. Note that trigger declaration ends with a semicolon.

- -

String Expressions

- -

Strings are put inside quotation marks: "some text inside quotation marks is a legal string".

- -

Strings can be easily concatenated using the &operator.

- -

For example: "String1" & "String2"will result in "String1String2".

- -

Strings can be compared using ==operator (case insensitive comparison) or strcmp()function.

- -

Such data types as integers, booleans and floats are automatically converted to strings when it is required, so given the following variable declaration:

- -

private float pi;

- -

private int myInteger;

- -

private string myString;

- -

private bool myBool;

- -

the following line is a valid string expression:

- -

console("value of pi is " & pi & ", value of myInteger is " & myInteger & ",

- -

value of myString is " & myString & ", value of myBool is " & myBool);

- -

Numeric Expressions

- -

Numeric expressions are made up of int variables, numeric constants and functions that return int values, e.g.:

- -

power * 32 - basePower

- -

numDroids(player) + 5

- -

The possible operators are :

- -

+ - * /

- -

Increment and decrement operators can only be applied to the integer variables outside of the expression context:

- -

myInteger++;

- -

myInteger--;

- -

There are also a number of operators that compare numeric expressions to give a boolean

- -

expression :

- -

< > Less than / Greater than

- -

<= >= Less or Equal / Greater or Equal

- -

== != Equal / Not Equal

- -

Boolean Expressions

- -

Boolean expressions are made up of bool variables, the boolean constants TRUEand

- -

FALSEand game functions that return a boolean value e.g.:

- -

not droidSeen and attackDroid

- -

The possible operators are:

- -

and or not == !=

- -

The operators ==and !=can also be used with user defined type variables.

- -

Floating-point Expressions

- -

Floating-point expressions are very similar to integer expressions. There are some differences though: it is not possible to use increment/decrement operators with floating-point variables. The integral and fractional parts of the float constant must be separated by a dot, even if fractional part is 0.

- -

Examples:

- -

myFloat = 1.0 + pi / 2.0 + 3.6;

- -

Floating point expressions can't be mixed with integer or boolean expressions. To use integers or booleans in floating-point expressions they must be cast to FLOATs first.

- -

For more information about casts refer to Casts.

- -

Assignment

- -

The value of a variable or an expression can be assigned to another using the = character,

- -

e.g.:

- -

currentDroid = foundDroid;

- -

index = base + found * 4;

- -

myString = "some text";

- -

myFloat = 2.0 + pi / 2.0;

- -

If Statements

- -

If statements are used to control which bits of code are executed. The simplest form is :

- -

if ( <bool exp> )

- -

{

- -

<code>

- -

}

- -

In this form if <bool exp> evaluates to true then the script code <code> is executed,

- -

otherwise the code is ignored.

- -

Examples:

- -

if ( <bool exp> )

- -

{

- -

<code>

- -

}

- -

else

- -

{

- -

<code>

- -

}

- -

if ( <bool exp> )

- -

{

- -

<code>

- -

}

- -

else if ( <bool exp> )

- -

{

- -

<code>

- -

}

- -

else

- -

{

- -

<code>

- -

}

- -

While Statements

- -

While statements allow <code>to be executed while <bool exp>evaluates to TRUE:

- -

while ( <bool exp> )

- -

{

- -

<code>

- -

}

- -

Casts

- -

Casts convert one data type into a different one. In WZ casts are mostly used to convert float to int, int to float and bool to float. To perform a cast write the required data type in paranthesis.

- -

Examples:

- -

myFloat = (float)myInteger + 2.3 + (float)500 + 500.0;

- -

myInteger = 100 + numPlayers + (int)myFloat;

- -

NOTE: Both (float)500and 500.0represent the same value. When converting FLOATs to INTs fractional part is discarded.

- -

Custom Functions

- -

It is possible to define custom script functions to reuse certain functionality throughout the script.

- -

Function have following syntax:

- -

function <return type> <function name> ( [ <argument type> < argument name> , ... ] )

- -

{

- -

<code>

- -

return ... ;

- -

}

- -

Examples:

- -

function void displayVictoryMessage( int winner )

- -

{

- -

console ( "Player " & getPlayerName(winner) & " has won the game" );

- -

}

- -

function float calculateMinimum ( float f1, float f2 )

- -

{

- -

if ( f1 < f2 )

- -

{

- -

return f1;

- -

}

- -

return f2;

- -

}

- -

Functions look almost identical to their C counterparts, except that the beginning of a function is marked with 'function' keyword.

- -

It is possible to declare function, like with events it is done in the Event and function declaration section:

- -

function void displayVictoryMessage( int winner );

- -

function float calculateMinimum ( float f1, float f2 );

- -

Declared this way it is possible to use a function before it is defined later in the script.

- -

To call a function simply provide its name with parameters in paranthesis:

- -

displayVictoryMessage(0);

- -

...

- -

console("Minimum of 2 and 2.1 is " & calculateMinimum(2.0, 2.1) );

- -

Like in C

- -

return <return expression>;

- -

or for void functions just:

- -

return;

- -

returns execution to the caller.

- -

Local Variables

- -

Local variables belong either to a function or event where they were declared and are not accessible outside of it. Local variables must be declared at the beginning of the function or event. Like public/private variables local variables of the same type can be declared on the same line separated by a comma.

- -

Declaration of a local variable looks as follows:

- -

local <variable type> <variable name> [, <variablename>, ...] ;

- -

Example:

- -

event myEvent(myTrigger)

- -

{

- -

local int count;

- -

<code>

- -

}

- -

function void myFunction()

- -

{

- -

local DROId myDroid1, myDroid2;

- -

local string myString;

- -

<code>

- -

}

- -

Macros

- -

Warzone Scripting language supports nested macros (current max depth is 10).

- -

Macros are defined as follows:

- -

#define <macro name> <macro body>

- -

Example:

- -

#define pi 3.14

- -

Example of a nested macro:

- -

#define CURRENT_PLAYER 0

- -

#define CURRENT_PLAYER_NAMe getPlayerName(CURRENT_PLAYER)

- -

During the compilation process macro names are replaced with the actual code.

- -

Parametrized macros are not supported.

- -

If any other text but "define" follows after # character then anything between # and end of the line is ignored by compiler making it possible to use #region and other tags in your favorite IDE.

- -

NOTE: "#include" is reserved but not fully supported yet.

- -

Data Types

- -

Apart from standard data types like string (string), integer (int), boolean (bool) and floating point (float) there are some warzone-specific data types available:

- -

INTMESSAGE- (simple) Name of a message as defined in Messages.txt, used mostly for campaign. In most cases it is easier to use a string instead.

- -

BASEOBJ- (complex) any of a DROID, FEATURE or STRUCTURE. It is a pointer to some droid/feature/structure on the map, can be NULLOBJECT if it wasn't assigned to a particular droid/feature/structure.
- You have access to:

- -

baseobj.x
- baseobj.y
- baseobj.z
- baseobj.id - unique id number
- baseobj.player - player id
- baseobj.type - one of OBJ_DROID, OBJ_STRUCTURE, OBJ_FEATURE
- baseobj.health - %age number of body points left
- baseobj.clusterID - the cluster the object is a member of

- -

baseobj.target - target of the object (in case of a multi-turret object returns target of the default weapon)

- -

NOTE: the functions objToDroid, objToStructure and objToFeature exist to convert a BASEOBJ
- to a droid, structure or feature if the base obj is of the right type.

- -

DROID- (complex) defined by the Id got from the world editor. It is a pointer to a particular droid on the map, can be NULLOBJECT when no droid is assigned to the DROID variable.
- You have access to :

- -

all BASEOBJ variables
- droid.order - current order of the droid
- droid.orderx - target location of the droid order
- droid.ordery - target location of the droid order
- droid.action - current action of the droid
- droid.body - the BODY of the droid
- droid.propulsion - the PROPULSION of the droid
- droid.weapon - the WEAPON of the droid DROIDID - (simple) literally just an Id of a droid

- -

droid.selected - holds TRUE if droid is currently selected
- droid.group - the GROUP droid belongs to

- -

FEATURE- (complex) defined by the ID got from the world editor. It is a pointer to a map decoration, like a tree, wrecked building, oil resource etc, can be NULLOBJECT.

- -

You have access to :

- -

all BASEOBj variables

- -

FEATURESTAT- (simple) type of a feature as defined in features.txt.

- -

TEMPLATE- (simple) name of a template as defined in templates.txt

- -

STRUCTURE- (complex) defined by the ID got from the world editor. It is a pointer to a particular structure on the map, can

- -

be NULLOBJECt when no structure is assigned to the STRUCTURE variable.

- -

You have access to :

- -

all BASEOBJ variables
- structure.stat - the STRUCTURESTAT of the structure, defined in structures.txt

- -

structure.stattype - structure type (likeREF_HQetc, refer to Script Function Constants)

- -

STRUCTUREID- (simple) literally just an ID of a struct
- STRUCTURESTAT- (simple) type of a structure as defined in structures.txt

- -

BODY- (simple) name of a body as defined in body.txt
- PROPULSION- (simple) name of a propulsion as defined in propulsion.txt
- ECM- (simple) name of a ECM as defined in ecm.txt
- SENSOR- (simple) name of a sensor as defined in sensor.txt
- CONSTRUCT- (simple) name of a construct as defined in construct.txt
- WEAPON- (simple) name of a weapon as defined in weapons.txt
- REPAIR- (simple) name of a repair type as defined in Repair.txt
- BRAIN- (simple) name of a brain type as defined in Brain.txt
- SOUND- (simple) ID of sound used in playSound()
- LEVEL- ID of a level as defined in GameDesc.lev
- RESEARCHSTAT- (simple) name of a research topic as defined in research.txt

- -


- GROUP- (complex) a group of droids. Don't confuse GROUP with in-game units groups that can be accessed with ctrl-<number>, they have nothing in common. GROUP is an internal structure used to simplify unit management.
- You have access to :

- -

group.x - average x coord
- group.y - average y coord
- group.members - number of units in the group
- group.health - average %age health of the units

- -

group.type - type of the group, one of: GT_NORMAL, GT_COMMAND or GT_TRANSPORTER (refer to Script Function Constants)

- -

group.commander - commander of the group, if type = GT_COMMAND or NULLOBJECT

- -

NOTE: transporters and commanders can't be added to a GROUP.

- -

With a complex object it is possible to access information specific to the instance of this object. Acomplex object is usually a pointer to a C structure in the code. For example a DROID is a complex object - its x,y,z can be queried whereas a DROIDID (a simple object - an integer) is just a placeholder for the numeric value of the ID.

- -

Script Functions

- -

setSnow(bool)

- -

This function switchs snow on or off. TRUE will turn snow on, FALSE will turn snow off. If rain is on when snow is started the rain will be turned off.

- -

setRain(bool)

- -

This function switchs rain on or off. TRUe will turn rain on, FALSE will turn rain off. If snow is on when rain is started the snow will be turned off.

- -

setBackgroundFog(bool)

- -

This function switchs background fog on or off. This sets the backdrop to the current fogcolour and fogs the edge of the visible world.

- -

TRUE will turn background fog on, FALSE will turn background fog off.

- -

setDepthFog(bool)

- -

This function switchs depth fog on or off. This sets the sets fog ramping up from zero in the middle of the view to full fog at the edge of the visible world. TRUE will turn depth fog on, FALSE will turn depth fog off.

- -

setFogColour(RED, GREEN, BLUE)

- -

This function sets the fog colour, to be used when fog is enabled. This colour is also used in the background clear when fog is enabled.

- -

The colour is specified as RED, GREEN and BLUe components each in the range 0 to 255. This yields a 24 bit colour value.

- -

Colour values outside the range 0 to 255 will have an indeterminate effect.

- -

WARNING setting the fog colour to BLACK(0, 0, 0) does not turn fog off and should be avoided.

- -

Arizona: NEW 204, 149, 70 Nick approved 24/09/98 (Old 176, 143, 95 B08F5F)

- -

Urban: 201, 146, 15 C9920F

- -

Rockies: 182, 225, 236 B6E1EC

- -

enableComponent(COMPONENT, PLAYER)

- -

This function makes a component found to a player - so that they can research a topic that requires the component COMPONENT is any type of Body, Propulsion, Weapon, ECM, Sensor, Construct etc

- -

PLAYER is the id of the player who gets the component

- -

makeComponentAvailable(COMPONENT, PLAYER)

- -

This function makes a component available to a player - so that they can build Units using this component

- -

COMPONENT is any type of Body, Propulsion, Weapon, ECM, Sensor, Construct etc

- -

PLAYER is the id of the player who gets the component

- -

enableStructure(STRUCTURESTAT, PLAYER)

- -

This function makes a structure available to a player - so that they can research a topic that requires the structure or build the structure STRUCTURESTAT is defined by the name from Access

- -

PLAYER is the id of the player who gets the structure

- -

enableResearch(RESEARCHSTAT, PLAYER)

- -

This function makes a research topic available to a player regardless of its pre-requisites

- -

RESEARCHSTAT is defined by the name from Access

- -

PLAYER is the id of the player who gets the research

- -

completeResearch(RESEARCHSTAT, PLAYER)

- -

This function acts as if the research was performed by the player giving them the results

- -

RESEARCHSTAT is defined by the name from Access

- -

PLAYER is the id of the player who gets the research

- -

bool objectInRange(PLAYER, X,Y, RANGE)

- -

bool droidInRange(PLAYER, X,Y, RANGE)

- -

bool structInRange(PLAYER, X,Y, RANGE)

- -

These functions check for when an object/droid/structure belonging to a player is within range of a position

- -

PLAYER is the id of the player whose unit is checked for in range

- -

X,Y is the position to check from in world coords

- -

RANGE is in world coords - 128 units = 1 tile

- -

bool objectInArea(PLAYER, X1,Y1, X2,Y2)

- -

bool droidInArea(PLAYER, X1,Y1, X2,Y2)

- -

bool structInArea(PLAYER, X1,Y1, X2,Y2)

- -

These functions check for when an object/droid/structure belonging to a player is in a square area

- -

PLAYER is the id of the player whose droid is checked for in area

- -

X1,Y1, X2,Y2 is the area to check in world coords

- -

X1,Y1 should be smaller than X2,Y2

- -

bool droidHasSeen(OBJECT, PLAYER)

- -

This functions checks for when a player has seen a given object - either by unit or structure

- -

OBJECT is any type of DROID, FEATURE, STRUCTURE

- -

PLAYER is the id of the player to check for having seen

- -

addDroid(TEMPLATE, X, Y, PLAYER)

- -

This function adds a unit for the player based on the template passed in.

- -

The unit is placed at x,y

- -

TEMPLATE is a valid template (doesn't have to belong to the player!)

- -

X, Y are in world coords

- -

PLAYER is the id of the player whose the unit belongs to

- -

buildDroid(TEMPLATE, STRUCTURE, PLAYER, QUANTITY)

- -

This function sets a factory defined by STRUCTURE to build units based on the TEMPLATE for the PLAYER.

- -

TEMPLATE is a valid template (doesn't have to belong to the player!)

- -

STRUCTURE is a structure defined by ID and MUST BE A FACTORY

- -

PLAYER is the id of the player whose the unit belongs to

- -

QUANTITY is the number of units that will be built

- -

bool buildingDestroyed(STRUCTUREID, PLAYER)

- -

This function checks that a structure (given by the id) no longer exists for the player

- -

STRUCTUREID is the id of the structure - Nb this is different to an object of type STRUCTURE

- -

PLAYER is the id of the player whose list is checked for the building

- -

bool structureIdle(STRUCTURE)

- -

This function checks whether the structure is doing anything. Returns TRUE if idle

- -

STRUCTURE is a valid structure defined by ID

- -

bool structureBeingBuilt(STRUCTURESTAT, PLAYER)

- -

This function checks that a structure of type STRUCTURESTAT is currently being built for the specified PLAYER

- -

STRUCTURESTAT is defined by the name from Access

- -

PLAYER is the id of the player who gets the structure

- -

bool structureBuilt(STRUCTURESTAT, PLAYER)

- -

This function checks that a structure of type STRUCTURESTAT is currently built for the specified PLAYER

- -

STRUCTURESTAT is defined by the name from Access

- -

PLAYER is the id of the player who gets the structure

- -

addReticuleButton(BUTTONID)

- -

This function adds a reticule button to the interface

- -

BUTTONID is the id of a button - see Script Function Constants

- -

removeReticuleButton(BUTTONID)

- -

This function removes a reticule button from the interface

- -

BUTTONID is the id of a button - see Script Function Constants

- -

addMessage(INTMESSAGE, MESSAGETYPE, PLAYER, PLAY_IMMEDIATE)

- -

This adds a message to the interface for the PLAYER

- -

INTMESSAGE is a variable defined in the values file

- -

MESSAGETYPE is a predefined type - see Script Function Constants

- -

PLAYER is the player who gets the message

- -

PLAY_IMMEDIATE is a bool for whether to bring the Intelligence Screen up with the message immediately or just store it

- -

removeMessage(INTMESSAGE, MESSAGETYPE, PLAYER)

- -

This removes a message from the interface for the PLAYER

- -

INTMESSAGE is a variable defined in the values file

- -

MESSAGETYPE is a predefined type - see Script Function Constants

- -

PLAYER is the player who loses the message

- -

bool selectDroidByID(DROIDID, PLAYER)

- -

This selects a unit defined by the ID since we can't guarantee the name! Only the list of units belonging to PLAYER will be checked. This returns TRUE if the unit could be found - it will be worth checking it exists!

- -

DROIDID is a valid unit defined by ID

- -

setAssemblyPoint(X, Y, STRUCTURE)

- -

This sets the location of where new units assemble at for a specific factory

- -

X, Y are the x and y in world coordinates

- -

STRUCTURE is a valid structure defined by ID

- -

FEATURE addFeature( FEATURESTAT, X, Y )

- -

Builds a feature at position (x,y).

- -

FEATURESTAT is the name of a feature stat defined in features.txt.

- -

The feature identifier is returned - this can be used in e.g. destroyFeature.

- -

destroyFeature(FEATURE)

- -

This removes the feature from the world

- -

FEATURE is a feature defined by ID

- -

centreView(OBJECT)

- -

This function centres the view on the object supplied

- -

OBJECT is any type of DROID, FEATURE, STRUCTURE

- -

STRUCTURE addStructure( STRUCTURESTAT, PLAYER, X, Y )

- -

Builds a structure belonging to PLAYER centred at (X, Y).

- -

The structure must be previously enabled via enableStructure().

- -

The structure identifier is returned - this can be used in e.g. destroyStructure.

- -

destroyStructure(STRUCTURE)

- -

This removes the structure from the world

- -

STRUCTURE is a structure defined by ID

- -

STRUCTURE getStructure(STRUCTURESTAT, PLAYER)

- -

This function returns the first STRUCTURe based on the stat for the player it can find.

- -

To use it create a STRUCTURE variable and assign it to the result of the function call.

- -

For example:

- -

STRUCTURe myNewStructure;

- -

STRUCTURESTAt Factory;

- -

myNewStructure = getStructure(Factory, 0);

- -

This will look through the player 0 list of structures to find a Factory and return a variable of type STRUCTURE. You will then be able to access the x, y, and z. If a structure cannot be found than NULL is returned . It will be worth checking that the STRUCTURE does not equal NULL before using it. For example:

- -

if (myNewStructure == NULLOBJECT)

- -

{

- -

do something

- -

}

- -

void initEnumStruct(bool any, STRUCTURESTAt type, int targetPlayer, int lookingPlayer)

- -

STRUCTURE enumStruct()

- -

Enumerate through visible structures of given 'type' of player 'targetPlayer' that are visible to 'lookingPlayer'. Returns NULLOBJECT when no more exist.

- -

If 'any' is set to TRUE, then 'type' is ignored and all structure types will be iterated.

- -

void InitEnumDroids(int targetPlayer, int lookingPlayer)

- -

DROID EnumDroid()

- -

Enumerate through all targetPlayer's droids that are visible to 'lookingPlayer'. Returns NULLOBJECT when no more exist.

- -

TEMPLATE getTemplate(COMPONENT, PLAYER)

- -

This function returns the first TEMPLATE based on the stat for the player it can find. It can be any type of component. To use it create a TEMPLATE variable and assign it to the result of the function call. For example:

- -

TEMPLATe myNewTemplate;

- -

WEAPOn Rocket;

- -

myNewTemplate = getStructure(Rocket, 0);

- -

This will look through the player 0 list of template to find one which contains a rocket and then return a variable of type TEMPLATE. You will then be able to access its attributes. If a template cannot be found than NULL is returned . It will be worth checking that the TEMPLATe does not equal NULL before using it. For example:

- -

if (myNewTemplate == NULLTEMPLATE)

- -

{

- -

do something

- -

}

- -

setScrollParams(minX, minY, maxX, maxY)

- -

This literally sets the scroll settings for the current map - be careful not to set the maxX/maxY greater than that possible for the map!

- -

minX, minY, maxX, maxY are all numbers. These are in TILE COORDINATES!!!!!!

- -

setScrollMinX(minX)

- -

This just sets the one variable. These are in TILE COORDINATES!!!!!!

- -

minX is a number

- -

setScrollMinY(minY)

- -

This just sets the one variable. These are in TILE COORDINATES!!!!!!

- -

minY is a number

- -

setScrollMaxX(maxX)

- -

This just sets the one variable. These are in TILE COORDINATES!!!!!!

- -

maxX is a number

- -

setScrollMaxY(maxY)

- -

This just sets the one variable. These are in TILE COORDINATES!!!!!!

- -

maxY is a number

- -

setDefaultSensor(SENSOR, PLAYER)

- -

This sets which sensor will be used as the default when designing units in game for the specified player. The SENSOR must be a valid DEFAULT sensor.

- -

setDefaultECM(ECM, PLAYER)

- -

Like the above functionm, this sets which ECm will be used as the default when designing units. Again the ECM must be a valid DEFAULT ECM.

- -

setStructureLimits(STRUCTURESTAT, LIMIT, PLAYER)

- -

This sets a limit for a specific structure on how many can be built on a map.

- -

STRUCTURESTAT is defined by the name from Access

- -

LIMIT is a number between 0 and 255

- -

PLAYER is the id of the player

- -

setAllStructureLimits(LIMIT, PLAYER)

- -

This sets a limit for all structures on how many can be built on a map.

- -

LIMIT is a number between 0 and 255

- -

PLAYER is the id of the player

- -

playSound( SOUND, PLAYER)

- -

Plays a '2D' sound ie speech and is audible for the player identified

- -

SOUND is a defined type.

- -

PLAYER is the id of the player

- -

playSoundPos( SOUND, PLAYER, x, y, z)

- -

Plays a '2D' sound ie speech and is audible for the player identified

- -

Position of sound is saved so camera can move to object playing sound if required.

- -

SOUND is a defined type.

- -

PLAYER is the id of the player

- -

x, y, z is the position of the object in game units.

- -

addConsoleText( TEXTSTRING, PLAYER)

- -

Adds console text to the top of the screen (centre justified) for the player concerned

- -

TEXTSTRING is a string ID obtained from strings.txt

- -

PLAYER is the id of the player

- -

turnPowerOn()

- -

Literally makes the power calculations be used

- -

turnPowerOff()

- -

Literally stops the power calculations being used

- -

setPowerLevel(POWER, PLAYER)

- -

sets the power level for a player - this overrides any current setting there is

- -

POWER is the value to set the player's power to

- -

PLAYER is the id of the player

- -

addPower(POWER, PLAYER)

- -

adds the POWER amount to the PLAYER's current level

- -

POWER is the value to add to the player's power

- -

PLAYER is the id of the player

- -

setLandingZone(x1, y1, x2, y2)

- -

sets the landing zone for the map. The coords are in tile units and must all be less than 255

- -

setLimboLanding(x1, y1, x2, y2)

- -

sets the landing zone for the Limbo Units.The coords are in tile units and must all be less than 255

- -

The units from the Limbo list are then placed at this location - so call in CALL_GAME_INIT of the mission you want them to appear in

- -

initAllNoGoAreas()

- -

initialises all the no go areas to 0. Should be called when a new map is loaded

- -

setNoGoArea(x1, y1, x2, y2, areaNum)

- -

defines an area that cannot be built on - used for enemy landing zones.

- -

areaNum is a number between 0 and 7. If 0, then this function is the same as calling setlandingZone

- -

setTransporterExit( PLAYER, exitTileX, exitTiley )

- -

setup transporter exit point on map for PLAYER

- -

flyTransporterIn( PLAYER, entryTileX, entryTileY, bool bTrackTransporter )

- -

flys PLAYER's transporter in from entry point on map; set bTrackTransporter true to

- -

track it onto the map.

- -

tutorialEnd()

- -

A bit of a hack to notify the game when the last of the tutorial events has been run

- -

so that the console messages can be turned back on to how they will appear for

- -

the rest of the game

- -

gameOver(bool)

- -

function to call for ending the game

- -

bool - true or false depending on whether the player has won or not

- -

anyDroidsLeft(PLAYER)

- -

checks the specified player for any units - returns TRUE if some exist, FALSE if

- -

they have all been destroyed

- -

anyStructButWallsLeft(PLAYER)

- -

checks the specified player for any structures except walls - returns TRUE if some

- -

exist, FALSE if they have all been destroyed

- -

anyFactoriesLeft(PLAYER)

- -

returns true if player has a factory/cyborg factory/ vtol factory

- -

setRetreatPoint(PLAYER, x,y)

- -

sets the position for a players units to retreat to

- -

setRetreatForce(int player, int level)

- -

Sets the percentage of the current force below which units for a side will retreat

- -

setRetreatLeadership(int player, int level)

- -

Sets the leadership level (chance to run away) for a player (1-100)

- -

startMission(MISSION_TYPE, LEVEL)

- -

Starts a mission for the currently selected player - NB Transporters must be filled if

- -

you want units to appear on the Mission map

- -

MISSION_TYPE is a predefined type - see Script Function Constants

- -

LEVEL is the name of the level to load as defined in GameDesc.lev

- -

endMission(bool)

- -

Ends the current mission the selected player is on - returns all Units that have been

- -

loaded onto the Transporter. False if player lost, true if player won????

- -

bool allianceExists()

- -

returns true if two or more players are in alliance. returns false otherwise.

- -

bool dominatingAlliance()

- -

returns true if there is a single dominating alliance, using all multi-players.

- -

bool playerInAlliance()

- -

returns true if player is in an alliance

- -

bool myResponsibility(PLAYER)

- -

returns true if this machine is responsible for 'player' in multiplayer games.

- -

STRUCTURe structureBuiltInRange(STRUCTURESTAT, X, Y, RANGE, PLAYER)

- -

Checks to see if a Structure has been built within a specified range of x, y. The first structure

- -

to be found within this range will be returned. Check the result of the function for being

- -

NULLOBJECT before using!

- -

STRUCTURE is a return value (structure defined by ID)

- -

STRUCTURESTAT is defined by the name from Access

- -

X, Y, RANGE are all in world coords

- -

PLAYER is the id of the player whose structure list is searched

- -

groupAddDroid(GROUP, DROID)

- -

Add a unit to a group

- -

groupAddArea(GROUP, PLAYER, X1,Y1, X2,Y2)

- -

Add all the units inside the rectangle X1,Y1, X2,Y2.

- -

Only units belonging to player PLAYER are added.

- -

groupAddAreaNoGroup(GROUP, PLAYER, X1,Y1, X2,Y2)

- -

as above but doesnt add units that are already grouped.

- -

groupAddGroup(group1, group2)

- -

Add all the units in group2 to group1.

- -

All the units are removed from group2.

- -

bool hasGroup(DROID droid)

- -

Returns TRUE if 'droid' belongs to any group, retzrns FALSE otherwise.

- -

orderDroid(DROID, order)

- -

Give a unit an order currently one of:

- -

DORDER_STOp - stop current order

- -

DORDER_RETREAt - retreat

- -

DORDER_DESTRUCT - self destruct

- -

DORDER_RTr - return to repair

- -

DORDER_RTb - return to base

- -

DORDER_RUn - run away for a bit (moral failure)

- -

orderDroidLoc(DROID, order, x,y)

- -

Give a unit an order with a location :

- -

DORDER_MOVe - move to location

- -

orderDroidObj(DROID, order, BASEOBJ)

- -

Give a unit an order with an object :

- -

DORDER_ATTACK- attack the object

- -

DORDER_HELPBUILD- help construct the object

- -

DORDER_DEMOLISH- demolish structure

- -

DORDER_REPAIR- repair structure

- -

DORDER_OBSERVE- (sensor units) keep a target in sensor range

- -

DORDER_EMBARK- get onto a transporter

- -

DORDER_FIRESUPPORT- follow this sensor unit and attack anything it DORDER_OBSERVE's

- -

orderDroidStatsLoc(DROID, int order, STRUCTURESTAT stats, int x, int y)

- -

Give a unit an order with stats and a location :

- -

DORDER_BUILD - build a structure at the location

- -

orderGroup(GROUP, order)

- -

Give all the units in the group an order

- -

orderGroupLoc(GROUP, order, x,y)

- -

Give all the units in the group an order with a location

- -

orderGroupObj(GROUP, order, BASEOBJ)

- -

Give all the units in the group an order with an object

- -

DROID objToDroid(BASEOBJ)

- -

Convert a BASEOBJ to DROID when BASEOBJ.type == OBJ_DROID. Returns NULLOBJECT otherwise

- -

STRUCTURE objToStructure(BASEOBJ)

- -

Convert a BASEOBJ to STRUCTURE when BASEOBJ.type == OBJ_STRUCTURE. Returns NULLOBJECT otherwise

- -

FEATURE objToFeature(BASEOBJ)

- -

Convert a BASEOBJ to FEATURE when BASEOBJ.type == OBJ_FEATURE. Returns NULLOBJECT otherwise

- -

int random(range)

- -

Return a random number between 0 and range - 1.

- -

flashOn(int buttonID)

- -

turn on flashing for a button (id's in Script Function Constants)

- -

... now works for all buttons not just reticule buttons

- -

flashOff(int buttonID)

- -

turn off flashing for a button

- -

createAlliance(int player1, int player2)

- -

Create an alliance between two players

- -

breakAlliance(int player1, int player2)

- -

Breake an alliance between two players

- -

setRadarZoom(int level)

- -

level is the zoom level between 0 .. 2 on the PC and 0 .. 1 on PSX.

- -

0 is the most zoomed out, 2 the most zoomed in.

- -

2 is mapped to 1 if the script is run on the PSX

- -

centreViewPos(int x, int y)

- -

center the view on the world coordinates x,y.

- -

setGroupRetreatForce(GROUP group, int level)

- -

Sets the percentage of the current force below which units for a side will retreat

- -

setGroupRetreatLeadership(GROUP group, int level)

- -

Sets the leadership level (chance to run away) for a player (1-100)

- -

setGroupRetreatPoint(GROUP group, int x, int y)

- -

Set the retreat position for a group

- -

setDroidSecondary(DROID droid, int secondaryOrder, int secondaryState)

- -

Set the state of a secondary order for a droid (values in Script Function Constants)

- -

setGroupSecondary(GROUP group, int secondaryOrder, int secondaryState)

- -

Set the state of a secondary order for a group (values in Script Function Constants)

- -

setMissionTime(int time)

- -

used to specify how long an OffWorld mission will last for - used in conjunction with the

- -

callback CALL_MISSION_TIME so that end conditions can be displayed if the player has not

- -

managed to finish the mission

- -

If time < 0, there is no limit. time is in 10th of a second

- -

int missionTimeRemaining()

- -

Returns how long left for the current mission. If the mission time has not been set it will return 0.

- -

The value returned is in 10ths of a second

- -

setReinforcementTime(int time)

- -

this defines how long it will take for reinforcements to arrive for an OffWorld mission

- -

If time < 0, there can be no reinforcements. Time is in 10th of a second.

- -

Set time to LZ_COMPROMISED_TIME to display '--:--' to indicate the Transporter is unable to land

- -

int idleGroup(GROUP group)

- -

returns number of units in group not doing anything.

- -

bool groupMember(GROUP group, DROId droid)

- -

return whether a unit is a member of a group.

- -

initIterateGroup(GROUP group)

- -

Prepare a group to iterate through the units in it.

- -

DROID iterateGroup(GROUP group)

- -

Get the next unit from the group. Must be called after an initial initGroupIterate.

- -

To reset a group back to the start call initGroupIterate.

- -

droidLeaveGroup(DROID droid)

- -

Make a unit leave the group it is a member of (if any).

- -

initGetFeature(STRUCTURESTAT, PLAYER,BUCKET)

- -

getFeature(BUCKET)

- -

enumerate features of a single feature type.

- -

PLAYER is the player to use, Only features visible to that player are returned.

- -

BUCKET is an int of range 0-MAX_PLAYERS(8), so up to 8 feature enumerations can be going on at any time! (wow)

- -

getFeature returns NULLOBJECT when no more features are visible.

- -

bool structButNoWallsInArea(PLAYER, X1,Y1, X2,Y2)

- -

See if there are any player structures excluding walls in an area.

- -

int numObjectsInArea(PLAYER, X1,Y1, X2,Y2)

- -

Return the number of player objects in an area.

- -

int numDroidsInArea(PLAYER, X1,Y1, X2,Y2)

- -

Return the number of player units in an area.

- -

int numStructsInArea(PLAYER, X1,Y1, X2,Y2)

- -

Return the number of player structures in an area.

- -

int numStructsButNotWallsInArea(PLAYER, X1,Y1, X2,Y2)

- -

Return the number of player structures excluding walls in an area.

- -

randomiseSeed()

- -

Generate a new random seed for the random number generator.

- -

int numStructsByTypeInArea(PLAYER, TYPE, X1,Y1, X2,Y2)

- -

Return the number of structures of a certain type in an area.

- -

flushConsoleMessages()

- -

Clear all the console messages

- -

bool pickStructLocation(STRUCTURESTAT,ref x, ref y, player);

- -

returns true if structure of type strucutrestat can be built at x,y.

- -

If a structure can be built nearby then returns true and modifies x and y

- -

to the coords of acceptable location. Player trying to build - uses this for the visibility

- -

int playerPower(int player)

- -

returns aspower[player].currentPower (players current power)

- -

bool seenStructInArea(int player,int enemy,bool walls,int x1,int y1,int x2,int y2)

- -

returns true if player has seen a structure belonging to enemy in area specified. Call with

- -

walls = true/false to include/exclude walls in the search.

- -

(note similar to StructInArea)

- -

int distBetweenTwoPoints(int x1, int y1, int x2, int y2)

- -

Returns the distance between the two points given.

- -

bool losTwoObjects(BASEOBJ source, BASEOBJ target, bool wallsMatter)

- -

Decides whether object source can see object target and you can specify whether

- -

walls matter or not. Note that whilst target can be anything, source needs to be

- -

something that can actually see - ie - have a sensor like a unit or structure.

- -

Returns TRUE or FALSE

- -

void killStructsInArea(int player, int buildingRef (like REF_WALL etc),

- -

int x1, int y1,int x2, int y2, bool bSeeEffect, bool bTakeFeatures)

- -

Blows up all the buildings of the specified reference within the specified area.

- -

If bSeeEffect is set, then you'll see it blow up (provided you can see the building

- -

in question of course).

- -

If bTakeFeatures is et, then it will also kill features of type BUILDING.

- -

Returns 'nowt.

- -

int getThreatInArea(int playerLooking, int playerTarget, int x1, int y1,

- -

int x2, int y2, int ldThreat, int mdThreat, int hdThreat)

- -

Returns the threat value of all units of a specified player within a certain area for a specified player.

- -

The user can 'calibrate' this threat value by specifying the relative weights attached to the threats of

- -

small,medium and heavy units respectively as the last three parameters to this function. The final boolean

- -

parameter allows the user to say whether they care about whether or not the units in question are

- -

presently visible.. TRUE means they only add to the threat if PlayerLooking can see this unit (owned by

- -

playerTarget), FALSE means they add to the threat if even they can't see that unit.

- -

bool getNearestGateway(int x, int y, ref rX, ref rY)

- -

Puts the coordinates of the nearest gateway into reference variables rX and rY. It might not though

- -

if there are no gateways on the present map. So make sure you look at the return value. If it's FALSE,

- -

then the values in rX and rY will be meaningless - unchanged actually, assuming the scripting works

- -

this way. Otherwise, they'll be the coordinates of the midpoint of the nearest gateway.

- -

void setWaterTile(int tileNum)

- -

Sets the tile to use for underwater. Count from the top of the tileset pcx - presently 17 for arizona.

- -

initIterateCluster(int clusterID)

- -

get ready to iterate a cluster

- -

BASEOBJ iterateCluster()

- -

return the next object in the cluster or NULLOBJ if none left

- -

cmdDroidAddDroid(DROID commander, DROId droid)

- -

adds the unit droid to the command group of the command unit commander

- -

cmdDroidMaxGroup(DROId commander)

- -

Returns max number of droids 'commander' can have in his group.

- -

bool testStructureModule(int playeNumber, ST_STRUCTURE structureToTest, int ref)

- -

Returns true if the structure in question has a module attached - presently the ref id is unused but

- -

could be later on. At the moment it returns true if the structure has _any_ number of modules attached.

- -

If the structure pointer that's sent in is NULL (ie - no structure is specified), then it'll return

- -

TRUE is _any_ of the player's structures possess _any_ module. In all other cases, it'll return FALSE.

- -

bool addTemplate(TEMPLATE, int player)

- -

given a template, gives the player the template so that build droid can be used. At least one

- -

player must have the template.

- -

void vanishUnit(DROID droid)

- -

Will remove 'droid' from the world without any graphical hoo ha.

- -

void forceDamageObject(BASEOBJ obj, int damage)

- -

Sets 'obj' to be 'damage' percent damaged. Obj must be a feature,droid or structure and damage

- -

must be <= 100.

- -

bool getGameStatus(int StatusRequired)

- -

Gets the status of some of the game TRUE/FALSe variables. Can be used to find if the reticule is up or the

- -

battle map is open, that sort of thing.

- -

e.g. getGameStatus(STATUS_ReticuleIsOpen); will return TRUE if the reticule is open (on screen) or FALSE if the reticule is not (disabled)

- -

or

- -

getGameStatus(STATUS_BattleMapViewEnabled); will return TRUE if we are in the battle map mode

- -

or

- -

getGameStatus(STATUS_DeliveryResposInProgress); will return TRUE if we are repositioning the delivery point

- -

these are currently the only two options implemented ... for other game modes (like design screen or intelligence map modes)

- -

use the externed variable intMode

- -

int getPlayerColour(int player)

- -

returns the colour of the player

- -

void setPlayerColour(int colour, int player)

- -

sets the colour to use for the player specified - colour must be 0 to (MAX_PLAYERS-1)

- -

DROID takeOverSingleDroid(DROId droidToTakeOver, int playerToGain)

- -

this replaces the existing droid (droidToTakeOver) by a new one for the playerToGain.

- -

The new droid is passed back to the script

- -

****Test for NULLOBJECT BEFORE calling this function****

- -

int takeOverDroidsInArea(int fromPlayer, int toPlayer, int x1, int y1, int x2, int y2)

- -

x1,y1,x2,y2 are in world units

- -

checks for units belonging to fromPlayer and if they are in the area they are 'given' to the toPlayer

- -

int takeOverDroidsInAreaExp(int fromPlayer, int toPlayer, int x1, int y1,

- -

int x2, int y2, int level, int max)

- -

x1,y1,x2,y2 are in world units

- -

checks for units belonging to fromPlayer and if they are in the area they are 'given' to the toPlayer

- -

if their experience level is less than or equal to level

- -

max specifies the maximum number of units to take over

- -

STRUCTURe takeOverSingleStructure(STRUCTURE structToTakeOver, int playerToGain)

- -

this replaces the existing structure (structToTakeOver) by a new one for the playerToGain.

- -

The new structure is passed back to the script

- -

****Test for NULLOBJECT BEFORE calling this function****

- -

int takeOverStructsInArea(int fromPlayer, int toPlayer, int x1, int y1,

- -

int x2, int y2)

- -

x1,y1,x2,y2 are in world units

- -

checks for structures belonging to fromPlayer and if they are in the area they are 'given' to the toPlayer

- -

This will NOT WORK for the selectedPlayer on any Factory. The structure limits will be increased if necessary

- -

void resetStructTargets()

- -

reset the structure preferences

- -

void resetDroidTargets()

- -

reset the unit preferences

- -

void setStructTarPref(int type)

- -

set a prefered structure target type, repeated calls combine the effect

- -

void setStructTarIgnore(int type)

- -

set structure target ignore types

- -

void setDroidTarPref(int type)

- -

set prefered unit target types

- -

void setDroidTarIgnore(int type)

- -

set unit target ignore types

- -

STRUCTURE structTargetInArea(int targetPlayer, int visibleToPlayer, int x1, int y1, int x2, int y2)

- -

get a structure target in an area using the preferences

- -

targetPlayer is the player to choose targets from, visibleToPlayer specifies the

- -

player that has to be able to see the target or -1 for no visibility check

- -

STRUCTURE structTargetOnMap(int targetPlayer, int visibleToPlayer)

- -

get a structure target on the map using the preferences

- -

DROID droidTargetInArea(int targetPlayer, int visibleToPlayer, int x1, int y1, int x2, int y2)

- -

get a unit target in an area using the preferences

- -

DROID droidTargetOnMap(int targetPlayer, int visibleToPlayer)

- -

get a unit target on the map using the preferences

- -

BASEOBJ targetInCluster(int clusterID, int visibleToPlayer)

- -

get a target from a cluster using the preferences

- -

void fireWeaponAtObj(WEAPON weap, BASEOBJ target)

- -

fire a single shot of the weapon weap at the object target

- -

void fireWeaponAtLoc(WEAPON weap, int x, int y)

- -

fire a single shot of the weapon weap at the location x,y

- -

bool isStructureAvailable(STRUCTURESTAt stat, int player)

- -

PC ONLY FOR NOW. returns true if structure is available to player, false otherwise.

- -

bool structureComplete(STRUCTURE struct)

- -

PC ONLY FOR NOW. returns true if the structure is completely built.

- -

int getDroidCount(int player)

- -

returns the number of units on the current map for the specified player

- -

setDroidKills(DROID droid, int kills)

- -

sets the number of kills for a unit. currently the level boudaries are:

- -

4, 8, 16, 32, 64, 128, 256, 128

- -

resetPlayerVisibility(int player)

- -

reset the visibility for a player

- -

void resetLimboMission(void)

- -

This can only be called mid Limbo Expand mission - the units that were stored in the

- -

mission list at the start of the mission are added back into the map, and the mission

- -

type is changed to an Expand Mission.

- -

int killDroidsInArea(int x1, int y1, int x2, int y2, int player)

- -

Kills all the player's units within the area defined. Returns how many it wiped out.

- -

traceOn()-- view the script debug info to stdout.

- -

traceOff()

- -

bool applyLimitSet (void)

- -

Apply the limits set in the structure limits screen.

- -

bool isHumanPlayer (int pl)

- -

Returns true is pl is human.

- -

void offerAlliance (int p1, int p2)

- -

Make p1 offer p2 an alliance

- -

bool allianceExistsBetween (int p1 , int p2)

- -

True if alliance exists between p1 and p2.

- -

void skDoResearch ( STRUCTURE str , int pl , int bias)

- -

Make player pl do some research with structure str.

- -

BASEOBJECT skLocateEnemy( int pl)

- -

Return a baseobject of interest belonging to player pl.

- -

bool skCanBuildTemplate ( int pl, STRUCTURE str, TEMPLATE tem)

- -

True when player pl can build design tem with structure str.

- -

bool skVtolEnableCheck( int pl)

- -

True when player pl is actively using vtols.

- -

int skGetFactoryCapacity( STRUCTURE str)

- -

Return the capacity of factory str.

- -

void skDifficultyModifier( int pl)

- -

Apply the frontend slider settings to player pl.

- -

bool skDefenseLocation (ref int x , ref int y , STRUCTURESTAT defenceStat,

- -

STRUCTURESTAT wallstat, DROID unit, int player)

- -

Given a starting x and y, make unit 'unit' belonging to 'player' build either a 'defenceStat' or a row of 'wallStat's. returns

- -

Modified x and y's.

- -

void skFireLassat (int pl, BASEOBJECT obj)

- -

Fire lassat of player pl's at object obj.

- -

void setEventTrigger(EVENt event, TRIGGER newTrigger)

- -

Assigns 'newTrigger' as new trigger for event 'event'.

- -

void dropBeacon (string msg, int forPlayer, int, fromPlayer,

- -

int x, int y, int z)

- -

Put a flashing beacon on the map for player 'forPlayer' on position x/y. Unless removed manually the beacon is removed automatically from the map after a timeout.

- -

void removeBeacon (int forPlayer, int fromPlayer)

- -

Remove a previously placed beacon from the map.

- -

int max(int value1, int value2)

- -

int min(int value1, int value2)

- -

Returns maximum/minimum of two integer values.

- -

float fmax(float value1, float value2)

- -

float fmin(float value1, float value2)

- -

Returns maximum/minimum of two float values.

- -

bool fogTileInRange(ref int tileX, ref int tileY, int x, int y,

- -

int rangeX, int rangeY, int searchRange, int player, int threatRange)

- -

Fills tileX/tileY with coordinates of the unrevealed location in range with starting location x/y, range 'searchRange' and closest to location x/y. If 'searchRange' is -1, then entire map is being searched. 'Player' is the player who is looking for an unrevealed map location. If 'threatRange' != -1 then also checks for enemy presence. Locations with enemy presence are ignored then.

- -

Returns TRUE if any locations satisfying the search conditions were found, returns FALSE otherwise.

- -

bool mapRevealedInRange(int x, int y, int range, int player)

- -

Returns TRUE if there are no unrevealed tiles left in locations for player 'player' with center x/y and radius 'range'. All coordinates are in world units.

- -

bool pursueResearch(STRUCTURE resFac, int player, RESEARCH targetResearch)

- -

Makes 'resFac' start researching the first prerequisite necessary for 'targetResearch'. If no prerequisites are left, then 'targetResearch' will be researched. Must be called again for the next prerequisite. 'resFac' must be a valid research facility.

- -

Returns TRUE if started researching, FALSe otherwise.

- -

int numResearchLeft(int player, RESEARCH research)

- -

Returns number of reserach topics that are left for player 'player' to research in order for a certain research 'research' to become available.

- -

bool researchFinished(RESEARCh research, int player)

- -

Returns TRUE if 'player' has researched 'research'.

- -

bool researchStarted(RESEARCH research, int player)

- -

Returns TRUE if 'research' is currently being researched by 'player'.

- -

bool threatInRange(int player, int rangeX, int rangeY, int range, bool includeVTOLs)

- -

Returns TRUE if there's a danger for 'player' at location x/y within radius 'range'. If includeVTOLs is set to FALSE then VTOLs are ignored. All coordinates are in worls units. If 'range' == -1 then entire map will be searched.

- -

int numEnemyWeapDroidsInRange(int lookingPlayer, int x, int y,

- -

int range, bool includeVTOLs)

- -

int numEnemyWeapStructsInRange(int lookingPlayer, int x, int y, int range, bool onlyFinishedStructs)

- -

int numEnemyWeapObjInRange(int lookingPlayer, int x, int y,

- -

int range, bool includeVTOLs, bool onlyFinishedStructs)

- -

Return total number of enemy military objects (either structures, droids or both) at location x/y and within 'range'. Units belonging to 'lookingPlayer' and his allies are ignored.

- -

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

- -

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

- -

int numFriendlyWeapDroidsInRange(int lookingPlayer, int x, int y,

- -

int range, bool includeVTOLs)

- -

int numFriendlyWeapStructsInRange(int lookingPlayer, int x, int y, int range, bool onlyFinishedStructs)

- -

int numFriendlyWeapObjInRange(int lookingPlayer, int x, int y,

- -

int range, bool includeVTOLs, bool onlyFinishedStructs)

- -

Return total number of friendly military objects (either structures, droids or both) at location x/y and within 'range'. Units belonging to enemies of 'lookingPlayer' are ignored.

- -

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

- -

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

- -

int numPlayerWeapDroidsInRange(int targetPlayer, int lookingPlayer,

- -

int x, int y, int range, bool includeVTOLs)

- -

int numPlayerWeapStructsInRange(int targetPlayer, int lookingPlayer,

- -

int x, int y, int range, bool onlyFinishedStructs)

- -

int numPlayerWeapObjInRange(int targetPlayer, int lookingPlayer,

- -

int x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

- -

Returns total number of targetPlayer's military objects (either structures, droids or both) at location x/y and within 'range' that are visible visible by 'lookingPlayer'.

- -

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

- -

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

- -

int numEnemyObjInRange(int lookingPlayer, int, x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

- -

Returns total number of enemy objects (structures and units) at location x/y within range 'range' that are visible to 'lookingPlayer'.

- -

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

- -

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

- -

int numAAinRange(int targetPlayer, int lookingPlayer,

- -

int x, int y, int range)

- -

Returns number of targetPlayer's AA defences at location x/y within range 'range' that are visible to 'lookingPlayer'.

- -

bool objHasWeapon(BASEOBJ object)

- -

Returns TRUE if 'object' has a weapon.

- -

bool objectHasIndirectWeapon(BASEOBj object)

- -

Returns TRUE if 'object' has an indirect weapon.

- -

bool alliancesLocked()

- -

Returns TRUE if the game doesn't allow to break alliances (ie when team mode is on).

- -

void selectDroid(DROID droid, bool select)

- -

Depending on value of 'select' selects or deselects droid 'droid'.

- -

void selectGroup(GROUP group, bool select)

- -

Depending on value of 'select' selects or deselects all droids belonging to group 'group'.

- -

int modulo(int divident, int divisor)

- -

Returns result of calculation (divident modulo divisor).

- -

float toPow(float base, float exponent)

- -

Returns floating-point result of calculation base^exponent.

- -

float exp(float exponent)

- -

Exponential function. Returns the result of e^exponent.

- -

float sqrt(float argument)

- -

Square root function. Returns square root of the argument: √argument.

- -

string getPlayerName(int player)

- -

Returns in-game name of 'player'.

- -

bool setPlayerName(int player, string newName)

- -

Set player's name to 'newName'. Returns TRUe on success.

- -

void console(string message)

- -

Outputs 'message' to game console.

- -

void msg(string message, int playerFrom, int playerTo)

- -

Sends a chat message from 'playerFrom' to 'playerTo'.

- -

bool strcmp(string string1, string string2)

- -

Returns TRUE if string1 and string2 are identical. Comparison is case-sensitive.

- -

int calcDroidPower(DROID droid)

- -

Returns cost of the 'droid'.

- -

boolisVtol(DROID droid)

- -

Returns TRUE if 'droid' is a vtol.

- -

int enemyWeapObjCostInRange(int lookingPlayer, int rangeX, int rangeY, int range, bool includeVtols, bool onlyFinishedStructs)

- -

Returns total cost (in power) of enemy objects with a weapon in a certain area.

- -

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

- -

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

- -

int friendlyWeapObjCostInRange(int lookingPlayer, int rangeX, int rangeY, int range, bool includeVtols, bool onlyFinishedStructs)

- -

Returns total cost (in power) of friendly objects with a weapon in a certain area.

- -

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

- -

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

- -

Debugging Script Functions

- -

The following functions can be used to debug warzone scripts.

- -

void dbgMsgOn(int player, bool on)

- -

Depending on the value of 'on' turns on/off debug output of dbg() and ASSERT() function which are listed below.

- -

void dbg(string debugMessage, int player)

- -

Outputs 'debugMessage' to the game console if debug output for player 'player' was previously turned on with dbgMsgOn().

- -

void ASSERT(bool assertExpression, string assertMessage, int player)

- -

If 'assertExpression' evaluates to FALSE, then 'assertMessage' is output to the game console. Must turn on debug output for 'player' with dbgMsgOn() first.

- -

NOTE: in debug game builds failed assertation will cause game assertation.

- -

void debug(string debugText)

- -

Writes 'debugText' to the standart output (usually a log file).

- -

void printCallStack()

- -

Outputs script call stack to the standard log file.

- -

Script Function Constants

- -

These values are used to represent numbers that are constant throughout the game.

- -

NULLOBJECT- used to check that a BASEOBJECT/FEATURE/STRUCTURE has been assigned by a function

- -

NULLTEMPLATE- used to check that a TEMPLATE has been assigned by a function

- -

NULLSTAT- used to check that a BASESTAT has been assigned by a function

- -

BARBARIAN1- this can used to represent enemy1 (PC:player 6, PSX:player2)

- -

BARBARIAN2- this can used to represent enemy2 (PC:player 7, PSX:player3)

- -

BUTTONID - these values are used when a particular reticule button needs to be identified

- -

OPTIONs - NOTE - this currently references the command button

- -

CANCEL

- -

BUILD

- -

MANUFACTURE

- -

RESEARCH

- -

INTELMAP

- -

DESIGN

- -

COMMAND

- -

- When flashing an icon - with scrFlashOn() scrFlashOff()

- -

you can additional use

- -

IDRET_OPTIONS

- -

IDRET_CANCEl

- -

IDRET_BUILD

- -

IDRET_MANUFACTURE

- -

IDRET_RESEARCH

- -

IDRET_INTEL_MAP

- -

IDRET_DESIGN

- -

IDRET_COMMAND

- -

IDDES_TEMPLSTART

- -

IDDES_SYSTEMBUTTON

- -

IDDES_BODYBUTTON

- -

IDDES_PROPBUTTON

- -

MESSAGETYPE - these values are used when a type of message needs to be identified

- -

RES_MSG

- -

CAMP_MSG

- -

MISS_MSG

- -

PROX_MSG

- -

Multiplayer alliance types:

- -

NO_ALLIANCES- alliances are disallowed

- -

ALLIANCES- alliances are allowed

- -

ALLIANCES_TEAMS- team mode, locked alliances

- -

MISSIONTYPE - these values are used when a type of mission needs to be identified

- -

CAMP_START - used for the starting point of a campaign

- -

CAMP_EXPAND - used to expand a current campaign map

- -

OFF_KEEP - used to load up an off world map, but keeping access

- -

to factories and research facilities back at home base

- -

OFF_CLEAR - used to load up an off world map, but having no access to home base

- -

LZ_COMPROMISED_TIME- value to set the reinforcement time with to display '--:--'

- -

when the Transporter is unable to land

- -

Droid Orders:

- -

DORDER_NONE- no order assigned

- -

DORDER_STOP- stop current order

- -

DORDER_RETREAT- retreat

- -

DORDER_DESTRUCT- self destruct

- -

DORDER_RTR- return to repair

- -

DORDER_RTB- return to base

- -

DORDER_RUN- run away for a bit (moral failure)

- -

DORDER_MOVE- move to location

- -

DORDER_ATTACK- attack the object

- -

DORDER_HELPBUILD- help construct the object

- -

DORDER_DEMOLISH- demolish structure

- -

DORDER_REPAIR- repair structure

- -

DORDER_OBSERVE- (sensor units) keep a target in sensor range

- -

DORDER_EMBARK- get onto a transporter

- -

DORDER_FIRESUPPORT- follow this sensor unit and attack anything it DORDER_OBSERVE's

- -

DORDER_SCOUT- same as move, but stop if enemy units are encountered.

- -

Unit secondary orders:

- -

DSO_ATTACK_RANGE

- -

DSO_REPAIR_LEVEL

- -

DSO_ATTACK_LEVEL

- -

DSO_RECYCLE

- -

DSO_PATROL- patrol between current pos and next move target

- -

DSO_HALTTYPE- what to do when stopped

- -

DSO_RETURN_TO_LOC- return to various locations

- -

Unit secondary states:

- -

DSS_ARANGE_SHORT

- -

DSS_ARANGE_LONG

- -

DSS_ARANGE_DEFAULT

- -

DSS_REPLEV_LOW- Medium Damage Taken

- -

DSS_REPLEV_HIGH- Heavy Damage Taken

- -

DSS_REPLEV_NEVER- Never Repair

- -

DSS_ALEV_ALWAYS

- -

DSS_ALEV_ATTACKED

- -

DSS_ALEV_NEVER

- -

DSS_PATROL_SET(0 to clear)

- -

DSS_HALT_HOLD

- -

DSS_HALT_GUARD

- -

DSS_HALT_PERSUE

- -

DSS_RECYCLE_SET(0 to clear)

- -

DSS_RTL_REPAIR(0 to clear)

- -

DSS_RTL_BASE(0 to clear)

- -

DSS_RTL_TRANSPORT(0 to clear)

- -

Button ID's:

- -

IDRET_OPTIONS- option button

- -

IDRET_BUILD- build button

- -

IDRET_MANUFACTURE- manufacture button

- -

IDRET_RESEARCH- research button

- -

IDRET_INTEL_MAP- intelligence map button

- -

IDRET_DESIGN- design units button

- -

IDRET_CANCEL- central cancel button

- -

Unit types:

- -

DROID_WEAPON- Weapon unit

- -

DROID_SENSOR- Sensor unit

- -

DROID_ECM- ECM unit

- -

DROID_CONSTRUCt - Constructor unit

- -

DROID_PERSON- person

- -

DROID_CYBORG- cyborg/super cyborg

- -

DROID_TRANSPORTER- guess what this is!

- -

DROID_COMMAND- Command unit

- -

DROID_REPAIR- Repair Unit

- -

DROID_CYBORG_CONSTRUCT- Cyborg engineer

- -

DROID_CYBORG_REPAIR- Cyborg mechanic

- -

Structure types:

- -

REF_HQ

- -

REF_FACTORY

- -

REF_FACTORY_MODULe

- -

REF_POWER_GEN

- -

REF_POWER_MODULE

- -

REF_RESOURCE_EXTRACTOR

- -

REF_DEFENSE

- -

REF_WALL

- -

REF_WALLCORNER- corner wall - no gun

- -

REF_RESEARCh

- -

REF_RESEARCH_MODULe

- -

REF_REPAIR_FACILITY

- -

REF_COMMAND_CONTROL- control centre for command units

- -

REF_CYBORG_FACTORY

- -

REF_VTOL_FACTORY

- -

REF_REARM_PAD

- -

REF_MISSILE_SILO

- -

Multiplayer Game Types:

- -

SKIRMISH

- -

DMATCH

- -

CAMPAIGN

- -

TEAMPLAY

- -

MultiPlayer Base Configurtations:

- -

CAMP_CLEAN- build units only

- -

CAMP_BASE- small base

- -

CAMP_WALLS- defensive base

- -

Cursor Mode (possible values of cursorType):

- -

IMAGE_CURSOR_SELECT

- -

IMAGE_CURSOR_ATTACK

- -

IMAGE_CURSOR_MOVE

- -

IMAGE_CURSOR_JAM

- -

IMAGE_CURSOR_PICKUP

- -

IMAGE_CURSOR_DEFAULT

- -

IMAGE_CURSOR_SEEKREPAIR

- -

IMAGE_CURSOR_BUILD

- -

IMAGE_CURSOR_GUARD

- -

IMAGE_CURSOR_BRIDGE

- -

IMAGE_CURSOR_ATTACH

- -

IMAGE_CURSOR_LOCKON

- -

IMAGE_CURSOR_FIX

- -

IMAGE_CURSOR_EMBARK

- -

Game mode - possible values for intMode external variable

- -

int_NORMAL- Standard mode (just the reticule)

- -

int_OPTION- Option screen

- -

int_EDITSTAT- Stat screen up for placing objects

- -

int_EDIT- Edit mode

- -

int_OBJECT- Object screen

- -

int_STAT- Object screen with stat screen

- -

int_CMDORDER- Object screen with command units and orders screen

- -

int_DESIGN- Design screen

- -

int_INTELMAP- Intelligence Map

- -

int_ORDER

- -

int_INGAMEOP- in game options.

- -

int_TRANSPORTER- Loading/unloading a Transporter

- -

int_MISSIONRES- Results of a mission display.

- -

int_MULTIMENU- multiplayer only, player stats etc...

- -

Possible options for getGameStatus():

- -

STATUS_ReticuleIsOpen- returns true is the reticule is open

- -

STATUS_BattleMapViewEnabled- returns true if we are in battlemap mode

- -

Possible values for targetedObjectType:

- -

MT_TERRAIN

- -

MT_RESOURCE

- -

MT_BLOCKING

- -

MT_RIVER

- -

MT_TRENCH

- -

MT_OWNSTRDAM

- -

MT_OWNSTROK

- -

MT_OWNSTRINCOMP

- -

MT_REPAIR

- -

MT_REPAIRDAM

- -

MT_ENEMYSTR

- -

MT_TRANDROID

- -

MT_OWNDROID

- -

MT_OWNDROIDDAM

- -

MT_ENEMYDROID

- -

MT_COMMAND

- -

MT_ARTIFACT

- -

MT_DAMFEATURE

- -

MT_SENSOR

- -

MT_WRECKFEATURE

- -

Structure Target preference types:

- -

ST_HQ

- -

ST_FACTORY

- -

ST_POWER_GEN

- -

ST_RESOURCE_EXTRACTOR

- -

ST_WALL

- -

ST_RESEARCH

- -

ST_REPAIR_FACILITY

- -

ST_COMMAND_CONTROL

- -

ST_CYBORG_FACTORY

- -

ST_VTOL_FACTORY

- -

ST_REARM_PAD

- -

ST_SENSOR

- -

ST_DEF_GROUND

- -

ST_DEF_AIR

- -

ST_DEF_IDF

- -

ST_DEF_ALL- ground/air/idf structures

- -

Unit target preference types:

- -

turret types:

- -

DT_COMMAND

- -

DT_SENSOR

- -

DT_CONSTRUCT

- -

DT_REPAIR

- -

DT_WEAP_GROUND

- -

DT_WEAP_AIR

- -

DT_WEAP_IDF

- -

DT_WEAP_ALL- ground/air/idf units

- -

Body types:

- -

DT_LIGHT

- -

DT_MEDIUM

- -

DT_HEAVY

- -

DT_SUPER_HEAVy - transporter only

- -

Propulsion:

- -

DT_TRACK

- -

DT_HTRACK

- -

DT_WHEEL

- -

DT_LEGS

- -

DT_GROUND

- -

DT_VTOL

- -

DT_HOVER

- -

Group types:

- -

GT_NORMAL

- -

GT_COMMAND

- -

GT_TRANSPORTER

- -

Script Function Externals

- -

These represent variables that are defined in the game which can be accessed in the scripts. It will only be possible to set the value that is held for some of the variables.

- -

mapWidth- (get) - field to hold the width of the map

- -

mapHeight- (get) - field to hold the height of the map

- -

gameInitialised- (get) flag to specify when all initialisation has been performed for the game - use it in place of a bool ie can be considered to equal true or false

- -

selectedPlayer- (get) field to hold the currently selected player

- -

gameTime- (get) the current time in the game (in 1/10 sec)

- -

multiPlayerGameType - (get) the type of multiplayer game underway.

- -

multiPlayerMaxPlayers - max number of human players in this game.(see constants for return values)

- -

multiPlayerBaseType - campaign game base type. (see constants for return values)

- -

multiPlayerAlliancesType- (get) alliance type (eg NO_ALLIANCES etc, see Script Function Constants)

- -

scrollX- (get/set) field to hold the starting x coordinate where the player can scroll

- -

scrollY- (get/set) field to hold the starting y coordinate where the player can scroll

- -

scrollWidth- (get/set) field to hold the width the player can scroll

- -

scrollHeight- (get/set) field to hold the height the player can scroll

- -

cursorType- (get) - Gets the current mode that the cursor is in (e.g. IMAGE_CURSOR_BUILD ... see Script Function Constants)

- -

intMode- (get) - Get the current game mode (e.g. int_DESIGN when the design screen is active) ... see Script Function Constants)

- -

targetedObjectType- (get) - The type of the object currently under the cursor (one of MT_... see Script Function Constants)

- -

boolextraVictoryFlag- use to mark additional victory conditions have been met - reset to FALSE at start of each level

- -

boolextraFailFlag- use to mark additional failure conditions have been met - reset to FALSE at start of each level

- -

GameLevel(get/set) - set single player difficulty.

- -

Script Function Callbacks

- -

These are used in the place of a trigger and are for events that are to be called at specific times in the game. They will cause the event they are associated with to be called every time unless the trigger for the event is set to inactive.

- -

CALL_GAMEINIT- this is triggered when the game has initialised

- -

CALL_DROIDDESIGNED- this is triggered when the player saves a template design

- -

CALL_DROIDBUILT- this is triggered when a unit has been built via a factory

- -

CALL_POWERGEN_BUILT- this is triggered when a Power generatot has been built

- -

CALL_RESEX_BUILT- this is triggered when a Resource Extractor has been built

- -

CALL_RESEARCH_BUILT- this is triggered when a Research Facility has been built

- -

CALL_FACTORY_BUILT- this is triggered when a Factory has been built

- -

CALL_MISSION_START- this is triggered when CTRL + 'M' is pressed so that the script can start a mission

- -

CALL_MISSION_END- this is triggered when CTRL + 'B' is pressed so that the script can end a mission

- -

CALL_VIDEO_QUIT- this is triggered when the CURRENT video sequence is over - either end of anim or when 'ESC' has been pressed

- -

CALL_LAUNCH_TRANSPORTER- this is triggered when the 'Launch' button is pressed on the Transporter interface

- -

CALL_START_NEXT_LEVEL- this is triggered when a new level is desired

- -

CALL_TRANSPORTER_REINFORCE- this is triggered when a transporter carrying reinforcements for player 0 enters the map

- -

CALL_MISSION_TIME- this is triggered when the time specified by setMissionTime() has elapsed

- -

CALL_ELECTRONIC_TAKEOVER- triggered when a unit or a structure for the selectedPlayer are taken over using Electronic weapons

- -

Callbacks with parameters:

- -

CALL_RESEARCHCOMPLETED, ref RESEARCHSTAT, ref STRUCTURE

- -

This is triggered when a research topic is complete - major or minor.

- -

RESEARCHSTAt is the research topic that was complete, STRUCTURE is research facility that has completed research.

- -

CALL_NEWDROID, player, ref DROID,ref STRUCTURE

- -

triggered when a unit for player is built by a factory. DROID is the unit that was built

- -

structure is the factory that built it, dont assume that the factory is still there!!

- -

CALL_STRUCT_ATTACKED, player, ref STRUCTURE, ref BASEOBJ

- -

triggered when a structure for player is attacked. STRUCTURE is the attacked structure,

- -

BASEOBJ is the unit that attacked the structure (could be NULLOBJECT)

- -

CALL_DROID_ATTACKED, player, ref DROID, ref BASEOBJ

- -

triggered when a unit for player is attacked. DROID is the attacked unit,

- -

BASEOBJ is the unit that attacked (could be NULLOBJECT)

- -

CALL_ATTACKED, player, ref BASEOBJ, ref BASEOBJ

- -

triggered when a structure or unit for player is attacked. BASEOBJ is the attacked unit,

- -

BASEOBJ is the unit that attacked (could be NULLOBJECT)

- -

CALL_TRANSPORTER_OFFMAP, player

- -

triggered when a transporter for player exits the map.

- -

CALL_TRANSPORTER_LANDED, GROUP, player

- -

triggered when transporter for player lands; units on transporter are unloaded

- -

into the given GROUP.

- -

Tutorial Callbacks

- -

CALL_BUILDLIST- Build structures interface up

- -

CALL_BUILDGRID- Place structure cursor up

- -

CALL_RESEARCHLIST- Choose research interface up

- -

CALL_MANURUN- Number of units to manufacture has changed

- -

CALL_MANULIST- Choose manufacturing interface up

- -

CALL_BUTTON_PRESSED, buttonID

- -

triggered when an interface button with id buttonID is pressed

- -

CALL_DESIGN_QUIT

- -

triggered when the design screen is closed

- -

CALL_OBJ_DESTROYED, int player, ref BASEOBJ object

- -

triggered when either a unit or a structure for player is destroyed

- -

CALL_DROID_DESTROYED, int player, ref DROID droid

- -

triggered when a unit for player is destroyed

- -

CALL_STRUCT_DESTROYED, int player, ref STRUCTURE structure

- -

triggered when a structure for player is destroyed

- -

CALL_FEATURE_DESTROYED, ref FEATURe feature

- -

triggered when either a unit or a structure for player is destroyed

- -

CALL_OBJ_SEEN, int player, ref BASEOBj object, ref BASEOBJ viewer

- -

triggered when either a unit or a structure is seen by a unit belonging to player.

- -

object is the thing that was seen, viewer is the thing that saw it (may be NULLOBJECT).

- -

CALL_DROID_SEEN, int player, ref BASEOBJ object, ref BASEOBJ viewer

- -

triggered when a unit is seen by a unit belonging to player.

- -

object is the thing that was seen, viewer is the thing that saw it (may be NULLOBJECT).

- -

CALL_STRUCT_SEEN, int player, ref BASEOBJ object, ref BASEOBJ viewer

- -

triggered when a structure is seen by a unit belonging to player.

- -

object is the thing that was seen, viewer is the thing that saw it (may be NULLOBJECT).

- -

CALL_NO_REINFORCEMENTS_LEFT- called when the player has transferred all reinforcements from one level to the next

- -

More tutorial callbacks - ALL tutorial only:

- -

CALL_DESIGN_WEAPON- a weapon button pressed

- -

CALL_DESIGN_SYSTEM- a system (constructor/ecm/sensor/etc) button pressed

- -

CALL_DESIGN_COMMAND- a command droid turret pressed

- -

CALL_DESIGN_BODY- a body selected

- -

CALL_DESIGN_PROPULSION- a propulsion selected

- -

CALL_ALL_ONSCREEN_DROIDS_SELECTED- does exactly when it says on the box

- -

CALL_UNITTAKEOVER, ref unit

- -

Unit has been taken over by nexus link...

- -

CALL_PLAYERLEFT, ref int player

- -

Player has left the multiplayer game.

- -

CALL_ALLIANCEOFFER, ref int one, ref int two

- -

One offers two an alliance.

+
+ +
+ +

Warzone 2100 - AI scripting language manual

+ +

Introduction

+

In order for Warzone scripts to function properly two files are required: a file with a .slo extension and a file with a .vlo extension.

+

A .slo file is the main part of the script and holds executable instructions while the .vlo file holds additional variable declarations necessary for the .slo file to function properly.

+

It is common for a script to deal with new or existing game components such as research topics, structures, unit bodies, propulsions, weapons etc. All these components are defined in appropriate text files like body.txt, structure.txt etc. If you want to use any of these components in your script - in your .slo file - like for example if you want to place certain structures on the map using scripts or enable certain research, you must first make these components available to your script by defining them in a .vlo file.

+

Roughly said a .slo file is equivalent to a ".c" file and .vlo to a header file in C/C++.

+

Specific skirmish/multiplayer notes:

+

Some of the file below doesn't apply to skirmish scripts! Make your changes to player0.slo and vlo -> player7.slo and vlo.

+
+

back to top

+
+
+ +

Comments

+

There are two type of comment for the script language. A multi-line comment is started by the characters /* and finishes with */. A single line comment is started by //.

+
+

back to top

+
+
+ +

Vlo files

+

When writing a script it is usually known what data (as defined in data .txt files, located in 'stats' folder) will be used in the script, so it's a good idea to start writing the script with a .vlo file.

+

Vlo files are structured as follows:

+ 
script "myScript.slo"
+run
+{
+ <variable_definitions>
+}
+

In the first line a .slo file is attached to this particular .vlo file. variable_definitions that resides inside the curly braces is the heart of every .vlo file, it contains definitions of the data that will be used in the main script part - the .slo file. Each variable definition starts on a new line and is structured as follows:

+ 
<variable_name> <variable_type> <variable_value>
+

NOTE: Available data types are covered later.

+

For example if you want to have access to certain droid bodies, like "Python" in your script you have to define it in your .vlo file and assign it to a variable of type BODY with some descriptive name, like:

+ 
myPythonBody BODY "Body11ABT"
+

"Body11ABT" is an internal name of the "Python" body used by warzone, it is defined in the body.txt file. Since it is a string it must be put inside quotation marks. All components, be it some research, structure, droid template or a weapon is referred by its internal name in the game and are defined in the appropriate txt data files.

+

Each variable definition in a .vlo file starts on the new line and ends at the end of the line.

+

It is also possible to define arrays of some data type. For example if you want to use the following 3 research topics in your script you might want to define them like this:

+ 
myResearch[0] RESEARCHSTAt "R-Vehicle-Body11"
+myResearch[1] RESEARCHSTAt "R-Vehicle-Prop-Tracks"
+myResearch[2] RESEARCHSTAt "R-Vehicle-Prop-Hover"
+

This defines an array of size 3 of type RESEARCHSTAT.

+
+

back to top

+
+
+ +

Slo files

+

As already mentioned .slo file is the heart of every script, it is the place for the executable code. Slo files can be devided into 3 main parts:

+
    +
  1. Variable declarations
    2. +
  2. Event and function declaration
    3. +
  3. Executable code
    4. +
+

Variables used throughout the script are defined in the Variable declarations part, with exception of the local variables, which are explained later.

+

For the .slo file to be able to access variables declared in the .vlo file they must be declared as public variables in the corresponding .slo file.

+

Coming back to the two examples above you will have to add following lines to the .slo file:

+ 
public BODy myPythonBody;
+public RESEARCHSTAT myResearch[3];
+

Keyword public signals that the variable is defined in the corresponding .vlo files. Note that unlike in .vlo files variable declarations in .slo files end with a semicolon and unlike in .vlo files it is possible to declare more than one variable of the same type at once.

+

More generally a variable declaration in a .slo file looks like this:

+ 
<storage> <variable_type> <variable_name1> [, <variable_name2> , ...];
+

storage is one of public or private. public means that the variable is declared and defined in the corresponding .vlo file. private means the value is only used in the .slo file. Unlike local variables public and private variables are global variables that can be access from anywhere in the .slo file.

+

NOTE: All variables are initialized to their default values when created. STRUCTURE/DROID/FEATURE variables are initialized to NULLOBJECT, STRINGs to "", FLOATs to 0.0, INTs to 0, BOOLs to FALSE etc.

+
+

back to top

+
+
+ +

Event/trigger concept

+

In Warzone 2100 scripts executable code consists of events. An event is a list of instructions activated by some trigger attached to it. Event defines what to do, a trigger defines when to run an event, i. e. when to execute the code inside an event.

+

All events are structured as follows:

+ 
event <event_name>(<trigger>)
+{
+ <code>
+}
+

Example:

+ 
event myFirstEvent(every, 50)
+{
+ console("Hello world!");
+}
+

This piece of code will output "Hello world!" to the game console every 5 seconds. Note that triggers are put inside the round braces after the event name while code that is to be executed resides inside the curly braces. The syntax of the executable code is very close to the C/C++ syntax.

+

The only difference between a WZ event and a function as used in programming languages like C/C++ is that an event is not called or activated by another function, but rather by a trigger attached to it.

+

It is always possible to interrupt execution of an event with the exit keyword, which is a counterpart of the return keyword used for functions; exit keyword does not deactivate an event.

+

Example:

+ 
event myEvent(every, 10) //run every second
+{
+ console ( "this text will be printed every second" );
+ if( (gameTime / 10) > 60) //did more than a minute pass?
+	{
+	 exit; //anything that comes after 'exit' will not be executed
+	 console( "this text will only get printed in the first" );
+	}
+}
+

Events must be defined before they can be referenced. If event definition comes after the place where this event is referenced it is necessary to declare this event beforehand in the event and function declaration section.

+

Events are declared like this:

+ 
event <event_name>;
+

Such a declaration reserves identifier used as event name.

+

Example:

+ 
event myEvent; //declaration of the event
+...
+// another event that references myEvent
+event anotherEvent(wait, 10)
+{
+ setEventTrigger(myEvent, inactive); //deactivate myEvent
+}
+...
+// myEvent is defined after being referenced by anotherEvent,
+// but it works, since we declared myEvent beforehand
+event myEvent(wait, 20)
+{
+ console("It all compiles, because I was declared beforehand!");
+}
+

If myEvent wasn't declared before being referenced by anotherEvent then this example would not compile.

+
+

back to top

+
+
+ +

Triggers

+

In Warzone 2100 triggers are usually simple timers that repeatedly trigger execution of events, but triggers can also be callbacks (special events that occur in the game, like destruction of a building) that are listed and explained later.

+

Here are available trigger types:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Trigger typeEffect
wait, <time>Run the event after delay <time>.
every, <time>Run the event at every <time> interval.
<callback>Run when callback occurs.
<bool exp>, <time>Run the event if <bool exp> is true, checking every <time> interval.
initRun the event when the script starts.
inactiveDo not run the event until a trigger is assigned to it.
+

NOTE: All time intervals are in 1/10 of a second.

+

For example every, 10 will trigger every second while wait, 50 will only activate once: 5 seconds after the game has started. If an event has inactive assigned as a trigger this event will never execute unless its trigger is reassigned by some other event with setEventTrigger(<event>, <trigger>) function.

+

NOTE: Complete function and callback listings are given below.

+

A few examples:

+ 
// 1. output text to game console every second
+event everySecond(every, 10)
+{
+ console("The game has started " + gameTime/10 + " seconds ago");
+}
+
+// 2. Code inside this event will never execute unless its event is reassigned later
+event inactiveEvent(inactive)
+{
+ console("Someone has just reactivated me!");
+}
+
+// 3. CALL_NEWDROID callback with parameters
+event droidBuilt(CALL_NEWDROID, 5, ref newDroid, ref myFactory)
+{
+ console("We got a new droid at coordinates " &
+         newDroid.x & "-" & newDroid.y );
+}
+

In the last example droidBuilt event will be triggered everytime a factory belonging to player 5 produces a new droid. newDroid variable refers to the new droid that was just built and myFactory to the factory that build this droid. This example assumes that newDroid and myFactory were correctly defined in the variable declarations section. For more callbacks see Script function callbacks.

+

NOTE: ref keyword means that a pointer to the provided variable is passed to the interpreter, so that a callback can modify value of the variable.

+

It is possible to reuse a trigger for more than one event if a trigger is declared in the event and function declaration. Trigger declaration has following syntax:

+ 
trigger <trigger_name> ( <trigger> );
+

Example:

+ 
trigger everySecond ( every, 10 ); //trigger declaration
+...
+event eventOne( everySecond ) // uses the trigger we declared above
+{
+ ...
+}
+
+event eventTwo( everySecond ) // uses the trigger we declared above
+{
+ ...
+}
+

In this example everySecond trigger is defined outside of an event. Such a trigger can be reused by its name. Note that trigger declaration ends with a semicolon.

+
+

back to top

+
+
+ +

Expressions

+

String expressions

+

Strings are put inside quotation marks: "some text inside quotation marks is a legal string".

+

Strings can be easily concatenated using the & operator.

+

For example: "String1" & "String2" will result in "String1String2".

+

Strings can be compared using == operator (case insensitive comparison) or strcmp() function.

+

Such data types as integers, booleans and floats are automatically converted to strings when it is required, so given the following variable declaration:

+ 
private float pi;
+private int myInteger;
+private string myString;
+private bool myBool;
+

The following line is a valid string expression:

+ 
console("value of pi is " & pi & ", value of myInteger is " & myInteger & ",
+value of myString is " & myString & ", value of myBool is " & myBool);
+
+

back to top

+
+
+ +

Numeric expressions

+

Numeric expressions are made up of int variables, numeric constants and functions that return int values, e. g.:

+ 
power * 32 - basePower
+numDroids(player) + 5
+

The possible operators are: + - * /

+

Increment and decrement operators can only be applied to the integer variables outside of the expression context:

+ 
myInteger++;
+myInteger--;
+

There are also a number of operators that compare numeric expressions to give a boolean

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning
<Less than
>Greater than
<=Less than or equal
>=Greater than or equal
==Equal
!=Not equal
+
+

back to top

+
+
+ +

Boolean expressions

+

Boolean expressions are made up of bool variables, the boolean constants TRUE and FALSE and game functions that return a boolean value e.g.:

+ 
not droidSeen and attackDroid
+

The possible operators are:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorMeaning
bool1 and bool2True if bool1 and bool2 are true
bool1 or bool2True if at least one of bool1 and bool2 is true
not bool1True becomes false and false becomes true
==Can also be used with user defined tyoe variables
!=Can also be used with user defined tyoe variables
+
+

back to top

+
+
+ +

Floating point expressions

+

Floating point expressions are very similar to integer expressions. There are some differences though: it is not possible to use increment/decrement operators with floating point variables. The integral and fractional parts of the float constant must be separated by a dot, even if fractional part is 0.

+

Examples:

+ 
myFloat = 1.0 + pi / 2.0 + 3.6;
+

Floating point expressions cannot be mixed with integer or boolean expressions. To use integers or booleans in floating point expressions they must be cast to FLOATs first.

+

For more information about casts refer to casts.

+
+

back to top

+
+
+ +

Assignment

+

The value of a variable or an expression can be assigned to another using the = character, e.g.:

+ 
currentDroid = foundDroid;
+index = base + found * 4;
+myString = "some text";
+myFloat = 2.0 + pi / 2.0;
+
+

back to top

+
+
+ +

If statements

+

If statements are used to control which bits of code are executed. The simplest form is:

+ 
if ( <bool exp> )
+{
+ <code>
+}
+

In this form if <bool exp> evaluates to true then the script code <code> is executed, otherwise the code is ignored.

+

Examples:

+ 
if ( <bool exp> )
+{
+ <code>
+}
+else
+{
+ <other code>
+}
+
+if ( <bool exp> )
+{
+ <code>
+}
+else if ( <other bool exp> )
+{
+ <other code>
+}
+else
+{
+ <yet another code>
+}
+
+

back to top

+
+
+ +

While statements

+

While statements allow <code> to be executed while <bool exp> evaluates to TRUE:

+ 
while ( <bool exp> )
+{
+ <code>
+}
+
+

back to top

+
+
+ +

Casts

+

Casts convert one data type into a different one. In Warzone 2100 casts are mostly used to convert float to int, int to float and bool to float. To perform a cast write the required data type in parenthesis.

+

Examples:

+ 
myFloat = (float)myInteger + 2.3 + (float)500 + 500.0;
+myInteger = 100 + numPlayers + (int)myFloat;
+

NOTE: Both (float)500 and 500.0 represent the same value. When converting FLOATs to INTs fractional part is discarded.

+
+

back to top

+
+
+ +

Custom functions

+

It is possible to define custom script functions to reuse certain functionality throughout the script.

+

Functions have following syntax:

+ 
function <return type> <function name> ( [ <argument type> < argument name> , ... ] )
+{
+ <code>
+ return ... ;
+}
+

Examples:

+ 
function void displayVictoryMessage( int winner )
+{
+ console ( "Player " & getPlayerName(winner) & " has won the game" );
+}
+
+function float calculateMinimum ( float f1, float f2 )
+{
+ if ( f1 < f2 )
+ {
+  return f1;
+ }
+ return f2;
+}
+

Functions look almost identical to their C counterparts, except that the beginning of a function is marked with function keyword.

+

It is possible to declare functions like with events it is done in the event and function declaration section:

+ 
function void displayVictoryMessage( int winner );
+function float calculateMinimum ( float f1, float f2 );
+

Declared this way it is possible to use a function before it is defined later in the script. To call a function simply provide its name with parameters in parenthesis:

+ 
displayVictoryMessage(0);
+...
+console("Minimum of 2 and 2.1 is " & calculateMinimum(2.0, 2.1) );
+

Like in C return <return expression>; or for void functions just return; returns execution to the caller.

+
+

back to top

+
+
+ +

Local variables

+

Local variables belong either to a function or event where they were declared and are not accessible outside of it. Local variables must be declared at the beginning of the function or event. Like public/private variables local variables of the same type can be declared on the same line separated by a comma.

+

Declaration of a local variable looks as follows:

+ 
local <variable type> <variable name> [, <variablename>, ...] ;
+

Example:

+ 
event myEvent(myTrigger)
+{
+ local int count;
+ <code>
+}
+
+function void myFunction()
+{
+ local DROId myDroid1, myDroid2;
+ local string myString;
+ <code>
+}
+
+

back to top

+
+
+ +

Macros

+

The Warzone 2100 Scripting language supports nested macros (current max. depth is 10). Parametrized macros are not supported. Macros are defined as follows:

+ 
#define <macro name> <macro body>
+

Example:

+ 
#define pi 3.14
+

Example of a nested macro:

+ 
#define CURRENT_PLAYER 0
+#define CURRENT_PLAYER_NAMe getPlayerName(CURRENT_PLAYER)
+

During the compilation process macro names are replaced with the actual code.

+

If any other text but "define" follows after # character then anything between # and end of the line is ignored by compiler making it possible to use #region and other tags in your favorite IDE.

+

NOTE: "#include" is reserved but not fully supported yet.

+
+

back to top

+
+
+ +

Data types

+

Apart from standard data types like string (string), integer (int), boolean (bool) and floating point (float) there are some Warzone 2100-specific data types available:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data typeMeaning
INTMESSAGESimple. Name of a message as defined in Messages.txt, used mostly for campaign. In most cases it is easier to use a string instead.
BASEOBJComplex. Any of a DROID, FEATURE or STRUCTURE. It is a pointer to some droid/feature/structure on the map, can be NULLOBJECT if it wasn't assigned to a particular droid/feature/structure. You have access to the following variables: +
    +
  • baseobj.x
    • +
  • baseobj.y
    • +
  • baseobj.z
    • +
  • baseobj.id - unique ID number
    • +
  • baseobj.player - player ID
    • +
  • baseobj.type - one of OBJ_DROID, OBJ_STRUCTURE, OBJ_FEATURE
    • +
  • baseobj.health - %age number of body points left
    • +
  • baseobj.clusterID - the cluster the object is a member of
    • +
  • baseobj.target - target of the object (in case of a multi-turret object returns target of the default weapon)
    • +
+
DROIDComplex. Defined by the ID got from the world editor. It is a pointer to a particular droid on the map, can be NULLOBJECT when no droid is assigned to the DROID variable. You have access to following variables: +
    +
  • droid.x
    • +
  • droid.y
    • +
  • droid.z
    • +
  • droid.id - unique ID number
    • +
  • droid.player - player ID
    • +
  • droid.type - one of OBJ_DROID, OBJ_STRUCTURE, OBJ_FEATURE
    • +
  • droid.health - %age number of body points left
    • +
  • droid.clusterID - the cluster the object is a member of
    • +
  • droid.target - target of the object (in case of a multi-turret object returns target of the default weapon)
    • +
  • droid.order - current order of the droid
    • +
  • droid.orderx - target location of the droid order
    • +
  • droid.ordery - target location of the droid order
    • +
  • droid.action - current action of the droid
    • +
  • droid.body - the BODY of the droid
    • +
  • droid.propulsion - the PROPULSION of the droid
    • +
  • droid.weapon - the WEAPON of the droid DROIDID - (simple) literally just an Id of a droid
    • +
  • droid.selected - holds TRUE if droid is currently selected
    • +
  • droid.group - the GROUP droid belongs to
    • +
+
FEATUREComplex. Defined by the ID got from the world editor. It is a pointer to a map decoration, like a tree, wrecked building, oil resource etc, can be NULLOBJECT. You have access to following variables: +
    +
  • feature.x
    • +
  • feature.y
    • +
  • feature.z
    • +
  • feature.id - unique ID number
    • +
  • feature.player - player ID
    • +
  • feature.type - one of OBJ_DROID, OBJ_STRUCTURE, OBJ_FEATURE
    • +
  • feature.health - %age number of body points left
    • +
  • feature.clusterID - the cluster the object is a member of
    • +
  • feature.target - target of the object (in case of a multi-turret object returns target of the default weapon)
    • +
+
FEATURESTATSimple. Type of a feature as defined in features.txt.
TEMPLATESimple. Name of a template as defined in templates.txt.
STRUCTUREComplex. Defined by the ID got from the world editor. It is a pointer to a particular structure on the map, can be NULLOBJECT when no structure is assigned to the STRUCTURE variable. You have access to the foillowing variables: +
    +
  • structure.x
    • +
  • structure.y
    • +
  • structure.z
    • +
  • structure.id - unique ID number
    • +
  • structure.player - player ID
    • +
  • structure.type - one of OBJ_DROID, OBJ_STRUCTURE, OBJ_FEATURE
    • +
  • structure.health - %age number of body points left
    • +
  • structure.clusterID - the cluster the object is a member of
    • +
  • structure.target - target of the object (in case of a multi-turret object returns target of the default weapon)
    • +
  • structure.stat - the STRUCTURESTAT of the structure, defined in structures.txt
    • +
  • structure.stattype - structure type (likeREF_HQ etc.; refers to Script function constants)
    • +
+
STRUCTUREIDSimple. Literally just an ID of a struct.
STRUCTURESTATSimple. Type of a structure as defined in structures.txt.
BODYSimple. Name of a body as defined in body.txt.
PROPULSIONSimple. Name of a propulsion as defined in propulsion.txt.
ECMSimple. Name of an ECM as defined in ecm.txt.
SENSORSimple. Name of a sensor as defined in sensor.txt.
CONSTRUCTSimple. Name of a construct as defined in construct.txt.
WEAPONSimple. Name of a weapon as defined in weapons.txt.
REPAIRSimple. Name of a repair type as defined in Repair.txt.
BRAINSimple. Name of a brain type as defined in Brain.txt.
SOUNDSimple. ID of sound used in playSound().
LEVELSimple. ID of a level as defined in GameDesc.lev.
RESEARCHSTATSimple. Name of a research topic as defined in research.txt.
GROUPComplex. A group of droids. Don't confuse GROUP with in-game units' groups that can be accessed with CTRL-<number>, they have nothing in common. GROUP is an internal structure used to simplify unit management. You have access to following variables: +
    +
  • group.x - average x coord
    • +
  • group.y - average y coord
    • +
  • group.members - number of units in the group
    • +
  • group.health - average %age health of the units
    • +
  • group.type - type of the group, one of: GT_NORMAL, GT_COMMAND or GT_TRANSPORTER (refer to Script function constants)
    • +
  • group.commander - commander of the group, if type = GT_COMMAND or NULLOBJECT
    • +
+
+

NOTE: The functions objToDroid, objToStructure and objToFeature exist to convert a BASEOBJ to a droid, structure or feature if the base obj is of the right type.

+

NOTE: Transporters and commanders can't be added to a GROUP.

+

With a complex object it is possible to access information specific to the instance of this object. Acomplex object is usually a pointer to a C structure in the code. For example a DROID is a complex object - its x,y,z can be queried whereas a DROIDID (a simple object - an integer) is just a placeholder for the numeric value of the ID.

+
+

back to top

+
+
+ +

Script functions

+

Environment

+
+
setSnow(bool)
+
This function switches snow on or off. TRUE will turn snow on, FALSE will turn snow off. If rain is on when snow is started the rain will be turned off.
+
setRain(bool)
+
This function switchs rain on or off. TRUe will turn rain on, FALSE will turn rain off. If snow is on when rain is started the snow will be turned off.
+
setBackgroundFog(bool)
+
This function switchs background fog on or off. This sets the backdrop to the current fogcolour and fogs the edge of the visible world. TRUE will turn background fog on, FALSE will turn background fog off.
+
setDepthFog(bool)
+
This function switchs depth fog on or off. This sets the sets fog ramping up from zero in the middle of the view to full fog at the edge of the visible world. TRUE will turn depth fog on, FALSE will turn depth fog off.
+
setFogColour(RED, GREEN, BLUE)
+
This function sets the fog colour, to be used when fog is enabled. This colour is also used in the background clear when fog is enabled. The colour is specified as RED, GREEN and BLUe components each in the range 0 to 255. This yields a 24 bit colour value. Colour values outside the range 0 to 255 will have an indeterminate effect.
+
Warning: Setting the fog colour to black (0, 0, 0) does not turn fog off and should be avoided.
+
Standard values: +
    +
  • Arizona: 204, 149, 70 (CC9546) (old: 176, 143, 95 (B08F5F))
    • +
  • Urban: 201, 146, 15 (C9920F)
    • +
  • Rockies: 182, 225, 236 (B6E1EC)
    • +
+
+
+ +

Components

+
+
enableComponent(COMPONENT, PLAYER)
+
This function makes a component found to a player - so that they can research a topic that requires the component COMPONENT is any type of Body, Propulsion, Weapon, ECM, Sensor, Construct etc. PLAYER is the id of the player who gets the component.
+
makeComponentAvailable(COMPONENT, PLAYER)
+
This function makes a component available to a player - so that they can build Units using this component. COMPONENT is any type of Body, Propulsion, Weapon, ECM, Sensor, Construct etc. PLAYER is the id of the player who gets the component
+
enableStructure(STRUCTURESTAT, PLAYER)
+
This function makes a structure available to a player - so that they can research a topic that requires the structure or build the structure STRUCTURESTAT is defined by the name from Access. PLAYER is the id of the player who gets the structure.
+
+ +

Research

+
+
enableResearch(RESEARCHSTAT, PLAYER)
+
This function makes a research topic available to a player regardless of its pre-requisites. RESEARCHSTAT is defined by the name from Access. PLAYER is the id of the player who gets the research
+
completeResearch(RESEARCHSTAT, PLAYER)
+
This function acts as if the research was performed by the player giving them the results. RESEARCHSTAT is defined by the name from Access. PLAYER is the id of the player who gets the research
+
+

Position and visibility

+
+
bool objectInRange(PLAYER, X,Y, RANGE)
+
This function checks for when an object belonging to a player is within range of a position. PLAYER is the id of the player whose unit is checked for in range. X,Y is the position to check from in world coords. RANGE is in world coords - 128 units = 1 tile.
+
bool droidInRange(PLAYER, X,Y, RANGE)
+
This function checks for when a droid belonging to a player is within range of a position. PLAYER is the id of the player whose unit is checked for in range. X,Y is the position to check from in world coords. RANGE is in world coords - 128 units = 1 tile.
+
bool structInRange(PLAYER, X,Y, RANGE)
+
This function checks for when a structure belonging to a player is within range of a position. PLAYER is the id of the player whose unit is checked for in range. X,Y is the position to check from in world coords. RANGE is in world coords - 128 units = 1 tile.
+
bool objectInArea(PLAYER, X1,Y1, X2,Y2)
+
This function checks for when an object belonging to a player is in a square area. PLAYER is the id of the player whose droid is checked for in area. X1,Y1, X2,Y2 is the area to check in world coords. X1,Y1 should be smaller than X2,Y2
+
bool droidInArea(PLAYER, X1,Y1, X2,Y2)
+
This function checks for when a droid belonging to a player is in a square area. PLAYER is the id of the player whose droid is checked for in area. X1,Y1, X2,Y2 is the area to check in world coords. X1,Y1 should be smaller than X2,Y2
+
bool structInArea(PLAYER, X1,Y1, X2,Y2)
+
This function checks for when a structure belonging to a player is in a square area. PLAYER is the id of the player whose droid is checked for in area. X1,Y1, X2,Y2 is the area to check in world coords. X1,Y1 should be smaller than X2,Y2
+
bool droidHasSeen(OBJECT, PLAYER)
+
This functions checks for when a player has seen a given object - either by unit or structure. OBJECT is any type of DROID, FEATURE, STRUCTURE. PLAYER is the id of the player to check for having seen
+
+

Droids

+

addDroid(TEMPLATE, X, Y, PLAYER)

+

This function adds a unit for the player based on the template passed in.

+

The unit is placed at x,y

+

TEMPLATE is a valid template (doesn't have to belong to the player!)

+

X, Y are in world coords

+

PLAYER is the id of the player whose the unit belongs to

+ +

buildDroid(TEMPLATE, STRUCTURE, PLAYER, QUANTITY)

+

This function sets a factory defined by STRUCTURE to build units based on the TEMPLATE for the PLAYER.

+

TEMPLATE is a valid template (doesn't have to belong to the player!)

+

STRUCTURE is a structure defined by ID and MUST BE A FACTORY

+

PLAYER is the id of the player whose the unit belongs to

+

QUANTITY is the number of units that will be built

+ +

bool buildingDestroyed(STRUCTUREID, PLAYER)

+

This function checks that a structure (given by the id) no longer exists for the player

+

STRUCTUREID is the id of the structure - Nb this is different to an object of type STRUCTURE

+

PLAYER is the id of the player whose list is checked for the building

+

bool structureIdle(STRUCTURE)

+

This function checks whether the structure is doing anything. Returns TRUE if idle

+

STRUCTURE is a valid structure defined by ID

+

bool structureBeingBuilt(STRUCTURESTAT, PLAYER)

+

This function checks that a structure of type STRUCTURESTAT is currently being built for the specified PLAYER

+

STRUCTURESTAT is defined by the name from Access

+

PLAYER is the id of the player who gets the structure

+

bool structureBuilt(STRUCTURESTAT, PLAYER)

+

This function checks that a structure of type STRUCTURESTAT is currently built for the specified PLAYER

+

STRUCTURESTAT is defined by the name from Access

+

PLAYER is the id of the player who gets the structure

+ + +

addReticuleButton(BUTTONID)

+

This function adds a reticule button to the interface

+

BUTTONID is the id of a button - see Script function constants

+

removeReticuleButton(BUTTONID)

+

This function removes a reticule button from the interface

+

BUTTONID is the id of a button - see Script function constants

+

addMessage(INTMESSAGE, MESSAGETYPE, PLAYER, PLAY_IMMEDIATE)

+

This adds a message to the interface for the PLAYER

+

INTMESSAGE is a variable defined in the values file

+

MESSAGETYPE is a predefined type - see Script function constants

+

PLAYER is the player who gets the message

+

PLAY_IMMEDIATE is a bool for whether to bring the Intelligence Screen up with the message immediately or just store it

+

removeMessage(INTMESSAGE, MESSAGETYPE, PLAYER)

+

This removes a message from the interface for the PLAYER

+

INTMESSAGE is a variable defined in the values file

+

MESSAGETYPE is a predefined type - see Script function constants

+

PLAYER is the player who loses the message

+

bool selectDroidByID(DROIDID, PLAYER)

+

This selects a unit defined by the ID since we can't guarantee the name! Only the list of units belonging to PLAYER will be checked. This returns TRUE if the unit could be found - it will be worth checking it exists!

+

DROIDID is a valid unit defined by ID

+

setAssemblyPoint(X, Y, STRUCTURE)

+

This sets the location of where new units assemble at for a specific factory

+

X, Y are the x and y in world coordinates

+

STRUCTURE is a valid structure defined by ID

+

FEATURE addFeature( FEATURESTAT, X, Y )

+

Builds a feature at position (x,y).

+

FEATURESTAT is the name of a feature stat defined in features.txt.

+

The feature identifier is returned - this can be used in e.g. destroyFeature.

+

destroyFeature(FEATURE)

+

This removes the feature from the world

+

FEATURE is a feature defined by ID

+

centreView(OBJECT)

+

This function centres the view on the object supplied

+

OBJECT is any type of DROID, FEATURE, STRUCTURE

+

STRUCTURE addStructure( STRUCTURESTAT, PLAYER, X, Y )

+

Builds a structure belonging to PLAYER centred at (X, Y).

+

The structure must be previously enabled via enableStructure().

+

The structure identifier is returned - this can be used in e.g. destroyStructure.

+

destroyStructure(STRUCTURE)

+

This removes the structure from the world

+

STRUCTURE is a structure defined by ID

+

STRUCTURE getStructure(STRUCTURESTAT, PLAYER)

+

This function returns the first STRUCTURe based on the stat for the player it can find.

+

To use it create a STRUCTURE variable and assign it to the result of the function call.

+

For example:

+

STRUCTURe myNewStructure;

+

STRUCTURESTAt Factory;

+

myNewStructure = getStructure(Factory, 0);

+

This will look through the player 0 list of structures to find a Factory and return a variable of type STRUCTURE. You will then be able to access the x, y, and z. If a structure cannot be found than NULL is returned . It will be worth checking that the STRUCTURE does not equal NULL before using it. For example:

+

if (myNewStructure == NULLOBJECT)

+

{

+

do something

+

}

+

void initEnumStruct(bool any, STRUCTURESTAt type, int targetPlayer, int lookingPlayer)

+

STRUCTURE enumStruct()

+

Enumerate through visible structures of given 'type' of player 'targetPlayer' that are visible to 'lookingPlayer'. Returns NULLOBJECT when no more exist.

+

If 'any' is set to TRUE, then 'type' is ignored and all structure types will be iterated.

+

void InitEnumDroids(int targetPlayer, int lookingPlayer)

+

DROID EnumDroid()

+

Enumerate through all targetPlayer's droids that are visible to 'lookingPlayer'. Returns NULLOBJECT when no more exist.

+

TEMPLATE getTemplate(COMPONENT, PLAYER)

+

This function returns the first TEMPLATE based on the stat for the player it can find. It can be any type of component. To use it create a TEMPLATE variable and assign it to the result of the function call. For example:

+

TEMPLATe myNewTemplate;

+

WEAPOn Rocket;

+

myNewTemplate = getStructure(Rocket, 0);

+

This will look through the player 0 list of template to find one which contains a rocket and then return a variable of type TEMPLATE. You will then be able to access its attributes. If a template cannot be found than NULL is returned . It will be worth checking that the TEMPLATe does not equal NULL before using it. For example:

+

if (myNewTemplate == NULLTEMPLATE)

+

{

+

do something

+

}

+

setScrollParams(minX, minY, maxX, maxY)

+

This literally sets the scroll settings for the current map - be careful not to set the maxX/maxY greater than that possible for the map!

+

minX, minY, maxX, maxY are all numbers. These are in TILE COORDINATES!!!!!!

+

setScrollMinX(minX)

+

This just sets the one variable. These are in TILE COORDINATES!!!!!!

+

minX is a number

+

setScrollMinY(minY)

+

This just sets the one variable. These are in TILE COORDINATES!!!!!!

+

minY is a number

+

setScrollMaxX(maxX)

+

This just sets the one variable. These are in TILE COORDINATES!!!!!!

+

maxX is a number

+

setScrollMaxY(maxY)

+

This just sets the one variable. These are in TILE COORDINATES!!!!!!

+

maxY is a number

+

setDefaultSensor(SENSOR, PLAYER)

+

This sets which sensor will be used as the default when designing units in game for the specified player. The SENSOR must be a valid DEFAULT sensor.

+

setDefaultECM(ECM, PLAYER)

+

Like the above functionm, this sets which ECm will be used as the default when designing units. Again the ECM must be a valid DEFAULT ECM.

+

setStructureLimits(STRUCTURESTAT, LIMIT, PLAYER)

+

This sets a limit for a specific structure on how many can be built on a map.

+

STRUCTURESTAT is defined by the name from Access

+

LIMIT is a number between 0 and 255

+

PLAYER is the id of the player

+

setAllStructureLimits(LIMIT, PLAYER)

+

This sets a limit for all structures on how many can be built on a map.

+

LIMIT is a number between 0 and 255

+

PLAYER is the id of the player

+

playSound( SOUND, PLAYER)

+

Plays a '2D' sound ie speech and is audible for the player identified

+

SOUND is a defined type.

+

PLAYER is the id of the player

+

playSoundPos( SOUND, PLAYER, x, y, z)

+

Plays a '2D' sound ie speech and is audible for the player identified

+

Position of sound is saved so camera can move to object playing sound if required.

+

SOUND is a defined type.

+

PLAYER is the id of the player

+

x, y, z is the position of the object in game units.

+

addConsoleText( TEXTSTRING, PLAYER)

+

Adds console text to the top of the screen (centre justified) for the player concerned

+

TEXTSTRING is a string ID obtained from strings.txt

+

PLAYER is the id of the player

+

turnPowerOn()

+

Literally makes the power calculations be used

+

turnPowerOff()

+

Literally stops the power calculations being used

+

setPowerLevel(POWER, PLAYER)

+

sets the power level for a player - this overrides any current setting there is

+

POWER is the value to set the player's power to

+

PLAYER is the id of the player

+

addPower(POWER, PLAYER)

+

adds the POWER amount to the PLAYER's current level

+

POWER is the value to add to the player's power

+

PLAYER is the id of the player

+

setLandingZone(x1, y1, x2, y2)

+

sets the landing zone for the map. The coords are in tile units and must all be less than 255

+

setLimboLanding(x1, y1, x2, y2)

+

sets the landing zone for the Limbo Units. The coords are in tile units and must all be less than 255

+

The units from the Limbo list are then placed at this location - so call in CALL_GAME_INIT of the mission you want them to appear in

+

initAllNoGoAreas()

+

initialises all the no go areas to 0. Should be called when a new map is loaded

+

setNoGoArea(x1, y1, x2, y2, areaNum)

+

defines an area that cannot be built on - used for enemy landing zones.

+

areaNum is a number between 0 and 7. If 0, then this function is the same as calling setlandingZone

+

setTransporterExit( PLAYER, exitTileX, exitTiley )

+

setup transporter exit point on map for PLAYER

+

flyTransporterIn( PLAYER, entryTileX, entryTileY, bool bTrackTransporter )

+

flys PLAYER's transporter in from entry point on map; set bTrackTransporter true to

+

track it onto the map.

+

tutorialEnd()

+

A bit of a hack to notify the game when the last of the tutorial events has been run

+

so that the console messages can be turned back on to how they will appear for

+

the rest of the game

+

gameOver(bool)

+

function to call for ending the game

+

bool - true or false depending on whether the player has won or not

+

anyDroidsLeft(PLAYER)

+

checks the specified player for any units - returns TRUE if some exist, FALSE if

+

they have all been destroyed

+

anyStructButWallsLeft(PLAYER)

+

checks the specified player for any structures except walls - returns TRUE if some

+

exist, FALSE if they have all been destroyed

+

anyFactoriesLeft(PLAYER)

+

returns true if player has a factory/cyborg factory/ vtol factory

+

setRetreatPoint(PLAYER, x,y)

+

sets the position for a players units to retreat to

+

setRetreatForce(int player, int level)

+

Sets the percentage of the current force below which units for a side will retreat

+

setRetreatLeadership(int player, int level)

+

Sets the leadership level (chance to run away) for a player (1-100)

+

startMission(MISSION_TYPE, LEVEL)

+

Starts a mission for the currently selected player - NB Transporters must be filled if

+

you want units to appear on the Mission map

+

MISSION_TYPE is a predefined type - see Script function constants

+

LEVEL is the name of the level to load as defined in GameDesc.lev

+

endMission(bool)

+

Ends the current mission the selected player is on - returns all Units that have been

+

loaded onto the Transporter. False if player lost, true if player won????

+

bool allianceExists()

+

returns true if two or more players are in alliance. returns false otherwise.

+

bool dominatingAlliance()

+

returns true if there is a single dominating alliance, using all multi-players.

+

bool playerInAlliance()

+

returns true if player is in an alliance

+

bool myResponsibility(PLAYER)

+

returns true if this machine is responsible for 'player' in multiplayer games.

+

STRUCTURe structureBuiltInRange(STRUCTURESTAT, X, Y, RANGE, PLAYER)

+

Checks to see if a Structure has been built within a specified range of x, y. The first structure

+

to be found within this range will be returned. Check the result of the function for being

+

NULLOBJECT before using!

+

STRUCTURE is a return value (structure defined by ID)

+

STRUCTURESTAT is defined by the name from Access

+

X, Y, RANGE are all in world coords

+

PLAYER is the id of the player whose structure list is searched

+

groupAddDroid(GROUP, DROID)

+

Add a unit to a group

+

groupAddArea(GROUP, PLAYER, X1,Y1, X2,Y2)

+

Add all the units inside the rectangle X1,Y1, X2,Y2.

+

Only units belonging to player PLAYER are added.

+

groupAddAreaNoGroup(GROUP, PLAYER, X1,Y1, X2,Y2)

+

as above but doesnt add units that are already grouped.

+

groupAddGroup(group1, group2)

+

Add all the units in group2 to group1.

+

All the units are removed from group2.

+

bool hasGroup(DROID droid)

+

Returns TRUE if 'droid' belongs to any group, retzrns FALSE otherwise.

+

orderDroid(DROID, order)

+

Give a unit an order currently one of:

+

DORDER_STOp - stop current order

+

DORDER_RETREAt - retreat

+

DORDER_DESTRUCT - self destruct

+

DORDER_RTr - return to repair

+

DORDER_RTb - return to base

+

DORDER_RUn - run away for a bit (moral failure)

+

orderDroidLoc(DROID, order, x,y)

+

Give a unit an order with a location :

+

DORDER_MOVe - move to location

+

orderDroidObj(DROID, order, BASEOBJ)

+

Give a unit an order with an object :

+

DORDER_ATTACK- attack the object

+

DORDER_HELPBUILD- help construct the object

+

DORDER_DEMOLISH- demolish structure

+

DORDER_REPAIR- repair structure

+

DORDER_OBSERVE- (sensor units) keep a target in sensor range

+

DORDER_EMBARK- get onto a transporter

+

DORDER_FIRESUPPORT- follow this sensor unit and attack anything it DORDER_OBSERVE's

+

orderDroidStatsLoc(DROID, int order, STRUCTURESTAT stats, int x, int y)

+

Give a unit an order with stats and a location :

+

DORDER_BUILD - build a structure at the location

+

orderGroup(GROUP, order)

+

Give all the units in the group an order

+

orderGroupLoc(GROUP, order, x,y)

+

Give all the units in the group an order with a location

+

orderGroupObj(GROUP, order, BASEOBJ)

+

Give all the units in the group an order with an object

+

DROID objToDroid(BASEOBJ)

+

Convert a BASEOBJ to DROID when BASEOBJ.type == OBJ_DROID. Returns NULLOBJECT otherwise

+

STRUCTURE objToStructure(BASEOBJ)

+

Convert a BASEOBJ to STRUCTURE when BASEOBJ.type == OBJ_STRUCTURE. Returns NULLOBJECT otherwise

+

FEATURE objToFeature(BASEOBJ)

+

Convert a BASEOBJ to FEATURE when BASEOBJ.type == OBJ_FEATURE. Returns NULLOBJECT otherwise

+

int random(range)

+

Return a random number between 0 and range - 1.

+

flashOn(int buttonID)

+

turn on flashing for a button (id's in Script function constants)

+

... now works for all buttons not just reticule buttons

+

flashOff(int buttonID)

+

turn off flashing for a button

+

createAlliance(int player1, int player2)

+

Create an alliance between two players

+

breakAlliance(int player1, int player2)

+

Breake an alliance between two players

+

setRadarZoom(int level)

+

level is the zoom level between 0 .. 2 on the PC and 0 .. 1 on PSX.

+

0 is the most zoomed out, 2 the most zoomed in.

+

2 is mapped to 1 if the script is run on the PSX

+

centreViewPos(int x, int y)

+

center the view on the world coordinates x,y.

+

setGroupRetreatForce(GROUP group, int level)

+

Sets the percentage of the current force below which units for a side will retreat

+

setGroupRetreatLeadership(GROUP group, int level)

+

Sets the leadership level (chance to run away) for a player (1-100)

+

setGroupRetreatPoint(GROUP group, int x, int y)

+

Set the retreat position for a group

+

setDroidSecondary(DROID droid, int secondaryOrder, int secondaryState)

+

Set the state of a secondary order for a droid (values in Script function constants)

+

setGroupSecondary(GROUP group, int secondaryOrder, int secondaryState)

+

Set the state of a secondary order for a group (values in Script function constants)

+

setMissionTime(int time)

+

used to specify how long an OffWorld mission will last for - used in conjunction with the

+

callback CALL_MISSION_TIME so that end conditions can be displayed if the player has not

+

managed to finish the mission

+

If time < 0, there is no limit. time is in 10th of a second

+

int missionTimeRemaining()

+

Returns how long left for the current mission. If the mission time has not been set it will return 0.

+

The value returned is in 10ths of a second

+

setReinforcementTime(int time)

+

this defines how long it will take for reinforcements to arrive for an OffWorld mission

+

If time < 0, there can be no reinforcements. Time is in 10th of a second.

+

Set time to LZ_COMPROMISED_TIME to display '--:--' to indicate the Transporter is unable to land

+

int idleGroup(GROUP group)

+

returns number of units in group not doing anything.

+

bool groupMember(GROUP group, DROId droid)

+

return whether a unit is a member of a group.

+

initIterateGroup(GROUP group)

+

Prepare a group to iterate through the units in it.

+

DROID iterateGroup(GROUP group)

+

Get the next unit from the group. Must be called after an initial initGroupIterate.

+

To reset a group back to the start call initGroupIterate.

+

droidLeaveGroup(DROID droid)

+

Make a unit leave the group it is a member of (if any).

+

initGetFeature(STRUCTURESTAT, PLAYER,BUCKET)

+

getFeature(BUCKET)

+

enumerate features of a single feature type.

+

PLAYER is the player to use, Only features visible to that player are returned.

+

BUCKET is an int of range 0-MAX_PLAYERS(8), so up to 8 feature enumerations can be going on at any time! (wow)

+

getFeature returns NULLOBJECT when no more features are visible.

+

bool structButNoWallsInArea(PLAYER, X1,Y1, X2,Y2)

+

See if there are any player structures excluding walls in an area.

+

int numObjectsInArea(PLAYER, X1,Y1, X2,Y2)

+

Return the number of player objects in an area.

+

int numDroidsInArea(PLAYER, X1,Y1, X2,Y2)

+

Return the number of player units in an area.

+

int numStructsInArea(PLAYER, X1,Y1, X2,Y2)

+

Return the number of player structures in an area.

+

int numStructsButNotWallsInArea(PLAYER, X1,Y1, X2,Y2)

+

Return the number of player structures excluding walls in an area.

+

randomiseSeed()

+

Generate a new random seed for the random number generator.

+

int numStructsByTypeInArea(PLAYER, TYPE, X1,Y1, X2,Y2)

+

Return the number of structures of a certain type in an area.

+

flushConsoleMessages()

+

Clear all the console messages

+

bool pickStructLocation(STRUCTURESTAT,ref x, ref y, player);

+

returns true if structure of type strucutrestat can be built at x,y.

+

If a structure can be built nearby then returns true and modifies x and y

+

to the coords of acceptable location. Player trying to build - uses this for the visibility

+

int playerPower(int player)

+

returns aspower[player].currentPower (players current power)

+

bool seenStructInArea(int player,int enemy,bool walls,int x1,int y1,int x2,int y2)

+

returns true if player has seen a structure belonging to enemy in area specified. Call with

+

walls = true/false to include/exclude walls in the search.

+

(note similar to StructInArea)

+

int distBetweenTwoPoints(int x1, int y1, int x2, int y2)

+

Returns the distance between the two points given.

+

bool losTwoObjects(BASEOBJ source, BASEOBJ target, bool wallsMatter)

+

Decides whether object source can see object target and you can specify whether

+

walls matter or not. Note that whilst target can be anything, source needs to be

+

something that can actually see - ie - have a sensor like a unit or structure.

+

Returns TRUE or FALSE

+

void killStructsInArea(int player, int buildingRef (like REF_WALL etc),

+

int x1, int y1,int x2, int y2, bool bSeeEffect, bool bTakeFeatures)

+

Blows up all the buildings of the specified reference within the specified area.

+

If bSeeEffect is set, then you'll see it blow up (provided you can see the building

+

in question of course).

+

If bTakeFeatures is et, then it will also kill features of type BUILDING.

+

Returns 'nowt.

+

int getThreatInArea(int playerLooking, int playerTarget, int x1, int y1,

+

int x2, int y2, int ldThreat, int mdThreat, int hdThreat)

+

Returns the threat value of all units of a specified player within a certain area for a specified player.

+

The user can 'calibrate' this threat value by specifying the relative weights attached to the threats of

+

small,medium and heavy units respectively as the last three parameters to this function. The final boolean

+

parameter allows the user to say whether they care about whether or not the units in question are

+

presently visible.. TRUE means they only add to the threat if PlayerLooking can see this unit (owned by

+

playerTarget), FALSE means they add to the threat if even they can't see that unit.

+

bool getNearestGateway(int x, int y, ref rX, ref rY)

+

Puts the coordinates of the nearest gateway into reference variables rX and rY. It might not though

+

if there are no gateways on the present map. So make sure you look at the return value. If it's FALSE,

+

then the values in rX and rY will be meaningless - unchanged actually, assuming the scripting works

+

this way. Otherwise, they'll be the coordinates of the midpoint of the nearest gateway.

+

void setWaterTile(int tileNum)

+

Sets the tile to use for underwater. Count from the top of the tileset pcx - presently 17 for arizona.

+

initIterateCluster(int clusterID)

+

get ready to iterate a cluster

+

BASEOBJ iterateCluster()

+

return the next object in the cluster or NULLOBJ if none left

+

cmdDroidAddDroid(DROID commander, DROId droid)

+

adds the unit droid to the command group of the command unit commander

+

cmdDroidMaxGroup(DROId commander)

+

Returns max number of droids 'commander' can have in his group.

+

bool testStructureModule(int playeNumber, ST_STRUCTURE structureToTest, int ref)

+

Returns true if the structure in question has a module attached - presently the ref id is unused but

+

could be later on. At the moment it returns true if the structure has _any_ number of modules attached.

+

If the structure pointer that's sent in is NULL (ie - no structure is specified), then it'll return

+

TRUE is _any_ of the player's structures possess _any_ module. In all other cases, it'll return FALSE.

+

bool addTemplate(TEMPLATE, int player)

+

given a template, gives the player the template so that build droid can be used. At least one

+

player must have the template.

+

void vanishUnit(DROID droid)

+

Will remove 'droid' from the world without any graphical hoo ha.

+

void forceDamageObject(BASEOBJ obj, int damage)

+

Sets 'obj' to be 'damage' percent damaged. Obj must be a feature,droid or structure and damage

+

must be <= 100.

+

bool getGameStatus(int StatusRequired)

+

Gets the status of some of the game TRUE/FALSe variables. Can be used to find if the reticule is up or the

+

battle map is open, that sort of thing.

+

e.g. getGameStatus(STATUS_ReticuleIsOpen); will return TRUE if the reticule is open (on screen) or FALSE if the reticule is not (disabled)

+

or

+

getGameStatus(STATUS_BattleMapViewEnabled); will return TRUE if we are in the battle map mode

+

or

+

getGameStatus(STATUS_DeliveryResposInProgress); will return TRUE if we are repositioning the delivery point

+

these are currently the only two options implemented ... for other game modes (like design screen or intelligence map modes)

+

use the externed variable intMode

+

int getPlayerColour(int player)

+

returns the colour of the player

+

void setPlayerColour(int colour, int player)

+

sets the colour to use for the player specified - colour must be 0 to (MAX_PLAYERS-1)

+

DROID takeOverSingleDroid(DROId droidToTakeOver, int playerToGain)

+

this replaces the existing droid (droidToTakeOver) by a new one for the playerToGain.

+

The new droid is passed back to the script

+

****Test for NULLOBJECT BEFORE calling this function****

+

int takeOverDroidsInArea(int fromPlayer, int toPlayer, int x1, int y1, int x2, int y2)

+

x1,y1,x2,y2 are in world units

+

checks for units belonging to fromPlayer and if they are in the area they are 'given' to the toPlayer

+

int takeOverDroidsInAreaExp(int fromPlayer, int toPlayer, int x1, int y1,

+

int x2, int y2, int level, int max)

+

x1,y1,x2,y2 are in world units

+

checks for units belonging to fromPlayer and if they are in the area they are 'given' to the toPlayer

+

if their experience level is less than or equal to level

+

max specifies the maximum number of units to take over

+

STRUCTURe takeOverSingleStructure(STRUCTURE structToTakeOver, int playerToGain)

+

this replaces the existing structure (structToTakeOver) by a new one for the playerToGain.

+

The new structure is passed back to the script

+

****Test for NULLOBJECT BEFORE calling this function****

+

int takeOverStructsInArea(int fromPlayer, int toPlayer, int x1, int y1,

+

int x2, int y2)

+

x1,y1,x2,y2 are in world units

+

checks for structures belonging to fromPlayer and if they are in the area they are 'given' to the toPlayer

+

This will NOT WORK for the selectedPlayer on any Factory. The structure limits will be increased if necessary

+

void resetStructTargets()

+

reset the structure preferences

+

void resetDroidTargets()

+

reset the unit preferences

+

void setStructTarPref(int type)

+

set a prefered structure target type, repeated calls combine the effect

+

void setStructTarIgnore(int type)

+

set structure target ignore types

+

void setDroidTarPref(int type)

+

set prefered unit target types

+

void setDroidTarIgnore(int type)

+

set unit target ignore types

+

STRUCTURE structTargetInArea(int targetPlayer, int visibleToPlayer, int x1, int y1, int x2, int y2)

+

get a structure target in an area using the preferences

+

targetPlayer is the player to choose targets from, visibleToPlayer specifies the

+

player that has to be able to see the target or -1 for no visibility check

+

STRUCTURE structTargetOnMap(int targetPlayer, int visibleToPlayer)

+

get a structure target on the map using the preferences

+

DROID droidTargetInArea(int targetPlayer, int visibleToPlayer, int x1, int y1, int x2, int y2)

+

get a unit target in an area using the preferences

+

DROID droidTargetOnMap(int targetPlayer, int visibleToPlayer)

+

get a unit target on the map using the preferences

+

BASEOBJ targetInCluster(int clusterID, int visibleToPlayer)

+

get a target from a cluster using the preferences

+

void fireWeaponAtObj(WEAPON weap, BASEOBJ target)

+

fire a single shot of the weapon weap at the object target

+

void fireWeaponAtLoc(WEAPON weap, int x, int y)

+

fire a single shot of the weapon weap at the location x,y

+

bool isStructureAvailable(STRUCTURESTAt stat, int player)

+

PC ONLY FOR NOW. returns true if structure is available to player, false otherwise.

+

bool structureComplete(STRUCTURE struct)

+

PC ONLY FOR NOW. returns true if the structure is completely built.

+

int getDroidCount(int player)

+

returns the number of units on the current map for the specified player

+

setDroidKills(DROID droid, int kills)

+

sets the number of kills for a unit. currently the level boudaries are:

+

4, 8, 16, 32, 64, 128, 256, 128

+

resetPlayerVisibility(int player)

+

reset the visibility for a player

+

void resetLimboMission(void)

+

This can only be called mid Limbo Expand mission - the units that were stored in the

+

mission list at the start of the mission are added back into the map, and the mission

+

type is changed to an Expand Mission.

+

int killDroidsInArea(int x1, int y1, int x2, int y2, int player)

+

Kills all the player's units within the area defined. Returns how many it wiped out.

+

traceOn()-- view the script debug info to stdout.

+

traceOff()

+

bool applyLimitSet (void)

+

Apply the limits set in the structure limits screen.

+

bool isHumanPlayer (int pl)

+

Returns true is pl is human.

+

void offerAlliance (int p1, int p2)

+

Make p1 offer p2 an alliance

+

bool allianceExistsBetween (int p1 , int p2)

+

True if alliance exists between p1 and p2.

+

void skDoResearch ( STRUCTURE str , int pl , int bias)

+

Make player pl do some research with structure str.

+

BASEOBJECT skLocateEnemy( int pl)

+

Return a baseobject of interest belonging to player pl.

+

bool skCanBuildTemplate ( int pl, STRUCTURE str, TEMPLATE tem)

+

True when player pl can build design tem with structure str.

+

bool skVtolEnableCheck( int pl)

+

True when player pl is actively using vtols.

+

int skGetFactoryCapacity( STRUCTURE str)

+

Return the capacity of factory str.

+

void skDifficultyModifier( int pl)

+

Apply the frontend slider settings to player pl.

+

bool skDefenseLocation (ref int x , ref int y , STRUCTURESTAT defenceStat,

+

STRUCTURESTAT wallstat, DROID unit, int player)

+

Given a starting x and y, make unit 'unit' belonging to 'player' build either a 'defenceStat' or a row of 'wallStat's. returns

+

Modified x and y's.

+

void skFireLassat (int pl, BASEOBJECT obj)

+

Fire lassat of player pl's at object obj.

+

void setEventTrigger(EVENt event, TRIGGER newTrigger)

+

Assigns 'newTrigger' as new trigger for event 'event'.

+

void dropBeacon (string msg, int forPlayer, int, fromPlayer,

+

int x, int y, int z)

+

Put a flashing beacon on the map for player 'forPlayer' on position x/y. Unless removed manually the beacon is removed automatically from the map after a timeout.

+

void removeBeacon (int forPlayer, int fromPlayer)

+

Remove a previously placed beacon from the map.

+

int max(int value1, int value2)

+

int min(int value1, int value2)

+

Returns maximum/minimum of two integer values.

+

float fmax(float value1, float value2)

+

float fmin(float value1, float value2)

+

Returns maximum/minimum of two float values.

+

bool fogTileInRange(ref int tileX, ref int tileY, int x, int y,

+

int rangeX, int rangeY, int searchRange, int player, int threatRange)

+

Fills tileX/tileY with coordinates of the unrevealed location in range with starting location x/y, range 'searchRange' and closest to location x/y. If 'searchRange' is -1, then entire map is being searched. 'Player' is the player who is looking for an unrevealed map location. If 'threatRange' != -1 then also checks for enemy presence. Locations with enemy presence are ignored then.

+

Returns TRUE if any locations satisfying the search conditions were found, returns FALSE otherwise.

+

bool mapRevealedInRange(int x, int y, int range, int player)

+

Returns TRUE if there are no unrevealed tiles left in locations for player 'player' with center x/y and radius 'range'. All coordinates are in world units.

+

bool pursueResearch(STRUCTURE resFac, int player, RESEARCH targetResearch)

+

Makes 'resFac' start researching the first prerequisite necessary for 'targetResearch'. If no prerequisites are left, then 'targetResearch' will be researched. Must be called again for the next prerequisite. 'resFac' must be a valid research facility.

+

Returns TRUE if started researching, FALSe otherwise.

+

int numResearchLeft(int player, RESEARCH research)

+

Returns number of reserach topics that are left for player 'player' to research in order for a certain research 'research' to become available.

+

bool researchFinished(RESEARCh research, int player)

+

Returns TRUE if 'player' has researched 'research'.

+

bool researchStarted(RESEARCH research, int player)

+

Returns TRUE if 'research' is currently being researched by 'player'.

+

bool threatInRange(int player, int rangeX, int rangeY, int range, bool includeVTOLs)

+

Returns TRUE if there's a danger for 'player' at location x/y within radius 'range'. If includeVTOLs is set to FALSE then VTOLs are ignored. All coordinates are in worls units. If 'range' == -1 then entire map will be searched.

+

int numEnemyWeapDroidsInRange(int lookingPlayer, int x, int y,

+

int range, bool includeVTOLs)

+

int numEnemyWeapStructsInRange(int lookingPlayer, int x, int y, int range, bool onlyFinishedStructs)

+

int numEnemyWeapObjInRange(int lookingPlayer, int x, int y,

+

int range, bool includeVTOLs, bool onlyFinishedStructs)

+

Return total number of enemy military objects (either structures, droids or both) at location x/y and within 'range'. Units belonging to 'lookingPlayer' and his allies are ignored.

+

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

+

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

+

int numFriendlyWeapDroidsInRange(int lookingPlayer, int x, int y,

+

int range, bool includeVTOLs)

+

int numFriendlyWeapStructsInRange(int lookingPlayer, int x, int y, int range, bool onlyFinishedStructs)

+

int numFriendlyWeapObjInRange(int lookingPlayer, int x, int y,

+

int range, bool includeVTOLs, bool onlyFinishedStructs)

+

Return total number of friendly military objects (either structures, droids or both) at location x/y and within 'range'. Units belonging to enemies of 'lookingPlayer' are ignored.

+

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

+

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

+

int numPlayerWeapDroidsInRange(int targetPlayer, int lookingPlayer,

+

int x, int y, int range, bool includeVTOLs)

+

int numPlayerWeapStructsInRange(int targetPlayer, int lookingPlayer,

+

int x, int y, int range, bool onlyFinishedStructs)

+

int numPlayerWeapObjInRange(int targetPlayer, int lookingPlayer,

+

int x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

+

Returns total number of targetPlayer's military objects (either structures, droids or both) at location x/y and within 'range' that are visible visible by 'lookingPlayer'.

+

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

+

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

+

int numEnemyObjInRange(int lookingPlayer, int, x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

+

Returns total number of enemy objects (structures and units) at location x/y within range 'range' that are visible to 'lookingPlayer'.

+

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

+

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

+

int numAAinRange(int targetPlayer, int lookingPlayer,

+

int x, int y, int range)

+

Returns number of targetPlayer's AA defences at location x/y within range 'range' that are visible to 'lookingPlayer'.

+

bool objHasWeapon(BASEOBJ object)

+

Returns TRUE if 'object' has a weapon.

+

bool objectHasIndirectWeapon(BASEOBj object)

+

Returns TRUE if 'object' has an indirect weapon.

+

bool alliancesLocked()

+

Returns TRUE if the game doesn't allow to break alliances (ie when team mode is on).

+

void selectDroid(DROID droid, bool select)

+

Depending on value of 'select' selects or deselects droid 'droid'.

+

void selectGroup(GROUP group, bool select)

+

Depending on value of 'select' selects or deselects all droids belonging to group 'group'.

+

int modulo(int divident, int divisor)

+

Returns result of calculation (divident modulo divisor).

+

float toPow(float base, float exponent)

+

Returns floating point result of calculation base^exponent.

+

float exp(float exponent)

+

Exponential function. Returns the result of e^exponent.

+

float sqrt(float argument)

+

Square root function. Returns square root of the argument: √argument.

+

string getPlayerName(int player)

+

Returns in-game name of 'player'.

+

bool setPlayerName(int player, string newName)

+

Set player's name to 'newName'. Returns TRUe on success.

+

void console(string message)

+

Outputs 'message' to game console.

+

void msg(string message, int playerFrom, int playerTo)

+

Sends a chat message from 'playerFrom' to 'playerTo'.

+

bool strcmp(string string1, string string2)

+

Returns TRUE if string1 and string2 are identical. Comparison is case-sensitive.

+

int calcDroidPower(DROID droid)

+

Returns cost of the 'droid'.

+

boolisVtol(DROID droid)

+

Returns TRUE if 'droid' is a vtol.

+

int enemyWeapObjCostInRange(int lookingPlayer, int rangeX, int rangeY, int range, bool includeVtols, bool onlyFinishedStructs)

+

Returns total cost (in power) of enemy objects with a weapon in a certain area.

+

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

+

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

+

int friendlyWeapObjCostInRange(int lookingPlayer, int rangeX, int rangeY, int range, bool includeVtols, bool onlyFinishedStructs)

+

Returns total cost (in power) of friendly objects with a weapon in a certain area.

+

If 'includeVTOLs' is set to FALSE, then VTOLs are ignored.

+

If 'onlyFinishedStructs' is set to TRUE, then unfinished structures will be ignored.

+
+

back to top

+
+
+ +

Debugging script functions

+

The following functions can be used to debug Warzone 2100 AI scripts.

+
+
void dbgMsgOn(int player, bool on)
+
Depending on the value of on turns on/off debug output of dbg() and ASSERT() function which are listed below.
+
void dbg(string debugMessage, int player)
+
Outputs debugMessage to the game console if debug output for player player was previously turned on with dbgMsgOn().
+
void ASSERT(bool assertExpression, string assertMessage, int player)
+
If 'assertExpression' evaluates to FALSE, then 'assertMessage' is output to the game console. Must turn on debug output for 'player' with dbgMsgOn() first. NOTE: In debug game builds failed assertion will cause game assertion.
+
void debug(string debugText)
+
Writes 'debugText' to the standart output (usually a log file).
+
void printCallStack()
+
Outputs script call stack to the standard log file.
+
+
+

back to top

+
+
+ +

Script function constants

+

These values are used to represent numbers that are constant throughout the game.

+

NULLOBJECT- used to check that a BASEOBJECT/FEATURE/STRUCTURE has been assigned by a function

+

NULLTEMPLATE- used to check that a TEMPLATE has been assigned by a function

+

NULLSTAT- used to check that a BASESTAT has been assigned by a function

+

BARBARIAN1- this can used to represent enemy1 (PC:player 6, PSX:player2)

+

BARBARIAN2- this can used to represent enemy2 (PC:player 7, PSX:player3)

+

BUTTONID - these values are used when a particular reticule button needs to be identified

+

OPTIONs - NOTE - this currently references the command button

+

CANCEL

+

BUILD

+

MANUFACTURE

+

RESEARCH

+

INTELMAP

+

DESIGN

+

COMMAND

+

- When flashing an icon - with scrFlashOn() scrFlashOff()

+

you can additional use

+

IDRET_OPTIONS

+

IDRET_CANCEl

+

IDRET_BUILD

+

IDRET_MANUFACTURE

+

IDRET_RESEARCH

+

IDRET_INTEL_MAP

+

IDRET_DESIGN

+

IDRET_COMMAND

+

IDDES_TEMPLSTART

+

IDDES_SYSTEMBUTTON

+

IDDES_BODYBUTTON

+

IDDES_PROPBUTTON

+

MESSAGETYPE - these values are used when a type of message needs to be identified

+

RES_MSG

+

CAMP_MSG

+

MISS_MSG

+

PROX_MSG

+

Multiplayer alliance types:

+

NO_ALLIANCES- alliances are disallowed

+

ALLIANCES- alliances are allowed

+

ALLIANCES_TEAMS- team mode, locked alliances

+

MISSIONTYPE - these values are used when a type of mission needs to be identified

+

CAMP_START - used for the starting point of a campaign

+

CAMP_EXPAND - used to expand a current campaign map

+

OFF_KEEP - used to load up an off world map, but keeping access

+

to factories and research facilities back at home base

+

OFF_CLEAR - used to load up an off world map, but having no access to home base

+

LZ_COMPROMISED_TIME- value to set the reinforcement time with to display '--:--'

+

when the Transporter is unable to land

+

Droid Orders:

+

DORDER_NONE- no order assigned

+

DORDER_STOP- stop current order

+

DORDER_RETREAT- retreat

+

DORDER_DESTRUCT- self destruct

+

DORDER_RTR- return to repair

+

DORDER_RTB- return to base

+

DORDER_RUN- run away for a bit (moral failure)

+

DORDER_MOVE- move to location

+

DORDER_ATTACK- attack the object

+

DORDER_HELPBUILD- help construct the object

+

DORDER_DEMOLISH- demolish structure

+

DORDER_REPAIR- repair structure

+

DORDER_OBSERVE- (sensor units) keep a target in sensor range

+

DORDER_EMBARK- get onto a transporter

+

DORDER_FIRESUPPORT- follow this sensor unit and attack anything it DORDER_OBSERVE's

+

DORDER_SCOUT- same as move, but stop if enemy units are encountered.

+

Unit secondary orders:

+

DSO_ATTACK_RANGE

+

DSO_REPAIR_LEVEL

+

DSO_ATTACK_LEVEL

+

DSO_RECYCLE

+

DSO_PATROL- patrol between current pos and next move target

+

DSO_HALTTYPE- what to do when stopped

+

DSO_RETURN_TO_LOC- return to various locations

+

Unit secondary states:

+

DSS_ARANGE_SHORT

+

DSS_ARANGE_LONG

+

DSS_ARANGE_DEFAULT

+

DSS_REPLEV_LOW- Medium Damage Taken

+

DSS_REPLEV_HIGH- Heavy Damage Taken

+

DSS_REPLEV_NEVER- Never Repair

+

DSS_ALEV_ALWAYS

+

DSS_ALEV_ATTACKED

+

DSS_ALEV_NEVER

+

DSS_PATROL_SET(0 to clear)

+

DSS_HALT_HOLD

+

DSS_HALT_GUARD

+

DSS_HALT_PERSUE

+

DSS_RECYCLE_SET(0 to clear)

+

DSS_RTL_REPAIR(0 to clear)

+

DSS_RTL_BASE(0 to clear)

+

DSS_RTL_TRANSPORT(0 to clear)

+

Button ID's:

+

IDRET_OPTIONS- option button

+

IDRET_BUILD- build button

+

IDRET_MANUFACTURE- manufacture button

+

IDRET_RESEARCH- research button

+

IDRET_INTEL_MAP- intelligence map button

+

IDRET_DESIGN- design units button

+

IDRET_CANCEL- central cancel button

+

Unit types:

+

DROID_WEAPON- Weapon unit

+

DROID_SENSOR- Sensor unit

+

DROID_ECM- ECM unit

+

DROID_CONSTRUCt - Constructor unit

+

DROID_PERSON- person

+

DROID_CYBORG- cyborg/super cyborg

+

DROID_TRANSPORTER- guess what this is!

+

DROID_COMMAND- Command unit

+

DROID_REPAIR- Repair Unit

+

DROID_CYBORG_CONSTRUCT- Cyborg engineer

+

DROID_CYBORG_REPAIR- Cyborg mechanic

+

Structure types:

+

REF_HQ

+

REF_FACTORY

+

REF_FACTORY_MODULe

+

REF_POWER_GEN

+

REF_POWER_MODULE

+

REF_RESOURCE_EXTRACTOR

+

REF_DEFENSE

+

REF_WALL

+

REF_WALLCORNER- corner wall - no gun

+

REF_RESEARCh

+

REF_RESEARCH_MODULe

+

REF_REPAIR_FACILITY

+

REF_COMMAND_CONTROL- control centre for command units

+

REF_CYBORG_FACTORY

+

REF_VTOL_FACTORY

+

REF_REARM_PAD

+

REF_MISSILE_SILO

+

Multiplayer Game Types:

+

SKIRMISH

+

DMATCH

+

CAMPAIGN

+

TEAMPLAY

+

MultiPlayer Base Configurtations:

+

CAMP_CLEAN- build units only

+

CAMP_BASE- small base

+

CAMP_WALLS- defensive base

+

Cursor Mode (possible values of cursorType):

+

IMAGE_CURSOR_SELECT

+

IMAGE_CURSOR_ATTACK

+

IMAGE_CURSOR_MOVE

+

IMAGE_CURSOR_JAM

+

IMAGE_CURSOR_PICKUP

+

IMAGE_CURSOR_DEFAULT

+

IMAGE_CURSOR_SEEKREPAIR

+

IMAGE_CURSOR_BUILD

+

IMAGE_CURSOR_GUARD

+

IMAGE_CURSOR_BRIDGE

+

IMAGE_CURSOR_ATTACH

+

IMAGE_CURSOR_LOCKON

+

IMAGE_CURSOR_FIX

+

IMAGE_CURSOR_EMBARK

+

Game mode - possible values for intMode external variable

+

int_NORMAL- Standard mode (just the reticule)

+

int_OPTION- Option screen

+

int_EDITSTAT- Stat screen up for placing objects

+

int_EDIT- Edit mode

+

int_OBJECT- Object screen

+

int_STAT- Object screen with stat screen

+

int_CMDORDER- Object screen with command units and orders screen

+

int_DESIGN- Design screen

+

int_INTELMAP- Intelligence Map

+

int_ORDER

+

int_INGAMEOP- in game options.

+

int_TRANSPORTER- Loading/unloading a Transporter

+

int_MISSIONRES- Results of a mission display.

+

int_MULTIMENU- multiplayer only, player stats etc...

+

Possible options for getGameStatus():

+

STATUS_ReticuleIsOpen- returns true is the reticule is open

+

STATUS_BattleMapViewEnabled- returns true if we are in battlemap mode

+

Possible values for targetedObjectType:

+

MT_TERRAIN

+

MT_RESOURCE

+

MT_BLOCKING

+

MT_RIVER

+

MT_TRENCH

+

MT_OWNSTRDAM

+

MT_OWNSTROK

+

MT_OWNSTRINCOMP

+

MT_REPAIR

+

MT_REPAIRDAM

+

MT_ENEMYSTR

+

MT_TRANDROID

+

MT_OWNDROID

+

MT_OWNDROIDDAM

+

MT_ENEMYDROID

+

MT_COMMAND

+

MT_ARTIFACT

+

MT_DAMFEATURE

+

MT_SENSOR

+

MT_WRECKFEATURE

+

Structure Target preference types:

+

ST_HQ

+

ST_FACTORY

+

ST_POWER_GEN

+

ST_RESOURCE_EXTRACTOR

+

ST_WALL

+

ST_RESEARCH

+

ST_REPAIR_FACILITY

+

ST_COMMAND_CONTROL

+

ST_CYBORG_FACTORY

+

ST_VTOL_FACTORY

+

ST_REARM_PAD

+

ST_SENSOR

+

ST_DEF_GROUND

+

ST_DEF_AIR

+

ST_DEF_IDF

+

ST_DEF_ALL- ground/air/idf structures

+

Unit target preference types:

+

turret types:

+

DT_COMMAND

+

DT_SENSOR

+

DT_CONSTRUCT

+

DT_REPAIR

+

DT_WEAP_GROUND

+

DT_WEAP_AIR

+

DT_WEAP_IDF

+

DT_WEAP_ALL- ground/air/idf units

+

Body types:

+

DT_LIGHT

+

DT_MEDIUM

+

DT_HEAVY

+

DT_SUPER_HEAVy - transporter only

+

Propulsion:

+

DT_TRACK

+

DT_HTRACK

+

DT_WHEEL

+

DT_LEGS

+

DT_GROUND

+

DT_VTOL

+

DT_HOVER

+

Group types:

+

GT_NORMAL

+

GT_COMMAND

+

GT_TRANSPORTER

+
+

back to top

+
+
+ +

Script function externals

+

These represent variables that are defined in the game which can be accessed in the scripts. It will only be possible to set the value that is held for some of the variables.

+

mapWidth- (get) - field to hold the width of the map

+

mapHeight- (get) - field to hold the height of the map

+

gameInitialised- (get) flag to specify when all initialisation has been performed for the game - use it in place of a bool ie can be considered to equal true or false

+

selectedPlayer- (get) field to hold the currently selected player

+

gameTime- (get) the current time in the game (in 1/10 sec)

+

multiPlayerGameType - (get) the type of multiplayer game underway.

+

multiPlayerMaxPlayers - max number of human players in this game.(see constants for return values)

+

multiPlayerBaseType - campaign game base type. (see constants for return values)

+

multiPlayerAlliancesType- (get) alliance type (eg NO_ALLIANCES etc, see Script function constants)

+

scrollX- (get/set) field to hold the starting x coordinate where the player can scroll

+

scrollY- (get/set) field to hold the starting y coordinate where the player can scroll

+

scrollWidth- (get/set) field to hold the width the player can scroll

+

scrollHeight- (get/set) field to hold the height the player can scroll

+

cursorType- (get) - Gets the current mode that the cursor is in (e.g. IMAGE_CURSOR_BUILD ... see Script function constants)

+

intMode- (get) - Get the current game mode (e.g. int_DESIGN when the design screen is active) ... see Script function constants)

+

targetedObjectType- (get) - The type of the object currently under the cursor (one of MT_... see Script function constants)

+

boolextraVictoryFlag- use to mark additional victory conditions have been met - reset to FALSE at start of each level

+

boolextraFailFlag- use to mark additional failure conditions have been met - reset to FALSE at start of each level

+

GameLevel(get/set) - set single player difficulty.

+
+

back to top

+
+
+ +

Script function callbacks

+

These are used in the place of a trigger and are for events that are to be called at specific times in the game. They will cause the event they are associated with to be called every time unless the trigger for the event is set to inactive.

+
+
CALL_GAMEINIT
+
this is triggered when the game has initialised
+
CALL_DROIDDESIGNED
+
this is triggered when the player saves a template design
+
CALL_DROIDBUILT
+
this is triggered when a unit has been built via a factory
+
CALL_POWERGEN_BUILT
+
this is triggered when a Power generatot has been built
+
CALL_RESEX_BUILT
+
this is triggered when a Resource Extractor has been built
+
CALL_RESEARCH_BUILT
+
this is triggered when a Research Facility has been built
+
CALL_FACTORY_BUILT
+
this is triggered when a Factory has been built
+
CALL_MISSION_START
+
this is triggered when CTRL + 'M' is pressed so that the script can start a mission
+
CALL_MISSION_END
+
this is triggered when CTRL + 'B' is pressed so that the script can end a mission
+
CALL_VIDEO_QUIT
+
this is triggered when the CURRENT video sequence is over, either end of anim or when 'ESC' has been pressed
+
CALL_LAUNCH_TRANSPORTER
+
this is triggered when the 'Launch' button is pressed on the Transporter interface
+
CALL_START_NEXT_LEVEL
+
this is triggered when a new level is desired
+
CALL_TRANSPORTER_REINFORCE
+
this is triggered when a transporter carrying reinforcements for player 0 enters the map
+
CALL_MISSION_TIME
+
this is triggered when the time specified by setMissionTime() has elapsed
+
CALL_ELECTRONIC_TAKEOVER
+
triggered when a unit or a structure for the selectedPlayer are taken over using Electronic weapons
+
+

Callbacks with parameters

+
+
CALL_RESEARCHCOMPLETED, ref RESEARCHSTAT, ref STRUCTURE
+
This is triggered when a research topic is complete - major or minor.. RESEARCHSTAt is the research topic that was complete, STRUCTURE is research facility that has completed research.
+
CALL_NEWDROID, player, ref DROID,ref STRUCTURE
+
triggered when a unit for player is built by a factory. DROID is the unit that was built. structure is the factory that built it, dont assume that the factory is still there!!
+
CALL_STRUCT_ATTACKED, player, ref STRUCTURE, ref BASEOBJ
+
triggered when a structure for player is attacked. STRUCTURE is the attacked structure,. BASEOBJ is the unit that attacked the structure (could be NULLOBJECT)
+
CALL_DROID_ATTACKED, player, ref DROID, ref BASEOBJ
+
triggered when a unit for player is attacked. DROID is the attacked unit,. BASEOBJ is the unit that attacked (could be NULLOBJECT)
+
CALL_ATTACKED, player, ref BASEOBJ, ref BASEOBJ
+
triggered when a structure or unit for player is attacked. BASEOBJ is the attacked unit,. BASEOBJ is the unit that attacked (could be NULLOBJECT)
+
CALL_TRANSPORTER_OFFMAP, player
+
triggered when a transporter for player exits the map.
+
CALL_TRANSPORTER_LANDED, GROUP, player
+
triggered when transporter for player lands; units on transporter are unloaded. into the given GROUP.
+
+

Tutorial Callbacks

+
+
CALL_BUILDLIST
+
Build structures interface up
+
CALL_BUILDGRID
+
Place structure cursor up
+
CALL_RESEARCHLIST
+
Choose research interface up
+
CALL_MANURUN
+
Number of units to manufacture has changed
+
CALL_MANULIST
+
Choose manufacturing interface up
+
CALL_BUTTON_PRESSED, buttonID
+
triggered when an interface button with id buttonID is pressed
+
CALL_DESIGN_QUIT
+
triggered when the design screen is closed
+
CALL_OBJ_DESTROYED, int player, ref BASEOBJ object
+
triggered when either a unit or a structure for player is destroyed
+
CALL_DROID_DESTROYED, int player, ref DROID droid
+
triggered when a unit for player is destroyed
+
CALL_STRUCT_DESTROYED, int player, ref STRUCTURE structure
+
triggered when a structure for player is destroyed
+
CALL_FEATURE_DESTROYED, ref FEATURe feature
+
triggered when either a unit or a structure for player is destroyed
+
CALL_OBJ_SEEN, int player, ref BASEOBj object, ref BASEOBJ viewer
+
triggered when either a unit or a structure is seen by a unit belonging to player.. object is the thing that was seen, viewer is the thing that saw it (may be NULLOBJECT).
+
CALL_DROID_SEEN, int player, ref BASEOBJ object, ref BASEOBJ viewer
+
triggered when a unit is seen by a unit belonging to player.. object is the thing that was seen, viewer is the thing that saw it (may be NULLOBJECT).
+
CALL_STRUCT_SEEN, int player, ref BASEOBJ object, ref BASEOBJ viewer
+
triggered when a structure is seen by a unit belonging to player.. object is the thing that was seen, viewer is the thing that saw it (may be NULLOBJECT).
+
CALL_NO_REINFORCEMENTS_LEFT
+
called when the player has transferred all reinforcements from one level to the next
+
+

Tutorial callbacks (tutorial only)

+
+
CALL_DESIGN_WEAPON
+
a weapon button pressed
+
CALL_DESIGN_SYSTEM
+
a system (constructor/ecm/sensor/etc) button pressed
+
CALL_DESIGN_COMMAND
+
a command droid turret pressed
+
CALL_DESIGN_BODY
+
a body selected
+
CALL_DESIGN_PROPULSION
+
a propulsion selected
+
CALL_ALL_ONSCREEN_DROIDS_SELECTED
+
does exactly when it says on the box
+
CALL_UNITTAKEOVER, ref unit
+
Unit has been taken over by nexus link
+
CALL_PLAYERLEFT, ref int player
+
Player has left the multiplayer game.
+
CALL_ALLIANCEOFFER, ref int one, ref int two
+
One offers two an alliance.
+
+
+

back to top

+
+
+ +

Warzone2100. Script language notes.

+

Original Author: Pumpkin Studios. 1999

+

Last Author: $Author$

+

Last update: $Date$, $Revision$, WRP

+

Note from Pumpkin Studios: making any modifications to Warzone 2100 will void any technical support open to you. We will not answer questions or help you in any way if you have modified Warzone 2100. Pumpkin Studios and Eidos will not take responsibility for any damage resulting from modifcation of Warzone 2100.

+