Wesnoth AI

From The Battle for Wesnoth Wiki
Revision as of 18:21, 19 July 2020 by Mattsc (talk | contribs) (AIs Available to Scenario and Map Designers: updated with current status in 1.15.3+dev)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Introduction to the Wesnoth AIs

Wesnoth provides an artificial intelligence (AI) which is active by default for all computer-controlled sides, as well as several optional AIs. These AIs are highly configurable and can be included and/or customized by scenario and map creators using simple WML code. For AI developers, it is also possible to replace parts or all of the default AI with custom code.

This page provides a brief summary of the available AIs and of the methods, tools and resources available for using and modifying them. Links are provided to detailed documentation on each of the topics. For reference, we also provide a brief timeline describing some of the main development milestones of the Wesnoth AIs.

Available AIs

This section briefly lists the different AIs available in Wesnoth. Click on the links provided here and in the resources section below for detailed descriptions of the AIs and for instructions for using and customizing them.

AIs Available to Scenario and Map Designers

Wesnoth comes with several built-in AIs from which scenario and map designers can choose:

  • Default (RCA) AI: If no special instructions are given, this AI is used automatically for all computer-controlled sides with no setup needed. It can be customized in many different ways.
  • The Experimental AI adds additional features to the RCA AI. (Version 1.15.3 and later only) Several of the actions of the Experimental AI have been merged into the default AI.
  • Micro AIs add specialized behavior to Wesnoth that cannot be achieved with the default AI. There is a large number of available Micro AIs and they can be set up using just a few lines of simple WML code.
  • Custom AIs: In addition to these AIs, Wesnoth provides a large variety of options for writing your own AI code.

AIs Available in the Multiplayer Setup Menu

Several AIs are available to be chosen for computer players in the multiplayer setup menu:

  • Default AI (RCA): This is the same AI as listed above.
  • Experimental_AI: Again, the same AI as described above.
  • Debug Mode Dev AIs: If Wesnoth is in debug mode, several additional AIs are available in the menu. For the most part, these are not meant as complete stand-alone AIs, or as AIs that are significantly different from the default AI, but rather as examples that can be used for development purposes. (Version 1.13.5 and later only) The list of AIs has been cleaned up. Only working and (somewhat) meaningful AIs remain.
  • Custom AIs: Just as it is possible to include custom AIs in the scenario code, they can also be provided for selection from the MP setup menu. These can be written either for specific scenarios/maps or so that they are available for all maps.

Available AI Tools

The default AI is written in C++ and therefore difficult to modify directly. However, it is a composite AI assembled from individual components which can be customized and modified in both WML and Lua. Documentation on the available AI tools can be found at:


  • Wesnoth has its own internal language called 'Formula' which can also be used for AI development. It is, however, not maintained any more and has by now been surpassed by Lua in ease of use in most cases. We therefore do not recommend using it any more, but links to the legacy documentation are still provided in the resources section below.
  • A Python API for AI development also existed for a while. It was removed for security reasons.

List of Wesnoth AI Resources

AI Resources for Scenario and Map Creators

  • RCA AI: Description of Wesnoth's default AI, with the following additional documentation:
  • Experimental AI: Experimental augmented version of the default AI with additional features
  • Micro AIs: Additional specialized AI behavior that cannot be achieved with the default AI

Resources for AI Coders

Legacy Resources for AI Coders

Miscellaneous Other Resources

The following resources are not generally needed for understanding, using and modifying Wesnoth AIs, but they might nevertheless contain some useful bits of information for the interested reader.

Finally, the link to the AI Category at the bottom of this page includes links to all the remaining AI-related pages.

A Very Brief History of Wesnoth AIs

While the general principle of the Wesnoth AI has been relatively stable throughout its development, the AI implementation has seen dramatic changes. That said, basic scenario creator tasks such as modifying AI parameters in WML are usually not changed much in order to keep backward compatibility. On the other hand, the steps needed to write, for example, custom candidate actions and bind them into the existing AI framework have definitely evolved significantly from Wesnoth 1.8 to 1.10 to 1.12.

It is not possible to capture all these changes on the Wesnoth AI wiki pages due to the complexity of the topic. They generally only refer to the latest stable release series and the current development release series. If, for some reason, you need to do AI work with an earlier version of Wesnoth, we still provide some of the legacy documentation, but you might also have to check out the history of the wiki pages. Another way to go about it is by checking out examples of how things are done in mainline or add-ons of the respective release series. In general, however, we strongly recommend using the latest Wesnoth versions, as modifying AI behavior has become a lot simpler than it used to be.

For reference, here is a list of some of the major milestones of the AI development:

  • Up to Wesnoth 1.6:
    • The default AI of Wesnoth is, in fact, called Default AI, with id=default_ai in the configuration.
  • Wesnoth 1.1/1.2:
    • A Python API for AI development is introduced. This was later removed for security reasons.
  • Wesnoth 1.5/1.6:
  • Wesnoth 1.7/1.8:
  • Wesnoth 1.11/1.12:
    • Introduction of the Micro AIs
    • External Lua candidate actions become fully usable. They are now the recommended method for creating custom AIs
  • Wesnoth 1.15/1.16:
This page was last edited on 19 July 2020, at 18:21.