Introduction

Introduction

This wiki contains a more detailed version of the API documentation, with example code and extensive inter-linking to related topics.

The goal is to encourage more people to get involved in scripting and modding Warzone 2100.

Please feel free to contribute to this wiki - you can get a user account via the login link top-right of this page. If you have any questions, please post a comment on the relevant page.

What can I use it for?

The JS API is extremely flexible and powerful. Thanks to Warzone's extensive modding features, several of which now support Javascript, you can achieve some incredible things with this API...

The Scavenger faction

Scavenger Faction were once a pitiful opponent, until the Ultimate Scavenger Mod was developed. Using the JS API and other modding features, Scavengers were given dozens of new units, including ice cream vans and helicopters, all controlled by a new AI written entirely in Javascript.

If you want to create a custom Scavenger faction, make a mod that replaces multiplay/script/scavfact.js and you can make the Scavengers do whatever you want!

AI players

As you might imagine, the primary use for the Javascript API was to allow new forms of AI players (bots) to be created. One of the most successful so far, an adaptive-AI called NullBot, receives regular updates thanks to the ease of scripting and deployment gained by using Javascript.

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 required:

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

Game rules

The game rules are written entirely in Javascript! Everything from player initialisation, victory conditions and situation reporting are all done using the JS API - and of course, that means you can change them if you so desire.

All you need to do is make a mod that overwrites multiplay/skirmish/rules.js and you can radically change how the game works.

Fore more tutorials on customising them, see: Game Rules & SitRep.

Challenge scripts

Challenge Games can load custom scripts, 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:

• Challenge Games – how to define challenge games
• Create an AI that's only available in challenges – exactly what it says on the tin

Basics of the JS API

Here's some basics about the key areas of functionality in the JS API...

Events

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

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