Other great resources: Official JS API docs, Scripting Forum
Contents
Quick Reference
Links to all the main JS API features (see also: Index or Contents)...
How To's
- Working with Power
- generatorsRequired(player) — Determine if more generators are required to power our oil derricks.
- Quickly testing script changes — What's the fastest way to check changes to my scripts?
- Making your first AI mod — I want to make an AI mod for warzone, where do I start?
- Working with Sensors
- Working with Repairs & Rearming
- Random Stuff — This section contains some random things that you might find useful...
- Prioritising research — Based on events in the game, how can I change my research priorities?
- getEnemyPlayerIDs() — Returns an array of all enemy player IDs, including scavengers, using caching for extra performance.
- enumEnemyStruct(structure[,viewer]) — Returns an array of all enemy structures of a given type, optionally filtered to visibility of lookingPlayer.
- Working with Modules
- Working with VTOLs
- Working with Factories — This guide explains the basics of working with factories in your scripts...
- Working with Transports — How to build and use transports...
- isTransporter(droidObj) — Determine if a droid object is a transporter.
- Working with Construction
- Working with Commanders
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...
- componentAvailable() — Check if a droid component is available...
- enableComponent() — Enable a player to research a specific droid component...
- makeComponentAvailable() — Make a component available to the player so they can use it in droid designs...
- enableTemplate() — Used to make construction trucks available before building a HQ...
- enumTemplates() — Return a list of buildable templates for the player...
- getWeaponInfo()
- makeTemplate() — Create a fake droid object that can be used to inspect droid attributes prior to production...
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)...
- enumCargo()
- orderDroidLoc()
- orderDroidStatsLoc() — Early implementation of orderDroidBuild()...
- addDroid() — Instantly place a droid on the map...
- isVTOL() — Determine if a droid is using VTOL propulsion.
- orderDroid() — Send a basic command, that does not require an object or location, to a droid.
- enumDroid() — Returns an array of droid objects, optionally filtered to a specific player, droid type and looking player...
- setTransporterExit() — Define the location where transports will exit the map...
- countDroid() — Count the number of droids of a given type for a specific player.
- droidCanReach() — Find out if a specific droid can reach a specific location from it's current location...
- buildDroid() — Instruct a factory to build a droid...
- startTransporterEntry() — Bring a mission transporter on to the map...
- orderDroidObj()
- setDroidExperience()
- orderDroidBuild() — Order a construction droid to build a new structure...
Events & Timers
Events are the driving force behind your scripts...
- eventSelectionChange() — Triggered when the user selects or deselects objects...
- eventDestroyed() — Triggered when a game object is destroyed...
- bind() — Register a function to be called when a game object gets destroyed.
- eventGameInit() — This event is triggered once at the start of a new game before the map is ready.
- eventDesignCreated() — Triggers when a player saves a new template in the droid designer...
- eventObjectTransfer() — This event is triggered when a droid or structure is transferred to or from another player...
- eventObjectSeen() — This event is triggered when one of your sensors detects something new on the map.
- eventVideoDone()
- eventChat() — This event is triggered each time a chat message is received.
- eventGameSaving()
- eventTransporterLanded() — Triggered when a transporter lands...
- eventCheatMode() — This event is called when the human player enters cheat mode...
- eventObjectRecycled() — Triggered when a droid is recycled or when a structure is demolished by a truck...
- eventTransporterLaunch() — Triggered when a mission transporter has been instructed to launch....
- eventLaunchTransporter() — Triggered when a mission transporter has been instructed to launch....
- eventTransporterDone() — Stick a fork in it, it's done...
- eventDroidIdle() — This event is triggered when a droid is twiddling it's turrets because it's got nothing to do.
- eventPlayerLeft() — Triggers if a player leaves the game...
- eventMissionTimeout() — This event triggers when the mission timer runs out...
- eventStructureBuilt()
- eventStartLevel() — This event is triggered once at the start of a new game after the map is ready and all game data loaded. It is also triggered once after a new level is loaded.
- eventGameSaved()
- eventGroupLoss() — Triggered when a game object leaves a group...
- eventAttacked() — This event is called when your droids or structures are attacked.
- eventBeacon() — This event is triggered each time a new beacon is received.
- eventResearched() — Triggered when a new technology has been researched by you or an ally...
- eventStructureReady() — This event is triggered when a structure is ready to perform its special ability.
- eventArea<Label>() — An event that's triggered when a droid enters a labelled Area object...
- eventAttackedUnthrottled() — This event is called when your droids or structures are attacked.
- eventGameLoaded() — This event is triggered once after a saved game is loaded.
- eventTransporterExit() — Triggered when a mission transporter leaves the map...
- eventPickup() — Triggered when an oil barrel or artifiact is picked up by a droid...
- eventTransporterArrived() — Triggered when a mission transporter has arrived on the map with reinforcements....
- eventReinforcementsArrived() — Triggered when a mission transporter has arrived on the map with reinforcements....
- eventDroidBuilt() — This event is triggered when you get a new droid as a result of buildDroid() or addDroid()...
- eventBeaconRemoved() — This event is triggered each time a beacon is removed.
Features
- addFeature() — Add a feature object (tree, log cabin, etc.) to the map...
- enumFeature() — Returns an array of feature objects (like trees and boulders), optionally filtered to a specific looking player...
Game Configuration
There's two parts to game settings - the game set-up, and player initialisation...
- 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...
- getBurnTime() — 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...
- getExperienceModifier() — Set the rate at which droids gain experience...
- getStructureLimit() — Determine the structure limits for a given type of structure...
- hackNetOff() — Used to disable network updates during Player Initialisation...
- hackNetOn()
- Player Initialisation — Initialise player structures, components, technologies and bases before the game starts...
- setBurnDamage() — Define the base damage applied per second to burning objects...
- setBurnTime() — Define how long units burn for when they catch fire...
- setDroidLimit() — Define the maximum number of droids a player can create.
- setExperienceModifier() — Set the rate at which droids gain experience...
- setStructureLimits() — Set limits on how many structures of a specific type a player can build.
Groups
Organise game objects in to groups for easier iteration...
- enumGroup() — Retrieve a list of objects in a group...
- groupAdd() — Add a game object to a group...
- groupAddArea() — Add most objects within an area of the map to a group...
- groupAddDroid() — Add a droid to an existing group...
- groupSize() — Find out how many droids there are in a specific group...
- groupSizes[] — An array of group sizes...
- newGroup() — Create a new droid group...
- orderGroupObj(group,dorder,obj) — Similar to orderDroidObj() but for a group of droids
Labels
Functions for labelling objects...
- addLabel() — Associate a game or map object with a label...
- enumLabels() — Returns a list of all currently defined labels...
- getLabel() — Get the label, if any, associated with a game object...
- removeLabel() — Remove a label from the game...
- resetArea() — Reset a labelled area trigger...
Map
- 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.
- distBetweenTwoPoints() — Returns the straight-line distance between two points on the map...
- enumArea()
- enumBlips() — Get positions of non-transient radar blips as seen by your radar detectors...
- enumGateways()
- enumRange() — List all objects within a specified range of a position on the map...
- getThreatsNear(x,y[,range]) — Returns an array of dangerous enemy objects near a specific location on the map.
- hackMarkTiles() — Highlight map tiles with a pulsing red glow...
- mapHeight — Defines the map height, in tiles, as an integer.
- mapName — A string containing the name of the map being played.
- mapWidth — Defines the map width, in tiles, as an integer.
- propulsionCanReach() — Find out if a specific propulsion can travel between two points 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.
- setNoGoArea()
- setScrollParams()
- startPositions[] — An array of player starting positions on the map.
- tilesetType — A global which states the major tileset used by the current map...
Missions / Campaign
- gameOverMessage() — End the game in either victory or defeat.
- gameTime — An integer representing the number of milliseconds since the game started.
- getMissionTime() — Get the current value of the mission timer...
- loadLevel() — Mark the current mission as complete and start a new level in a campaign...
- setMissionTime() — Set or clear the mission countdown timer...
- setReinforcementTime() — Set or clear reinforcement timer...
Players & Alliances
Player data and scripts, alliances/teams, and player interactions...
- Alliance
- allianceExistsBetween() — Determine whether two players are allies with each other...
- alliancesType — Defines the alliance mode selected for the current game...
- Player Scope — These constants group players in various ways.
- ALL_PLAYERS — Send a chat message to all players.
- ALLIES — Send a chat message to your allies.
- ENEMIES — Filter enumeration to enemy objects.
- setAlliance()
- Interactions
- addBeacon() — Send a beacon to a specific player or allies...
- chat() — Send an in-game message to a specific player, your alliance or everyone.
- donateObject() — Transfer an object to another player...
- donatePower() — Transfer some power to another player...
- removeBeacon() — Send a beacon to a specific player or allies...
- Players
- difficulty — A constant representing the difficulty level selected for your script.
- isMultiplayer — Determine if the game is an online multiplayer 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...
- 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.
- scavengerPlayer — Defines the player ID for the scavenger faction on the map.
- scavengers — Indicates whether scavengers are enabled in this game.
- selectedPlayer — Indicates which player is currently being played/viewed by the human on the current machine.
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.
- AREA
- DROID
- FEATURE
- GROUP
- PLAYER_DATA — Indicates the object contains player data.
- POSITION
- RESEARCH_DATA
- STRUCTURE
- Data objects — These objects relate to players and game config ("stats")...
- Group Object — A group of Game objects...
- Player object — Specifies useful static information about a specific player in the game.
- Research object — Describes various attributes related to a specific researchable technology.
- Template Object — An object describing a droid template...
- Weapon Object — An object describing a weapon turret...
- Game objects — The common properties for all objects that appear on the map such as droids, features and structures.
- Droid object — Droids are mobile game objects (items on the map), and have a huge number of properties and related API features...
- .action — Defines the current action a Droid object is taking to fulfil its current .order.
- .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_COMMAND — A commander unit, to which other units can be assigned.
- DROID_CONSTRUCT — A construction truck or a cyborg engineer.
- DROID_CYBORG — A cyborg warrior capable of attacking the enemy.
- DROID_ECM — A droid that has an Electronic Counter Measures (radar jammer) turret.
- DROID_PERSON — A droid that uses "legs" propulsion, for example a civilian or a scavenger machinegunner.
- DROID_REPAIR — A droid that has a repair turret, capable of repairing other droids.
- DROID_SENSOR
- DROID_SUPERTRANSPORTER — A heavy transport unit, capable of airlifting any type of droid (including VTOLs) to some other location on the map...
- 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_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_ATTACK — Instruct a droid to attack something.
- DORDER_BUILD — Instruct a construction droid to build a Structure object at a specific location.
- DORDER_CIRCLE — Instruct a VTOL to circle around a specific location.
- DORDER_COMMANDERSUPPORT — Assign an attacker droid to a commander droid so that it will attack whatever the commander droid targets.
- DORDER_DEMOLISH — Instruct a construction droid to demolish one of your structures.
- DORDER_DESTRUCT — Instruct a droid to self-destruct!
- DORDER_DISEMBARK
- DORDER_DROIDREPAIR — Instruct a repair droid to repair a damaged Droid object.
- DORDER_EMBARK
- DORDER_FIRESUPPORT — Assign a attacker droid to a sensor droid so that it can attack whatever the sensor droid targets.
- DORDER_GUARD — Instruct a droid to guard a structure.
- DORDER_HELPBUILD — Instruct a construction droid to help with an existing structure building site.
- DORDER_HOLD — Instruct the droid to hold its current position until instructed otherwise.
- DORDER_LINEBUILD — Indicates that a construction droid is building a line of structures (eg. a long wall).
- DORDER_MOVE — Instruct a droid to move to a new location.
- DORDER_NONE — Indicates that a droid is currently idle.
- DORDER_OBSERVE — Instruct a sensor droid to observe (target) a Droid object, Structure object, or even a Feature object.
- 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_REARM — Instruct a VTOL to return to a rearming pad for repairs and rearming.
- DORDER_RECOVER — Order a droid to recover a collectible item such as an oil barrel or artefact (crate).
- DORDER_RECYCLE — Recycle a droid...
- DORDER_REPAIR — Instruct a construction droid to repair a damaged Structure object.
- DORDER_RETREAT — Instruct a droid to retreat to a pre-defined retreat point. Does not retreat to HQ! Read docs before using!
- DORDER_RTB — Instruct a droid to return to your base.
- DORDER_RTR — Instruct a land droid to go to a repair facility for repairs.
- DORDER_RTR_SPECIFIED — Instruct a land droid to go to a specific repair facility for repairs.
- DORDER_SCOUT — Instruct a droid to "scout" to a new location.
- DORDER_STOP — Instruct a droid to stop what it's doing.
- DORDER_TEMP_HOLD — Use DORDER_HOLD instead of DORDER_TEMP_HOLD.
- DORDER_UNUSED — As it's name suggests, this constant is not used.
- Feature object — Feature objects describe inanimate game objects such as oil barrels and resources, artefacts, log cabins and skyscrapers, trees, etc.
- Structure object — Describes a structure (something a truck can build) on the map.
- .stattype — The .stattype of a Structure object and, in Warzone 3.2 and above, also certain Feature objects...
- ARTIFACT — Indicates an artifact Feature object...
- BUILDING — A Feature object representing a building...
- COMMAND_CONTROL
- CYBORG_FACTORY
- DEFENSE
- FACTORY
- GATE
- HQ
- LASSAT
- OIL_DRUM — Indicates an oil drum (barrel) Feature object...
- OIL_RESOURCE — Indicates an oil resource Feature object...
- POWER_GEN
- REARM_PAD
- REPAIR_FACILITY
- RESEARCH_LAB
- RESOURCE_EXTRACTOR
- SAT_UPLINK
- VTOL_FACTORY
- WALL
- .status — Defines the build status of a structure – the .status of a Structure object.
- BEING_BUILT
- BEING_DEMOLISHED — This constant is no longer available, but this article provides some guidance on dealing with structure demolition...
- BUILT
- .stattype — The .stattype of a Structure object and, in Warzone 3.2 and above, also certain Feature objects...
- Droid object — Droids are mobile game objects (items on the map), and have a huge number of properties and related API features...
- getObject() — Three ways to retrieve a specific object...
- 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...
- objFromId() — Retrieve a game object based on it's ID...
- label() — Retrieve the object associated with a label...
- hackGetObj() — Retrieve a game object based on it's type, player and ID...
- Location objects
- Area object — Specifies the top-left and bottom-right co-ordinates of an area of the map.
- Position object — Defines a position on the map via its x,y co-ordinates.
- removeObject() — Remove a game object from the map...
- removeStruct() — Immediately remove a structure object from the map...
Power
- extraPowerTime() — Increase the player's power reserve as if they'd played the game for an additional number of seconds...
- playerPower() — Find out how much available power a specific player has...
- powerType — Defines the rate at which oil derricks produce power, prior to applying any power upgrades.
- queuedPower() — Find out if your power reserves have gone negative, indicating that you have one or more tasks stalled due to lack of power...
- setPower() — Set the power reserves for a player...
- setPowerModifier()
Research & Technology
- completeResearch()
- enableResearch()
- enumResearch() — List all technologies that can you can start researching immediately...
- findResearch() — Returns a list of technologies that need to be researched to achieve a specific research goal.
- getResearch()
- pursueResearch()
- Stats — A read-only list of the default game stats (prior to any modifiers or upgrades) for droid components, buildings, etc...
Script Environment
This section contains general information about the Javascript environment used by 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.
- Common Mistakes — A summary of common issues you *will* run in to whilst developing against the JS API...
- debug() — Outputs text to the terminal or log file depending on operating system.
- dump() — Dumps text to a log file...
- Environment Sequences — Details of the main environment sequences that occur in Warzone...
- Error Handling — Most JS API functions and Javascript operations will "thow" an error if you use them incorrectly...
- hackAssert() — Assert a value and throw a game assert and JS error if it's falsey...
- include() — Include library scripts in to your main script...
- Introduction — Warzone2100 contains a scripting language for implementing AIs, campaigns and some of the game rules...
- Javascript Debugger — The JS debugger allows you to inspect scripts and labels...
- Native JS Features — A summary of the native Javascript features of the Warzone JS environment.
- Player Scripts — Each player in the game has a specific script associated with them...
- 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?
- Scopes & Closures — This article explains some important javascript concepts...
- scriptName — The filename of the main script loaded in to a particular scripting environment...
- scriptPath — The path to the main script loaded in to a particular scripting environment...
- syncRandom() — Generate a synchronised random integer...
- Timers
- queue() — Invoke a function at some point in the future...
- removeTimer() — Allows you to cancel all queued and timed calls associated with a specific function...
- setTimer() — Allows you to trigger a function at some point in the future.
- version — A string representing the game version being played.
- 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...
Structures
- activateStructure() — Activates the special feature of a structure, such as firing laser satellite...
- addStructure()
- baseType — A constant defining what sort of bases players start with in the current game.
- CAMP_BASE — Walls, gates, defences, HQ and cyborg factory will be removed at the start of the game. Insane AIs keep their walls and defences.
- CAMP_CLEAN — Base structures will be removed at the start of the game, except for Scavengers and "Insane" AIs.
- CAMP_WALLS — All structures will remain at the start of the game.
- countStruct() — Count the number of structures of a given type...
- enableStructure()
- enumStruct() — List structures on the current map...
- enumStructOffWorld()
- getDroidProduction() — Determine what droid, if any, a factory is currently producing...
- iHave(structure) — Quickly determine if a structure of the specified type has been fully built.
- isStructureAvailable()
- pickStructLocation() — Find a good location for a specific droid to build a specific structure.
- setAssemblyPoint()
- structureIdle() — Check if a structure is idle...
- wasDemolished(structure) — Determine if a destroyed structure was demolished by trucks or engineers.
User Interface
- _() localise — Used for string localisation (translation in to other languages)...
- addReticuleButton() — Enable a reticule button...
- audioAlert(filename,pos,despam) — Throttled alternative for playSound().
- Camera
- cameraSlide() — Change the camera position...
- cameraTrack() — Instruct the camera to track a droid...
- cameraZoom() — Zoom the camera in or out...
- centreView() — Centre the camera view on a specific x,y tile co-ordinate...
- 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.
- 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.
- setTutorialMode() — Toggles "tutorial mode" in a single-player game...
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...