Introduction

Overview

It uses JavaScript, so you should become familiar with this language before proceeding with this document. A number of very good guides to JavaScript exist on the Internet – Mozilla Developer Network is arguably the best. Note, however, that most online Javascript guides are aimed at web development - Warzone is most certainly not a web browser, so there is no DOM, no HTML, etc.

I've done some digging in to the JS environment in which your scripts run and posted the results here: What's in the JS environment? and API.

The ECMA-262 implementation (Javascript to you and me) used in Warzone is based on Spidermonkey, the JS engine used in Apple's Safari web browser. For more information on it's native features from a C++ developer perspective, see Nokia's QtScript documentation.

Regardless of your knowledge of the game or programming experience, I highly recommend reading Common Mistakes as you will almost certainly fall prey to one of these.

Game rules and Scavenger AI

The following hard-coded files exist for game rules that use this API:

• multiplay/skirmish/rules.js – Default game rules including base setup, starting research, winning and losing. 
• multiplay/script/scavfact.js – If scavengers are active, this script controls their actions.

Also, you can create mods to overwrite these files if desired.  need to link to mods page on wz2100.net

AI scripts

AI scripts are registered using ’.ai’ files in the ’multiplayer/skirmish’ directory.

Here is an example of an ’.ai’ file that defines an AI called "Semperfi JS":

[AI]
name = "Semperfi JS"
js = semperfi.js

There are two properties defined:

• name – the AIs name that will be displayed to end-users when they set up a skirmish or multiplayer game
• js – the filename of the AI javascript file (which must be in same folder as the ".ai" file)

Challenge scripts

Challenges may load scripts as well, if a [scripts] section is present in the challenge file, and has the keys ”extra” or ”rules”.

The ”extra” key sets up an additional script to be run during the challenge. The ”rules” key sets up an alternative rules file, which means that the ”rules.js” mentioned above is not run. In this case, you must implement your own rules for winning and losing, among other things. Here is an example of such a scripts section:

[scripts]
rules = towerdefense.js

You can also specify which AI scripts are to be run for each player in the challenge. These are read from the ”multiplay/skirmish” directory. If you do not want an AI script to be loaded for a player (for example, if you want this player to be controlled from one of your challenge scripts), then you can give it the special value ”null”. Here is an example if a challenge player definition with its AI specified:

[player_2]
team = 1
difficulty = "Medium"
position = 4
ai = semperfi.js

See also: Create an AI that's only available in challenges

Events

The code in a javascript file is triggered by specially named functions called Events.

An event is expected to carry out some computation then return immediately. The game is on hold while an event is processed, so do not do too many things at once, or else the player will experience stuttering.

Constants

Any value written in ALL_CAPS_WITH_UNDERSCORES are enums, special read-only Constants defined by the game.

Persisting data

All global variables are saved when the game is saved. However, do not try to keep JavaScript ob jects that are returned from API functions defined here around in the global scope. They are not meant to be used this way, and bad things may happen.

If you need to keep static arrays around, it is better to keep them locally defined to a function, as they will then not be saved and loaded.

See also: Saved game files