Triggers

This document will describe how to add triggers to maps, how to program triggers, and what the possibilities of triggers are.

We will try to give a lot of examples, that should be easy to copy-paste and modify where needed. But this isn't meant as an introductory course to JavaScript. For a JavaScript reference, it's best to look at the ​Mozilla Development Network (MDN). For creating and editing JavaScript files, it's best to use a decent text editor. Syntax highlighting is a must, so ​Notepad++ on Windows should be sufficient.

Modifying your map

For now, Atlas isn't very prepared for triggers. So we have no GUI to edit triggers (obviously), but also no GUI to add trigger scripts to your map. This means you need to edit your map data. For scenarios and skirmish maps, this map data is a JSON part in the map.xml file (see example). For random maps it's in the map.json file directly (see example​). (TODO: add link to committed triggers examples).

In this JSON part of the data, you define an array of loaded trigger scripts. You can define multiple more general helper scripts, and your custom script(s).

{
  "CircularMap": true,
  "Description": "The first steps of playing 0 A.D.",
  "...": "...",
  "TriggerScripts": [
    "scripts/TriggerHelper.js",
    "skirmishes/basic_tutorial.js"
  ]
}

The root of these paths is in modName/maps/, and it's custom to put general scripts in the scripts directory, and map-specific scripts next to the existing map files.

Of course, you need to make sure these files exist by creating them with your favourite text editor. You can write a small warning in the script, so you know your script is executed

warn("My first trigger script");

This should show a yellow warning in the top left of your screen when the map loading is finished.

Tip: See Logging for more logging options.

Writing the trigger scripts

Trigger scripts are executed when the map is completely loaded, but right before the game starts. So you can already access all existing entities and their properties s.a. position, owner, ... This is the right time to bind actions to certain events, a.k.a. registering triggers.

Action functions

Actions are regular JavaScript functions, registered under the Trigger prototype.

Trigger.prototype.MyAction = function(data)
{
    // Do Something
};

Note that these functions only exist, and aren't executed by default. They're only executed when bound to a trigger, or when a different function in your trigger calls it. Chaining functions like the following example is possible, and a good way to split up complicated logic.

Trigger,prototype.MyAction = function(data)
{
    var entities = this.GetRelevantEntities(data.player);
    // Do something with those entities
};

Trigger.prototype.GetRelevantEntities = function(player)
{
    // calculate something
    return relevantEntities;
};

The this keyword refers to the Trigger object anything defined under the prototype + additional data, which makes it easy to use.

Keeping track of data

Quite often, you'll want to keep track of data that changes throughout the game (number of units killed, number of times a certain trigger is executed, ...). As this data changes during the game, it's important that the last saved data is also loaded when loading a saved game, or when a player rejoins in a multiplayer game. Keeping track of data also happens under the Trigger object, so with the this keyword.

Data initialisation

There's a special method (InitGame), that gets called when loading a new game, so it can be used for data initialisation. You can initialise any counters or other data there.

Trigger.prototype.InitGame = function(data)
{
    this.executedTriggers = 0;
    this.killedUnits = 0;
}

Data usage

After data initialisation, you can just use it in other trigger functions.

Trigger.prototype.MyAction = function(data)
{
    this.executedTriggers++; // will enlarge the counter with one
    this.killedUnits += TriggerHelper.GetKilledEntities(data); // execute a function with separate logic, and add it to a counter
}

Note: both the Trigger prototype and the data you add directly to this can be accessed via this. But only the data added directly to this will be saved in a saved game. So although it's possible to add other stuff to the prototype than just functions, it shouldn't change throughout the game. Also note that functions can't be saved in saved games. So in short, functions should always be defined under the prototype, and never change.

Registering functions