Changes between Version 24 and Version 25 of Triggers


Ignore:
Timestamp:
Jun 18, 2015, 11:56:19 AM (9 years ago)
Author:
sanderd17
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Triggers

    v24 v25  
    4444== Writing the trigger scripts ==
    4545
    46 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.
     46A trigger script typically consists of '''actions''' which are fired when certain '''events''' happen, and it keeps a bit of '''data''' to know the state of the game. These three parts are explained below.
    4747
    4848=== Action functions ===
    4949
    50 Actions are regular JavaScript functions, registered under the `Trigger` prototype. Actions called by triggers always receive a data object with more information about the event that just happened. How the data looks depends on the actual event. See the table below.
     50Actions are regular JavaScript functions, registered under the `Trigger` prototype. These functions can call each other, or be called from a trigger. When actions are called from a trigger, they always receive a data object with more information about the event that just happened. How the data looks depends on the actual event (see the table at the bottom).
    5151
    5252{{{
    … …  
    5454Trigger.prototype.MyAction = function(data)
    5555{
     56    // The action was called on a certain event
    5657    // Do Something
    5758};
    5859}}}
    5960
    60 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.
     61Calling one function from another is possible with the following type of calls:
    6162
    6263{{{
    … …  
    6465Trigger.prototype.MyAction = function(data)
    6566{
     67    // Ask a different function to calculate something, or execute some sub-action
    6668    var entities = this.GetRelevantEntities(data.player);
    6769    // Do something with those entities
    … …  
    7779The `this` keyword refers to the `Trigger` object anything defined under the prototype + additional data, which makes it easy to use.
    7880
     81== Registering triggers ==
     82
     83When you have your actions made, you need to bind them to a certain event. This is done via the predefined RegisterTrigger function. Triggers can be enabled in any method, but you usually need to enable some at the start of the game. You can use the following schema:
     84
     85{{{
     86#!js
     87// get the cmpTrigger object
     88var cmpTrigger = Engine.QueryInterface(SYSTEM_ENTITY, IID_Trigger);
     89
     90// register the trigger directly
     91var myData = {"enabled": true};
     92cmpTrigger.RegisterTrigger("OnPlayerCommand", "MyAction", myData);
     93}}}
     94
     95The first parameter of the trigger is the event on which it will be executed (see the table at the bottom for supported events). In the example, the trigger will be executed for every player command (move, gather, attack, donate, ...). The second parameter is the name of the action, which has to be defined under the Trigger prototype. And the third part is a data object. For most triggers, this data will be just enabled = true or false. But for more complicated triggers (range triggers, time triggers, ...) this data can contain other elements, such as the the distance of the range trigger, or the interval of the timer. Again, see the table below.
     96
     97The combination of event and action name must be unique. This combination can be used to enable and disable triggers. Registering a trigger twice isn't possible, and you will be warned when you do that.
     98
     99When you have your first triggers registered, they can fire actions, but actions can again register new triggers. As this time, it happens within the `Trigger` prototype, you can access `cmpTrigger` simply with `this`.
     100
     101{{{
     102#!js
     103Trigger.prototype.MyTriggerRegisteringAction = function(data)
     104{
     105    var myData = {"enabled": true};
     106    this.RegisterTrigger("OnPlayerCommand", "MySecondAction", myData);
     107};
     108}}}
     109
     110
     111Enabling and disabling triggers in action functions happens as shown:
     112
     113{{{
     114#!js
     115Trigger.prototype.MySecondAction = function(data)
     116{
     117    this.EnableTrigger("OnPlayerCommand", "MyAction");
     118    // OR
     119    this.DisableTrigger("OnPlayerCommand", "MyAction");
     120};
     121}}}
     122
     123You can enable and disable triggers as often as you want.
     124
    79125=== Keeping track of data ===
    80126
    81 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.
     127Quite 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, ...). Keeping track of data also happens under the `Trigger` object, so with the `this` keyword.
    82128
    83129==== Data initialisation ====
    … …  
    109155}}}
    110156
    111 '''Note:''' both the `Trigger` prototype (e.g. `Trigger.prototype.myData`) and the data you add directly to `this` (`this.myData`) can be accessed via `this`. But only the data added directly to `this` will be saved in a saved game (e.g. `this.myVar` will be saved but `Trigger.protoype.myVar` not!). So although it's possible to add other stuff to the prototype than just functions, only do so if it doesn't change throughout the game (i.e. constants like `Trigger.prototype.MIN_UNITS_REQUIRED_FOR_ATTACK = 1;` are fine). 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.
    112 
    113 == Registering triggers ==
    114 
    115 When you have your actions made, you need to bind them to a certain event. This is done via the predefined RegisterTrigger function. Triggers can be enabled in any method, but you usually need to enable some at the start of the game. You can use the following schema:
    116 
    117 {{{
    118 #!js
    119 // get the cmpTrigger object
    120 var cmpTrigger = Engine.QueryInterface(SYSTEM_ENTITY, IID_Trigger);
    121 
    122 // register the trigger directly
    123 var myData = {"enabled": true};
    124 cmpTrigger.RegisterTrigger("OnPlayerCommand", "MyAction", myData);
    125 }}}
    126 
    127 The first parameter of the trigger is the event on which it will be executed. In the example, the trigger will be executed for every player command. See the table below for a list of all possible events. The second parameter is the name of the action, which has to be defined under the Trigger prototype. And the third part is a data object. For most triggers, this data will be just enabled = true or false. But for more complicated triggers (range triggers, time triggers, ...) this data can contain other elements, such as the the distance of the range trigger, or the interval of the timer. Again, see the data in the table below.
    128 
    129 The combination of event and action name must be unique. This combination can be used to enable and disable triggers. Registering a trigger twice isn't possible, and you will be warned when you do that.
    130 
    131 When you have your first triggers registered, they can fire actions, but actions can again register new triggers. As this time, it happens within the `Trigger` prototype, you can access `cmpTrigger` simply with `this`.
    132 
    133 {{{
    134 #!js
    135 Trigger.prototype.MyTriggerRegisteringAction = function(data)
    136 {
    137     var myData = {"enabled": true};
    138     this.RegisterTrigger("OnPlayerCommand", "MySecondAction", myData);
    139 };
    140 }}}
    141 
    142 
    143 Enabling and disabling triggers in action functions happens as shown:
    144 
    145 {{{
    146 #!js
    147 Trigger.prototype.MySecondAction = function(data)
    148 {
    149     this.EnableTrigger("OnPlayerCommand", "MyAction");
    150     // OR
    151     this.DisableTrigger("OnPlayerCommand", "MyAction");
    152 };
    153 }}}
    154 
    155 You can enable and disable triggers as often as you want.
     157== Loading technicalities (how to support saved games) ==
     158
     159When a saved game is loaded, or someone joins an existing multiplayer game, it's important that the same state is kept. This requires you to know how and when trigger scripts are loaded.
     160
     161The trigger script is loaded as the last step when loading a game. In JavaScript, loading a script means executing it. So this creates all functions (without executing them), and adds the data to objects like you define them.
     162
     163When loading a saved game, the same happens, but after loading the script, it also restores data saved under the trigger object (but not under the prototype) to the old variables. Which means that it will overwrite registered triggers (as that's data) and your data, to give an equal state.
     164
     165Thus both the `Trigger` prototype (e.g. `Trigger.prototype.myData`) and the data you add directly to `this` (`this.myData`) can be accessed via `this`. But only the data added directly to `this` will be saved in a saved game (e.g. `this.myVar` will be saved but `Trigger.protoype.myVar` not!). So although it's possible to add other stuff to the prototype than just functions, only do so if it doesn't change throughout the game (i.e. constants like `Trigger.prototype.MIN_UNITS_REQUIRED_FOR_ATTACK = 1;` are fine). Also note that functions can't be saved in saved games. So functions should always be defined under the prototype, and never change.
    156166
    157167== Reference Table ==