(info) Other great resources: Official JS API docs, Scripting Forum

Contents

Owned by Aubergine
Last updated: Mar 15, 2013Version comment

Quick Reference

Links to all the main JS API features (see also: Index or Contents)...

How To's

Compatibility Matrix

A record of all changes to the Javascript API features since it's initial release...

  • Events 3.1 — Matrix of events availability in Warzone 3.1...
  • Change log — A summary of the main changes in the JS API from Warzone 3.1 Beta 1 to present day...
  • Functions 3.1 — Matrix of functions availability in Warzone 3.1...
  • Globals 3.1 — Matrix of globals availability in Warzone 3.1...
  • Constants 3.1 — Matrix of constant availability in Warzone 3.1...

Atmosphere

  • setSunPosition() — Set the position of the Sun, which affects shadows on the map...
  • setSunIntensity() — Change the lighting effects applied to game objects...
  • setWeather() — Sets the weather effect applied to the whole map.
    • WEATHER_SNOW — Adds a snow effect to the entire map, disabling any previous weather setting in the process.
    • WEATHER_CLEAR — Clears any active weather effect.
    • WEATHER_RAIN — Adds a rain effect to the entire map, disabling any previous weather setting in the process.
  • setSky() — Set the sky image, rotation speed and scale...

Components & Templates

Droids in Warzone are predominantly built from component parts, with component configurations stored as templates...

Constants

The JS API defines a number of constants which are used in Functions and Objects.

Droids

A wide range of features for working with droids (tanks, etc)...

Events & Timers

Events are the driving force behind your scripts...

Features

  • enumFeature() — Returns an array of feature objects (like trees and boulders), optionally filtered to a specific looking player...
  • addFeature() — Add a feature object (tree, log cabin, etc.) to the map...

Game Configuration

There's two parts to game settings - the game set-up, and player initialisation...

  • hackNetOff() — Used to disable network updates during Player Initialisation...
  • hackNetOn()
  • applyLimitSet() — Merges limits set by your script with limits set on the Structure Limits Screen...
  • getBurnDamage() — Get the base damage applied per second to a player's burning objects...
  • setBurnDamage() — Define the base damage applied per second to burning objects...
  • getBurnTime() — Define how long units burn for when they catch fire...
  • setBurnTime() — Define how long units burn for when they catch fire...
  • getDroidLimit() — Get the current production limit for a specific droid type or the total number of droids a player can produce...
  • setDroidLimit() — Define the maximum number of droids a player can create.
  • getExperienceModifier() — Set the rate at which droids gain experience...
  • setExperienceModifier() — Set the rate at which droids gain experience...
  • getStructureLimit() — Determine the structure limits for a given type of structure...
  • setStructureLimits() — Set limits on how many structures of a specific type a player can build.
  • Player Initialisation — Initialise player structures, components, technologies and bases before the game starts...

Groups

Organise game objects in to groups for easier iteration...

Labels

Functions for labelling objects...

  • getLabel() — Get the label, if any, associated with a game object...
  • addLabel() — Associate a game or map object with a label...
  • removeLabel() — Remove a label from the game...
  • resetArea() — Reset a labelled area trigger...
  • enumLabels() — Returns a list of all currently defined labels...

Map

  • distBetweenTwoPoints() — Returns the straight-line distance between two points on the map...
  • enumGateways()
  • enumRange() — List all objects within a specified range of a position on the map...
  • safeDest() — Determine if, based on the script player's current knowledge of the map, whether a specific map location is safe or not.
  • derrickPositions[] — An array of oil resources on the map, filtered to those that don't have derricks built on them at the start of the game.
  • enumBlips() — Get positions of non-transient radar blips as seen by your radar detectors...
  • hackMarkTiles() — Highlight map tiles with a pulsing red glow...
  • setNoGoArea()
  • tilesetType — A global which states the major tileset used by the current map...
  • propulsionCanReach() — Find out if a specific propulsion can travel between two points on the map...
  • startPositions[] — An array of player starting positions on the map.
  • getThreatsNear(x,y[,range]) — Returns an array of dangerous enemy objects near a specific location on the map.
  • mapHeight — Defines the map height, in tiles, as an integer.
  • mapName — A string containing the name of the map being played.
  • setScrollParams()
  • mapWidth — Defines the map width, in tiles, as an integer.
  • enumArea()

Missions / Campaign

Players & Alliances

Player data and scripts, alliances/teams, and player interactions...

  • Players
    • scavengerPlayer — Defines the player ID for the scavenger faction on the map.
    • playerData[] — An array of Player objects describing each human/AI player slot on the current map regardless of whether those slots have been assigned players for the current game.
    • difficulty — A constant representing the difficulty level selected for your script.
      • EASY — Act like a punching bag...
      • MEDIUM — Act like a regular skirmish player...
      • HARD — Act like a seasoned MP player...
      • INSANE — Be evil, cheat if you have to...
    • selectedPlayer — Indicates which player is currently being played/viewed by the human on the current machine.
    • scavengers — Indicates whether scavengers are enabled in this game.
    • maxPlayers — Defines the maximum number of human/AI player slots on the current map, regardless of whether those slots are filled in the current game.
    • me — Stores the player ID your script is associated with...
    • isMultiplayer — Determine if the game is an online multiplayer game...
  • Alliance
  • Interactions
    • donateObject() — Transfer an object to another player...
    • chat() — Send an in-game message to a specific player, your alliance or everyone.
    • donatePower() — Transfer some power to another player...
    • removeBeacon() — Send a beacon to a specific player or allies...
    • addBeacon() — Send a beacon to a specific player or allies...

Objects

The JS API has several object types that you'll encounter regularly when developing scripts...

  • .type — Defines the type of a game object – the .type of Objects.
  • getObject() — Three ways to retrieve a specific object...
    • label() — Retrieve the object associated with a label...
    • hackGetObj() — Retrieve a game object based on it's type, player and ID...
      • objFromId() — Retrieve a game object based on it's ID...
        • droidFromId() — Get an object based on it's object ID and player ID...
  • removeObject() — Remove a game object from the map...
    • removeStruct() — Immediately remove a structure object from the map...
  • Data objects — These objects relate to players and game config ("stats")...
    • Weapon Object — An object describing a weapon turret...
    • Group Object — A group of Game objects...
    • Template Object — An object describing a droid template...
    • Research object — Describes various attributes related to a specific researchable technology.
    • Player object — Specifies useful static information about a specific player in the game.
  • Game objects — The common properties for all objects that appear on the map such as droids, features and structures.
    • Structure object — Describes a structure (something a truck can build) on the map.
    • Droid object — Droids are mobile game objects (items on the map), and have a huge number of properties and related API features...
      • .droidType — Defines the type of a droid – the .droidType of a Droid object.
        • DROID_ANY — Used to bypass droid type filtering in functions that list or count droids.
        • DROID_TRANSPORTER — A cyborg transporter (or possibly a super transporter in Warzone 3.1 Beta 4 and earlier), capable of airlifting droids to some other location on the map.
        • DROID_REPAIR — A droid that has a repair turret, capable of repairing other droids.
        • DROID_PERSON — A droid that uses "legs" propulsion, for example a civilian or a scavenger machinegunner.
        • DROID_SUPERTRANSPORTER — A heavy transport unit, capable of airlifting any type of droid (including VTOLs) to some other location on the map...
        • DROID_CONSTRUCT — A construction truck or a cyborg engineer.
        • DROID_SENSOR
        • DROID_ECM — A droid that has an Electronic Counter Measures (radar jammer) turret.
        • DROID_COMMAND — A commander unit, to which other units can be assigned.
        • DROID_CYBORG — A cyborg warrior capable of attacking the enemy.
        • DROID_WEAPON — A droid capable of attacking other droids.
      • .order — Defines the order which a droid is currently performing (the .order property of a Droid object) or must perform (orderDroid*() functions).
        • DORDER_HELPBUILD — Instruct a construction droid to help with an existing structure building site.
        • DORDER_RECOVER — Order a droid to recover a collectible item such as an oil barrel or artefact (crate).
        • DORDER_DISEMBARK
        • DORDER_GUARD — Instruct a droid to guard a structure.
        • DORDER_TEMP_HOLD — Use DORDER_HOLD instead of DORDER_TEMP_HOLD.
        • DORDER_RTR — Instruct a land droid to go to a repair facility for repairs.
        • DORDER_EMBARK
        • DORDER_UNUSED — As it's name suggests, this constant is not used.
        • DORDER_CIRCLE — Instruct a VTOL to circle around a specific location.
        • DORDER_HOLD — Instruct the droid to hold its current position until instructed otherwise.
        • DORDER_SCOUT — Instruct a droid to "scout" to a new location.
        • DORDER_OBSERVE — Instruct a sensor droid to observe (target) a Droid object, Structure object, or even a Feature object.
        • DORDER_RTR_SPECIFIED — Instruct a land droid to go to a specific repair facility for repairs.
        • DORDER_DESTRUCT — Instruct a droid to self-destruct!
        • DORDER_RETREAT — Instruct a droid to retreat to a pre-defined retreat point. Does not retreat to HQ! Read docs before using!
        • DORDER_NONE — Indicates that a droid is currently idle.
        • DORDER_BUILD — Instruct a construction droid to build a Structure object at a specific location.
        • DORDER_ATTACK — Instruct a droid to attack something.
        • DORDER_LINEBUILD — Indicates that a construction droid is building a line of structures (eg. a long wall).
        • DORDER_REARM — Instruct a VTOL to return to a rearming pad for repairs and rearming.
        • DORDER_RECYCLE — Recycle a droid...
        • DORDER_FIRESUPPORT — Assign a attacker droid to a sensor droid so that it can attack whatever the sensor droid targets.
        • DORDER_RTB — Instruct a droid to return to your base.
        • DORDER_MOVE — Instruct a droid to move to a new location.
        • DORDER_COMMANDERSUPPORT — Assign an attacker droid to a commander droid so that it will attack whatever the commander droid targets.
        • DORDER_STOP — Instruct a droid to stop what it's doing.
        • DORDER_DEMOLISH — Instruct a construction droid to demolish one of your structures.
        • DORDER_PATROL — Instruct a droid to patrol between it's current location and a specified location, attacking any enemies it detects along the way.
        • DORDER_DROIDREPAIR — Instruct a repair droid to repair a damaged Droid object.
        • DORDER_REPAIR — Instruct a construction droid to repair a damaged Structure object.
      • .action — Defines the current action a Droid object is taking to fulfil its current .order.
    • Feature object — Feature objects describe inanimate game objects such as oil barrels and resources, artefacts, log cabins and skyscrapers, trees, etc.
  • Location objects
    • Position object — Defines a position on the map via its x,y co-ordinates.
    • Area object — Specifies the top-left and bottom-right co-ordinates of an area of the map.

Power

  • setPowerModifier()
  • queuedPower() — Find out if your power reserves have gone negative, indicating that you have one or more tasks stalled due to lack of power...
  • extraPowerTime() — Increase the player's power reserve as if they'd played the game for an additional number of seconds...
  • powerType — Defines the rate at which oil derricks produce power, prior to applying any power upgrades.
  • playerPower() — Find out how much available power a specific player has...
  • setPower() — Set the power reserves for a player...

Research & Technology

Script Environment

This section contains general information about the Javascript environment used by Warzone.

  • scriptPath — The path to the main script loaded in to a particular scripting environment...
  • Native JS Features — A summary of the native Javascript features of the Warzone JS environment.
  • scriptName — The filename of the main script loaded in to a particular scripting environment...
  • dump() — Dumps text to a log file...
  • hackAssert() — Assert a value and throw a game assert and JS error if it's falsey...
  • Scopes & Closures — This article explains some important javascript concepts...
  • syncRandom() — Generate a synchronised random integer...
  • debug() — Outputs text to the terminal or log file depending on operating system.
  • Timers
    • queue() — Invoke a function at some point in the future...
    • setTimer() — Allows you to trigger a function at some point in the future.
    • removeTimer() — Allows you to cancel all queued and timed calls associated with a specific function...
  • WZscript (.vlo and .slo) to Javascript (.js) — This guide is designed to help developers who are converting their old WZScripts to the new Javascript API...
  • Error Handling — Most JS API functions and Javascript operations will "thow" an error if you use them incorrectly...
  • Common Mistakes — A summary of common issues you *will* run in to whilst developing against the JS API...
  • include() — Include library scripts in to your main script...
  • Javascript Debugger — The JS debugger allows you to inspect scripts and labels...
  • Environment Sequences — Details of the main environment sequences that occur in Warzone...
  • Code sandboxing — A brief tutorial showing how to sandbox a chunk of code, primarily to avoid it's variables leaking on to the global scope.
  • version — A string representing the game version being played.
  • Player Scripts — Each player in the game has a specific script associated with them...
  • Introduction — Warzone2100 contains a scripting language for implementing AIs, campaigns and some of the game rules...
  • Save / Load Cycle
    • Saved game files — How do I work out what data is getting stored in save game files? Will it show me why my script is broken?

Structures

User Interface

  • _() localise — Used for string localisation (translation in to other languages)...
  • console() — Outputs text to the player console associated with the script.
  • enumSelected() — Get a list of all objects selected by the the game host...
  • Mini Map and Design Mode — Enable or disable the mini map and design mode depending on the presence of a HQ.
    • setDesign() — Enable or disable the design tool...
    • setMiniMap() — Display or hide the localhost human player's radar mini-map...
  • playSound() — Plays a sound, optionally displaying a beacon on the map and mini map.
  • audioAlert(filename,pos,despam) — Throttled alternative for playSound().
  • setTutorialMode() — Toggles "tutorial mode" in a single-player game...
  • addReticuleButton() — Enable a reticule button...
  • removeReticuleButton() — Disable a reticule button...
  • Reticule buttons — These constants are used by addReticuleButton() and removeReticuleButton().
    • BUILD — Used to show or hide the "Build" (hammer) reticule button.
    • CANCEL — Used to show or hide the "Cancel" (central) reticule button.
    • COMMAND — Used to show or hide the "Command" (star) reticule button.
    • DESIGN — Used to show or hide the "Design" (blue components) reticule button.
    • INTELMAP — Used to show or hide the "Intelligence" (earth map) reticule button.
    • MANUFACTURE — Used to show or hide the "Maufacture" (factory) reticule button.
    • OPTIONS — This constant is deprecated, use COMMAND instead.
    • RESEARCH — Used to show or hide the "Research" (green circuit board) reticule button.
  • Camera

To-Do List

Just a dumping ground for things I spot in the forums that need adding to this guide...

Useful Links

There's lots of useful information elsewhere on the intertubes...