| 81 | == Registering triggers == |
| 82 | |
| 83 | 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: |
| 84 | |
| 85 | {{{ |
| 86 | #!js |
| 87 | // get the cmpTrigger object |
| 88 | var cmpTrigger = Engine.QueryInterface(SYSTEM_ENTITY, IID_Trigger); |
| 89 | |
| 90 | // register the trigger directly |
| 91 | var myData = {"enabled": true}; |
| 92 | cmpTrigger.RegisterTrigger("OnPlayerCommand", "MyAction", myData); |
| 93 | }}} |
| 94 | |
| 95 | The 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 | |
| 97 | 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. |
| 98 | |
| 99 | 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`. |
| 100 | |
| 101 | {{{ |
| 102 | #!js |
| 103 | Trigger.prototype.MyTriggerRegisteringAction = function(data) |
| 104 | { |
| 105 | var myData = {"enabled": true}; |
| 106 | this.RegisterTrigger("OnPlayerCommand", "MySecondAction", myData); |
| 107 | }; |
| 108 | }}} |
| 109 | |
| 110 | |
| 111 | Enabling and disabling triggers in action functions happens as shown: |
| 112 | |
| 113 | {{{ |
| 114 | #!js |
| 115 | Trigger.prototype.MySecondAction = function(data) |
| 116 | { |
| 117 | this.EnableTrigger("OnPlayerCommand", "MyAction"); |
| 118 | // OR |
| 119 | this.DisableTrigger("OnPlayerCommand", "MyAction"); |
| 120 | }; |
| 121 | }}} |
| 122 | |
| 123 | You can enable and disable triggers as often as you want. |
| 124 | |
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 | |
| 159 | When 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 | |
| 161 | The 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 | |
| 163 | When 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 | |
| 165 | Thus 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. |