| 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 < 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> |