Script_functions – Warzone 2100 Trac

Context Navigation

Standard functions

; int random(range)

Return a random number between 0 and range - 1.

; randomiseSeed()

Generate a new random seed for the random number generator.

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

Returns the distance between the two points given.

; int max(int value1, int value2)

Returns maximum of two integer values.

; int min(int value1, int value2)

Returns minimum of two integer values.

; float fmax(float value1, float value2)

Returns maximum of two float values.

; float fmin(float value1, float value2)

Returns minimum of two float values.

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

; bool strcmp(string string1, string string2)

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

Type conversion

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

Objects

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

; centreView(OBJECT)

This function centres the view on the object supplied. OBJECT is any type of DROID, FEATURE, STRUCTURE.

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

Return the number of player objects in an area.

; 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 - i. e. - have a sensor like a unit or structure. Returns TRUE or FALSE.

; void forceDamageObject(BASEOBJ obj, int damage)

Sets obj to be damage percent damaged. obj must be a feature, droid or structure. damage ≥ 0 &and; damage ≤ 100.

; void fireWeaponAtObj(WEAPON weap, BASEOBJ target)

Fire a single shot of the weapon weap at the object target.

; BASEOBJECT skLocateEnemy(int pl)

Return a baseobject of interest belonging to player pl.

; void skFireLassat (int pl, BASEOBJECT obj)

Fire lassat of player pl's at object obj.

; int numEnemyWeapObjInRange(int lookingPlayer, int x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

Return total number of enemy military structures and droids 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 numFriendlyWeapObjInRange(int lookingPlayer, int x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

Return total number of friendly military objects structures and droids 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 numPlayerWeapObjInRange(int targetPlayer, int lookingPlayer, int x, int y, int range, bool includeVTOLs, bool onlyFinishedStructs)

Returns total number of targetPlayer's military structures and droids 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.

; bool objHasWeapon(BASEOBJ object)

Returns TRUE if object has a weapon.

; bool objectHasIndirectWeapon(BASEOBj object)

Returns TRUE if object has an indirect weapon.

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

Structures

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

; 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. Note that 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.

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

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

; 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)[[BR]]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.

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

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

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

See if there are any player structures excluding walls 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.

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

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

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

Returns true if structure of type structurestat 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.

; 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. Similar to StructInArea.

; 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 will see it blow up (provided you can see the building in question of course). If bTakeFeatures is set, then it will also kill features of type BUILDING. Returns 'nowt.

; bool testStructureModule(int playerNumber, 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 is sent in is NULL (i. e. - no structure is specified), then it will return TRUE if _any_ of the player's structures possess _any_ module. In all other cases, it will return FALSE.

; 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 setStructTarPref(int type)

Set a preferred structure target type, repeated calls combine the effect.

; void setStructTarIgnore(int type)

Set structure 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.

; bool isStructureAvailable(STRUCTURESTAT stat, int player)

Returns true if structure is available to player, false otherwise.

; bool structureComplete(STRUCTURE struct)

Returns true if the structure is completely built.

; int skGetFactoryCapacity(STRUCTURE str)

Return the capacity of factory str.

; 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. Returns modified x and ys.

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

Return total number of enemy military structures 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 numFriendlyWeapStructsInRange(int lookingPlayer, int x, int y, int range, bool onlyFinishedStructs)

Return total number of friendly military structures at location x, y and within range. Units belonging to enemies of lookingPlayer are ignored. If onlyFinishedStructs is set to TRUE, then unfinished structures will be ignored.

; int numPlayerWeapStructsInRange(int targetPlayer, int lookingPlayer, int x, int y, int range, 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 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.

Features

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

; initGetFeature(STRUCTURESTAT, PLAYER, BUCKET)[[BR]]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! getFeature returns NULLOBJECT when no more features are visible.

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 (does not 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 (does not 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 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 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 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.

; bool selectDroidByID(DROIDID, PLAYER)

This selects a unit defined by the ID since we cannot 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.

; void InitEnumDroids(int targetPlayer, int lookingPlayer)[[BR]]DROID EnumDroid()

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

; anyDroidsLeft(PLAYER)

checks the specified player for any units - returns TRUE if some exist, FALSE if they have all been destroyed.

; 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 does not 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, returns 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.

; 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).

; int idleGroup(GROUP group)

Returns number of units in group not doing anything.

; bool groupMember(GROUP group, DROID droid)

Returns 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).

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

Return the number of player units in an area.

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

; void vanishUnit(DROID droid)

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

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

; void resetDroidTargets()

Reset the unit preferences.

; void setDroidTarPref(int type)

Set prefered unit target types.

; void setDroidTarIgnore(int type)

Set unit target ignore types.

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

; 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 boundaries are:. 4, 8, 16, 32, 64, 128, 256, 512.

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

; int numEnemyWeapDroidsInRange(int lookingPlayer, int x, int y, int range, bool includeVTOLs)

Return total number of enemy military droids 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)

Return total number of friendly military droids 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.

; int numPlayerWeapDroidsInRange(int targetPlayer, int lookingPlayer, int x, int y, int range, bool includeVTOLs)

Returns total number of targetPlayer's military droids at location x, y and within range that are visible visible by lookingPlayer. If includeVTOLs is set to FALSE, then VTOLs are ignored.

; 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 calcDroidPower(DROID droid)

Returns cost of the droid.

; boolisVtol(DROID droid)

Returns TRUE if droid is a vtol.

Templates

; 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

}

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

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

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

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.

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

Make player pl do some research with structure str.

; 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 research 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.

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.

Power

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

; int playerPower(int player)

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

Environment/Map

; 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)

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

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

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

; void setWaterTile(int tileNum)

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

; 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).

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

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

; bool applyLimitSet (void)

Apply the limits set in the structure limits screen.

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

Game states

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

; 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 myResponsibility(PLAYER)

Returns true if this machine is responsible for PLAYER in multiplayer games.

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

; 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. Examples:

getGameStatus(STATUS_ReticuleIsOpen); will return TRUE if the reticule is open (on screen) or FALSE if the reticule is not (disabled)
getGameStatus(STATUS_BattleMapViewEnabled); will return TRUE if we are in the battle map mode
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.

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

; void skDifficultyModifier(int pl)

Apply the frontend slider settings to player pl.

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

Diplomacy

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

; createAlliance(int player1, int player2)

Create an alliance between two players.

; breakAlliance(int player1, int player2)

Breake an alliance between two players.

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

; bool alliancesLocked()

Returns TRUE if the game does not allow to break alliances (i. e. when team mode is on).

Strategy

; 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 cannot see that unit.

; bool isHumanPlayer (int pl)

Returns true is pl is human.

; bool skVtolEnableCheck(int pl)

True when player pl is actively using vtols.

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

Returns TRUE if there is 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 world units. If range == -1 then entire map will be searched.

GUI

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

; flashOn(int buttonID)

Turn on flashing for a button (ids in Script function constants). Works for all buttons not just reticule buttons.

; flashOff(int buttonID)

Turn off flashing for a button.

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

; 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, z. 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.

Multimedia

; playSound(SOUND, PLAYER)

Plays a '2D' sound i. e. 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 i. e. 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.

; flushConsoleMessages()

Clear all the console messages.

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

Unsorted

; setRetreatPoint(PLAYER, x, y)

Sets the position for a players units to retreat to.

; setGroupRetreatPoint(GROUP group, int x, int y)

Set the retreat position for a group.

; setRetreatForce(int player, int level)

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

; setGroupRetreatForce(GROUP group, 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).

; setGroupRetreatLeadership(GROUP group, int level)

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

; 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 is FALSE, then the values in rX and rY will be meaningless - unchanged actually, assuming the scripting works this way. Otherwise, they will be the coordinates of the midpoint of the nearest gateway.

; initIterateCluster(int clusterID)

Get ready to iterate a cluster.

; BASEOBJ iterateCluster()

Return the next object in the cluster or NULLOBJ if none left.

; BASEOBJ targetInCluster(int clusterID, int visibleToPlayer)

Get a target from a cluster using the preferences.

; traceOn()

View the script debug info to stdout.

; traceOff()

Stop viewing the script debug info to stdout.

; centreViewPos(int x, int y)

Center the view on the world coordinates x, y.

; void setEventTrigger(EVENT event, TRIGGER newTrigger)

Assigns newTrigger as new trigger for event event.

{{Scripting manual}} Category:Scripting manual ?

Download in other formats:

Plain Text