Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | Private Attributes

ScriptInfo Class Reference

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

#include <script_info_docs.hpp>

Inheritance diagram for ScriptInfo:
SimpleCountedObject AIInfo AILibrary

Public Types

enum  ScriptConfigFlags {
  CONFIG_NONE, CONFIG_RANDOM, CONFIG_BOOLEAN, CONFIG_INGAME,
  CONFIG_DEVELOPER
}
 

Miscellaneous flags for Script settings.

More...

Public Member Functions

string GetAuthor ()
 Gets the author name to be shown in the 'Available Scripts' window.
string GetName ()
 Gets the Scripts name.
string GetShortName ()
 Gets a 4 ASCII character short name of the Script to uniquely identify it from other Scripts.
string GetDescription ()
 Gets the description to be shown in the 'Available Scripts' window.
int GetVersion ()
 Gets the version of the Script.
int MinVersionToLoad ()
 Gets the lowest version of the Script that OpenTTD can still load the savegame of.
string GetDate ()
 Gets the development/release date of the Script.
bool UseAsRandomAI ()
 Can this Script be used as random Script?
string CreateInstance ()
 Gets the name of main class of the Script so OpenTTD knows what class to instantiate.
string GetAPIVersion ()
 Gets the API version this Script is written for.
string GetURL ()
 Gets the URL to be shown in the 'this Script has crashed' message and in the 'Available Scripts' window.
void GetSettings ()
 Gets the settings that OpenTTD shows in the "Script Parameters" window so the user can customize the Script.
void AddSetting (table setting_description)
 Add a user configurable setting for this Script.
void AddLabels (const char *setting_name, table value_names)
 Add labels for the values of a setting.
const char * GetAuthor () const
 Get the Author of the script.
const char * GetName () const
 Get the Name of the script.
const char * GetShortName () const
 Get the 4 character long short name of the script.
const char * GetDescription () const
 Get the description of the script.
int GetVersion () const
 Get the version of the script.
const char * GetDate () const
 Get the last-modified date of the script.
const char * GetInstanceName () const
 Get the name of the instance of the script to create.
const char * GetURL () const
 Get the website for this script.
const char * GetMainScript () const
 Get the filename of the main.nut script.
const char * GetTarFile () const
 Get the filename of the tar the script is in.
bool CheckMethod (const char *name) const
 Check if a given method exists.
virtual class ScriptScannerGetScanner ()
 Get the scanner which has found this ScriptInfo.
bool GetSettings ()
 Get the settings of the Script.
const ScriptConfigItemListGetConfigList () const
 Get the config list for this Script.
const ScriptConfigItemGetConfigItem (const char *name) const
 Get the description of a certain Script config option.
SQInteger AddSetting (HSQUIRRELVM vm)
 Set a setting.
SQInteger AddLabels (HSQUIRRELVM vm)
 Add labels for a setting.
int GetSettingDefaultValue (const char *name) const
 Get the default value for a setting.

Static Public Member Functions

static SQInteger Constructor (HSQUIRRELVM vm, ScriptInfo *info)
 Process the creation of a FileInfo object.

Protected Attributes

class Squirrelengine
 Engine used to register for Squirrel.
HSQOBJECT * SQ_instance
 The Squirrel instance created for this info.
ScriptConfigItemList config_list
 List of settings from this Script.

Private Attributes

char * main_script
 The full path of the script.
char * tar_file
 If, which tar file the script was in.
const char * author
 Author of the script.
const char * name
 Full name of the script.
const char * short_name
 Short name (4 chars) which uniquely identifies the script.
const char * description
 Small description of the script.
const char * date
 The date the script was written at.
const char * instance_name
 Name of the main class in the script.
int version
 Version of the script.
const char * url
 URL of the script.
class ScriptScannerscanner
 ScriptScanner object that was used to scan this script info.

Detailed Description

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

All static information from an Script like name, version, etc.

Note:
This class is not part of the API. It is purely to document what Scripts must or can implemented to provide information to OpenTTD to base configuring/starting/loading the Script on.
The required functions are also needed for Script Libraries. 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.

ai

Definition at line 27 of file script_info_docs.hpp.


Member Enumeration Documentation

Miscellaneous flags for Script settings.

Enumerator:
CONFIG_NONE 

Normal setting.

CONFIG_RANDOM 

When randomizing the Script, pick any value between min_value and max_value.

CONFIG_BOOLEAN 

This value is a boolean (either 0 (false) or 1 (true) ).

CONFIG_INGAME 

This setting can be changed while the Script is running.

CONFIG_DEVELOPER 

This setting will only be visible when the Script development tools are active.

Definition at line 189 of file script_info_docs.hpp.


Member Function Documentation

void ScriptInfo::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 the 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 Script but should just call it from GetSettings.

Referenced by AIInfo::RegisterAPI().

void ScriptInfo::AddSetting ( table  setting_description  ) 

Add a user configurable setting for this Script.

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 Scripts. 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 user_configured_value + random(-random_deviation, random_deviation). 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 ScriptConfigFlags. Required.
Note:
This is a function provided by OpenTTD, you don't have to include it in your Script but should just call it from GetSettings.

Referenced by AIInfo::RegisterAPI().

string ScriptInfo::CreateInstance (  ) 

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

Returns:
The class name of the Script.
Note:
This function is required.
string ScriptInfo::GetAPIVersion (  ) 

Gets the API version this Script is written for.

If this function does not exist API compatability 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 Script will not be loaded.

Although in the future we might need to make a separate compatability '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"
  • "1.0"
  • "1.1"
  • "1.2"
Returns:
The version this Script is compatible with.
Note:
This function is optional.
string ScriptInfo::GetAuthor (  ) 

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

Returns:
The author name of the Script.
Note:
This function is required.

Referenced by AIListWindow::DrawWidget().

string ScriptInfo::GetDate (  ) 

Gets the development/release date of the Script.

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

Returns:
The development/release date for the Script.
Note:
This function is required.
string ScriptInfo::GetDescription (  ) 

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

Returns:
The description for the Script.
Note:
This function is required.

Referenced by AIListWindow::DrawWidget(), and ScriptScanner::GetConsoleList().

string ScriptInfo::GetName (  ) 

Gets the Scripts name.

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

Returns:
The name of the Script.
Note:
This function is required.

Referenced by AIInfo::Constructor(), AIScannerInfo::FindInfo(), ScriptScanner::GetConsoleList(), AIScannerInfo::GetScriptName(), CrashLog::LogConfiguration(), MakePNGImage(), ScriptScanner::RegisterScript(), and AI::StartNew().

bool ScriptInfo::GetSettings (  ) 

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

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.

Definition at line 110 of file script_info.cpp.

References Squirrel::CallMethod(), engine, MAX_GET_SETTING_OPS, and SQ_instance.

Referenced by Constructor().

string ScriptInfo::GetShortName (  ) 

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

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

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

Returns:
The name of the Script.
Note:
This function is required.

Referenced by IsSameScript(), and ScriptScanner::RegisterScript().

string ScriptInfo::GetURL (  ) 

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

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

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

Returns:
The URL to show.
Note:
This function is optional.

Referenced by AIInstance::Died(), and AIListWindow::DrawWidget().

int ScriptInfo::GetVersion (  ) 

Gets the version of the Script.

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

When OpenTTD finds, during starting, a duplicate Script 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 Script.
Note:
This function is required.

Referenced by AIInfo::CanLoadFromVersion(), ScriptConfig::Change(), AIInfo::Constructor(), AIListWindow::DrawWidget(), AIScannerInfo::FindInfo(), ScriptScanner::GetConsoleList(), CrashLog::LogConfiguration(), MakePNGImage(), and ScriptScanner::RegisterScript().

int ScriptInfo::MinVersionToLoad (  ) 

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

In other words, from which version until this version can the Script 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.
bool ScriptInfo::UseAsRandomAI (  ) 

Can this Script be used as random Script?

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

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

Returns:
True if the Script can be used as random Script.
Note:
This function is optional.

-game


The documentation for this class was generated from the following files: