src/script/api/script_controller.hpp

   1 /* $Id$ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * 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.
   6  * 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.
   7  * 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/>.
   8  */
   9
  10 /** @file script_controller.hpp The controller of the script. */
  11
  12 #ifndef SCRIPT_CONTROLLER_HPP
  13 #define SCRIPT_CONTROLLER_HPP
  14
  15 #include "script_types.hpp"
  16 #include "../../core/string_compare_type.hpp"
  17 #include <map>
  18
  19 /**
  20  * The Controller, the class each Script should extend. It creates the Script,
  21  *  makes sure the logic kicks in correctly, and that #GetTick() has a valid
  22  *  value.
  23  *
  24  * When starting a new game, or when loading a game, OpenTTD tries to match a
  25  *  script that matches to the specified version as close as possible. It tries
  26  *  (from first to last, stopping as soon as the attempt succeeds)
  27  *
  28  *  - load the exact same version of the same script,
  29  *  - load the latest version of the same script that supports loading data from
  30  *    the saved version (the version of saved data must be equal or greater
  31  *    than ScriptInfo::MinVersionToLoad),
  32  *  - load the latest version of the same script (ignoring version requirements),
  33  *  - (for AIs) load a random AI, and finally
  34  *  - (for AIs) load the dummy AI.
  35  *
  36  * After determining the script to use, starting it is done as follows
  37  *
  38  * - An instance is constructed of the class derived from ScriptController
  39  *   (class name is retrieved from ScriptInfo::CreateInstance).
  40  * - If there is script data available in the loaded game and if the data is
  41  *   loadable according to ScriptInfo::MinVersionToLoad, #Load is called with the
  42  *   data from the loaded game.
  43  * - Finally, #Start is called to start execution of the script.
  44  *
  45  * See also http://wiki.openttd.org/AI:Save/Load for more details.
  46  *
  47  * @api ai game
  48  */
  49 class ScriptController {
  50         friend class AIScanner;
  51         friend class ScriptInstance;
  52
  53 public:
  54         /**
  55          * Initializer of the ScriptController.
  56          * @param company The company this Script is normally serving.
  57          */
  58         ScriptController(CompanyID company);
  59
  60         /**
  61          * Destructor of the ScriptController.
  62          */
  63         ~ScriptController();
  64
  65         /**
  66          * This function is called to start your script. Your script starts here. If you
  67          *   return from this function, your script dies, so make sure that doesn't
  68          *   happen.
  69          * @note Cannot be called from within your script.
  70          */
  71         void Start();
  72
  73 #ifdef DOXYGEN_API
  74         /**
  75          * Save the state of the script.
  76          *
  77          * By implementing this function, you can store some data inside the savegame.
  78          *   The function should return a table with the information you want to store.
  79          *   You can only store:
  80          *
  81          *   - integers,
  82          *   - strings,
  83          *   - arrays (max. 25 levels deep),
  84          *   - tables (max. 25 levels deep),
  85          *   - booleans, and
  86          *   - nulls.
  87          *
  88          * In particular, instances of classes can't be saved including
  89          *   ScriptList. Such a list should be converted to an array or table on
  90          *   save and converted back on load.
  91          *
  92          * The function is called as soon as the user saves the game,
  93          *   independently of other activities of the script. The script is not
  94          *   notified of the call. To avoid race-conditions between #Save and the
  95          *   other script code, change variables directly after a #Sleep, it is
  96          *   very unlikely, to get interrupted at that point in the execution.
  97          * See also http://wiki.openttd.org/AI:Save/Load for more details.
  98          *
  99          * @note No other information is saved than the table returned by #Save.
 100          *   For example all pending events are lost as soon as the game is loaded.
 101          *
 102          * @return Data of the script that should be stored in the save game.
 103          */
 104         SquirrelTable Save();
 105
 106         /**
 107          * Load saved data just before calling #Start.
 108          * The function is only called when there is data to load.
 109          * @param version Version number of the script that created the \a data.
 110          * @param data Data that was saved (return value of #Save).
 111          */
 112         void Load(int version, SquirrelTable data);
 113 #endif /* DOXYGEN_API */
 114
 115         /**
 116          * Find at which tick your script currently is.
 117          * @return returns the current tick.
 118          */
 119         static uint GetTick();
 120
 121         /**
 122          * Get the number of operations the script may still execute this tick.
 123          * @return The amount of operations left to execute.
 124          * @note This number can go negative when certain uninteruptable
 125          *   operations are executed. The amount of operations that you go
 126          *   over the limit will be deducted from the next tick you would
 127          *   be allowed to run.
 128          */
 129         static int GetOpsTillSuspend();
 130
 131         /**
 132          * Get the value of one of your settings you set via info.nut.
 133          * @param name The name of the setting.
 134          * @return the value for the setting, or -1 if the setting is not known.
 135          */
 136         static int GetSetting(const char *name);
 137
 138         /**
 139          * Get the OpenTTD version of this executable. The version is formatted
 140          * with the bits having the following meaning:
 141          * 28-31 major version
 142          * 24-27 minor version
 143          * 20-23 build
 144          *    19 1 if it is a release, 0 if it is not.
 145          *  0-18 revision number; 0 when the revision is unknown.
 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 char* 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 char *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 char *library, const char *class_name, int version);
 204
 205 private:
 206         typedef std::map<const char *, const char *, StringCompare> 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 */