src/script/api/script_controller.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_controller.hpp The controller of the script. */
   9
  10 #ifndef SCRIPT_CONTROLLER_HPP
  11 #define SCRIPT_CONTROLLER_HPP
  12
  13 #include "script_types.hpp"
  14
  15 /**
  16  * The Controller, the class each Script should extend. It creates the Script,
  17  *  makes sure the logic kicks in correctly, and that #GetTick() has a valid
  18  *  value.
  19  *
  20  * When starting a new game, or when loading a game, OpenTTD tries to match a
  21  *  script that matches to the specified version as close as possible. It tries
  22  *  (from first to last, stopping as soon as the attempt succeeds)
  23  *
  24  *  - load the latest version of the same script that supports loading data from
  25  *    the saved version (the version of saved data must be equal or greater
  26  *    than ScriptInfo::MinVersionToLoad),
  27  *  - load the latest version of the same script (ignoring version requirements),
  28  *  - (for AIs) load a random AI, and finally
  29  *  - (for AIs) load the dummy AI.
  30  *
  31  * After determining the script to use, starting it is done as follows
  32  *
  33  * - An instance is constructed of the class derived from ScriptController
  34  *   (class name is retrieved from ScriptInfo::CreateInstance).
  35  * - If there is script data available in the loaded game and if the data is
  36  *   loadable according to ScriptInfo::MinVersionToLoad, #Load is called with the
  37  *   data from the loaded game.
  38  * - Finally, #Start is called to start execution of the script.
  39  *
  40  * See also https://wiki.openttd.org/en/Development/Script/Save%20and%20Load for more details.
  41  *
  42  * @api ai game
  43  */
  44 class ScriptController {
  45         friend class AIScanner;
  46         friend class ScriptInstance;
  47
  48 public:
  49 #ifndef DOXYGEN_API
  50         /**
  51          * Initializer of the ScriptController.
  52          * @param company The company this Script is normally serving.
  53          */
  54         ScriptController(CompanyID company);
  55
  56 #else
  57         /**
  58          * This function is called to start your script. Your script starts here. If you
  59          *   return from this function, your script dies, so make sure that doesn't
  60          *   happen.
  61          * @note Cannot be called from within your script.
  62          */
  63         void Start();
  64
  65         /**
  66          * Save the state of the script.
  67          *
  68          * By implementing this function, you can store some data inside the savegame.
  69          *   The function should return a table with the information you want to store.
  70          *   You can only store:
  71          *
  72          *   - integers,
  73          *   - strings,
  74          *   - arrays (max. 25 levels deep),
  75          *   - tables (max. 25 levels deep),
  76          *   - booleans, and
  77          *   - nulls.
  78          *
  79          * In particular, instances of classes can't be saved including
  80          *   ScriptList. Such a list should be converted to an array or table on
  81          *   save and converted back on load.
  82          *
  83          * The function is called as soon as the user saves the game,
  84          *   independently of other activities of the script. The script is not
  85          *   notified of the call. To avoid race-conditions between #Save and the
  86          *   other script code, change variables directly after a #Sleep, it is
  87          *   very unlikely, to get interrupted at that point in the execution.
  88          * See also https://wiki.openttd.org/en/Development/Script/Save%20and%20Load for more details.
  89          *
  90          * @note No other information is saved than the table returned by #Save.
  91          *   For example all pending events are lost as soon as the game is loaded.
  92          *
  93          * @return Data of the script that should be stored in the save game.
  94          */
  95         table Save();
  96
  97         /**
  98          * Load saved data just before calling #Start.
  99          * The function is only called when there is data to load.
 100          * @param version Version number of the script that created the \a data.
 101          * @param data Data that was saved (return value of #Save).
 102          */
 103         void Load(int version, table data);
 104 #endif /* DOXYGEN_API */
 105
 106         /**
 107          * Find at which tick your script currently is.
 108          * @return returns the current tick.
 109          */
 110         static uint GetTick();
 111
 112         /**
 113          * Get the number of operations the script may still execute this tick.
 114          * @return The amount of operations left to execute.
 115          * @note This number can go negative when certain uninteruptable
 116          *   operations are executed. The amount of operations that you go
 117          *   over the limit will be deducted from the next tick you would
 118          *   be allowed to run.
 119          */
 120         static int GetOpsTillSuspend();
 121
 122         /**
 123          * Get the value of one of your settings you set via info.nut.
 124          * @param name The name of the setting.
 125          * @return the value for the setting, or -1 if the setting is not known.
 126          */
 127         static int GetSetting(const std::string &name);
 128
 129         /**
 130          * Get the OpenTTD version of this executable. The version is formatted
 131          * with the bits having the following meaning:
 132          * 24-31 major version + 16.
 133          * 20-23 minor version.
 134          *    19 1 if it is a release, 0 if it is not.
 135          *  0-18 revision number; 0 when the revision is unknown.
 136          * You have to subtract 16 from the major version to get the correct
 137          * value.
 138          *
 139          * Prior to OpenTTD 12, the bits have the following meaning:
 140          * 28-31 major version.
 141          * 24-27 minor version.
 142          * 20-23 build.
 143          *    19 1 if it is a release, 0 if it is not.
 144          *  0-18 revision number; 0 when the revision is unknown.
 145          *
 146          * @return The version in newgrf format.
 147          */
 148         static uint GetVersion();
 149
 150         /**
 151          * Change the minimum amount of time the script should be put in suspend mode
 152          *   when you execute a command. Normally in SP this is 1, and in MP it is
 153          *   what ever delay the server has been programmed to delay commands
 154          *   (normally between 1 and 5). To give a more 'real' effect to your script,
 155          *   you can control that number here.
 156          * @param ticks The minimum amount of ticks to wait.
 157          * @pre Ticks should be positive. Too big values will influence performance of the script.
 158          * @note If the number is lower than the MP setting, the MP setting wins.
 159          */
 160         static void SetCommandDelay(int ticks);
 161
 162         /**
 163          * Sleep for X ticks. The code continues after this line when the X script ticks
 164          *   are passed. Mind that an script tick is different from in-game ticks and
 165          *   differ per script speed.
 166          * @param ticks the ticks to wait
 167          * @pre ticks > 0.
 168          * @post the value of GetTick() will be changed exactly 'ticks' in value after
 169          *   calling this.
 170          */
 171         static void Sleep(int ticks);
 172
 173         /**
 174          * Break execution of the script when script developer tools are active. For
 175          * other users, nothing will happen when you call this function. To resume
 176          * the script, you have to click on the continue button in the AI debug
 177          * window. It is not recommended to leave calls to this function in scripts
 178          * that you publish or upload to bananas.
 179          * @param message to print in the AI debug window when the break occurs.
 180          * @note gui.ai_developer_tools setting must be enabled or the break is
 181          * ignored.
 182          */
 183         static void Break(const std::string &message);
 184
 185         /**
 186          * When Squirrel triggers a print, this function is called.
 187          *  Squirrel calls this when 'print' is used, or when the script made an error.
 188          * @param error_msg If true, it is a Squirrel error message.
 189          * @param message The message Squirrel logged.
 190          * @note Use ScriptLog.Info/Warning/Error instead of 'print'.
 191          */
 192         static void Print(bool error_msg, const std::string &message);
 193
 194         /**
 195          * Import a library.
 196          * @param library The name of the library to import. The name should be composed as ScriptInfo::GetCategory() + "." +
 197          * ScriptInfo::CreateInstance().
 198          * @param class_name Under which name you want it to be available (or "" if you just want the returning object).
 199          * @param version Which version you want specifically.
 200          * @return The loaded library object. If class_name is set, it is also available (under the scope of the import) under that name.
 201          * @note This command can be called from the global space, and does not need an instance.
 202          */
 203         static HSQOBJECT Import(const std::string &library, const std::string &class_name, int version);
 204
 205 private:
 206         typedef std::map<std::string, std::string, CaseInsensitiveComparator> LoadedLibraryList; ///< The type for loaded libraries.
 207
 208         uint ticks;                       ///< The amount of ticks we're sleeping.
 209         LoadedLibraryList loaded_library; ///< The libraries we loaded.
 210         int loaded_library_count;         ///< The amount of libraries.
 211
 212         /**
 213          * Register all classes that are known inside the script API.
 214          */
 215         void RegisterClasses();
 216 };
 217
 218 #endif /* SCRIPT_CONTROLLER_HPP */