Debian Codegraph @

doc/scripts/triggers.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2002-2007 by Lutz Sammer, Russell Smith, Fran�is Beerten
5
6 ---- This program is free software; you can redistribute it and/or modify
7 ---- it under the terms of the GNU General Public License as published by
8 ---- the Free Software Foundation; only version 2 of the License.
9 ----
10 ---- This program is distributed in the hope that it will be useful,
11 ---- but WITHOUT ANY WARRANTY; without even the implied warranty of
12 ---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 ---- GNU General Public License for more details.
14 ----
15 ---- You should have received a copy of the GNU General Public License
16 ---- along with this program; if not, write to the Free Software
17 ---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
18 ---- 02111-1307, USA.
19 -->
20 <title>Bos Wars Scripting API: Triggers</title>
21 <meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
22 <link rel="stylesheet" type="text/css" href="scripts.css">
23 </head>
24 <body>
25 <h1>Bos Wars Scripting API: Triggers</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="sound.html">PREV</a>
30 <a href="ui.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#ActionDefeat">ActionDefeat</a>
34 <a href="#ActionDraw">ActionDraw</a>
35 <a href="#ActionSetTimer">ActionSetTimer</a>
36 <a href="#ActionStartTimer">ActionStartTimer</a>
37 <a href="#ActionStopTimer">ActionStopTimer</a>
38 <a href="#ActionVictory">ActionVictory</a>
39 <a href="#AddTrigger">AddTrigger</a>
40 <a href="#IfNearUnit">IfNearUnit</a>
41 <a href="#GetNumOpponents">GetNumOpponents</a>
42 <a href="#IfRescuedNearUnit">IfRescuedNearUnit</a>
43 <a href="#GetTimer">GetTimer</a>
44 <a href="#GetNumUnitsAt">GetNumUnitsAt</a>
45 <hr>
46 <h2>Intro - Introduction to trigger functions and variables</h2>
47
48 Everything around triggers.<br>
49 Triggers are a couple of (condition, action).
50 Each cycles in the game, if the condition of the active triggers is true,
51 then the associated actions are executed.
52 There are used for condition's victory
53 and could be usefull to add special actions when an event occurs.
54
55 <h2>Functions</h2>
56
57 <a name="ActionDefeat"></a>
58 <h3>ActionDefeat()</h3>
59
60 The player lose the game.
61
62
63 <h4>Example</h4>
64
65 <pre class="lua">
66 -- Adds a trigger. If the player on the console has 0 units then he loses.
67 AddTrigger(
68 function() return IfUnit("this", "==", 0, "all") end,
69 function() return ActionDefeat() end)
70 </pre>
71
72 <a name="ActionDraw"></a>
73 <h3>ActionDraw()</h3>
74
75 The condition player is set to draw. (NOT SUPPORTED)
76
77
78 <a name="ActionSetTimer"></a>
79 <h3>ActionSetTimer(cycles, increasing)</h3>
80
81 Set the timer.
82
83
84 <dl>
85 <dt>cycles</dt>
86 <dd>The number of cycles (default setting is 30 cycles per second).</dd>
87 <dt>increasing</dt>
88 <dd>Set this to 1 if you want the timer to increase, set it to 0 for decreasing.</dd>
89 </dl>
90
91 <h4>Example</h4>
92
93 <pre class="lua">
94 -- Sets the timer to 9000 cycles (300 seconds or 5 minutes) and decreasing.
95 ActionSetTimer(9000, 0)
96 </pre>
97
98 <a name="ActionStartTimer"></a>
99 <h3>ActionStartTimer()</h3>
100
101 Start the timer.
102
103
104 <a name="ActionStopTimer"></a>
105 <h3>ActionStopTimer()</h3>
106
107 Stop the timer.
108
109
110 <a name="ActionVictory"></a>
111 <h3>ActionVictory()</h3>
112
113 The condition player is set to victory.
114
115 <h4>Example</h4>
116
117 <pre class="lua">
118 -- Adds a trigger. If the player on the console has killed all his
119 -- opponents he won.
120 AddTrigger(
121 function() return IfOpponents("this", "==", 0) end,
122 function() return ActionVictory() end)
123 </pre>
124
125 <a name="AddTrigger"></a>
126 <h3>AddTrigger(condition, action)</h3>
127
128 Creates a new trigger.
129 <br>FIXME: in code, action could be a table, but crash on execution..
130
131 <dl>
132 <dt>condition</dt>
133 <dd>Function which must return true to execute the condition. It is tested every FIXME.</dd>
134 <dt>action</dt>
135 <dd>
136 Function executed when condition return true. The trigger remains active
137 if the action returns true and is removed if the action returns false.
138 </dd>
139 </dl>
140
141 <h4>Example</h4>
142
143 <pre class="lua">
144 -- Adds a trigger. If the player on the console has killed all his
145 -- opponents he won.
146 AddTrigger(
147 function() return IfOpponents("this", "==", 0) end,
148 function() return ActionVictory() end)
149 </pre>
150
151 <a name="IfNearUnit"></a>
152 <h3>IfNearUnit(player, op, quantity, unit1, unit2)</h3>
153
154 Return true if the number of unit1 near of unit2 "op" quantity is true for the player.
155
156
157 <dl>
158 <dt>player</dt>
159 <dd><pre>
160 0 .. 16 Player number
161 "any" Matches any player
162 "this" Player on the local computer, Human player in the campaign.
163 </pre></dd>
164 <dt>op</dt>
165 <dd><pre>
166 "==" operator equal
167 "&gt;" operator greater than
168 "&gt;=" operator greater than or equal
169 "&lt;" operator less than
170 "&lt;=" operator less than or equal
171 </pre></dd>
172 <dt>quantity</dt>
173 <dd>Number to compare with number of units</dd>
174 <dt>unit1</dt>
175 <dd><pre>
176 unit-name Unit type of this name
177 "any" Matches any unit type
178 "all" All units (sum of units and buildings)
179 "units" All non building units
180 "building" All building units
181 </pre></dd>
182 <dt>unit2</dt>
183 <dd>unit-name, so unit type of this name.</dd>
184 </dl>
185
186 <h4>Example</h4>
187
188 <pre class="lua">
189 -- true when the player on the console has 6 archers near one of his/her circle of power.
190 IfNearUnit("this", "==", 6, "unit-archer", "unit-circle-of-power")
191 </pre>
192
193 <a name="GetNumOpponents"></a>
194 <h3>GetNumOpponents(player)</h3>
195
196 Returns the number of opponent's for the given player.
197
198 <dl>
199 <dt>player</dt>
200 <dd><pre>
201 0 .. 16 Player number
202 </pre></dd>
203 </dl>
204
205 <h4>Example</h4>
206
207 <pre class="lua">
208 -- You win when you have no opponents left.
209 if (GetNumOpponents(ThisPlayer.Index) == 0) then
210 ActionVictory()
211 </pre>
212
213 <a name="IfRescuedNearUnit"></a>
214 <h3>IfRescuedNearUnit(player, op, quantity, unit1, unit2)</h3>
215
216 Return true if the number of rescued-units of type unit1 which are currently near of unit2
217 of the player "op" quantity is true.
218
219 <dl>
220 <dt>player</dt>
221 <dd><pre>
222 0 .. 16 Player number
223 "any" Matches any player
224 "this" Player on the local computer, Human player in the campaign.
225 </pre></dd>
226 <dt>op</dt>
227 <dd><pre>
228 "==" operator equal
229 "&gt;" operator greater than
230 "&gt;=" operator greater than or equal
231 "&lt;" operator less than
232 "&lt;=" operator less than or equal
233 </pre></dd>
234 <dt>quantity</dt>
235 <dd>Number to compare with number of rescued-unit</dd>
236 <dt>unit1</dt>
237 <dd><pre>
238 unit-name Unit type of this name
239 "any" Matches any unit type
240 "all" All units (sum of units and buildings)
241 "units" All non building units
242 "building" All building units
243 </pre></dd>
244 <dt>unit2</dt>
245 <dd>unit-name, so unit type of this name.</dd>
246 </dl>
247
248 <h4>Example</h4>
249
250 <pre class="lua">
251 -- True when The player on the console has 1 rescued archer near the circle of power.
252 IfRescuedNearUnit("this", "==", 1, "unit-archer", "unit-circle-of-power")
253 </pre>
254
255
256 <a name="GetTimer"></a>
257 <h3>GetTimer()</h3>
258
259 Return the number of cycles the timer ran.
260
261 <h4>Example</h4>
262
263 <pre class="lua">
264 -- True when the timer is at 17 cycles.
265 time = GetTimer() == 17
266 </pre>
267
268 <a name="GetNumUnitsAt"></a>
269 <h3>GetNumUnitsAt(player, unit-type, {x1, y1}, {x2, y2})</h3>
270
271 Return the number of units of type unit-type which are in the rectangle defined with (x1, y1, x2, y2)
272 of the player.
273
274 <dl>
275 <dt>player</dt>
276 <dd><pre>
277 0 .. 16 Player number
278 </pre></dd>
279 <dt>unit</dt>
280 <dd><pre>
281 unit-name Unit type of this name
282 "any" Matches any unit type
283 "all" All units (sum of units and buildings)
284 "units" All non building units
285 "building" All building units
286 </pre></dd>
287 <dt>{x1, y1}</dt>
288 <dd>Upper left corner</dd>
289 <dt>{x2, y2}</dt>
290 <dd>Lower right corner</dd>
291 </dl>
292
293 <h4>Example</h4>
294
295 <pre class="lua">
296 -- True when the player on the console has at least 8 archers in the rectangle
297 -- (10 10) to (12 14).
298 GetNumUnitsAt(ThisPlayer.Index, "unit-archer", {10, 10}, {12, 14}) >= 8
299 </pre>
300
301 <hr>
302 All trademarks and copyrights on this page are owned by their respective owners.
303 <address>(c) 2002-2006 by <a href="http://boswars.org">
304 The Bos Wars Project</a></address></body></html>