Started as a fork of Aegis bot, Petra is the default AI for 0AD since alpha17.

General structure

When starting a game, the 0AD AI API creates a PetraBot object which inherits from the BaseAI. Then every game turn, PetraBot's OnUpdate() function is called. Then every n turn (presently n = 8 for performance reasons, but could be reduced in the near future), this function calls the update function of the modules constituting the AI.

The Petra AI is currently based on two main modules which are the headquarter and the queueManager.The first one is responsible for the choice of the different actions performed by the AI while the latter allocates the available resources to these choices by a system of queues with adequate priorities.

All modules must have an update() function, this gets called every n turn that the AI runs. They also have an optional init() function which is called once before the first turn of the AI, once the gameState is available. Futhermore, all the events (i.e. messages sent when an entity is destroyed, renamed, ...) received by the AI in turns where it does not update its modules are kept and concatenated so that none are lost.

Headquarter

The headquarter module is divided in several sub-modules as attackManager, baseManager, ... which are described below. It is responsible for the development of the civilization (building structures and training units) and the steering of its different sub-modules.

AttackManager

The attackManager deals with the different attacks. It is mainly a steering function, the real code which handles the training, the preparation and the actual attack is in attackPlan.js. In practise, the attackManager decides on the kind of attack (rush with small number of units, standard attack with medium-size army or attack with a huge army) by creating an attack plan. Then each attack plan defines its target player and the enemy entity which is its primary target. Then it creates build orders (to train the needed units) using three queues (soldiers, champion and siege units). The attack plan may require a transport to attack overseas. Once the primary target is destroyed, the attack plan choose a new target (from the same target player) which is accessible by land. This continues until either the AI army is destroyed or no new target is found, in which case the army is disbanded.

BaseManager

Each new cc is the root of a new base, which is governed by its own baseManager. This manager handles workers assigned to that base (for gathering, hunting, fishing, ...) through the file worker.js. It is also responsible for checking base's resources levels, building new dropsites if necessary, repairing its hurt structures.

DefenseManager

The defenseManager is responsible for the response to attacks (either directed towards the AI itself or towards its allies). It also deals with unit garrisoning (either garrisoning ranged units inside a "fighting" structures or garrisoning hurt units inside healing structures).

GarrisonManager

It keeps track of all units garrisoned except those garrisoned in ships for transport.

NavalManager

The navalManager is in charge of maintaining the fleet (except trader ships which are dealt with in tradeManager) and managing the transport of units (done in transportPlan.js).

ResearchManager

It looks for new tech available and decides on which one to research.

TradeManager

The tradeManager deals with barter and trade. It is responsible for finding the best available trade route (either on land or water), training traders and switching trade route when a better one is available. (the version in A17 was rudimentary, a more complete is ready and will be commited after the release).

QueueManager

The queueManager has several individual queues under its control, which each have a priority (dynamically adjustable). Plans (queueplan-building.js, queueplan-research.js and queueplan-training.js, all deriving from queueplan--.js) are created when necessary by the modules and are added to a suitable queue. The plans persist and are never destroyed until they are executed.

The queueManager controls resource allocation so it is proportional to priority. It attempts it do this fairly while not locking other queues, e.g. if building an outpost (stone + wood) and there is not enough stone, the queue manager may make a lower priority house with the surplus wood. Note that this only happens between queues, the next item in a queue will block everything following it. For this reason it is generally best to have lots of separate queues.

Note: This is the only code that ever trains or builds things. If the word is used within other modules then it means adding to to queue system in order to be trained or built.

Accessibility

Variability of AI strategy

In order to vary the strategy of the AI, several personality traits are used in the form of numbers between 0 and 1. Those already implemented include:

• aggressive: the higher this number, the more rushes in early game
• cooperative: the higher this number, the more helpful the AI will be when an allied is attacked. It is foreseen to make this number dynamic, increasing it (very slowly) with the tributes received.
• defensive: the higher this number, the more prone to build defensive structure (ready, but to be committed after A17 is released)

Presently, these numbers are randomly chosen during the bot initialisation.

Help for debugging

Debug printouts can be set by modifying the value of this.debug in public/simulation/ai/petra/config.js. Different levels of printouts are possible:

• 0 = no printout, should be the default for releases.
• 1 = sanity checks intended to check the proper behaviour of the AI (for example when developping a new feature or mod).
• 2 = debug printouts for the main AI's decisions and detailed lists of resources and queues at regular time intervals.
• 3 = much detailed printouts.