Modifying AI Components

This page is currently under construction (Feb 2016)

The AI and its parameters are usually set up at the beginning of a scenario and often left unchanged for the entire scenario. Sometimes it is, however, desirable to modify parts or all of the AI mid-scenario. For this purpose, Wesnoth provides the [modify_ai] tag and a large number of helper macros.

[modify_ai] Tag Overview

The [modify_ai] tag provides a method to modfiy stages, candidate actions, ascpects and goals of the active AI on the fly at any time during a scenario. Since all this functionality is packed into a single tag, its syntax is a bit more complex than that of other tags, but it is well worth spending a little time trying to understand how it works. If you do not want to bother with that, Wesnoth also provides a large variety of helper macros. These are described further below on this page.

Note that the [modify_ai] tag can be used both in [event] tags and in [side][ai] tags.

[modify_ai] Tag Syntax

The [modify_ai] tag has the following keys:

side: The side of the AI to be modified if used in an event. Not needed if used in [side][ai].
- More generally, a StandardSideFilter can be used.
action (string): The action to take concerning the component. The following values are allowed:
- add: Add a component.
- change: Change an existing component.
- delete: Delete an existing component.
- try_delete: Delete a component if it exists. This does not produce a warning if [modify_ai] fails to change the AI.
path (string): Defines the component of the AI to be modified. More on this below.
value (key or tag): Defines the new value(s) of the component. See below for details

Possible values for [modify_ai]path

Depending on the AI component one wants to modify, the path key can take on different values:

aspect[aspect_id].facet[facet_id]
goal[goal_id]
stage[stage_id]
stage[CA_avaluation_loop_stage_id].candidate_action[CA_id]

Notes on the different ids:

aspect_id: name of the aspect, such as aggression
CA_avaluation_loop_stage_id: usually this will be main_loop, although it is in principle possible to assign a different id to this stage
CA_id: takes on the value described here
facet_id, goal_id and stage_id: these can take on a variety of different formats:
- When adding one of these components, these ids are meaningless. In fact, they do not define the actual ids and can therefore simply be left empty. Instead, the ids are either assigned automatically or can be defined in the value key/tag of [modify_ai]. More on that below.
- By contrast, when deleting or changing a component, these ids need to be given. The following values are possible:
  - A string identifying the id used when defining the component
  - An integer, starting at 0, defining the number of the aspect in the order in which they were set up
  - *: All components of this type

Possible values for [modify_ai]value

This depends on the type of component and needs to be in the same format as these are added to the AI configuration. A summary of these is given here. The syntax can also be seen using the in-game gamestate inspector dialog, by typing ':inspect' in debug mode and selecting 'ai config full'.

[Todo: not sure yet whether to add examples for all component types here, or simply to go with the examples below.]

If all this seemed a bit theoretical, don't worry. We provide many examples how to do this in practice below.