Class: API3.BaseAI

[No frames]

new BaseAI(settings)

Base class for computer players.

In 0AD, each computer player ("bot") is implemented as a set of JavaScript files, located within a separate directory below /binaries/data/mods/public/simulation/ai. A file named data.json controls loading the AI script code: 
{
 "name": "Tutorial AI",
 "description": "The Tutorial AI should only be used on the \"Introductory Tutorial\" scenario.",
 "constructor": "TutorialAI",
 "moduleName" : "TutorialAI",
 "hidden": true,
 "useShared": true
}
In this file, the "moduleName" has to refer to a JavaScript namespace which holds an object constructor as named in the "constructor" property of the JSON file.This object is constructed when the AI enters a game. Usually, this constructor is a derivative of the BaseAI class (it is possible to operate without the BaseAI, but cumbersome as the engine data decoding had to be done by the implementor). The BaseAI class does not perform any action on its own during a game, but provides the infrastructure to communicate with the Pyrogenesis engine in a more friendly way.
Parameters:
settings : Object The game settings as passed by the GameSetup code.
Source:
Member summary
player :Number Numeric player index of this AI instance.
turn :Number Turn counter.
Method summary
chat(message) Sends a message to all players in the current game.
chatEnemies(message) Sends a message to all enemies of the current player.
chatTeam(message) Sends a message to all player allied with the current player.
CustomInit() Allows for initialization of the AI.
Deserialize(data, sharedScript) Restores the AI to a previous state.
HandleMessage(state, sharedAI) Handles the game engine update messages.
OnUpdate() Hook for derived classes to perform periodic updates.
Serialize() → {Object} Converts the AI runtime data into a simple structure.

Members

player :Number

Numeric player index of this AI instance.

Type:
  • Number
Source:

turn :Number

Turn counter.

For AIs, it is advisable to not run through all of its computations at each game turn to limit CPU usage. A common method is to run the AI only at each n-th turn, where n is the number of players in the game. To distribute CPU load evenly, usually player 1 will operate when the turn counter is 1 (modulo number of players), player 2 when turn counter is 2 (modulo...), and so on.
Type:
  • Number
Source:

Methods

chat(message)

Sends a message to all players in the current game.

Parameters:
message : String The chat message to send.
Source:
Returns:
undefined

chatEnemies(message)

Sends a message to all enemies of the current player.

Parameters:
message : String The chat message to send.
Source:
Returns:
undefined

chatTeam(message)

Sends a message to all player allied with the current player.

Parameters:
message : String The chat message to send.
Source:
Returns:
undefined

CustomInit()

Allows for initialization of the AI.

During the constructor run of an AI, dynamic game data such as the territory and passability maps are not yet available. When initializations require such values, they may be done during the CustomInit step.
Source:
Returns:
undefined

Deserialize(data, sharedScript)

Restores the AI to a previous state.

This function shall be overridden by derived classes to allow saving and loading of games. See the description of Serialize on how to use these functions. The function will be called right after the object constructor when a game is loaded.
Parameters:
data : Object An object returned by a previous serialization of the AI.
sharedScript : API3.SharedScript The new shared component to use.
Source:
Returns:
undefined

HandleMessage(state, sharedAI)

Handles the game engine update messages.

The game simulation is computed in "turns", where in each turn, the engine passes the differences to the previous turn to the AI players. At the very first turn, a complete description of the whole game is handed to the AIs.
Parameters:
state : Object The delta values of the current game state to the previous state.
sharedAI : API3.SharedScript The shared data container to be used by the AI.
Source:
To Do:
  • Describe the intention of the playerID parameter.

OnUpdate()

Hook for derived classes to perform periodic updates.

This function is run once each game turn, after all of the delta values sent by the game engine have been applied to the representation seen by the AI (see HandleMessage for a description on the update cycle). For simpler AIs, overriding this function is the preferred method of running periodic tasks. Advanced AIs might override HandleMessage to analyze the engine messages directly for performance optimizations.
Source:
Returns:
undefined

Serialize() → {Object}

Converts the AI runtime data into a simple structure.

For saving and restoring of games, the whole game state is serialized, i.e. stored in a permanent format. To allow continuation of the AI after a save/restore cycle, an AI player has to return an object here which allows to restore it to it's exact same state using the Deserialize function. This function shall be overridden by derived classes.
Source:
Returns:
An arbitrary but simple object (JSON-compatible) which describes the current internal state of the AI. As this object has to be stored in a file, no complex elements (like classes, functions or closures) shall be used.
Type
Object