OpenTTD GameScript API: GSController Class Reference

OpenTTD GameScript API 15.0-beta2

Public Member Functions | Static Public Member Functions
GSController Class Reference

The Controller, the class each GS should extend. More...

`#include <script_controller.hpp>`

## Public Member Functions
void | Start ()
| This function is called to start your script.
table | Save ()
| Save the state of the script.
void | Load (int version, table data)
| Load saved data just before calling Start.

## Static Public Member Functions
static int | GetTick ()
| Find at which tick your script currently is.
static int | GetOpsTillSuspend ()
| Get the number of operations the script may still execute this tick.
static int | GetSetting (string name)
| Get the value of one of your settings you set via info.nut.
static int | GetVersion ()
| Get the OpenTTD version of this executable.
static void | SetCommandDelay (int ticks)
| Change the minimum amount of time the script should be put in suspend mode when you execute a command.
static void | Sleep (int ticks)
| Sleep for X ticks.
static void | Break (string message)
| Break execution of the script when script developer tools are active.
static void | Print (bool error_msg, string message)
| When Squirrel triggers a print, this function is called.
static object | Import (string library, string class_name, int version)
| Import a library.

## Detailed Description

The Controller, the class each GS should extend.

It creates the GS, makes sure the logic kicks in correctly, and that GetTick() has a valid value.

When starting a new game, or when loading a game, OpenTTD tries to match a script that matches to the specified version as close as possible. It tries (from first to last, stopping as soon as the attempt succeeds)

- load the latest version of the same script that supports loading data from the saved version (the version of saved data must be equal or greater than GSInfo::MinVersionToLoad),
- load the latest version of the same script (ignoring version requirements),
- (for AIs) load a random AI, and finally
- (for AIs) load the dummy AI.

After determining the script to use, starting it is done as follows

- An instance is constructed of the class derived from GSController (class name is retrieved from GSInfo::CreateInstance).
- If there is script data available in the loaded game and if the data is loadable according to GSInfo::MinVersionToLoad, Load is called with the data from the loaded game.
- Finally, Start is called to start execution of the script.

See also https://wiki.openttd.org/en/Development/GS/Save%20and%20Load for more details.

## Member Function Documentation

## ◆ Break()

static void GSController::Break | ( | string | message | ) |
| static

Break execution of the script when script developer tools are active.

For other users, nothing will happen when you call this function. To resume the script, you have to click on the continue button in the AI debug window. It is not recommended to leave calls to this function in scripts that you publish or upload to bananas.

Parameters

  message | to print in the AI debug window when the break occurs.

Note
  gui.ai_developer_tools setting must be enabled or the break is ignored.

## ◆ GetOpsTillSuspend()

static int GSController::GetOpsTillSuspend | ( |  | ) |
| static

Get the number of operations the script may still execute this tick.

Returns
  The amount of operations left to execute.

Note
  This number can go negative when certain uninteruptable operations are executed. The amount of operations that you go over the limit will be deducted from the next tick you would be allowed to run.

## ◆ GetSetting()

static int GSController::GetSetting | ( | string | name | ) |
| static

Get the value of one of your settings you set via info.nut.

Parameters

  name | The name of the setting.

Returns
  the value for the setting, or -1 if the setting is not known.

## ◆ GetTick()

static int GSController::GetTick | ( |  | ) |
| static

Find at which tick your script currently is.

Returns
  returns the current tick.

## ◆ GetVersion()

static int GSController::GetVersion | ( |  | ) |
| static

Get the OpenTTD version of this executable.

The version is formatted with the bits having the following meaning: 24-31 major version + 16. 20-23 minor version. 19 1 if it is a release, 0 if it is not. 0-18 revision number; 0 when the revision is unknown. You have to subtract 16 from the major version to get the correct value.

Prior to OpenTTD 12, the bits have the following meaning: 28-31 major version. 24-27 minor version. 20-23 build. 19 1 if it is a release, 0 if it is not. 0-18 revision number; 0 when the revision is unknown.

Returns
  The version in newgrf format.

## ◆ Import()

static object GSController::Import | ( | string | library,
|  | string | class_name,
|  | int | version
| ) |  |
| static

Import a library.

Parameters

  library | The name of the library to import. The name should be composed as GSInfo::GetCategory() + "." + GSInfo::CreateInstance().
  class_name | Under which name you want it to be available (or "" if you just want the returning object).
  version | Which version you want specifically.

Returns
  The loaded library object. If class_name is set, it is also available (under the scope of the import) under that name.

Note
  This command can be called from the global space, and does not need an instance.

## ◆ Load()

void GSController::Load | ( | int | version,
|  | table | data
| ) |  |

Load saved data just before calling Start.

The function is only called when there is data to load.

Parameters

  version | Version number of the script that created the data.
  data | Data that was saved (return value of Save).

## ◆ Print()

static void GSController::Print | ( | bool | error_msg,
|  | string | message
| ) |  |
| static

When Squirrel triggers a print, this function is called.

Squirrel calls this when 'print' is used, or when the script made an error.

Parameters

  error_msg | If true, it is a Squirrel error message.
  message | The message Squirrel logged.

Note
  Use GSLog.Info/Warning/Error instead of 'print'.

## ◆ Save()

table GSController::Save | ( |  | ) |

Save the state of the script.

By implementing this function, you can store some data inside the savegame. The function should return a table with the information you want to store. You can only store:

- integers,
- strings,
- arrays (max. 25 levels deep),
- tables (max. 25 levels deep),
- booleans, and
- nulls.

In particular, instances of classes can't be saved with the exception of GSList.

The function is called as soon as the user saves the game, independently of other activities of the script. The script is not notified of the call. To avoid race-conditions between Save and the other script code, change variables directly after a Sleep, it is very unlikely, to get interrupted at that point in the execution. See also https://wiki.openttd.org/en/Development/GS/Save%20and%20Load for more details.

Note
  No other information is saved than the table returned by Save. For example all pending events are lost as soon as the game is loaded.

Returns
  Data of the script that should be stored in the save game.

## ◆ SetCommandDelay()

static void GSController::SetCommandDelay | ( | int | ticks | ) |
| static

Change the minimum amount of time the script should be put in suspend mode when you execute a command.

Normally in SP this is 1, and in MP it is what ever delay the server has been programmed to delay commands (normally between 1 and 5). To give a more 'real' effect to your script, you can control that number here.

Parameters

  ticks | The minimum amount of ticks to wait.

Precondition
  Ticks should be positive. Too big values will influence performance of the script.

Note
  If the number is lower than the MP setting, the MP setting wins.

## ◆ Sleep()

static void GSController::Sleep | ( | int | ticks | ) |
| static

Sleep for X ticks.

The code continues after this line when the X script ticks are passed. Mind that an script tick is different from in-game ticks and differ per script speed.

Parameters

  ticks | the ticks to wait

Precondition
  ticks > 0.

Postcondition
  the value of GetTick() will be changed exactly 'ticks' in value after calling this.

## ◆ Start()

void GSController::Start | ( |  | ) |

This function is called to start your script.

Your script starts here. If you return from this function, your script dies, so make sure that doesn't happen.

Note
  Cannot be called from within your script.