Changes between Version 2 and Version 3 of AIEngineAPI

Timestamp:

Jul 19, 2012, 12:20:25 AM (12 years ago)

Author:

Jonathan Waller

Comment:

Added some information about entities

AIEngineAPI

@@ -3 +3 @@
 > Note by lexa: here is [http://code.google.com/p/split-bot/source/browse/#svn%2Ftrunk%2Fsrc%2Forg%2Fzeroad%2Fcommon_api a fully typed description of the javascript classes]
 
+The Engine uses the AIInterface and AIProxy components to provide this data.  The AIInterface is a player level component which handles communication with the AI.  AIProxy is an entity level component which creates a proxy representation of each entity to be given to the AI.
+
 The AI's `HandleMessage` method is called with one argument:
 
-{{{
+{{{#!js
 state = {
   entities: ...,
@@ -11 +13 @@
   players: [...],
   timeElapsed: ..., // seconds since the start of the match
-  map: ...,
+  territoryMap: ..., // map of player territories
+  passabilityMap: ..., // Map showing where obstructions are
   passabilityClasses: ...
-};
 }}}
 == `entities` ==
-TODO
+Each entity has a set of dynamic properties which are kept up to date.  The AI can also access the template data for all entities.
+
+An entity will have the form
+
+{{{#!js
+var ret = {
+  "id": 172, // This id is unique and permanent
+  "template": "unit/hele_spearman",
+  "position": [102.2, 34.7], // The unit position is undefined in some cases (e.g. garrisoned)
+  "hitpoints": 80,
+  "owner": 4, // Player who owns this unit
+  "idle": true, 
+  "unitAIState": "UNIT/INDIVIDUAL/GATHERING",
+  "unitAIOrderData": cmpUnitAI.GetOrderData(),
+  "trainingQueue": [{
+                      "id": 7,
+                      "unitTemplate": "spearman", // If this is a unit being trained
+                      "technologyTemplate": "phase_city", // If this is a technology being researched
+                      "count": 5, // number of units being trained
+                      "progress": 0.78, // Proportion of training completed (range 0.0 to 1.0)
+                      "metadata": {"role": "worker"}, // The AI can set metadata when adding a unit to the queue
+                    }, ... ], // Array of items currently in the training queue
+  "foundationProgress": 78, // Percentage complete for construction
+  "resourceSupplyAmount": 195, // Current resources in a resource deposit (tree, mine, ...)
+  "resourceCarrying": [{
+                         "type": "wood", // Resource type
+                         "amount": 8, // Amount currently being carried
+                         "max": 20 // Maximum amout of this resource which can be carried
+                       }, ... ], // array of resources being carried by a gathering unit
+  "garrisoned": [167, 377, 345] // array of entity id's for the garrisoned entities
+}
+}}}
 
 == `events` ==
 TODO
 
-== `map` and `passabilityClasses` ==
-{{{
-state.map = {
+== `passabilityMap` and `passabilityClasses` ==
+{{{#!js
+state.passabilityMap = {
   width: 256,
   height: 256,
@@ -29 +62 @@
 };
 }}}
-{{{
+{{{#!js
 state.passabilityClasses = {
   "pathfinderObstruction": 1,
@@ -37 +70 @@
 };
 }}}
-`state.map.data` encodes all the passability data of each terrain tile. `state.passabilityClasses` gives bitmasks that define how to interpret `state.map.data`. For example:
+`state.passabilityMap.data` encodes all the passability data of each terrain tile. `state.passabilityClasses` gives bitmasks that define how to interpret `state.map.data`. For example:
 
-{{{
+{{{#!js
 // Get the bitmask for tiles that will obstruct foundations (i.e. you can't place any buildings there)
 var obstructionMask = gameState.getPassabilityClassMask("foundationObstruction");
@@ -50 +83 @@
 Since these are bitmasks, you can 'or' them together:
 
-{{{
+{{{#!js
 var obstructionMask = gameState.getPassabilityClassMask("foundationObstruction");