Return

Programmed by Strata Drake

- A little help file from Strata Drake -
And as an added feature

Warzone Construction kit 2.0 ORE

- the A.I Script Language Notes from Pumpkin 1999 follows -

Return to Beginners Guide To the A.I.Editor

**Please note that this is an extremely long document!

First thing you may want to do on WZCK is get a look at the editors. WZCK's editors come in two varieties:

- The "Warheads" and "Terrain Tables" editors are the simplest editors in WZCK. They are arranged as simple charts that you may double-click any square in to edit the values. The Warheads editor is an attack modifier chart showing how effective each kind of warhead is against each kind of target, whereas the Terrain Tables editor is a speed modifier chart plotting each kind of propulsion against each kind of terrain (the terrains are identified by their Edit World colors).

Use care when editing the Warheads / Terrain Tables editors, because any changes made to the values will affect all weapons/propulsions in Warzone regardless of whether they're part of your mod or not.

- The other editors, which you may call the "component editors", are for Weapons, Chassis, Propulsions, Unit Templates, Structures, Sensors, ECM's, Repair turrets, Construction turrets, and Commanders. They all have similar layouts. Each editor is sorted into various tabs containing related sets of options.

The first tab in each component editor contains two lists: The list on the right shows all available components in the current dataset, and the list on the left shows all components currently contained in your mod.

You may also sort the lists according to their internal order (the default), alphabetically, or by their type, to make things easier to find.

When you have decided what you want to modify, select it from the list of default components and press the "Add" button.

Then, select it from the list of components and flip through the various pages of options to find what you want to change.

Now, onto a specific example. First tutorial: Modify the Bunker Buster.

There are two complaints about the Bunker Buster in Warzone: (1) the tank version has insufficient firepower, and (2) the VTOL version has insufficient range.

For this experiment, let's up the range and power of the tank Bunker Buster.

First, go to the "File" menu of the Weapons Editor and select "Begin New Project". WZCK will ask you whether you want to create a v1.10 or v1.11 compatible mod. Choose which kind of mod you want to make and hit OK. (You can change this later if you want to)

Next, find "Bunker Buster" in the list of default weapons (it is close to the top using the default sort option) and press "Add".

To edit the range of the weapon, go to the "Targetting" tab. Near the center of this tab are three range values -- minimum range, "short" range, and maximum range. The minimum and maximum ranges determine the distances required to fire the weapon at a target. "Short Range" is just the "preferred" distance-to-target when a unit is ordered for Short Range attacks.

To make things interesting, try giving the Bunker Buster a minimum range of 4 squares, maximum range of 16 squares, and short range of 8.

Also, since the Bunker Buster is intended for use against stationary targets also try flicking off the "Fire while Moving" switch. This will require a BB tank to stop before firing at a bunker or hardpoint.

Now, to fix that insufficient firepower: Go to the "Damage" tab. The first option on it is the brute-force firepower of the weapon, which is about 125 by default. Let's try changing that to 200 (keep in mind that these values are unupgraded).

Also try assigning a blast radius of 3 squares, 100% accuracy, and 100 firepower.

All of the changes so far have turned the measly tank-variety Bunker Buster into a super strength bunkerdestroyer. Feel like changing the name of the Bunker Buster to match? How about "BunkerBlaster"? To change the screen name, go back to the "Edit" tab and change its name.

Lastly, it wouldn't be quite fair (for gameplay reasons) to increase firepower without some sort of balancer -- say, a slightly higher cost and build time? Go to the "Production / Design" tab. The first two options listed here are "Cost" and "Build Time". Up the cost to something slightly higher (you decide), leave the build times unchanged.

Here is another interesting idea to try: Switch the modified Bunker Buster tosalvo fire with 3 shots per salvo, 1.0 second shot-reload time, and 30 second salvo-reload time. Of course, firing 3 shots per salvo effectively triples the firepower of our modified BB, so how would we balance that? The obvious way is to up the cost -- but here's a sneakier method. Increase the weight to about 5,000, then go to the "Reload" tab and set the turret rotation tozero. This will slow down a unit using the bunker buster, giving the enemy a little more slack.

Now, using the "File" menu on the editor, save this file to disk. Give it any name you like, and it will be saved to disk so you can retrieve it later.

Finally, to compile and test this weapon in Warzone, hit the "Compile WDG..." button that appears. On the dialog box that appears, hit the "Next ->" button at the bottom to check the mod for errors. (There should be no errors in it). Then hit the same button again to create the WDG. The WDG will be created in WZCK's directory.

Then, using the Windows Explorer, copy the WDG (named "WeaponMod.wdg" by default) into Warzone's directory and give it a play-test.

In Warzone, try the following:
- Shoot the modified Bunker Buster at short ranges and long ranges alike
- Fire the Bunker Buster at both stationary and moving enemy targets

Make sure no other mods (except v1.11 if you created a v1.11 compatible mod) are active except for the one you are going to test, otherwise you could get those annoying mod conflict errors (like "Can't find StatsWeapons.Txt")

Up

Warzone2100.A.I Script language notes.

Pumpkin Studios. 1999

- above are some of the structures found in wz2100

Up

Below is the original Script language Pumpkin shipped with wz2100

- using the A.I. editor you are able to change some of the behaviors.

Specific skirmish notes:

Much of the file below doesn't apply to skirmish scripts!

Make your changes to player0.slo and vlo -> player7.slo and vlo.

This file may not be complete or contain out of date information.

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 //.

Declaring Variables

A variable declaration is structured :

                <storage> <type> <name> [ , <name> , & ] ;

<storage> is one of public or private.  public means that the variable can have a

value assigned in the world editor.  private means the value is only used within the script

and cannot be set in the editor.

<type> is the data type of the variable.  There are four default types of variable: int bool

trigger event.  int is a numeric value.  bool stores only a true or false value. 

trigger stores a reference to a script trigger.  event stores a reference to a script event. 

There are also a number of extra user defined types specific to the game.

<name> is the identifier by which the variable is referred to.  If more than one variable of a

type is required, additional names separated by commas can be added.

Declaring Triggers

Triggers are used to schedule when an event should occur.  The format of a declaration is:

                trigger <name> ( <trigger type> );

<trigger type> can be any of:

                init          Run the event when the script starts.

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

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

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

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

                                <time> interval.

<bool exp> is a Boolean expression (described below) which may include game function

calls and script variables.

Declaring Events

Events contain the actual code to execute when a trigger is activated.  They are declared :

                event <name> ( <trigger> ) { <code> }

<name> is the identifier for the event.

<trigger> is either the identifier of a previously declared trigger, or a new <trigger type>

declaration.

<code> is the actual script code to execute when the event is activated.

Number 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 :

                +  -  *  /

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 true and

false and 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.

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;

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.

                if ( <bool exp> )

                {

                                <code>

                }

                else

                {

                                <code>

}

                if ( <bool exp> )

                {

                                <code>

                }

                else if ( <bool exp> )

                {

                                <code>

}

                else

                {

                                <code>

}

while statements

                while ( <bool exp> )

                {

                                <code>

                }

SCRIPT FUNCTION TYPES

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

INTMESSAGE - (simple) Name of a message as defined in Messages.txt

BASEOBJ              - (complex) any of a DROID,FEATURE or 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

                baseobj.clusterID - the cluster the object is a member of

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

                You have access to :

                                all BASEOBJ variables

                                droid.order    -  current order 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

FEATURE - (complex) defined by the ID got from the world editor

                You have access to :

                                all BASEOBJ variables

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

TEMPLATE - (simple) name of a template as defined in templ.bjo - loaded in as part of the save game

STRUCTURE - (complex) defined by the ID got from the world editor

                You have access to :

                                all BASEOBJ variables

                                structure.stat        - the STRUCTURESTAT of the structure

STRUCTUREID - (simple) literally just an ID of a struct

STRUCTURESTAT - (simple) name 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

GROUP - (complex) a group of droids

                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

NOTE: these are calculated the first time you access them for a group

and then cached for repeated access for this group.  It is therefore

much quicker if you do all actions on one group before accessing another

RESEARCHSTAT - (simple) name of a research topic as defined in research.txt (and the database)

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 color, to be used when fog is enabled. This color is also used in the background clear when fog is enabled.

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

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

WARNING setting the fog color 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 ScriptConstants.txt

removeReticuleButton(BUTTONID)

This function removes a reticule button from the interface

BUTTONID is the id of a button - see ScriptConstants.txt

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 ScriptConstants.txt

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 ScriptConstants.txt

PLAYER is the player who loses the message

!!!!!!!!!!!NO LONGER AVAILABLE!!!!!!!!!!

//addTutorialMessage(INTMESSAGE, PLAYER)

//This adds a tutorial message to the display for the PLAYER - its is played immediately //without the intelligence screen coming up. The message is not stored and therefore cannot //be re-displayed. It can be added over and over again though!

//INTMESSAGE is a variable defined in the values file

//PLAYER is the player who gets 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 centers 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 centered 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

}

initEnumStruct(STRUCTURESTAT,player,player2)

STRUCTURE enumStruct()

Enumerate through visible structures of given type, enum struct returns NULLOBJECT when no more exist.

player  = player who is looking (eg selectedPlayer)

player2 = player whose structures are to be enumerated.

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 (center 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()

initializes 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 ScriptConstants.txt

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????

!!!! DISABLED, no group wins at this time !!!!!!

!!BOOL allianceState()

!!returns true if group wins are allowed in the particular multiplayer game.

!!returns false otherwise.

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 doesn't add units that are already grouped.

groupAddGroup(group1, group2)

Add all the units in group2 to group1.

All the units are removed from group2.

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 scriptConstants.txt)

  ... 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 scriptConstants.txt)

setGroupSecondary(GROUP group, INT secondaryOrder, INT secondaryState)

Set the state of a secondary order for a group (values in scriptConstants.txt)

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 the