OpenTTD AI API: AIInfo Class Reference

OpenTTD AI API 12.0

Public Types | Public Member Functions
AIInfo Class Reference

'Abstract' class of the AIs use to register themselves. More...

## Public Types
enum | AIConfigFlags { CONFIG_NONE, CONFIG_RANDOM, CONFIG_BOOLEAN, CONFIG_INGAME, CONFIG_DEVELOPER }
| Miscellaneous flags for AI settings. More...

## Public Member Functions
string | GetAuthor ()
| Gets the author name to be shown in the 'Available AIs' window. More...
string | GetName ()
| Gets the AIs name. More...
string | GetShortName ()
| Gets a 4 ASCII character short name of the AI to uniquely identify it from other AIs. More...
string | GetDescription ()
| Gets the description to be shown in the 'Available AIs' window. More...
int | GetVersion ()
| Gets the version of the AI. More...
int | MinVersionToLoad ()
| Gets the lowest version of the AI that OpenTTD can still load the savegame of. More...
string | GetDate ()
| Gets the development/release date of the AI. More...
bool | UseAsRandomAI ()
| Can this AI be used as random AI? More...
string | CreateInstance ()
| Gets the name of main class of the AI so OpenTTD knows what class to instantiate. More...
string | GetAPIVersion ()
| Gets the API version this AI is written for. More...
string | GetURL ()
| Gets the URL to be shown in the 'this AI has crashed' message and in the 'Available AIs' window. More...
void | GetSettings ()
| Gets the settings that OpenTTD shows in the "AI Parameters" window so the user can customize the AI. More...
void | AddSetting (table setting_description)
| Add a user configurable setting for this AI. More...
void | AddLabels (const char *setting_name, table value_names)
| Add labels for the values of a setting. More...

## Detailed Description

'Abstract' class of the AIs use to register themselves.

Note
  This class is not part of the API. It is purely to document what AIs must or can implemented to provide information to OpenTTD to base configuring/starting/loading the AI on.
  The required functions are also needed for AI Libraries, but in that case you extend AILibrary. As such the information here can be used for libraries, but the information will not be shown in the GUI except for error/debug messages.

## Member Enumeration Documentation

## ◆ AIConfigFlags

enum AIInfo::AIConfigFlags

Miscellaneous flags for AI settings.

Enumerator
CONFIG_NONE | Normal setting.
CONFIG_RANDOM | When randomizing the AI, pick any value between min_value and max_value (inclusive).
CONFIG_BOOLEAN | This value is a boolean (either 0 (false) or 1 (true) ).
CONFIG_INGAME | This setting can be changed while the AI is running.
CONFIG_DEVELOPER | This setting will only be visible when the AI development tools are active.

## Member Function Documentation

## ◆ AddLabels()

void AIInfo::AddLabels | ( | const char * | setting_name,
|  | table | value_names
| ) |  |

Add labels for the values of a setting.

Instead of a number the user will see the corresponding name.

Parameters

  setting_name | The name of the setting.
  value_names | A table that maps values to names. The first character of every identifier is ignored and the rest should be an integer of the value you define a name for. The value is a short description of that value. To define labels for a setting named "competition_level" you could for example call it like this: AddLabels("competition_level", {_0 = "no competition", _1 = "some competition", _2 = "a lot of competition"});

Note
  This is a function provided by OpenTTD, you don't have to include it in your AI but should just call it from GetSettings.

## ◆ AddSetting()

void AIInfo::AddSetting | ( | table | setting_description | ) |

Add a user configurable setting for this AI.

You can call this as many times as you have settings.

Parameters

  setting_description | A table with all information about a single setting. The table should have the following name/value pairs: name The name of the setting, this is used in openttd.cfg to store the current configuration of AIs. Required. description A single line describing the setting. Required. min_value The minimum value of this setting. Required for integer settings and not allowed for boolean settings. max_value The maximum value of this setting. Required for integer settings and not allowed for boolean settings. easy_value The default value if the easy difficulty level is selected. Required. medium_value The default value if the medium difficulty level is selected. Required. hard_value The default value if the hard difficulty level is selected. Required. custom_value The default value if the custom difficulty level is selected. Required. random_deviation If this property has a nonzero value, then the actual value of the setting in game will be randomized in the range [user_configured_value - random_deviation, user_configured_value + random_deviation] (inclusive). Not allowed if the CONFIG_RANDOM flag is set, otherwise optional. step_size The increase/decrease of the value every time the user clicks one of the up/down arrow buttons. Optional, default is 1. flags Bitmask of some flags, see AIConfigFlags. Required.

Note
  This is a function provided by OpenTTD, you don't have to include it in your AI but should just call it from GetSettings.

## ◆ CreateInstance()

string AIInfo::CreateInstance | ( |  | ) |

Gets the name of main class of the AI so OpenTTD knows what class to instantiate.

For libraries, this name is also used when other scripts import it using AIController::Import.

Returns
  The class name of the AI.

Note
  This function is required.

## ◆ GetAPIVersion()

string AIInfo::GetAPIVersion | ( |  | ) |

Gets the API version this AI is written for.

If this function does not exist API compatibility with version 0.7 is assumed. If the function returns something OpenTTD does not understand, for example a newer version or a string that is not a version, the AI will not be loaded.

Although in the future we might need to make a separate compatibility 'wrapper' for a specific version of OpenTTD, for example '0.7.1', we will use only the major and minor number and not the bugfix number as valid return for this function.

Valid return values are:

- "0.7" (for AI only)
- "1.0" (for AI only)
- "1.1" (for AI only)
- "1.2" (for both AI and GS)
- "1.3" (for both AI and GS)

Returns
  The version this AI is compatible with.

## ◆ GetAuthor()

string AIInfo::GetAuthor | ( |  | ) |

Gets the author name to be shown in the 'Available AIs' window.

Returns
  The author name of the AI.

Note
  This function is required.

## ◆ GetDate()

string AIInfo::GetDate | ( |  | ) |

Gets the development/release date of the AI.

The intention of this is to give the user an idea how old the AI is and whether there might be a newer version.

Returns
  The development/release date for the AI.

Note
  This function is required.

## ◆ GetDescription()

string AIInfo::GetDescription | ( |  | ) |

Gets the description to be shown in the 'Available AIs' window.

Returns
  The description for the AI.

Note
  This function is required.

## ◆ GetName()

string AIInfo::GetName | ( |  | ) |

Gets the AIs name.

This is shown in the 'Available AIs' window and at all other places where the AI is mentioned, like the debug window or OpenTTD's help message. The name is used to uniquely identify an AI within OpenTTD and this name is used in savegames and the configuration file.

Returns
  The name of the AI.

Note
  This function is required.
  This name is not used as library name by AIController::Import, instead the name returned by CreateInstance is used.

## ◆ GetSettings()

void AIInfo::GetSettings | ( |  | ) |

Gets the settings that OpenTTD shows in the "AI Parameters" window so the user can customize the AI.

This is a special function that doesn't need to return anything. Instead you can call AddSetting and AddLabels here.

Note
  This function is optional.

## ◆ GetShortName()

string AIInfo::GetShortName | ( |  | ) |

Gets a 4 ASCII character short name of the AI to uniquely identify it from other AIs.

The short name is primarily used as unique identifier for the content system. The content system uses besides the short name also the MD5 checksum of all the source files to uniquely identify a specific version of the AI.

The short name must consist of precisely four ASCII characters, or more precisely four non-zero bytes.

Returns
  The name of the AI.

Note
  This function is required.

## ◆ GetURL()

string AIInfo::GetURL | ( |  | ) |

Gets the URL to be shown in the 'this AI has crashed' message and in the 'Available AIs' window.

If this function does not exist no URL will be shown.

This function purely exists to redirect users of the AI to the right place on the internet to discuss the AI and report bugs of this AI.

Returns
  The URL to show.

Note
  This function is optional.

## ◆ GetVersion()

int AIInfo::GetVersion | ( |  | ) |

Gets the version of the AI.

This is a number to (in theory) uniquely identify the versions of an AI. Generally the 'instance' of an AI with the highest version is chosen to be loaded.

When OpenTTD finds, during starting, a duplicate AI with the same version number one is randomly chosen. So it is important that this number is regularly updated/incremented.

Returns
  The version number of the AI.

Note
  This function is required.

## ◆ MinVersionToLoad()

int AIInfo::MinVersionToLoad | ( |  | ) |

Gets the lowest version of the AI that OpenTTD can still load the savegame of.

In other words, from which version until this version can the AI load the savegames.

If this function does not exist OpenTTD assumes it can only load savegames of this version. As such it will not upgrade to this version upon load.

Returns
  The lowest version number we load the savegame data.

Note
  This function is optional.

## ◆ UseAsRandomAI()

bool AIInfo::UseAsRandomAI | ( |  | ) |

Can this AI be used as random AI?

The idea behind this function is to 'forbid' highly competitive or other special AIs from running in games unless the user explicitly selects the AI to be loaded. This to try to prevent users from complaining that the AI is too aggressive or does not build profitable routes.

If this function does not exist OpenTTD assumes the AI can be used as random AI. As such it will be randomly chosen.

Returns
  True if the AI can be used as random AI.

Note
  This function is optional.