Debian Codegraph @

doc/scripts/ai.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2002-2010 by Lutz Sammer, Russell Smith
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: Artificial Intelligence (AI)</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: Artificial Intelligence (AI)</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="unittype.html">PREV</a>
30 <a href="config.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#AiTypes">AiTypes</a>
34 <a href="#AiState">AiState</a>
35 <a href="#DefineAiType">DefineAiType</a>
36 <a href="#DefineAiHelper">DefineAiHelper</a>
37 <a href="#AiCheckForce">AiCheckForce</a>
38 <a href="#AiDebug">AiDebug</a>
39 <a href="#AiDebugPlayer">AiDebugPlayer</a>
40 <a href="#AiAttackWithForce">AiAttackWithForce</a>
41 <a href="#AiForce">AiForce</a>
42 <a href="#AiForceRole">AiForceRole</a>
43 <a href="#AiNeed">AiNeed</a>
44 <a href="#AiPlayer">AiPlayer</a>
45 <a href="#AiSet">AiSet</a>
46 <a href="#AiSleep">AiSleep</a>
47 <a href="#AiWait">AiWait</a>
48 <a href="#AiWaitForce">AiWaitForce</a>
49
50 <hr>
51 <h2>Intro - Introduction to AI functions and variables</h2>
52
53 Everything around the control of the Bos Wars AI.
54
55 <p>
56 Warning: The AI documentation is slightly outdated. This documentation hasn't
57 been fully converted to the lua API yet.
58 </p>
59
60 <h2>How does it work</h2>
61
62 AI in Bos Wars is script based. Each AI player keeps executing scripts.
63 There are two kinds of scripts :
64 <ul>
65 <li>The main script. It starts buildings, ...</li>
66 <li>The action/reaction scripts. They are started by the AI engine, under certain condition.<br>
67 </li>
68 </ul>
69 Scripts can arrange and control units using forces : <br>
70 A script can ask for some type of unit in a force (using <a href="#AiForce">AiForce</a>),
71 and then wait for them to be ready (using <a href="#AiWaitForce">AiWaitForce</a>).<br>
72 <br>
73 <br>
74 The force 0 is a special case : it holds all the unassigned units, and is used to fill other forces.
75 ( when needed, units are transfered from force 0 to others ). Attacker units in force 0 won't be used for attacks<br>
76 Forces from 1 to 3 are also special : They are used as the attack reserve.
77 Attack forces will only be created using units available in those forces.<br>
78 <br>
79 The main script is responsible for setting minimums for the forces 0 and 1. This will influence the balance
80 between defend and attack for an AI player.<br>
81 <br>
82
83 <h2>Variables</h2>
84
85 <a name="AiTypes"></a>
86 <h3>AiTypes</h3>
87
88 <p>This table lists all the AI types defined in Lua. It is used by
89 both the engine and the Lua code. In AiTypes, every AI type has an
90 entry that is a table with these keys:</p>
91
92 <dl>
93 <dt>Ident = string</dt>
94 <dd>Unique, language-independent identifier of this AI type.
95 By convention, each identifier should begin with "ai-".
96 The Ident string is also the key of the entry within AiTypes.
97 The map setup file sets e.g. <code>Players[1].AiName = "ai-blitz"</code>
98 and the engine then finds the AI type whose identifier is that string;
99 or if no such AI type exists, the engine falls back to "ai-passive".
100 In saved games, these names are used in
101 the "ai-type" parameter of <a href="savegame.html#DefineAiPlayer">DefineAiPlayer</a>
102 and the "ai-name" parameter of <a href="savegame.html#Player">Player</a>.</dd>
103 <dt>Name = string</dt>
104 <dd>Name of the AI the Player sees and which gets translated.
105 The engine does not use this; only the Lua code does.</dd>
106 <dt id="AiTypes.Init">Init = function or nil</dt>
107 <dd>Initializes
108 <a href="#AiState">AiState</a>[<a href="#AiPlayer">AiPlayer()</a>]
109 to whatever the AI type requires.
110 When starting a new game, the engine calls the Init function
111 for each player that is going to use this AI type.
112 Typically, the Init function creates a table and writes it to
113 AiState[AiPlayer()], and the <a href="#AiTypes.EachSecond">EachSecond</a>
114 function will then maintain that table.
115 Even if the AI type does not use AiState for its own purposes,
116 the Init function must regardless write a non-nil value to
117 AiState[AiPlayer()], so that the engine will know the AI state
118 has been initialized and not call the Init function again
119 if the game is later saved and loaded.
120 (Of course, if the AI type has no Init function, then there
121 is no such requirement.)</dd>
122 <dt id="AiTypes.EachSecond">EachSecond = function</dt>
123 <dd>Decides AI actions: primarily, what to build.
124 The engine calls the EachSecond function once per second
125 (at the default game speed).</dd>
126 <dt>(other)</dt>
127 <dd>Lua code can add other keys in the table.
128 The engine will ignore them.
129 (Perhaps there should be a naming convention so that
130 Lua-specific and engine-specific keys won't clash.
131 Or we can just document all keys here.)</dd>
132 </dl>
133
134 <p>Lua code is free to read the AiTypes table but should not
135 modify it or its elements directly. Instead, it should call
136 <a href="#DefineAiType">DefineAiType</a>, so that the engine
137 knows to update its data structures accordingly.</p>
138
139 <a name="AiState"></a>
140 <h3>AiState</h3>
141
142 <p>The AI state of the map and each AI player.
143 The AI scripts should write all persistent state into AiState,
144 so that the engine will save and load it as part of the game,
145 and so that the engine can easily clear the state when
146 starting a new game.</p>
147
148 <dl>
149 <dt>AiState[<a href="#AiPlayer">AiPlayer()</a>] = table</dt>
150 <dd>AI state of a single AI player.
151 The <a href="#AiTypes.Init">Init</a> function of the AI type
152 creates this table, and the other functions of the AI type
153 can then use the fields of the table as they please.
154 If AiState[AiPlayer()] is nil, that means the engine has not
155 called the Init function yet.</dd>
156
157 <dt>AiState.cache = table</dt>
158 <dd>Cached information shared by all AI players.
159 Lua scripts of individual AI types should not access this directly.
160 Instead, they should use shared functions.
161 <p><b>Not in engine:</b>
162 The engine does not know about AiState.cache.
163 Only the Lua code does.</p></dd>
164 </dl>
165
166 <p>The engine does not currently preserve object identity when saving
167 and loading a game. That means, if the AI script does</p>
168
169 <pre class="lua">
170 local x = {}
171 AiState[AiPlayer()].first = x
172 AiState[AiPlayer()].second = x
173 </pre>
174
175 <p>then a comparison like
176 <code>AiState[AiPlayer()].first == AiState[AiPlayer()].second</code>
177 will initially return true, but if the game is saved and loaded, the
178 comparison will start returning false because <code>first</code> and
179 <code>second</code> now refer to different empty tables.
180 However, scripts should not depend on this behavior.</p>
181
182 <h2>Functions</h2>
183 <a name="DefineAiType"></a>
184 <h3>DefineAiType(table)</h3>
185
186 <p>Defines an AI type and adds it to <a href="#AiTypes">AiTypes</a>.</p>
187
188 <dl>
189 <dt>table</dt>
190 <dd>Describes the AI type, in the same format
191 as an element of <a href="#AiTypes">AiTypes</a>.</dd>
192 </dl>
193
194 <p><b>Note:</b> Individual maps should not call DefineAiType.
195 Call it during global initialization instead.
196 The engine does not provide any way to undefine an AI type
197 and reacts poorly to redefinitions.</p>
198
199 <h4>Example</h4>
200
201 <pre class="lua">
202 -- Defines the passive computer AI, which does nothing.
203 DefineAiType({
204 Ident = "ai-passive",
205 Name = _("Passive"),
206 Init = nil, -- which is the default anyway
207 EachSecond = function() end })
208 </pre>
209
210 <a name="DefineAiHelper"></a>
211 <h3>DefineAiHelper(list)</h3>
212
213 The AI is complete configurable, nothing is hardcoded. The AI knows nothing
214 about any units without this table. This table defines F.E. what unit can build
215 and what they can build and many other things that the AI must know.
216
217
218 <dl>
219 <dt>list</dt>
220 <dd>A list of features:
221 <dl>
222 <dt class="obsolete"><code>{"build", <var>builder-type</var>, <var>building-type-1</var>, ... <var>building-type-n</var>}</code></dt>
223 <dd class="obsolete">
224 <em>Obsolete since r8101 (2006-06-21):
225 Ignored. The AI instead gets this information from
226 <a href="ui.html#DefineButton">DefineButton</a> calls
227 that have Action = "build".</em>
228 <dl>
229 <dt>builder-type</dt>
230 <dd>Name of the unit-type that can build.
231 </dd>
232 <dt>building-type-1</dt>
233 <dt>building-type-n</dt>
234 <dd>Names of the unit-types that can be built by the builder.
235 </dd>
236 </dl>
237 <b>Note:</b> If more units can build the same buildings
238 you need the same list for all units.
239 </dd>
240 <dt class="obsolete"><code>{"train", <var>trainer-type</var>, <var>unit-type-1</var>, ... <var>unit-type-n</var>}</code></dt>
241 <dd class="obsolete">
242 <em>Obsolete since r8101 (2006-06-21):
243 Ignored. The AI instead gets this information from
244 <a href="ui.html#DefineButton">DefineButton</a> calls
245 that have Action = "train".</em>
246 <dl>
247 <dt>trainer-type</dt>
248 <dd>Name of the unit-type that can train the units.
249 </dd>
250 <dt>unit-type-1</dt>
251 <dt>unit-type-n</dt>
252 <dd>Names of the unit-types that can be trained by the trainer.
253 </dd>
254 </dl>
255 <b>Note:</b> If more units can train the same unit
256 you need the same list for all units.
257 </dd>
258 <dt class="obsolete"><code>{"repair", <var>worker-type</var>, <var>unit-type-1</var>, ... <var>unit-type-n</var>}</code></dt>
259 <dd class="obsolete">
260 <em>Obsolete since r8101 (2006-06-21):
261 Ignored. The AI instead gets this information from
262 <a href="ui.html#DefineButton">DefineButton</a> calls
263 that have Action = "repair".</em>
264 <dl>
265 <dt>worker-type</dt>
266 <dd>Name of the unit-type that can repair other units.
267 </dd>
268 <dt>unit-type-1</dt>
269 <dt>unit-type-n</dt>
270 <dd>Names of the unit-types that can be repaired by the worker.
271 </dd>
272 </dl>
273 <b>Note:</b> If more units can repair the same units
274 you need the same list for all units.
275 </dd>
276 <dt><code>{"unit-equiv", <var>unit-type</var>, <var>unit-type-1</var>, ... <var>unit-type-n</var>}</code></dt>
277 <dd>Declares unit types as equivalent for AI purposes.
278 When <a href="#AiForce">AiForce</a> is asked to train
279 any of them, it instead trains the best one it can;
280 "best" here is controlled by the Priority setting in
281 <a href="unittype.html#DefineUnitType">DefineUnitType</a>.
282 <dl>
283 <dt>unit-type</dt>
284 <dd>Name of the unit-type that have equivalent units.
285 </dd>
286 <dt>unit-type-1</dt>
287 <dt>unit-type-n</dt>
288 <dd>Names of the unit-types that can be used by the AI equivalent.
289 </dd>
290 </dl>
291 </dd>
292 <dt class="obsolete"><code>{"unit-limit", <var>unit-type</var>, <var>resource</var>}</code></dt>
293 <dd class="obsolete">
294 <em>Obsolete since r8101 (2006-06-21) and r8658 (2007-04-01):
295 Ignored. The engine no longer limits the number of units
296 according to resources.</em>
297 <dl>
298 <dt>unit-type</dt>
299 <dd>Name of the unit-type that must be produced to increase the unit limit.
300 </dd>
301 <dt>resource</dt>
302 <dd>Name of the resource producing the shortage.
303 </dd>
304 </dl>
305 <i>I think we should swap the arguments: "resource", "unit-type".</i>
306 </dd>
307 </dl>
308 </dd>
309 </dl>
310
311 <h4>Example</h4>
312
313 A minimal AI helper definition:
314
315 <pre class="lua">
316 DefineAiHelper(
317 {"build", "unit-peasant", "unit-farm"},
318 {"train", "unit-town-hall", "unit-peasant"},
319 {"repair", "unit-peasant", "unit-town-hall"},
320 {"unit-limit", "unit-farm", "food"},
321 {"unit-equiv", "unit-town-hall", "unit-keep"})
322 </pre>
323
324 <p>A peasant can build a farm.
325 <p>The town hall can train a peasant.
326 <p>A peasant can repair the town hall.
327 <p>To fix the food shortage the AI must build farms.
328 <p>For the AI is a keep equivalent to a town hall.
329
330 <a name="AiAttackWithForce"></a>
331 <h3>AiAttackWithForce(force)</h3>
332
333 <p>Attack the opponent with the given force. The place is choosen by the AI. If there
334 are flyers, ships and land units in the force they could attack different
335 goals.</p>
336
337 <dl>
338 <dt>force</dt>
339 <dd>ID of the force to which the attacking units belong. The force ids 0 to 9
340 are currently supported.
341 </dd>
342 <dt>returns</dt>
343 <dd>False.</dd>
344 </dl>
345
346 <i>The force isn't moved as a single unit: faster units attacks first, than later the
347 slower units will attack.</i>
348
349 <h4>Example</h4>
350
351 <pre class="lua">
352 -- Force 0 is built with one assault unit. The script continues processing, when
353 -- the assault unit is ready. When ready, the script attacks the opponent
354 -- with force 0.
355 {
356 function() return AiForce(0, "unit-assault", 1) end,
357 function() return AiWaitForce(0) end,
358 function() return AiAttackWithForce(0) end
359 }
360 </pre>
361
362 <a name="AiCheckForce"></a>
363 <h3>AiCheckForce(force)</h3>
364
365 <p>Check if a force is complete.</p>
366
367 <dl>
368 <dt>force</dt>
369 <dd>Number of the force to which the units should belong. 0 - 9 is currently
370 supported.
371 </dd>
372 <dt>returns</dt>
373 <dd>True if the force is complete, false if not yet.</dd>
374 </dl>
375
376 <h4>Example</h4>
377
378 <pre class="lua">
379 -- Force 0 is build with one assault.
380 AiForce(0, "unit-assault", 1)
381 ...
382 -- If the force is ready, use it to attack.
383 if (AiCheckForce(0)) then AiAttackWithForce(0) end
384 </pre>
385
386 <div class="obsolete">
387 <a name="AiDebug"></a>
388 <h3>AiDebug(flag)</h3>
389
390 <p><em>Obsolete since r5923 (2004-01-01):
391 The debug flag no longer affects the engine,
392 and scripts cannot read it.</em></p>
393
394 Enable or disable the debug output of the AI script execution.
395
396
397 <dl>
398 <dt>flag</dt>
399 <dd>If true enables printing of the AI commands, if false disables it.
400 </dd>
401 </dl>
402
403 <h4>Example</h4>
404
405 <pre class="lua">
406 -- Prints now the commands of this computer player.
407 AiDebug(true)
408 </pre>
409 </div>
410
411 <div class="obsolete">
412 <a name="AiDebugPlayer"></a>
413 <h3>AiDebugPlayer(1, 2, 3, ...)</h3>
414
415 <p><em>Obsolete since r5923 (2004-01-01):
416 The debug flag no longer affects the engine,
417 and scripts cannot read it.</em></p>
418
419 Activate dump of AI forces and strategy on stdout.<br>
420 Parameters are player number, or "self", for thisplayer.<br>
421 "none" will stop all AI debug output.
422
423 <h4>Example</h4>
424
425 <pre class="lua">
426 AiDebugPlayer("self")
427 </pre>
428 </div>
429
430 <a name="AiForce"></a>
431 <h3>AiForce(force, unit-type-1, count-1, ... ,unit-type-N, count-N)</h3>
432
433 <p>Define a force, what and how many units should belong to a force. Up to 10
434 forces are currently supported.
435 <br>
436 Force 0 is currently fixed to be the defence force. Send to a building or
437 unit under attack.
438 <br>
439 If there are any unassigned units of the requested unit-type, than they are
440 assigned to the force.
441 <br>
442 Note: The low-level didn't support the reduce of a force.
443 </p>
444
445 <dl>
446 <dt>force</dt>
447 <dd>Number of the force to which the units should belong. 0 - 9 is currently
448 supported.
449 </dd>
450 <dt>unit-type-1</dt>
451 <dt>unit-type-N</dt>
452 <dd>Unit-type that should be in the force. Currently only mobile (trained) units
453 are allowed.
454 </dd>
455 <dt>count-1</dt>
456 <dt>count-N</dt>
457 <dd>How many of this units should be in the force.
458 </dd>
459 <dt>returns</dt>
460 <dd>False.</dd>
461 </dl>
462
463 <i>The unit-types should be build in a fixed order. From left to right? or from
464 each unit-type one after the other?</i>
465
466 <h4>Example</h4>
467
468 <pre class="lua">
469 -- First the force 0 is filled up with 4 assaults and 5 bazoos, after this
470 -- force 1 is filled with 3 assaults and 2 bazoos.
471 AiForce(0, "unit-assault", 4, "unit-bazoo", 5)
472 AiForce(1, "unit-assault", 3, "unit-bazoo", 2)
473 </pre>
474
475 <div class="obsolete">
476 <a name="AiForceRole"></a>
477 <h3>AiForceRole(force, role)</h3>
478
479 <p><em>Obsolete since r5923 (2004-01-01):
480 Roles of forces no longer affect the engine,
481 and scripts cannot read them.</em></p>
482
483 Define the role of a force.
484
485
486 <dl>
487 <dt>force</dt>
488 <dd>Number of the force to which the units belong. 0 - 9 is currently
489 supported.
490 </dd>
491 <dt>role</dt>
492 <dd>The role of the force. Can be either "attack" or "defend".
493 </dd>
494 </dl>
495
496 <h4>Example</h4>
497
498 <pre class="lua">
499 -- Sets the role of force 0 to attack.
500 AiForceRole(0, "attack")
501 </pre>
502 </div>
503
504 <a name="AiNeed"></a>
505 <h3>AiNeed(unit-type)</h3>
506
507 Tells the AI that it should have a unit of this unit-type. The AI builds or
508 trains units in this order of the AiSet/AiNeed commands. If the unit or an
509 equivalent unit already exists, the AI does nothing. If the unit is lost, it is
510 automatically rebuilt. If the units are requested in wrong order, the AI could
511 hang up. Resources are collected automatic and farms are automatic build, but
512 additional could be requested.
513
514
515 <dl>
516 <dt>unit-type</dt>
517 <dd>Name of the unit-type required.
518 </dd>
519 <dt>returns</dt>
520 <dd>False.</dd>
521 </dl>
522
523 <h4>Example</h4>
524
525 <pre class="lua">
526 -- The magmapump must be build before a powerplant.
527 AiNeed("unit-magmapump")
528 AiNeed("unit-powerplant")
529 </pre>
530
531 <a name="AiPlayer"></a>
532 <h3>AiPlayer()</h3>
533
534 Return the player number of the running AI.
535 This is often used for indexing the <a href="#AiState">AiState</a> table.
536
537 <h4>Example</h4>
538
539 <pre class="lua">
540 -- If the player of the running AI has insufficient magma
541 -- then build a magmapump:
542 player = AiPlayer()
543 if (Players[player].MagmaStored &lt; 300) then
544 AiNeed("unit-magmapump")
545 end
546 </pre>
547
548 <a name="AiSet"></a>
549 <h3>AiSet(unit-type, count)</h3>
550
551 This AiNeed with a number. Tells the AI that it should have a specified number
552 of a unit of this unit-type. The AI builds or trains units in this order of
553 the AiSet/AiNeed commands. If the unit or an equivalent unit already exists,
554 the AI does nothing. If the units are lost, they are automatic rebuild. If the
555 units are requested in wrong order, the AI could hang up. Resources are
556 collected automatic and farms are automatic build, but additional could be
557 requested. In the opposite to AiNeed, which always inserts a request, AiSet
558 modifies the last request to the new number.
559
560
561 <dl>
562 <dt>unit-type</dt>
563 <dd>Name of the unit-type(s) required.
564 </dd>
565 <dt>count</dt>
566 <dd>Number of unit-types(s) required. Zero is not allowed.
567 </dd>
568 <dt>returns</dt>
569 <dd>False.</dd>
570 </dl>
571
572 <h4>Example</h4>
573
574 <pre class="lua">
575 -- Request two assault units.
576 AiSet("unit-assault", 2)
577 </pre>
578
579 <a name="AiSleep"></a>
580 <h3>AiSleep(frames)</h3>
581
582 <p>Wait some frames, to let the opponent (you) recover.</p>
583
584 <p>The first time this function is called,
585 the frames value is stored, and "true" is returned. The next times,
586 also "true" is returned, until the timeout is over:
587 then "false" is returned.</p>
588
589 <p>The frames parameter is ignored except during the first call.</p>
590
591
592 <dl>
593 <dt>frames</dt>
594 <dd>How many frames (~1/30s) the AI shouldn't proceed with the script.
595 </dd>
596 <dt>returns</dt>
597 <dd>True if we need to wait longer.</dd>
598 <dd>False if the waiting period is over.</dd>
599 </dl>
600
601 <h4>Example</h4>
602
603 <pre class="lua">
604 {
605 -- Wait 500 frames ~16s.
606 function() return AiSleep(500) end,
607 }
608 </pre>
609
610 <a name="AiWait"></a>
611 <h3>AiWait(type)</h3>
612
613 Waits until the *first* request of this unit-type is completed.
614 Don't forget to request a unit-type, before you wait on it.
615
616 <dl>
617 <dt>type</dt>
618 <dd>The unit type name string.
619 </dd>
620 <dt>returns</dt>
621 <dd>True if this unit type is not yet available.</dd>
622 <dd>False if at least one instance of this unit-type exists.</dd>
623 </dl>
624
625 <h4>Example</h4>
626
627 <pre class="lua">
628 {
629 -- Proceed only if an engineer is ready:
630 function() return AiNeed("unit-engineer") end,
631 function() return AiWait("unit-engineer") end,
632 -- Proceed only if two magmapumps are ready:
633 function() return AiSet("unit-magmapump", 2) end,
634 function() return AiWait("unit-magmapump") end,
635 }
636 </pre>
637
638 <a name="AiWaitForce"></a>
639 <h3>AiWaitForce(force)</h3>
640
641 <p>Check if a force is complete.</p>
642
643 <p>The forces are build in force number order. First 0, than 1, last 9.</p>
644
645
646 <dl>
647 <dt>force</dt>
648 <dd>Number of the force to which the units should belong. 0 - 9 is currently
649 supported.
650 </dd>
651 <dt>returns</dt>
652 <dd>False if the force is complete, true if not yet.</dd>
653 </dl>
654
655 <h4>Example</h4>
656
657 <pre class="lua">
658 -- Force 0 is build with one assault unitn. The script continues processing, if the
659 -- unit is ready trained.
660 AiForce(0, "unit-assault", 1)
661 AiWaitForce(0)
662 </pre>
663
664 <h2>Notes</h2>
665
666 The current AI script support is very limited, many new functions are needed.
667 If you want to write this you know who to contact.
668
669 <hr>
670 All trademarks and copyrights on this page are owned by their respective owners.
671 <address>(c) 2002-2010 by <a href="http://boswars.org">
672 The Bos Wars Project</a></address></body></html>