source: branches/delphi/AI/manual.html

Last change on this file was 22, checked in by chronos, 8 years ago
  • Added: Delphi AI development kit.
File size: 52.5 KB
Line 
1<html>
2<head>
3<title>The AI Development Kit</title>
4
5<style type="text/css">
6<!--
7h1 {font-size:20pt;font-family:Arial,Helvetica;color:#C00000;}
8h2 {font-size:14pt;font-family:Arial,Helvetica;color:#C00000;}
9h3 {font-size:11pt;font-family:Arial,Helvetica;font-weight:bold;color:#000000;}
10p {font-size:11pt;font-family:Arial,Helvetica;color:#000000;}
11p.question {font-size:11pt;font-family:Arial,Helvetica;font-weight:bold;color:#000000;}
12li {font-size:11pt;font-family:Arial,Helvetica;color:#000000;}
13td {font-size:11pt;font-family:Arial,Helvetica;color:#000000;vertical-align:top;}
14td.header {font-size:11pt;font-family:Arial,Helvetica;color:#000000;background-color:#CCCCCC;vertical-align:top;}
15td.turntime {font-size:11pt;font-family:Arial,Helvetica;color:#000000;background-color:#CCCCFF;vertical-align:top;}
16//-->
17</style>
18</head>
19<body bgcolor="#FFFFFF" link="#0000FF" vlink="#000080" alink="#FF0000">
20
21<h1>The AI Development Kit</h1>
22
23<p>This is the documentation of the AI development kit that comes with the
24C-evo standard package. The kit is meant to be a starting point for
25developing your own AI module for C-evo. Please, always consider that the whole
26C-evo project is
27still in the course of development, which counts for this text as well. If you
28have ideas how to improve the content or the structure of this
29document, or in case you notice any problem or have a question,
30<a href="http://c-evo.org/_sg/contact">contact me</a>!
31There's also a <a href="http://c-evo.org/aiforum/">web forum</a> for
32C-evo AI developers.
33
34<p>The programming language of this kit is Pascal. In order to work with it,
35you need a Pascal compiler capable of generating Win32-DLLs, for example:
36<ul>
37<li>FreePascal for Win32, see <a href="http://www.freepascal.org">freepascal.org</a>. The
38mandatory downloads are about 3 MB together and already sufficient to compile the code.
39<li>Borland Delphi. I tested with D4/Standard, older or newer Delphi versions
40might make minor code changes necessary. Delphi is more convenient for this use
41than FreePascal, because of the Windows-based development environment with
42integrated debugging.
43</ul>
44
45<p>Note that using this kit is not the only way to make an AI for C-evo. You can
46alternatively build an AI DLL from the scratch using your programming
47language of choice. The DLL interface
48documentation is to be found <a href="http://c-evo.org/aidev.html">here</a>.
49There is also another, completely
50different AI template (using C++) available from the
51<a href="http://c-evo.org/files">files section</a> of the project homepage.
52
53<br><br><h3>Important</h3>
54<p>Trying to program a C-evo AI makes no sense if you don't have good
55knowledge in two fields:
56<ul>
57<li>C-evo
58<li>Programming
59</ul>
60
61<br><h3>Files of the Kit</h3>
62<p><ul>
63<li><i>AIProject.dpr</i> - The project. When using a command line compiler,
64compile this file. The code is tailor-made for
65CustomAI.pas, these two files are the heart of the kit and make sense only
66together.
67<li><i>CustomAI.pas</i> - Contains the class TCustomAI, which is the base class of
68your AI. It encapsulates the server communication. You don't need to
69change this class, but you have to know its interface well. This
70interface is the main subject of this manual!
71<li><i>Protocol.pas</i> - This source file is part of any C-evo related code module,
72even of the game itself. It defines common values and data structures.
73Don't change it!
74<li><i>Switches.pas</i> - Compiler switches which ensure correct and optimized
75compilation. If you add new files to your AI, I suggest to include this file.
76<li><i>AIProject.ai.txt</i> - A template for your AI description file, see <a href="#inst">Installing Your AI</a>.
77</ul>
78
79
80<br><h3>Debug and Release Version</h3>
81
82<p>The AI can be compiled in a debug or in a release version. The debug version
83does no optimization and adds several checks. It should be used during
84development. The release version of the AI contains only what is necessary for
85playing with it, thus being smaller and faster. The release version is the one
86that you should publish.
87
88<p>In Delphi, switch
89between debug and release by the <i>Optimization</i> checkbox in the project
90settings: Optimization means release, no optimization means debug.
91In FreePascal, make the debug version by defining the symbol <i>DEBUG</i>
92(for example, by passing the command line option <i>-dDEBUG</i> to the compiler).
93Without this symbol, FreePascal compiles the release version. (Unfortunately,
94this is only theory since FreePascal doesn't seem to generate a valid DLL with
95assertions enabled, so you have to debug the AI in the release version.)
96
97
98<br><br><h3>Concepts</h3>
99
100<p>First, you have to say goodbye to something that you're used to from playing
101the game: Names. For example, you can't define or even <i>find out</i> the names of your cities.
102The same counts for the names of your unit classes, not to speak of their
103pictures. This is because the game core does not support names.
104All objects are indentified by numbers only. Names and pictures are
105generated by the user interface in its own estimation, because humans like
106playing with names and pictures more than with numbers. AI likes numbers more,
107so be happy that you're spared by the names...
108
109<p>The source code files listed above are not meant to be edited.
110You're doing the
111AI implementation by creating a new unit <i>AI.pas</i> with a new class
112<i>TAI</i> derived from
113<i>TCustomAI</i>. (The names are fixed because AIProject.dpr relies on them.)
114Your class TAI has nothing to do but to override virtual methods of the
115base class by own implementations. You can choose which methods to override.
116Even if your class doesn't implement any
117method, the compiled AI works. (But, of course, does almost nothing.)
118
119<p>Each nation has its own AI object, so inside the TCustomAI and TAI classes
120it's all about only one nation. The whole AI module is capable of controlling
121more than one nation, but this is implemented by the kit infrastructure, you
122don't have to care for it.
123
124<p>Apart from that, the code is not object oriented. Units,
125unit classes (called <i>models</i>), cities and other items are not modelled
126as Object Pascal classes. Instead, the items of the game are identified by
127numbers (always zero-based) and managed in arrays of records.
128
129
130<br><br><h2>Playground Coordinates</h2>
131
132<p>You have to deal with three types of playground coordinates: location codes,
133(a,b)-coordinates and vicinity codes. A <i>location code</i> is a unique integer code for a tile.
134For example, you can use it to find the city that is located at a certain tile,
135or to find all units which are located inside a certain city (because they have
136the same location code as the city). All location
137codes in the range 0..MapSize-1 are valid, all other location
138codes are invalid. Whenever there is a field or parameter that refers to a single
139tile resp. location in the communication with the game, it contains a location code.
140
141<p>The other coordinate types are <i>relative</i>, they always relate
142to a base tile. This base tile can be chosen freely.
143<i>(a,b)-coordinates</i> are universal relative coordinates that are capable of addressing
144any other tile in relation to the base tile. Such a coordinate is a pair of
145two components, a and b, which both
146count the distance to the base tile. The a-component
147steps south-east and the b-component south-west:
148
149<p><img src="_aidev3.gif">
150
151<p>The base tile always has the (a,b)-coordinate <i>(0,0)</i>.
152
153<p>The other relative coordinates, <i>vicinity codes</i>, can only address the vicinity
154of the base tile. Vicinity codes are small integers.
155There are two subtypes: Vicinity-21 and Vicinity-8.
156Vicinity-21 codes contain the base tile and 20 surrounding tiles, in a shape
157equal to a city exploitation radius or to an enhanced unit visibility range.
158The vicinity has 21 tiles, they have codes in the range 1..26. The base tile
159has the code 13 (= constant <i>CityOwnTile</i>). One application of Vicinity-21
160is addressing tiles inside a city's exploitation radius - the city own tile is
161the base tile then. Sometimes, the codes
162are used as indices for bit arrays. For example, if the exploited tiles
163of a city are 11000000000010 (binary), this means that the city exploits the
164tiles with the Vicinity-21 codes 1, 12 and 13:
165
166<p><img src="_aidev4.gif">
167
168<p>Vicinity-8 codes are the most limited coordinates, they
169address only the 8 adjacent tiles of the base tile. The base tile
170itself has <i>no</i> Vicinity-8 code:
171
172<p><img src="_aidev5.gif">
173
174<p>(a,b)-coordinates and vicinity-8 codes are introduced by this kit in order
175to make AI programming
176easier. You must not use them, it's up to you which coordinate types to use in
177which AI calculation. However, they can be very
178valuable for AI algorithms that consider
179geographic neighbourhood and distances. The Sample AI contains several
180applications that you can take for examples.
181
182<p>The unit <i>CustomAI</i> provides some conversion functions between the
183different coordinate types:
184
185<p><i>procedure ab_to_Loc(Loc0,a,b: integer; var Loc: integer);</i>
186<br>This function calculates the location code of the tile which has the
187passed (a,b)-coordinates
188in relation to the base tile with location code Loc0.
189If there is no such tile because the relative coordinates are beyond the
190northern resp. southern end of the world, the code returned is less than 0 resp. greater than
191MapSize-1. The calculation respects the cylindrical world (no left or right end).
192
193<p><i>procedure Loc_to_ab(Loc0,Loc: integer; var a,b: integer);</i>
194<br>This function calculates the (a,b)-coordinates of the tile with
195location code <i>Loc</i>
196in relation to the base tile with location code Loc0.
197Because of the cylindrical world, this calculation is ambiguous. The function
198always returns the absolutely smallest possible values for a and b, e.g. (-1,1)
199instead of (lx-1,-lx+1).
200
201<p><i>procedure ab_to_V8(a,b: integer; var V8: integer);</i>
202<br>Converts an (a,b)-coordinate into a Vicinity-8 code.
203
204<p><i>procedure V8_to_ab(V8: integer; var a,b: integer);</i>
205<br>Converts a Vicinity-8 code into an (a,b)-coordinate.
206
207<p><i>procedure ab_to_V21(a,b: integer; var V21: integer);</i>
208<br>Converts an (a,b)-coordinate into a Vicinity-21 code.
209
210<p><i>procedure V21_to_ab(V21: integer; var a,b: integer);</i>
211<br>Converts a Vicinity-21 code into an (a,b)-coordinate.
212
213<p><i>procedure V8_to_Loc(Loc0: integer; var VicinityLoc: TVicinity8Loc);</i>
214<br>Returns the location codes of <i>all</i> tiles adjacent to the base tile
215at Loc0. The array index in VicinityLoc is the Vicinity-8 code. Tiles beyound
216a pole are indicated by an invalid location code.
217
218<p><i>procedure V21_to_Loc(Loc0: integer; var VicinityLoc: TVicinity21Loc);</i>
219<br>Returns the location codes of <i>all</i> tiles in the 21-tile vicinity
220of the base tile at Loc0. The array index in VicinityLoc is the
221Vicinity-21 code. Array indices which are not a valid Vicinity-21 code are set
222to an invalid location code. The same counts for tiles beyound a pole.
223
224
225<p><br><h2>The Overridables</h2>
226
227<p>There are three ways of control and information flow between the game and
228your AI: <i>Overridables</i>, <i>Functions</i> and the <i>ReadOnly-block</i>,
229described within this section and the following ones.
230
231<p>A few of the methods of TCustomAI are overridable. By overriding such a
232method, you can handle a call to your AI, for example the call to make your
233turn. Each overridable has already a default implementation in TCustomAI
234that remains
235effective if you do not override it in TAI. This default implementation
236does <i>nothing</i>.
237
238<p>The overridables <i>WantNegotiation</i> and <i>DoNegotiation</i> are
239described under <a href="#dip">Diplomacy</a>. Two others,
240<i>SetDataDefaults</i> and <i>SetDataRandom</i>, will be explained in the section
241<a href="#save">Saving Data</a>. Apart from those four, the overridables are:
242
243<p><table border cellspacing=0 cellpadding=3>
244<tr><td class="header">Overridable</td><td class="header">Event</td><td class="header">To do</td></tr>
245<tr><td class="turntime">DoTurn</td><td>It's your turn.</td>
246<td>Move units, manage cities etc.</td></tr>
247<tr><td class="turntime">ChooseResearchAdvance</td><td>Research completed.</td>
248<td>Return next advance to research. Prerequisites must be researched!
249Return -1 for random choice.
250If you return <i>adMilitary</i>, you must define the model to develop within this
251overridable.</td></tr>
252<tr><td class="turntime">ChooseStealAdvance</td><td>Enemy city captured while owning the Temple of Zeus.</td>
253<td>Return advance to steal from captured city. Return -1 for random choice.</td></tr>
254<tr><td class="turntime">ChooseGovernment</td><td>Anarchy is over.</td><td>Return desired new government form.</td></tr>
255<tr><td class="turntime">OnNegoRejected_CancelTreaty</td><td>Other nation has rejected your contact request. The <i>Opponent</i> field tells which nation that was.</td><td>Return <i>true</i> if you want to cancel the treaty that you have with this nation.</td></tr>
256<tr><td>OnBeforeEnemyAttack</td><td>Enemy unit will attack you. This unit is not necessarily in your enemy unit list, because it might be covered by a stronger unit at the same tile. Get information about the unit from the UnitInfo parameter of the overridable. Additional parameters also tell the exact outcome of the battle, although it has not yet happened.
257<br>This overridable is also called when enemies bombard one of your cities or expel a commando.</td><td>Whatever you like, but don't call in-turn functions.</td></tr>
258<tr><td>OnAfterEnemyAttack</td><td>Always follows to OnBeforeEnemyAttack. Attack has been performed now, either the attacking unit or your defender is destroyed. An attacked city might be destroyed.</td><td>Whatever you like, but don't call in-turn functions.</td></tr>
259<tr><td>OnBeforeEnemyCapture</td><td>Enemy unit is going to capture one of your cities. Capturing unit is already removed from origin tile, thus not in your enemy unit list, only specified by the UnitInfo parameter of the overridable. The city is still in your city list.</td><td>Whatever you like, but don't call in-turn functions.</td></tr>
260<tr><td>OnAfterEnemyCapture</td><td>Always follows to OnBeforeEnemyCapture. Capture has been performed now, city is destroyed or in enemy city list, unit is in enemy unit list and located at city tile.</td><td>Whatever you like, but don't call in-turn functions.</td></tr>
261</table>
262
263<p>The overridables marked blue are the <i>in-turn</i> overridables, only they can call in-turn functions.
264
265
266<p><br><h2>The Functions</h2>
267
268<p>Functions are the tools to implement the play of the nation,
269call them in order to give commands like moving a unit etc.
270Functions are methods declared by the base class TCustomAI.
271
272<p>Most of the functions return a server return code as result. These return
273codes are described in the file Protocol.pas. If this code doesn't have the <i>rExecuted</i> bit set,
274it's an error code, means the function has not been executed. Common
275server return codes are:
276<br><i>eNoTurn</i> - function can not be called from this overridable
277<br><i>eInvalid</i> - you have called the function with invalid parameters
278<br><i>eViolation</i> - function can't be executed, because this operation does
279not comply with the rules of the game
280<br><i>eNotChanged</i> - function was executed, but didn't change anything
281<br>Other return codes are function-specific and listed below.
282
283<p>All available functions are described in the tables below.
284Parameters are integers except where stated different.
285Most functions can only be called from in-turn overridables. These functions are
286marked blue in the table.
287
288
289<br><br><h3>General Functions</h3>
290<p><table border cellspacing=0 cellpadding=3>
291<tr><td class="header">Function</td><td class="header">Parameters</td><td class="header">Usage</td></tr>
292
293<tr><td>IsResearched</td><td>Advance</td>
294<td>Returns whether a specific advance is already
295researched or not. The function returns <i>false</i> also for advances that are
296traded from other nations but not researched yet (tsSeen).</td></tr>
297
298<tr><td>ResearchCost</td><td>-</td><td>Returns the research points necessary to complete the current research, independent on the points that are already collected (RO.Research).</td></tr>
299
300<tr><td>ChangeAttitude</td><td>Nation<br>Attitude</td><td>Change your nation's attitude to another nation.<br>Return code: eOK</td></tr>
301
302<tr><td class="turntime">Revolution</td><td>-</td><td>Do the revolution!<br>Return code: eOK</td></tr>
303
304<tr><td class="turntime">ChangeRates</td><td>Tax<br>Lux</td><td>Change tax and luxury rate, both must be multiples of 10.<br>Return code: eOK</td></tr>
305
306<tr><td class="turntime">PrepareNewModel</td><td>Domain</td><td>Prepares military research. Pass the domain of the new model that you want to develop.
307<br>Makes only sense from overridable <i>ChooseResearchAdvance</i>!<br>Return Codes: eOK, eNoPreq</td></tr>
308
309<tr><td class="turntime">SetNewModelFeature</td><td>Feature<br>Count</td><td>Lets you specify a feature or capacity of the new model that you want to develop. PrepareNewModel must have been called before in this turn! To turn on binary features like Stealth, pass 1 as count. The result of the change, including strength and cost, can be read from RO.DevModel.
310<br>Makes only sense from overridable <i>ChooseResearchAdvance</i>!<br>Return Codes: eOK, eNoModel, eNoPreq, eDomainMismatch</td></tr>
311
312<tr><td class="turntime">AdvanceResearchable</td><td>Advance</td><td>Returns true if the specified advanced can be researched now.<br>Makes only sense from overridable <i>ChooseResearchAdvance</i>!</td></tr>
313
314<tr><td class="turntime">AdvanceStealable</td><td>Advance</td><td>Returns true if the specified advanced can be stolen now.<br>Makes only sense from overridable <i>ChooseStealAdvance</i>!</td></tr>
315</table>
316
317
318<br><br><h3>Unit Functions</h3>
319<p>Most of these functions have an integer <i>uix</i> as first parameter.
320These functions can only be applied to one of your units, not to foreign
321ones. The uix
322parameter specifies the unit which to apply the function to and is not
323explicitely listed in the table below.
324<p><table border cellspacing=0 cellpadding=3>
325<tr><td class="header">Function (Unit_...)</td><td class="header">Parameters</td><td class="header">Usage</td></tr>
326
327<tr><td>FindMyDefender</td><td>Loc<br>var uix</td><td>Determines, which of your units would defend the tile with the specified location, when attacked. The unit index is returned in uix. It's a value &lt;0 when your nation has no units at this location.</td></tr>
328
329<tr><td>FindEnemyDefender</td><td>Loc<br>var euix</td><td>Determines, which enemy unit would defend the tile with the specified location, when attacked. The enemy unit index is returned in euix. It's a value &lt;0 when there is no known enemy unit at this location.</td></tr>
330
331<tr><td class="turntime">Move</td><td>ToLoc</td><td>Move unit to another tile, as fast as possible. Be aware that the unit can die during this operation due to hostile terrain. This is indicated by the function return code having the <i>rUnitRemoved</i> flag set.
332Usually, the unit is moved to the specified tile (ToLoc). Only in the following two situations, it's moved to the most convenient adjacent tile:
333<br>- ToLoc is occupied by a unit of another nation
334<br>- an undefended foreign city is at ToLoc, but the unit is not able to capture cities
335<br>So you can also use this function in preparation of attacks, bombardments and covert operations.
336<br>If it takes more than one turn to reach the destination, the unit starts movement but will not remember the destination in the next turn. You have to call Unit_Move again in each turn, until the unit reaches the destination tile.
337The return code <i>eNoWay</i> tells that the unit can not at all move there on its own.
338<br>If formerly unknown foreign units or cities appear along the way, the function stops immediately, even if the destination is not reached yet.
339<br>Alternatively to a location code, you can pass <i>maNextCity</i> as destination, which causes the unit to move to the nearest of your cities.
340<br>Return codes (complete move done): eOK+rLocationReached, eOK+rMoreTurns, eEnemySpotted+rLocationReached, eEnemySpotted+rMoreTurns, eLoaded+rLocationReached, eLoaded+rMoreTurns
341<br>Return codes (move not or not completely done): eNoWay, eEnemySpotted, eDied, eEnemySpotted_Died, eHiddenUnit, eStealthUnit, eZOC_EnemySpotted, eNoCapturer</td></tr>
342
343<tr><td class="turntime">Attack</td><td>ToLoc</td><td>Let the unit attack an enemy unit, bombard an enemy city or expel a commando at the specified <i>adjacent</i> tile.
344<br>Return codes: eLost, eWon, eBloody, eBombarded, eExpelled, eHiddenUnit, eStealthUnit, eNoTime_Attack, eNoTime_Bombard, eNoTime_Expel, eDomainMismatch, eTreaty, eNoBombarder</td></tr>
345
346<tr><td class="turntime">DoMission</td><td>MissionType<br>ToLoc</td><td>Let special commando do covert operation in <i>adjacent</i> foreign city at ToLoc.
347<br>Return codes: eMissionDone, eNoTime_Move, eTreaty</td></tr>
348
349<tr><td class="turntime">MoveForecast</td><td>ToLoc<br>var&nbsp;RemainingMovement</td><td>Calculates the movement points the unit would have left for the current turn after moving to ToLoc. Returns false if the unit can't reach this tile within the turn.</td></tr>
350
351<tr><td class="turntime">AttackForecast</td><td>ToLoc<br>AttackMovement<br>var&nbsp;RemainingHealth</td><td>Calculates the health that the unit would have left after attacking the enemy unit at ToLoc. The movement points left for the attack must be specified, values &lt;100 reduce the attack power. If the attacker would be lost, the calculated health value is the negative remaining health of the defender.
352<br>Returning false indicates that this unit can't attack there.</td></tr>
353
354<tr><td class="turntime">DefenseForecast</td><td>euix<br>ToLoc<br>var&nbsp;RemainingHealth</td><td>Calculates the health that the defender at ToLoc would have left after an attack of the enemy unit with index <i>euix</i> in the enemy unit list. If the defender would be lost, the calculated health value is the negative remaining health of the attacker.
355<br>Returning false indicates that this unit can't attack there.</td></tr>
356
357<tr><td class="turntime">Disband</td><td>-</td><td>Disband the unit. If it's located in a city with a project it can be utilized for, utilize it.
358<br>Return codes: eUtilized, eRemoved</td></tr>
359
360<tr><td class="turntime">StartJob</td><td>NewJob</td><td>Let settlers start/change terrain improvement job. Pass <i>jNone</i> to cancel the current job only. Be aware that the unit can die during this operation due to hostile terrain. This is indicated by the function return code having the <i>rUnitRemoved</i> flag set.
361<br>Return Codes: eOK, eDied, eJobDone, eJobDone_Died, eCity, eNoPreq, eTreaty, eDeadLands, eNoCityTerrain, eNoBridgeBuilding</td></tr>
362
363<tr><td class="turntime">SetHomeHere</td><td>-</td><td>Change the home city of the unit to the city it's located in.<br>Return code: eOK</td></tr>
364
365<tr><td class="turntime">Load</td><td>-</td><td>Load the unit to a transport unit at the same tile.<br>Return codes: eOK, eNoTime_Load, eNoLoadCapacity</td></tr>
366
367<tr><td class="turntime">Unload</td><td>-</td><td>Unload the unit from its transport.<br>Return codes: eOK, eNoTime_Load, eDomainMismatch</td></tr>
368
369<tr><td class="turntime">SelectTransport</td><td>-</td><td>Prefer this transport when loading units. Voids any former call to this function.<br>Return codes: eOK</td></tr>
370
371<tr><td class="turntime">AddToCity</td><td>-</td><td>Add settlers, slaves or conscripts to the city they're located in.<br>Return codes: eOK, eMaxSize</td></tr>
372
373</table>
374
375
376<br><br><h3>City Functions</h3>
377<p>Most of these functions have an integer <i>cix</i> as first parameter.
378These functions can only be applied to one of your cities, not to foreign
379ones. The cix parameter specifies the city which to apply the function to
380and is not explicitely listed in the table below.
381<p><table border cellspacing=0 cellpadding=3>
382<tr><td class="header">Function (City_...)</td><td class="header">Parameters</td><td class="header">Usage</td></tr>
383
384<tr><td>FindMyCity</td><td>Loc<br>var cix</td><td>Find the city at the specified location. The city index is returned in cix. It's a value &lt;0 when your nation has no city at this location.</td></tr>
385
386<tr><td>FindEnemyCity</td><td>Loc<br>var ecix</td><td>Find enemy city at the specified location. The enemy city index is returned in ecix. It's a value &lt;0 when there is no known enemy city at this location.</td></tr>
387
388<tr><td>HasProject</td><td>-</td><td>Returns true whenever the city is producing something different from trade goods.</td></tr>
389
390<tr><td>CurrentImprovementProject</td><td>-</td><td>Returns the city improvement, national project or wonder that is currently in production. If the city is producing a unit or trade goods, the function returns a value &lt;0.</td></tr>
391
392<tr><td>CurrentUnitProject</td><td>-</td><td>Returns the model index of the unit that is currently in production. If the city is not producing a unit, the function returns a value &lt;0.</td></tr>
393
394<tr><td class="turntime">GetTileInfo</td><td>TileLoc<br>var TileInfo: TTileInfo</td>
395<td>Fills the fields of TileInfo with the resource production of this tile when it would be exploited by this city.<br>Return code: eOK</td></tr>
396
397<tr><td class="turntime">GetReport</td><td>var Report: TCityReport</td>
398<td>Get a detailed report of this city. (Similar to what a player sees on the city screen.) The information is returned in the fields of <i>Report</i>:
399<br><i>Working</i> - number of working citizens
400<br><i>Happy</i> - number of happy citizens, can be higher than number of working citizens if more working citizens would be happy
401<br><i>FoodRep, ProdRep, Trade</i> - total per turn collected food, material and trade points after improvement effects
402<br><i>PollRep</i> - pollution
403<br><i>Corruption, Tax, Lux, Science</i> - corruption, tax, luxury and science output of city
404<br><i>Support, Eaten</i> - production and food taken for citizens and unit support
405<br><i>Storage</i> - size of food storage
406<br><i>Deployed</i> - number of deployed units
407<br>Return code: eOK</td></tr>
408
409<tr><td class="turntime">GetHypoReport</td><td>HypoTiles<br>HypoTax<br>HypoLux<br>var Report: TCityReport</td>
410<td>Same as City_GetReport, but hypothecial: Report as if the city would exploit different
411tiles, and if tax and luxury rates were different.
412<br>Calling City_GetHypoReport(cix, MyCity[cix].Tiles, RO.TaxRate, RO.LuxRate) results in the same report as City_GetReport.</td></tr>
413
414<tr><td class="turntime">GetAreaInfo</td><td>var AreaInfo: TCityAreaInfo</td><td>Fills AreaInfo with availability information about all tiles in the exploitation radius of the city. Index in AreaInfo.Available is the Vicinity-21 code.<br>Return code: eOK</td></tr>
415
416<tr><td class="turntime">StartUnitProduction</td><td>mix</td><td>Change city's project to a unit with the specified model index.<br>Return code: eOK</td></tr>
417
418<tr><td class="turntime">StartEmigration</td><td>mix<br>AllowDisbandCity: boolean<br>AsConscripts: boolean</td><td>Same as StartUnitProduction, but additionally allows producing conscripts and/or disbanding the city.</td></tr>
419
420<tr><td class="turntime">StartImprovement</td><td>iix</td><td>Change city's project to city improvement, national project or wonder.<br>Return codes: eOK, eNoPreq, eObsolete</td></tr>
421
422<tr><td class="turntime">Improvable</td><td>iix</td><td>Returns true if this improvement, national project or wonder can be built in this city. This includes the check if this improvement already exists in this city (resp. in the world in case of a wonder).</td></tr>
423
424<tr><td class="turntime">StopProduction</td><td>-</td><td>Cancel the city's project, change the collected material to money and let the city produce trade goods instead.<br>Return code: eOK</td></tr>
425
426<tr><td class="turntime">BuyProject</td><td>-</td><td>Buy the city's project, so that it's complete the next turn.<br>Return codes: eOK, eOutOfControl</td></tr>
427
428<tr><td class="turntime">SellImprovement</td><td>iix</td><td>Sell the specified city improvement or national project.<br>Return codes: eOK, eOutOfControl, eOnlyOnce</td></tr>
429
430<tr><td class="turntime">RebuildImprovement</td><td>iix</td><td>Rebuild the specified city improvement or national project for the building currently in production.<br>Return codes: eOK, eOutOfControl, eOnlyOnce</td></tr>
431
432<tr><td class="turntime">SetTiles</td><td>NewTiles</td><td>Set tiles to exploit by a city. The parameter <i>NewTiles</i> is a bit array with the Vicinity-21 code as index. Currently unexploited tiles with 1-bits will be exploited, currently exploited tiles with 0-bits will be unexploited.
433<br>This function does not work partially. If not all tiles can be set as requested, the function does nothing and returns an error.<br>Return codes: eOK, eTileNotAvailable, eNoWorkerAvailable</td></tr>
434
435<tr><td class="turntime">OptimizeTiles</td><td>ResourceWeights</td><td>Optimize the exploitation of tiles in the city area. Food supply and unit support are ensured, if possible.
436Extra food, material, tax and science are maximized according to the parameter, which can be one of the values below "resource weights" in Protocol.pas. The optimization also works in connection with Luxury or Michelangelo's Chapel.</td></tr>
437
438</table>
439
440
441<br><br><h3>Negotiation Functions</h3>
442<p><table border cellspacing=0 cellpadding=3>
443<tr><td class="header">Function</td><td class="header">Parameters</td><td class="header">Usage</td></tr>
444<tr><td>Nego_CheckMyAction</td><td>-</td><td>Lets you check whether the currently set MyAction/MyOffer is valid. The return value does not contain the <i>rExecuted</i> flags if not.<br>Only allowed from overridable <i>DoNegotiation</i>!</td></tr>
445</table>
446
447
448<a name="debug"></a>
449<br><br><h3>Development Support Functions</h3>
450<p><table border cellspacing=0 cellpadding=3>
451<tr><td>DebugMessage</td><td>Level<br>Text: string</td><td>Display an AI debug message. Note that debug messages are turned off by default. Open the debug message popup menu with a right mouse click into the AI debug message window, choose there which message levels to display.</td></tr>
452<tr><td>SetDebugMap</td><td>var DebugMap</td><td>Set a map of debug numbers, one for each tile. In the game, you can turn the number display on using the menu. The values are directly read from the array (32 bit) passed to this function everytime the map display is updated, means you only have to call this function once.<br>Never set the debug map to a local variable, only to memory that lives as long as your AI, e.g. fields of the AI object.</td></tr>
453</table>
454
455
456<p><br><h2>The ReadOnly-Block</h2>
457
458<p>The TCustomAI class contains a field <i>RO</i>, which is a pointer to a
459complex data structure. This data structure contains a lot of information
460about your nation and its view of the world. This is an important source of
461information for you, but it is read-only! The data is managed by the game,
462so please never change it directly by writing it. This would
463mean to cheat! This counts for all structures and fields pointed directly or
464indirectly by RO, as well as for the fields <i>Map</i>, <i>MyUnit</i>,
465<i>MyCity</i> and <i>MyModel</i> of
466the AI class, which are actually nothing but shortcuts for parts of RO.
467The only exception to the read-only rule are the fields <i>Data</i>
468and <i>Status</i>, which are described under <a href="#save">Saving Data</a>.
469
470<p>The data structure which the RO pointer refers to has the type
471<i>TPlayerContext</i>, defined in the file <i>Protocol.pas</i>.
472Please see this file for the definition details of this structure and the
473structures that are pointed to from it. The fields of these structures are
474commented inside the Protocol.pas.
475
476<br><br><h3>Unit and City Lists: Beware of Gaps!</h3>
477<p>The unit and city lists (MyUnit/RO.Un, MyCity/RO.City, RO.EnemyUn,
478RO.EnemyCity) might have gaps, means non-existing objects at an array position
479between existing objects. Such non-existing objects are indicated by a
480Location &lt;0. Commands will not work for them. Furthermore, the
481items in these lists might change their position within the list
482whenever the server prepares your turn. So you can <i>not</i>
483identify cities and units of former turns by their array index! (You could
484use their ID instead.) The enemy units might even
485change their indices while the enemies are moving. However, indices never
486change while your AI is processing an overridable.
487
488
489<br><br><h3>The Map</h3>
490<p>The playground map information (AI.Map or AI.RO.Map) is represented
491as a list of 32-bit values. The value at array index x provides information
492about the tile at location x. In order to save memory, several blocks of bits
493of these 32-bit values are used for different purpose. Means,
494you can <i>not</i> use the 32-bit value of a tile directly, you always have to
495extract the bits containing the information that you need. You're doing this
496by applying an AND operation with the appropriate bit mask or single flag to the value.
497The table below shows the bit structure of the map values in detail
498and gives some examples of usage:
499
500<p><table border cellspacing=0 cellpadding=3>
501<tr><td class="header">Bits</td><td class="header">Bit mask/flag</td><td class="header">Content</td><td class="header">Example of usage: test whether tile at location...</td></tr>
502<tr><td>0..4</td><td>fTerrain</td>
503 <td>terrain type if tile is already discovered,<br>fUNKNOWN if not</td>
504 <td>...is ground tile:<br><i>if (Map[Loc] and fTerrain)>=fGrass</i></td></tr>
505<tr><td>5..6</td><td>fSpecial</td>
506 <td>1 or 2 if tile has special resource,<br>0 if not</td>
507 <td>...is a wheat tile:
508 <br><i>if ((Map[Loc] and fTerrain)=fPrairie) and ((Map[Loc] and fSpecial)=fSpecial1)</i>
509 <br>or shorter:
510 <br><i>if (Map[Loc] and (fTerrain or fSpecial))=(fPrairie or fSpecial1)</i></td></tr>
511<tr><td>7</td><td>fRiver</td><td>river</td><td>&nbsp;</td></tr>
512<tr><td>8</td><td>fRoad</td><td>road</td>
513 <td rowspan=2>...has road or railroad:<br><i>if (Map[Loc] and (fRoad or fRR))<>0</i></td></tr>
514<tr><td>9</td><td>fRR</td><td>railroad</td></tr>
515<tr><td>10</td><td>fCanal</td><td>canal</td><td>&nbsp;</td></tr>
516<tr><td>11</td><td>fPoll</td><td>pollution</td><td>&nbsp;</td></tr>
517<tr><td>12..15</td><td>fTerImp</td>
518 <td>terrain improvement code if tile has<br>Irrigation, Farm, Mine, Fort or Base,<br>tiNone if not</td>
519 <td>...has fort:<br><i>if (Map[Loc] and fTerImp)=tiFort</i></td></tr>
520<tr><td>16</td><td>fGrWall</td><td>tile is protected by great wall</td><td>&nbsp;</td></tr>
521<tr><td>17</td><td>fSpiedOut</td><td>enemy city resp. enemy unit stack has been investigated by a special commando or spy plane</td><td>&nbsp;</td></tr>
522<tr><td>18</td><td>fStealthUnit</td><td>tile is occupied by enemy stealth plane</td><td>&nbsp;</td></tr>
523<tr><td>19</td><td>fHiddenUnit</td><td>tile is occupied by enemy submarine</td><td>&nbsp;</td></tr>
524<tr><td>20</td><td>fObserved</td><td>tile information is from this turn</td><td>&nbsp;</td></tr>
525<tr><td>21</td><td>fOwned</td><td>unit/city here is own one</td>
526 <td rowspan=3>...has foreign unit:
527 <br><i>if ((Map[Loc] and fUnit)<>0) and ((Map[Loc] and fOwned)=0)</i>
528 <br>or shorter:
529 <br><i>if (Map[Loc] and (fUnit or fOwned))=fUnit</i></td></tr>
530<tr><td>22</td><td>fUnit</td><td>unit present</td></tr>
531<tr><td>23</td><td>fCity</td><td>city present</td></tr>
532<tr><td>24</td><td>fDeadLands</td><td>dead lands</td><td>&nbsp;</td></tr>
533<tr><td>25..26</td><td>fModern</td>
534 <td>fCobalt, fUranium or fMercury,<br>0 if no modern resource</td>
535 <td>...has a modern resource:<br><i>if (Map[Loc] and fModern)<>0</i></td></tr>
536<tr><td>28</td><td>fOwnZoCUnit</td><td>own ZoC unit present at this tile</td><td>&nbsp;</td></tr>
537<tr><td class="turntime">29</td><td class="turntime">fInEnemyZoC</td><td>tile is in zone of control of known unit of foreign nation that you're not allied with
538 <br>this information is only valid during your own turn</td>
539 <td>test whether at least one of two tiles is not in foreign zone of control:
540 <br><i>if ((Map[Loc1] and fEnemyControl)=0) or ((Map[Loc2] and fEnemyControl)=0)</i>
541 <br>or shorter:
542 <br><i>if (Map[Loc1] and Map [Loc2] and fEnemyControl)=0</i></td></tr>
543<tr><td class="turntime">30</td><td class="turntime">fPeace</td><td>tile belongs to territory of nation that you're in peace with but not allied
544 <br>this information is only valid during your own turn</td><td>&nbsp;</td></tr>
545</table>
546
547<p>Concerning terrain types, note that there are small differences between the
548software internal and the player view. <i>Jungle</i> and <i>Forest</i> are the same
549internally, named forest. <i>Plains</i> do not exist as terrain type, they are grassland with a
550special resource of type 1 (fSpecial1). <i>Dead Lands</i> also not exist as
551terrain type. They always have the terrain type <i>Desert</i>, also having the same
552properties as desert in every aspect, except that settlers can't work there.
553To distinguish dead land tiles from desert, these tiles have the <i>fDeadLands</i>
554flag set. The special resources of dead lands (modern resources) are specified
555by the fModern bits, while the fSpecial bits are always 0.
556
557
558<a name="dip"></a>
559<p><br><h2>Diplomacy</h2>
560
561<p>The diplomacy implementation of an AI based on this kit has two parts. One part (overridable
562<i>WantNegotiation</i>) is the decision whether to contact another nation or
563not. This overridable is called by the kit framework for each known foreign nation
564in the beginning of your turn (before DoTurn) and again in the end of your turn
565(after DoTurn). The <i>NegoTime</i> parameter tells you which case it is.
566You should return <i>true</i> if you wish to ask this nation for
567negotiation. For
568example, if you'd like to contact Enemy <i>p</i> after moving your units, return
569<i>false</i> from <i>WantNegotiation(p,BeginOfTurn)</i> but <i>true</i> from
570<i>WantNegotiation(p,EndOfTurn)</i>. The kit does not support negotiations in
571the middle of your turn. The third possible value of the NegoTime parameter,
572<i>EnemyCalled</i>, tells that the other nation is asking you for contact,
573means it's their turn, not yours. With the EnemyCalled parameter, this is not an
574in-turn overridable, otherwise it is.
575
576<p>The second part of your diplomacy implementation is the negotiation
577(overridable <i>DoNegotiation</i>). Negotiations are built around making and
578accepting offers. An offer contains
579prices which will be delivered when the offer gets accepted as well as prices
580which have to be paid in order to accept the offer. Each price is represented
581by a 32 bit code, depending on its kind:
582
583<p><table border cellspacing=0 cellpadding=3>
584<tr><td class="header">Price</td><td class="header">Code</td></tr>
585<tr><td>Your nation's state report</td><td>opCivilReport + me shl 16</td></tr>
586<tr><td>Opponent's state report</td><td>opCivilReport + Opponent shl 16</td></tr>
587<tr><td>Your nation's military report</td><td>opMilReport + me shl 16</td></tr>
588<tr><td>Opponent's military report</td><td>opMilReport + Opponent shl 16</td></tr>
589<tr><td>World map</td><td>opMap</td></tr>
590<tr><td>Next closer treaty</td><td>opTreaty + tr+1, tr = current treaty</td></tr>
591<tr><td>End current treaty</td><td>opTreaty + tr-1, tr = current treaty</td></tr>
592<tr><td>Colony Ship Parts</td><td>opShipParts + t shl 16 + n, t = part type, n = number</td></tr>
593<tr><td>Money</td><td>opMoney + v, v = value</td></tr>
594<tr><td>Tribute</td><td>opTribute + v, v = value</td></tr>
595<tr><td>Advance</td><td>opTech + ad, ad = advance</td></tr>
596<tr><td>All advances</td><td>opAllTech</td></tr>
597<tr><td>Unit design</td><td>opModel + mix, mix = model index</td></tr>
598<tr><td>All unit designs</td><td>opAllModel</td></tr>
599<tr><td>Price of choice</td><td>opChoose</td></tr>
600</table>
601
602<p>Offering to deliver things you do not have is not allowed. Also, offers containing
603more than one treaty price are not possible. But even if an offer is
604allowed, it is not necessarily useful, for example demanding a price of choice.
605Please consider that offers the opponent does not understand are wasted, because
606he will never accept them.
607
608<p>Offers are represented by data records of the type <i>TOffer</i>, containing these fields:
609<br><i>nDeliver</i> - number of prices delivered if offer is accepted
610<br><i>nCost</i> - number of prices required to pay to accept this offer
611<br><i>Price</i> - codes of the prices delivered in [0..nDeliver-1],
612codes of the prices to pay in [nDeliver..nDeliver+nCost-1]
613<br>An offer can not contain more than 12 prices in total.
614
615<p>A special kind of offers are null-offers, containing no prices. Such an offer
616means the player has no more offers to make for this negotiation. If null-offers
617of both players immediately follow one another, the negotiation ends in agreement
618(in contrast to one player breaking it).
619
620<p>DoNegotiation has no parameters, you can
621read the negotiation opponent and his last action from the fields
622<i>Opponent</i> and <i>OppoAction</i> of the AI. In case his action was an
623offer, the field <i>OppoOffer</i> is valid additionally. Your DoNegotiation
624implementation must define your next negotiation action in the field <i>MyAction</i>.
625If it's an offer, you should fill the field <i>MyOffer</i>, too. After
626DoNegotiation ended, the game will call the other nation and then, maybe, call
627DoNegotiation again, with the field OppoAction now filled
628with the other nation's response. See the Sample AI for an example of usage.
629
630<p>The negotiation actions are:
631<p><table border cellspacing=0 cellpadding=3>
632<tr><td class="header">Action</td><td class="header">Usage</td><td class="header">Valid as MyAction if OppoAction is...</td></tr>
633<tr><td>scDipStart</td><td>-</td><td>Never! This is the OppoAction, when the negotiation starts and the opponent didn't have the chance to speak yet.</td></tr>
634<tr><td>scDipOffer</td><td>Make offer. Always fill the <i>MyOffer</i> field when you set this action.</td><td>scDipStart, scDipOffer, scDipAccept, scDipNotice</td></tr>
635<tr><td>scDipAccept</td><td>Accept opponent's offer.</td><td>scDipOffer</td></tr>
636<tr><td>scDipNotice</td><td>Notice latest opponent decision.</td><td>scDipCancelTreaty, scDipBreak</td></tr>
637<tr><td>scDipCancelTreaty</td><td>Cancel current treaty with opponent.</td><td>any</td></tr>
638<tr><td>scDipBreak</td><td>Break negotiation (unagreed).</td><td>any except scDipBreak</td></tr>
639</table>
640
641
642<a name="save"></a>
643<p><br><h2>Saving Data</h2>
644
645<p>Like most other games, C-evo offers the player to break a game, save it and
646resume it later from the saved file. If your AI has information that it
647collects in order to use it in later turns, this information would normally be
648lost after breaking and reloading the game. In particular, all information
649that you store
650in local memory, e.g. in fields of the AI object, is <i>undefined</i> in the
651beginning of a turn, because the game could have been loaded from a file
652right before. You should check your AI object occasionally whether you're
653trying to transport information from turn to turn with it. If so, this will
654probably fail as soon as a game is saved and resumed. (BTW, the same rule counts
655for base classes like TCustomAI and TToolAI. Just in case you intend to modify
656them.)
657
658<p>There are only a few cases in which data exchange between subsequent
659overridables using local memory in the AI is safe:
660<ul>
661<li>between <i>OnBefore...</i> and <i>OnAfter...</i>
662<li>between subsequent <i>DoNegotiation</i> calls during negotiation with a single opponent
663<li>between in-turn overridables during a single turn
664</ul>
665
666<p>The C-evo AI interface offers two ways to make storing long-term information
667possible: <i>Status</i> fields and the <i>ReadWrite</i>-block.
668
669<br><br><h3>Status Fields</h3>
670
671<p>Status fields are easy to use. Units, cities and models of your nation have
672a field <i>Status</i>, enemy cities have it too. It's not used by the game and
673exists only for the needs of AI programming. You can simply write
674information to these fields and rely on it any number of turns later. When
675resuming a saved game,
676the game infrastructure will automatically restore the values that were
677actual in the year in which the game is loaded.
678But it's only 32 bit, so consider carefully what to do with them...
679
680<p>The status of newly appearing objects is always initialized with 0. This
681happens also when a city is captured, means when an enemy city becomes an
682own city or vice versa. The status content is lost then, it's not copied to the
683new city object in the other list. (Of course, if this is a problem for your
684AI, you can implement <i>OnBeforeEnemyCapture / OnAfterEnemyCapture</i>
685so that it's solved.)
686
687<br><br><h3>The ReadWrite-Block</h3>
688
689<p>In order to collect information that is not related to units, cities or
690models, e.g. general information about foreign nations, you should use the
691ReadWrite block. This is a freely definable collection of information that
692has to be maintained by the AI and is being restored just like the Status fields
693whenever a saved game is resumed. Define a record type for the structure of
694this block, and,
695in the initialization section of AI.pas, assign the size of this structure
696(in bytes) to <i>RWDataSize</i>. The game will allocate the memory for this
697data structure and pass the pointer to it in the <i>Data</i> field of the
698ReadOnly-block.
699
700<p>However, the ReadWrite-block is pretty small: The maximum size is 4096 Bytes.
701So you should only save there what you can't calculate from other information.
702(The limitation has to do with the size of saved C-evo books. Since the changes
703must be saved in each turn, even 4k of information can cause huge book files.)
704
705<p>There are two overridables related to the ReadWrite-block.
706
707<p><i>SetDataDefaults</i>
708<br>Initialize the ReadWrite-block here. This initialization must not depend
709on anything but the map size and the values from the ReadOnly-block.
710Particularly, you should not generate random values here, because this
711overridable is also executed
712when resuming a saved game - random values would not be generated in the same
713way as before.
714
715<p><i>SetDataRandom</i>
716<br>Well, if you <i>have</i> random values to set in the beginning of a game
717(e.g. basic orientation of behavior), do this here. This overridable is called
718after SetDataDefaults, when a new game is started. When loading games, it is
719<i>not</i> executed - the values generated here before are being restored instead.
720
721<p>The kit does not yet support updates of the ReadWrite-block. If you change
722the structure of the data, loading games that were initially played with an older
723version of your AI will cause problems.
724
725
726<p><br><h2>Cheating</h2>
727
728<p>I don't have the time for any effort to make the AI interface
729swindler proof. The game's internal memory is wide open for AI DLLs to read and
730even to write, leaving several ways to cheat. Some of
731them will lead to corrupted books, e.g. simple writing to RO data. Other
732tricks work fine, technically. For example, a nation can calculate the
733addresses of the other nation's RO blocks and read information from there, such
734as current unit positions. If you'd like to make use of these <i>monster
735security leaks</i>, I cannot
736prevent you from that, but please don't call the result a C-evo AI.
737
738
739<a name="inst"></a>
740<p><br><h2>Installing Your AI</h2>
741
742<p>There are some steps necessary in order to make the game recognize and use
743your AI. First, you should choose a name for your AI - let's take <i>MyAI</i>
744as example. Modify the file names, project
745settings or compiler command line options so that the AI DLL has the name
746<i>MyAI.dll</i> instead of <i>AIProject.dll</i>.
747
748<p>Then you need an AI description
749file, this is a small text file. The kit contains a template, the file
750<i>AIProject.ai.txt</i>. Rename it to <i>MyAI.ai.txt</i>, move it to the
751folder where the cevo.exe is located and edit it.
752An AI description file can contain the following statements, each on the
753beginning of a separate line (take care for the capitals!):
754<ul>
755<li>#NAME s - If the name of your AI is different from the file name.
756<li>#PATH s - Path of the DLL, relative to the main C-evo directory. If this line
757does not exist, the path "MyAI.dll" is expected. So you can develop the AI
758DLL in any folder. However, in case you publish
759the AI, change the PATH entry so that it expects the DLL in the main C-evo
760folder, because anything else would make it too difficult for players to
761install your AI.
762<li>#GAMEVERSION i.i.i - lowest C-evo version number that this AI works with,
763should be 1.0.0 when the AI was built with this kit. This line is a MUST.
764<li>#CREDITS s - A line telling your name or whatever you like.
765This information will be displayed on the credits screen whenever the AI is in use.
766</ul>
767
768<p>It's also possible (and appreciated) to create a picture for an AI, to represent
769it on the start screen. This picture must have a size
770of 64x64 pixels and be present as <i>MyAI.bmp</i> in the main C-evo folder.
771
772
773<p><br><h2>Publishing Your AI</h2>
774
775<p>If you'd like to make the AI public, simply upload it to the
776<a href="http://c-evo.org/files">files section</a> of the project homepage.
777But please, only do this if you invested a considerable amount of work.
778Do <i>not</i> publish the Sample AI after you changed three lines of code in
779it...
780
781
782<p><br><h2>The Sample AI</h2>
783
784<p>The kit contains a sample AI demonstrating some unit movement, city management
785and simple diplomacy. This code is made for demonstration, so in contrast to the
786kit files, it's no infrastructure for development, means it does not have a settled
787interface. Be aware of that! Of course, you can use the Sample AI as starting
788point for AI development, or you can copy parts of it to your AI. But when
789future versions of C-evo come with an improved version of the Sample
790AI, your AI does not automatically benefit from this. You only
791have the option then to merge the changes manually.
792
793<p><b>Files of the Sample AI</b>
794<p><ul><li><i>AI.pas</i> - This is the actual top-level AI code.
795It is not mainly made to make up a
796strong AI but to demonstrate the kit system and the usage of the lower level units.
797<li><i>ToolAI.pas</i> - Contains a few advanced tools for AI programming. Their usage
798is documented in the unit interface code, you don't need to understand how they
799are implemented. If you like, this gives you a ready-to-use solution for some common problems.
800<li><i>Names.pas</i> - String constants for improvements, advances etc. (for easier debugging).
801<li><i>Pile.pas</i> - A unit with a universal priority queue implementation that
802is used by the Sample AI.
803</ul>
804
805<p>The Sample AI also shows a possibility to structure AI code built with this kit:
806By making the TAI class not base directly on TCustomAI but introducing
807intermediate class layer(s).
808
809
810<p><br><h2>FAQ</h2>
811
812<p class="question">Q1. The rules of the game are not exactly specified.
813I need more information than what is written in the manual.
814<p>Answer: Sometimes an AI programmer needs very exact information about
815calculations or about the behavior of the game in special situations. This exact
816information often is
817not contained in the in-game manual, because this manual is for <i>players</i>.
818Players usually don't need and don't want that precision overkill. If you need more
819information, please ask me or go to the <a href="http://c-evo.org/aiforum/">AI forum</a>.
820(Or maybe try to analyze the sources of the game...)
821
822<br><br><p class="question">Q2. How can my AI...
823<ul>
824<li>...select a unit?
825<li>...order the unit command <i>stay here</i> or <i>recover</i>?
826<li>...recognize free citizens?
827<li>...mark models to be obsolete?
828<li>...access the macro management (city types, research focus, terrain enhancement)?
829</ul>
830<p>Answer: All of these things are not part of the actual game. The user interface
831implements these mechanisms in order to make the game better playable by human
832players. If you think something similar could be helpful in your AI, you must
833implement it. The means described in this manual are enough for that.
834
835<br><br><p class="question">Q3. How can I debug my AI?
836<p>Answer:
837<ul>
838<li>In <i>Delphi</i>, check the box "Include remote debug symbols" on the
839page "Linker" of the project options and rebuild the project. Then, set the
840cevo.exe as host application in the run parameters. Now you can run,
841set breakpoints in your AI, inspect expressions, view call stacks etc. from
842within the Delphi IDE.
843(But, for me, this only seems to work if I execute the DLL in the folder
844where the source files are located.)
845<li>In <i>FreePascal</i>, I cannot help you. Seems to me that there is no way to debug
846a Windows DLL with the available FreePascal and GNU utilities. (If you know one,
847please let me know!) I'm afraid, you'll have to use <a href="#debug">debug
848messages</a> or implement a kind of logfile for debugging.
849</ul>
850
851<p><br>
852
853</body>
854</html>
855
Note: See TracBrowser for help on using the repository browser.