src/script/api/script_info_docs.hpp

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /** @file script_info_docs.hpp Description of the functions an Script can/must provide in ScriptInfo. */
   9
  10 /* This file exists purely for doxygen purposes. */
  11
  12 /**
  13  * 'Abstract' class of the Scripts use to register themselves.
  14  *
  15  * @note This class is not part of the API. It is purely to document what
  16  *       Scripts must or can implemented to provide information to OpenTTD to
  17  *       base configuring/starting/loading the Script on.
  18  *
  19  * @note The required functions are also needed for Script Libraries, but in
  20  *       that case you extend ScriptLibrary. As such the information here can
  21  *       be used for libraries, but the information will not be shown in the
  22  *       GUI except for error/debug messages.
  23  *
  24  * @api ai game
  25  */
  26 class ScriptInfo {
  27 public:
  28         /**
  29          * Gets the author name to be shown in the 'Available Scripts' window.
  30          *
  31          * @return The author name of the Script.
  32          * @note This function is required.
  33          */
  34         string GetAuthor();
  35
  36         /**
  37          * Gets the Scripts name. This is shown in the 'Available Scripts' window
  38          * and at all other places where the Script is mentioned, like the debug
  39          * window or OpenTTD's help message. The name is used to uniquely
  40          * identify an Script within OpenTTD and this name is used in savegames
  41          * and the configuration file.
  42          *
  43          * @return The name of the Script.
  44          * @note This function is required.
  45          * @note This name is not used as library name by ScriptController::Import,
  46          * instead the name returned by #CreateInstance is used.
  47          */
  48         string GetName();
  49
  50         /**
  51          * Gets a 4 ASCII character short name of the Script to uniquely
  52          * identify it from other Scripts. The short name is primarily
  53          * used as unique identifier for the content system.
  54          * The content system uses besides the short name also the
  55          * MD5 checksum of all the source files to uniquely identify
  56          * a specific version of the Script.
  57          *
  58          * The short name must consist of precisely four ASCII
  59          * characters, or more precisely four non-zero bytes.
  60          *
  61          * @return The name of the Script.
  62          * @note This function is required.
  63          */
  64         string GetShortName();
  65
  66         /**
  67          * Gets the description to be shown in the 'Available Scripts' window.
  68          *
  69          * @return The description for the Script.
  70          * @note This function is required.
  71          */
  72         string GetDescription();
  73
  74         /**
  75          * Gets the version of the Script. This is a number to (in theory)
  76          * uniquely identify the versions of an Script. Generally the
  77          * 'instance' of an Script with the highest version is chosen to
  78          * be loaded.
  79          *
  80          * When OpenTTD finds, during starting, a duplicate Script with the
  81          * same version number one is randomly chosen. So it is
  82          * important that this number is regularly updated/incremented.
  83          *
  84          * @return The version number of the Script.
  85          * @note This function is required.
  86          */
  87         int GetVersion();
  88
  89         /**
  90          * Gets the lowest version of the Script that OpenTTD can still load
  91          * the savegame of. In other words, from which version until this
  92          * version can the Script load the savegames.
  93          *
  94          * If this function does not exist OpenTTD assumes it can only
  95          * load savegames of this version. As such it will not upgrade
  96          * to this version upon load.
  97          *
  98          * @return The lowest version number we load the savegame data.
  99          * @note This function is optional.
 100          */
 101         int MinVersionToLoad();
 102
 103         /**
 104          * Gets the development/release date of the Script.
 105          *
 106          * The intention of this is to give the user an idea how old the
 107          * Script is and whether there might be a newer version.
 108          *
 109          * @return The development/release date for the Script.
 110          * @note This function is required.
 111          */
 112         string GetDate();
 113
 114         /**
 115          * Can this Script be used as random Script?
 116          *
 117          * The idea behind this function is to 'forbid' highly
 118          * competitive or other special Scripts from running in games unless
 119          * the user explicitly selects the Script to be loaded. This to
 120          * try to prevent users from complaining that the Script is too
 121          * aggressive or does not build profitable routes.
 122          *
 123          * If this function does not exist OpenTTD assumes the Script can
 124          * be used as random Script. As such it will be randomly chosen.
 125          *
 126          * @return True if the Script can be used as random Script.
 127          * @note This function is optional.
 128          *
 129          * @api -game
 130          */
 131         bool UseAsRandomAI();
 132
 133         /**
 134          * Can a non-developer select Script for a new game.
 135          *
 136          * The idea behind this function is to 'forbid' using your script with a new
 137          *  game if you for example specifically wrote it for a certain scenario.
 138          *
 139          * @return True if the Script can be selected from the GUI as non-developer.
 140          * @note This function is optional. Default is false.
 141          *
 142          * @api -ai
 143          */
 144         bool IsDeveloperOnly();
 145
 146         /**
 147          * Gets the name of main class of the Script so OpenTTD knows
 148          * what class to instantiate. For libraries, this name is also
 149          * used when other scripts import it using ScriptController::Import.
 150          *
 151          * @return The class name of the Script.
 152          * @note This function is required.
 153          */
 154         string CreateInstance();
 155
 156         /**
 157          * Gets the API version this Script is written for. If this function
 158          * does not exist API compatibility with version 0.7 is assumed.
 159          * If the function returns something OpenTTD does not understand,
 160          * for example a newer version or a string that is not a version,
 161          * the Script will not be loaded.
 162          *
 163          * Although in the future we might need to make a separate
 164          * compatibility 'wrapper' for a specific version of OpenTTD, for
 165          * example '0.7.1', we will use only the major and minor number
 166          * and not the bugfix number as valid return for this function.
 167          *
 168          * Valid return values are:
 169          * - "0.7" (for AI only)
 170          * - "1.0" (for AI only)
 171          * - "1.1" (for AI only)
 172          * - "1.2" (for both AI and GS)
 173          * - "1.3" (for both AI and GS)
 174          *
 175          * @return The version this Script is compatible with.
 176          */
 177         string GetAPIVersion();
 178
 179         /**
 180          * Gets the URL to be shown in the 'this Script has crashed' message
 181          * and in the 'Available Scripts' window. If this function does not
 182          * exist no URL will be shown.
 183          *
 184          * This function purely exists to redirect users of the Script to the
 185          * right place on the internet to discuss the Script and report bugs
 186          * of this Script.
 187          *
 188          * @return The URL to show.
 189          * @note This function is optional.
 190          */
 191         string GetURL();
 192
 193         /**
 194          * Gets the settings that OpenTTD shows in the "Script Parameters" window
 195          * so the user can customize the Script. This is a special function that
 196          * doesn't need to return anything. Instead you can call AddSetting
 197          * and AddLabels here.
 198          *
 199          * @note This function is optional.
 200          */
 201         void GetSettings();
 202
 203         /** Miscellaneous flags for Script settings. */
 204         enum ScriptConfigFlags {
 205                 CONFIG_NONE,      ///< Normal setting.
 206                 CONFIG_BOOLEAN,   ///< This value is a boolean (either 0 (false) or 1 (true) ).
 207                 CONFIG_INGAME,    ///< This setting can be changed while the Script is running.
 208                 CONFIG_DEVELOPER, ///< This setting will only be visible when the Script development tools are active.
 209         };
 210
 211         /**
 212          * Add a user configurable setting for this Script. You can call this
 213          * as many times as you have settings.
 214          * @param setting_description A table with all information about a
 215          *  single setting. The table should have the following name/value pairs:
 216          *  - name The name of the setting, this is used in openttd.cfg to
 217          *    store the current configuration of Scripts. Required.
 218          *  - description A single line describing the setting. Required.
 219          *  - min_value The minimum value of this setting. Required for integer
 220          *    settings and not allowed for boolean settings. The value will be
 221          *    clamped in the range [MIN(int32_t), MAX(int32_t)] (inclusive).
 222          *  - max_value The maximum value of this setting. Required for integer
 223          *    settings and not allowed for boolean settings. The value will be
 224          *    clamped in the range [MIN(int32_t), MAX(int32_t)] (inclusive).
 225          *  - default_value The default value. Required. The value will be
 226          *    clamped in the range [MIN(int32_t), MAX(int32_t)] (inclusive).
 227          *  - step_size The increase/decrease of the value every time the user
 228          *    clicks one of the up/down arrow buttons. Optional, default is 1.
 229          *  - flags Bitmask of some flags, see ScriptConfigFlags. Required.
 230          *
 231          * @note This is a function provided by OpenTTD, you don't have to
 232          * include it in your Script but should just call it from GetSettings.
 233          */
 234         void AddSetting(table setting_description);
 235
 236         /**
 237          * Add labels for the values of a setting. Instead of a number the
 238          *  user will see the corresponding name.
 239          * @param setting_name The name of the setting.
 240          * @param value_names A table that maps values to names. The first
 241          *   character of every identifier is ignored, the second character
 242          *   could be '_' to indicate the value is negative, and the rest should
 243          *   be an integer of the value you define a name for. The value
 244          *   is a short description of that value.
 245          * To define labels for a setting named "competition_level" you could
 246          * for example call it like this:
 247          * AddLabels("competition_level", {_0 = "no competition", _1 = "some competition",
 248          * _2 = "a lot of competition"});
 249          * Another example, for a setting with a negative value:
 250          * AddLabels("amount", {__1 = "less than one", _0 = "none", _1 = "more than one"});
 251          *
 252          * @note This is a function provided by OpenTTD, you don't have to
 253          * include it in your Script but should just call it from GetSettings.
 254          */
 255         void AddLabels(string setting_name, table value_names);
 256 };