This section describes functions that can be called from scripts to make things happen in the game (usually called our script 'API').
Calls a function with given arguments, measures time it took to evaluate the function, and adds this time to performance monitor statistics. Transparently returns the function's return value. The function to run is the first parameter, and it must be quoted. (3.2+ only)
Includes another source code file at this point. You should generally only specify the filename, not try to specify its path, here. However, if you specify sub-paths / sub-folders, the path separator should always be forward-slash ("/").
Reads a JSON file and returns an object. You should generally only specify the filename, However, if you specify sub-paths / sub-folders, the path separator should always be forward-slash ("/").
Set a function to run repeated at some given time interval. The function to run is the first parameter, and it must be quoted, otherwise the function will be inlined. The second parameter is the interval, in milliseconds. A third, optional parameter can be a game object to pass to the timer function. If the game object dies, the timer stops running. The minimum number of milliseconds is 100, but such fast timers are strongly discouraged as they may deteriorate the game performance.
function conDroids()
{
... do stuff ...
}
// call conDroids every 4 seconds
setTimer("conDroids", 4000);Removes an existing timer. The first parameter is the function timer to remove, and its name must be quoted.
Queues up a function to run at a later game frame. This is useful to prevent stuttering during the game, which can happen if too much script processing is done at once. The function to run is the first parameter, and it must be quoted, otherwise the function will be inlined. The second parameter is the delay in milliseconds, if it is omitted or 0, the function will be run at a later frame. A third optional parameter can be a game object to pass to the queued function. If the game object dies before the queued call runs, nothing happens.
Registers a new event namespace. All events can now have this prefix. This is useful for code libraries, to implement event that do not conflict with events in main code. This function should be called from global; do not (for hopefully obvious reasons) put it inside an event.
Returns the function name of the caller of the current context as a string (if available). ex.
function funcA() {
const callerFuncName = debugGetCallerFuncName();
debug(callerFuncName);
}
function funcB() {
funcA();
}
funcB();Will output: "funcB" Useful for debug logging.
Return an array containing all the buildable templates for the given player. (3.2+ only)
Remove reticule button. DO NOT USE FOR ANYTHING.
Remove a beacon message sent to target player. Target may also be ALLIES.
Returns a boolean that is true on success. (3.2+ only)
Reset the trigger on an label. Next time a unit enters the area, it will trigger
an area event. Next time an object or a group is seen, it will trigger a seen event.
Optionally add a filter on it in the second parameter, which can
be a specific player to watch for, or ALL_PLAYERS by default.
This is a fast operation of O(log n) algorithmic complexity. (3.2+ only)
Reset the trigger on an area. Next time a unit enters the area, it will trigger
an area event. Optionally add a filter on it in the second parameter, which can
be a specific player to watch for, or ALL_PLAYERS by default.
This is a fast operation of O(log n) algorithmic complexity. DEPRECATED - use resetLabel instead. (3.2+ only)
Returns a string list of labels that exist for this map. The optional filter parameter can be used to only return labels of one specific type. (3.2+ only)
Add a label to a game object. If there already is a label by that name, it is overwritten. This is a fast operation of O(log n) algorithmic complexity. (3.2+ only) Can optionally specify an initial "triggered" value for the label. (3.4+ only)
Remove a label from the game. Returns the number of labels removed, which should normally be either 1 (label found) or 0 (label not found). (3.2+ only)
Get a label string belonging to a game object. If the object has multiple labels, only the first label found will be returned. If the object has no labels, undefined is returned. This is a relatively slow operation of O(n) algorithmic complexity. (3.2+ only)
Fetch something denoted by a label, a map position or its object ID. A label refers to an area, a position or a game object on the map defined using the map editor and stored together with the map. In this case, the only argument is a text label. The function returns an object that has a type variable defining what it is (in case this is unclear). This type will be one of DROID, STRUCTURE, FEATURE, AREA, GROUP or POSITION. The AREA has defined 'x', 'y', 'x2', and 'y2', while POSITION has only defined 'x' and 'y'. The GROUP type has defined 'type' and 'id' of the group, which can be passed to enumGroup(). This is a fast operation of O(log n) algorithmic complexity. If the label is not found, an undefined value is returned. If whatever object the label should point at no longer exists, a null value is returned.
You can also fetch a STRUCTURE or FEATURE type game object from a given map position (if any). This is a very fast operation of O(1) algorithmic complexity. Droids cannot be fetched in this manner, since they do not have a unique placement on map tiles. Finally, you can fetch an object using its ID, in which case you need to pass its type, owner and unique object ID. This is an operation of O(n) algorithmic complexity. (3.2+ only)
Returns an array of game objects seen within the given area that passes the optional filter
which can be one of a player index, ALL_PLAYERS, ALLIES or ENEMIES. By default, filter is
ALL_PLAYERS. Finally an optional parameter can specify whether only visible objects should be
returned; by default only visible objects are returned. The label can either be actual
positions or a label to an AREA. Calling this function is much faster than iterating over all
game objects using other enum functions. (3.2+ only)
Return an array containing all the members of a given group.
Allocate a new group. Returns its numerical ID. Deprecated since 3.2 - you should now use your own number scheme for groups.
Add any droids inside the given area to the given group. (3.2+ only)
Add given droid to given group. Deprecated since 3.2 - use groupAdd() instead.
Add given game object to the given group.
Return the number of droids currently in the given group. Note that you can use groupSizes[] instead.
Mark string for translation.
Generate a synchronized random number in range 0...(limit - 1) that will be the same if this function is run on all network peers in the same game frame. If it is called on just one peer (such as would be the case for AIs, for instance), then game sync will break. (3.2+ only)
Set alliance status between two players to either true or false. (3.2+ only)
Send an alliance request to a player. (3.3+ only)
Give a droid an order to do something. (3.2+ only)
Give a droid an order to build something at the given position. Returns true if allowed.
Set the assembly point droids go to when built for the specified structure. (3.2+ only)
Move the position of the Sun, which in turn moves where shadows are cast. (3.2+ only)
setSunIntensity(ambient_r, ambient_g, ambient_b, diffuse_r, diffuse_g, diffuse_b, specular_r, specular_g, specular_b)
Set the ambient, diffuse and specular colour intensities of the Sun lighting source. (3.2+ only)
Set the colour of the fog (4.2.5+ only)
Set the current weather. This should be one of WEATHER_RAIN, WEATHER_SNOW or WEATHER_CLEAR. (3.2+ only)
Change the skybox. (3.2+ only)
Slide the camera over to the given position on the map. (3.2+ only)
Slide the camera to the given zoom distance. Normal camera zoom ranges between 500 and 5000. (3.2+ only)
Make the camera follow the given droid object around. Pass in a null object to stop. (3.2+ only)
Add an invisible viewer at a given position for given player that shows map in given range. radar
is false for vision reveal, or true for radar reveal. The difference is that a radar reveal can be obstructed
by ECM jammers. expiry, if non-zero, is the game time at which the spotter shall automatically be
removed. The function returns a unique ID that can be used to remove the spotter with removeSpotter. (3.2+ only)
Remove a spotter given its unique ID. (3.2+ only)
Generate a synchronized event request that is sent over the network to all clients and executed simultaneously. Must be caught in an eventSyncRequest() function. All sync requests must be validated when received, and always take care only to define sync requests that can be validated against cheating. (3.2+ only)
Replace one texture with another. This can be used to for example give buildings on a specific tileset different looks, or to add variety to the looks of droids in campaign missions. (3.2+ only)
Change a player's colour slot. The current player colour can be read from the playerData array. Available colours
are green, orange, gray, black, red, blue, pink, cyan, yellow, purple, white, bright blue, neon green, infrared,
ultraviolet, and brown, represented by the integers 0 - 15 respectively.
Change the health of the given game object, in percentage. Does not take care of network sync, so for multiplayer games, needs wrapping in a syncRequest. (3.2.3+ only.)
Change if the mission transporter will fetch droids in non offworld missions setReinforcementTime() is be used to hide it before coming back after the set time which is handled by the campaign library in the victory data section (3.3+ only).
Swap mission type and bring back units previously stored at the start of the mission (see cam3-c mission). (3.3+ only).
Returns the current multiplayer tech level. (3.3+ only)
Set the campaign number. (3.3+ only)
Return the current mission type. (3.3+ only)
Return the current fog reveal status. (3.3+ only)
Set the fog reveal status. (3.3+ only)
Perform automatic save
Turn off network transmissions. FIXME - find a better way.
Turn on network transmissions. FIXME - find a better way.
See wzscript docs for info, to the extent any exist. (3.2+ only)
See wzscript docs for info, to the extent any exist. (3.2+ only)
Function to find and return a game object of DROID, FEATURE or STRUCTURE types, if it exists.
Otherwise, it will return null. This function is DEPRECATED by getObject(). (3.2+ only)
Function to perform unit testing. It will throw a script error and a game assert. (3.2+ only)
Make the current script receive all events, even those not meant for 'me'. (3.2+ only)
Do not save the given global given by name to savegames. Must be done again each time game is loaded, since this too is not saved.
(3.3+ only)
Stop the in-game music. (3.3+ only) This should be called from the eventStartLevel() event (or later). Currently only used from the tutorial.
Mark the given tile(s) on the map. Either give a POSITION or AREA label,
or a tile x, y position, or four positions for a square area. If no parameter
is given, all marked tiles are cleared. (3.2+ only)
Output text to a debug file. (3.2+ only)
Output text to the command line.
Print text to the player console.
Clear the console. (3.3+ only)
Is given structure idle?
Returns an array of structure objects. If no parameters given, it will
return all of the structures for the current player. The second parameter
can be either a string with the name of the structure type as defined in
"structures.json", or a stattype as defined in Structure. The
third parameter can be used to filter by visibility, the default is not
to filter.
Returns an array of structure objects in your base when on an off-world mission, NULL otherwise.
If no parameters given, it will return all of the structures for the current player.
The second parameter can be either a string with the name of the structure type as defined
in "structures.json", or a stattype as defined in Structure.
The third parameter can be used to filter by visibility, the default is not
to filter.
Returns an array of droid objects. If no parameters given, it will return all of the droids for the current player. The second, optional parameter is the name of the droid type. The third parameter can be used to filter by visibility - the default is not to filter.
Returns an array of all features seen by player of given name, as defined in "features.json".
If player is ALL_PLAYERS, it will return all features irrespective of visibility to any player. If
name is empty, it will return any feature.
Return an array containing all the non-transient radar blips that the given player can see. This includes sensors revealed by radar detectors, as well as ECM jammers. It does not include units going out of view.
Return an array containing all game objects currently selected by the host player. (3.2+ only)
Return an array containing all the gateways on the current map. The array contains object with the properties x1, y1, x2 and y2. (3.2+ only)
Fetch information about a given technology item, given by a string that matches its definition in "research.json". If not found, returns null.
Returns an array of all research objects that are currently and immediately available for research.
Returns an array of game objects seen within range of given position that passes the optional playerFilter
which can be one of a player index, ALL_PLAYERS, ALLIES or ENEMIES. By default, playerFilter is
ALL_PLAYERS. Finally an optional parameter can specify whether only visible objects should be
returned; by default only visible objects are returned. Calling this function is much faster than
iterating over all game objects using other enum functions. (3.2+ only)
Start researching the first available technology on the way to the given technology. First parameter is the structure to research in, which must be a research lab. The second parameter is the technology to pursue, as a text string as defined in "research.json". The second parameter may also be an array of such strings. The first technology that has not yet been researched in that list will be pursued.
Return list of research items remaining to be researched for the given research item. (3.2+ only) (Optional second argument 3.2.3+ only)
Return distance between two points.
Give a droid an order to do something at the given location.
Return amount of power held by the given player.
Return amount of power queued up for production by the given player. (3.2+ only)
Returns true if given structure can be built. It checks both research and unit limits.
Pick a location for constructing a certain type of building near some given position.
Returns an object containing "type" POSITION, and "x" and "y" values, if successful.
Return whether or not the given droid could possibly drive to the given position. Does not take player built blockades into account.
Return true if a droid with a given propulsion is able to travel from (x1, y1) to (x2, y2). Does not take player built blockades into account. (3.2+ only)
Returns tile type of a given map tile, such as TER_WATER for water tiles or TER_CLIFFFACE for cliffs.
Tile types regulate which units may pass through this tile. (3.2+ only)
Returns whether the given map tile is burning. (3.5+ only)
Give a droid an order to do something to something.
Start factory production of new droid with the given name, body, propulsion and turrets. The reserved parameter should be passed null for now. The components can be passed as ordinary strings, or as a list of strings. If passed as a list, the first available component in the list will be used. The second reserved parameter used to be a droid type. It is now unused and in 3.2+ should be passed "", while in 3.1 it should be the droid type to be built. Returns a boolean that is true if production was started.
Create and place a droid at the given x, y position as belonging to the given player, built with the given components. Currently does not support placing droids in multiplayer, doing so will cause a desync. Returns the created droid on success, otherwise returns null. Passing "" for reserved parameters is recommended. In 3.2+ only, to create droids in off-world (campaign mission list), pass -1 as both x and y.
Create a template (virtual droid) with the given components. Can be useful for calculating the cost of droids before putting them into production, for instance. Will fail and return null if template could not possibly be built using current research. (3.2+ only)
Load a droid, which is currently located on the campaign off-world mission list, into a transporter, which is also currently on the campaign off-world mission list. (3.2+ only)
Create and place a feature at the given x, y position. Will cause a desync in multiplayer. Returns the created game object on success, null otherwise. (3.2+ only)
Checks whether a given component is available to the current player. The first argument is optional and deprecated.
Returns true if given droid is a VTOL (not including transports).
Returns true if given player is safe from hostile fire at the given location, to the best of that player's map knowledge. Does not work in campaign at the moment.
Activate a special ability on a structure. Currently only works on the lassat. The lassat needs a target.
Send a message to playerFilter. playerFilter may also be ALL_PLAYERS or ALLIES.
Returns a boolean that is true on success. (3.2+ only)
Send a message to playerFilter. playerFilter may also be ALL_PLAYERS or ALLIES.
messageEnum is the WzQuickChatMessage value. (See the WzQuickChatMessages global
object for constants to use. Pass in these constants directly, do not hard-code values!)
Returns a boolean that is true on success. (4.4+ only)
Get path of a droid. Returns an array of positions.
Send a beacon message to target player. Target may also be ALLIES.
Message is currently unused. Returns a boolean that is true on success. (3.2+ only)
Remove a beacon message sent to playerFilter. Target may also be ALLIES.
Returns a boolean that is true on success. (3.2+ only)
Return droid in production in given factory. Note that this droid is fully virtual, and should never be passed anywhere. (3.2+ only)
Return maximum number of droids that this player can produce. This limit is usually fixed throughout a game and the same for all players. If no arguments are passed, returns general droid limit for the current player. If a second, droid type argument is passed, the limit for this droid type is returned, which may be different from the general droid limit (eg for commanders and construction droids). (3.2+ only)
Get the percentage of experience this player droids are going to gain. (3.2+ only)
Set the maximum number of droids that this player can produce. If a third
parameter is added, this is the droid type to limit. It can be DROID_ANY
for droids in general, DROID_CONSTRUCT for constructors, or DROID_COMMAND
for commanders. (3.2+ only)
Set the maximum number of commanders that this player can produce. THIS FUNCTION IS DEPRECATED AND WILL BE REMOVED! (3.2+ only)
Set the maximum number of constructors that this player can produce. THIS FUNCTION IS DEPRECATED AND WILL BE REMOVED! (3.2+ only)
Set the percentage of experience this player droids are going to gain. (3.2+ only)
Returns an array of droid objects inside given transport. (3.2+ only)
Returns whether a particular player is a spectator. (4.2+ only) Can pass -1 as player to get the spectator status of the client running the script. (Useful for the "rules" scripts.)
Return information about a particular weapon type. DEPRECATED - query the Stats object instead. (3.2+ only)
Center the player's camera at the given position.
Play a sound, optionally at a location.
Add a guide topic to the in-game guide.
guideTopicID is expected to be a "::"-delimited guide topic id (which corresponds to the .json file containing the guide topic information).
For example,
"wz2100::structures::hq"will attempt to load"guidetopics/wz2100/structures/hq.json", the guide topic file about the hq / command center.
guideTopicID also has limited support for trailing wildcards. For example:
"wz2100::units::*"will load all guide topic .json files in the folder"guidetopics/wz2100/units/"(but not any subfolders)"wz2100::**"will load all guide topic .json files within the folder"guidetopics/wz2100/"and all subfolders
(The wildcard is only supported in the last position.)
showFlags can be used to configure automatic display of the guide, and can be set to one or more of:
SHOWTOPIC_FIRSTADD: open guide only if this topic is newly-added (this playthrough) - if topic was already added, the guide won't be automatically displayedSHOWTOPIC_NEVERVIEWED: open guide only if this topic has never been viewed by the player before (in any playthrough) You can also specify multiple flags (ex.SHOWTOPIC_FIRSTADD | SHOWTOPIC_NEVERVIEWED). The default behavior (where showFlags is omitted) merely adds the topic to the guide, but does not automatically display / open the guide.
excludedTopicIDs can be a string or a list of string guide topic IDs (non-wildcard) to be excluded, when supplying a wildcard guideTopicID.
End game in victory or defeat.
Set build limits for a structure.
Mix user set limits with script set limits and defaults.
Set mission countdown in seconds.
Get time remaining on mission countdown in seconds. (3.2+ only)
Set time for reinforcements to arrive. If time is negative, the reinforcement GUI
is removed and the timer stopped. Time is in seconds.
If time equals to the magic LZ_COMPROMISED_TIME constant, reinforcement GUI ticker
is set to "--:--" and reinforcements are suppressed until this function is called
again with a regular time value.
Finish a research for the given player. forceResearch will allow a research topic to be researched again. 3.3+
Finish all researches for the given player.
Enable a research for the given player, allowing it to be researched.
Set a player's power directly. (Do not use this in an AI script.)
Set a player's power modifier percentage. (Do not use this in an AI script.) (3.2+ only)
Set a player's power storage maximum. (Do not use this in an AI script.) (3.2+ only)
Increase a player's power as if that player had power income equal to current income over the given amount of extra time. (3.2+ only)
Sets a number of restrictions appropriate for tutorial if set to true.
Whether to allow player to design stuff.
Enable a specific template (even if design is disabled).
Remove a template.
Turns visible minimap on or off in the GUI.
Add reticule button. buttonId is which button to change, where zero is zero is the middle button, then going clockwise from the uppermost button. filename is button graphics and filenameDown is for highlighting. The tooltip is the text you see when you mouse over the button. Finally, the callback is which scripting function to call. Hide and show the user interface for such changes to take effect. (3.2+ only)
Set reticule flash on or off. (3.2.3+ only)
Open the reticule menu widget. (3.3+ only)
Show user interface. (3.2+ only)
Hide user interface. (3.2+ only)
The given structure type is made available to the given player. It will appear in the player's build list.
The given component is made available for research for the given player.
The given component is made available to the given player. This means the player can actually build designs with it.
Returns true if an alliance exists between the two players, or they are the same player.
Immediately remove the given structure from the map. Returns a boolean that is true on success.
No special effects are applied. DEPRECATED since 3.2. Use removeObject instead.
Queue the given game object for removal with or without special effects. Returns a boolean that is true on success. A second, optional boolean parameter specifies whether special effects are to be applied. (3.2+ only)
BREAKING CHANGE (4.5+): the effect of this function is not immediate anymore, the object will be queued for later removal instead of destroying it right away. User scripts should not rely on this function having immediate side-effects.
Limit the scrollable area of the map to the given rectangle. (3.2+ only)
Get the limits of the scrollable area of the map as an area object. (3.2+ only)
Create a structure on the given position. Returns the structure on success, null otherwise. Position uses world coordinates, if you want use position based on Map Tiles, then use as addStructure(structureName, players, x128, y128) Direction is optional, and is specified in degrees.
Returns build limits for a structure.
Count the number of structures of a given type.
The playerFilter parameter can be a specific player, ALL_PLAYERS, ALLIES or ENEMIES.
Count the number of droids that a given player has. Droid type must be either
DROID_ANY, DROID_COMMAND or DROID_CONSTRUCT.
The playerFilter parameter can be a specific player, ALL_PLAYERS, ALLIES or ENEMIES.
Load the level with the given name.
Set the amount of experience a droid has. Experience is read using floating point precision.
Donate a game object (restricted to droids before 3.2.3) to another player. Returns true if donation was successful. May return false if this donation would push the receiving player over unit limits. (3.2+ only)
Donate power to another player. Returns true. (3.2+ only)
Creates an area on the map on which nothing can be built. If playerFilter is zero,
then landing lights are placed. If playerFilter is ALL_PLAYERS, then a limbo landing zone
is created and limbo droids placed.
Set the entry position for the mission transporter, and make it start flying in reinforcements. If you want the camera to follow it in, use cameraTrack() on it. The transport needs to be set up with the mission droids, and the first transport found will be used. (3.2+ only)
Set the exit position for the mission transporter. (3.2+ only)
Set or unset an object flag on a given game object. Does not take care of network sync, so for multiplayer games,
needs wrapping in a syncRequest. (3.3+ only.)
Recognized object flags: OBJECT_FLAG_UNSELECTABLE - makes object unavailable for selection from player UI.
Fires a weapon at the given coordinates (3.3+ only). The player is who owns the projectile. Please use fireWeaponAtObj() to damage objects as multiplayer and campaign may have different friendly fire logic for a few weapons (like the lassat).
Fires a weapon at a game object (3.3+ only). The player is who owns the projectile.
Set a key + value string associated with a player, to be output to the playerData in the game story log (4.4+ only) (Intended to be called from endconditions.js to pass a useful string that describes the player state for display-only purposes.) (Not currently intended to be called from anywhere else.)
Transform a player to a spectator. (4.2+ only) This is a one-time transformation, destroys the player's HQ and all of their remaining units, and must occur deterministically on all clients.