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

Public Types
enum	GSConfigFlags { CONFIG_NONE, CONFIG_BOOLEAN, CONFIG_INGAME, CONFIG_DEVELOPER }
	Miscellaneous flags for GS settings. More...

Public Member Functions
string	GetAuthor ()
	Gets the author name to be shown in the 'Available GSs' window. More...

string	GetName ()
	Gets the GSs name. More...

string	GetShortName ()
	Gets a 4 ASCII character short name of the GS to uniquely identify it from other GSs. More...

string	GetDescription ()
	Gets the description to be shown in the 'Available GSs' window. More...

int	GetVersion ()
	Gets the version of the GS. More...

int	MinVersionToLoad ()
	Gets the lowest version of the GS that OpenTTD can still load the savegame of. More...

string	GetDate ()
	Gets the development/release date of the GS. More...

bool	IsDeveloperOnly ()
	Can a non-developer select GS for a new game. More...

string	CreateInstance ()
	Gets the name of main class of the GS so OpenTTD knows what class to instantiate. More...

string	GetAPIVersion ()
	Gets the API version this GS is written for. More...

string	GetURL ()
	Gets the URL to be shown in the 'this GS has crashed' message and in the 'Available GSs' window. More...

void	GetSettings ()
	Gets the settings that OpenTTD shows in the "GS Parameters" window so the user can customize the GS. More...

void	AddSetting (table setting_description)
	Add a user configurable setting for this GS. 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 GSs use to register themselves.

Note: This class is not part of the API. It is purely to document what GSs must or can implemented to provide information to OpenTTD to base configuring/starting/loading the GS on.; The required functions are also needed for GS Libraries, but in that case you extend GSLibrary. 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

◆ GSConfigFlags

enum GSInfo::GSConfigFlags

Miscellaneous flags for GS settings.

Enumerator
CONFIG_NONE	Normal setting.
CONFIG_BOOLEAN	This value is a boolean (either 0 (false) or 1 (true) ).
CONFIG_INGAME	This setting can be changed while the GS is running.
CONFIG_DEVELOPER	This setting will only be visible when the GS development tools are active.

Member Function Documentation

◆ AddLabels()

void GSInfo::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, the second character could be '_' to indicate the value is negative, 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"}); Another example, for a setting with a negative value: AddLabels("amount", {__1 = "less than one", _0 = "none", _1 = "more than one"});

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

◆ AddSetting()

void GSInfo::AddSetting ( table setting_description )

Add a user configurable setting for this GS.

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 GSs. 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. The value will be clamped in the range [MIN(int32_t), MAX(int32_t)] (inclusive).
max_value The maximum value of this setting. Required for integer settings and not allowed for boolean settings. The value will be clamped in the range [MIN(int32_t), MAX(int32_t)] (inclusive).
default_value The default value. Required. The value will be clamped in the range [MIN(int32_t), MAX(int32_t)] (inclusive).
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 GSConfigFlags. Required.

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

◆ CreateInstance()

string GSInfo::CreateInstance ( )

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

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

Returns: The class name of the GS.

Note: This function is required.

◆ GetAPIVersion()

string GSInfo::GetAPIVersion ( )

Gets the API version this GS 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 GS 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 GS is compatible with.

◆ GetAuthor()

string GSInfo::GetAuthor ( )

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

Returns: The author name of the GS.

Note: This function is required.

◆ GetDate()

string GSInfo::GetDate ( )

Gets the development/release date of the GS.

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

Returns: The development/release date for the GS.

Note: This function is required.

◆ GetDescription()

string GSInfo::GetDescription ( )

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

Returns: The description for the GS.

Note: This function is required.

◆ GetName()

string GSInfo::GetName ( )

Gets the GSs name.

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

Returns: The name of the GS.

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

◆ GetSettings()

void GSInfo::GetSettings ( )

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

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 GSInfo::GetShortName ( )

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

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 GS.

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

Returns: The name of the GS.

Note: This function is required.

◆ GetURL()

string GSInfo::GetURL ( )

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

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

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

Returns: The URL to show.

Note: This function is optional.

◆ GetVersion()

int GSInfo::GetVersion ( )

Gets the version of the GS.

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

When OpenTTD finds, during starting, a duplicate GS 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 GS.

Note: This function is required.

◆ IsDeveloperOnly()

bool GSInfo::IsDeveloperOnly ( )

Can a non-developer select GS for a new game.

The idea behind this function is to 'forbid' using your script with a new game if you for example specifically wrote it for a certain scenario.

Returns: True if the GS can be selected from the GUI as non-developer.

Note: This function is optional. Default is false.

◆ MinVersionToLoad()

int GSInfo::MinVersionToLoad ( )

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

In other words, from which version until this version can the GS 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.

Public Types

Public Member Functions