src/script/script_instance.hpp

   1 /* $Id: script_instance.hpp 25342 2013-06-09 12:19:09Z zuu $ */
   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_instance.hpp The ScriptInstance tracks a script. */
  11
  12 #ifndef SCRIPT_INSTANCE_HPP
  13 #define SCRIPT_INSTANCE_HPP
  14
  15 #include <squirrel.h>
  16 #include "script_suspend.hpp"
  17
  18 #include "../command_type.h"
  19 #include "../company_type.h"
  20 #include "../fileio_type.h"
  21
  22 static const uint SQUIRREL_MAX_DEPTH = 25; ///< The maximum recursive depth for items stored in the savegame.
  23
  24 /** Runtime information about a script like a pointer to the squirrel vm and the current state. */
  25 class ScriptInstance {
  26 public:
  27         friend class ScriptObject;
  28         friend class ScriptController;
  29
  30         /**
  31          * Create a new script.
  32          */
  33         ScriptInstance(const char *APIName);
  34         virtual ~ScriptInstance();
  35
  36         /**
  37          * Initialize the script and prepare it for its first run.
  38          * @param main_script The full path of the script to load.
  39          * @param instance_name The name of the instance out of the script to load.
  40          * @param company Which company this script is serving.
  41          */
  42         void Initialize(const char *main_script, const char *instance_name, CompanyID company);
  43
  44         /**
  45          * Get the value of a setting of the current instance.
  46          * @param name The name of the setting.
  47          * @return the value for the setting, or -1 if the setting is not known.
  48          */
  49         virtual int GetSetting(const char *name) = 0;
  50
  51         /**
  52          * Find a library.
  53          * @param library The library name to find.
  54          * @param version The version the library should have.
  55          * @return The library if found, NULL otherwise.
  56          */
  57         virtual class ScriptInfo *FindLibrary(const char *library, int version) = 0;
  58
  59         /**
  60          * A script in multiplayer waits for the server to handle his DoCommand.
  61          *  It keeps waiting for this until this function is called.
  62          */
  63         void Continue();
  64
  65         /**
  66          * Run the GameLoop of a script.
  67          */
  68         void GameLoop();
  69
  70         /**
  71          * Let the VM collect any garbage.
  72          */
  73         void CollectGarbage() const;
  74
  75         /**
  76          * Get the storage of this script.
  77          */
  78         class ScriptStorage *GetStorage();
  79
  80         /**
  81          * Get the log pointer of this script.
  82          */
  83         void *GetLogPointer();
  84
  85         /**
  86          * Return a true/false reply for a DoCommand.
  87          */
  88         static void DoCommandReturn(ScriptInstance *instance);
  89
  90         /**
  91          * Return a VehicleID reply for a DoCommand.
  92          */
  93         static void DoCommandReturnVehicleID(ScriptInstance *instance);
  94
  95         /**
  96          * Return a SignID reply for a DoCommand.
  97          */
  98         static void DoCommandReturnSignID(ScriptInstance *instance);
  99
 100         /**
 101          * Return a GroupID reply for a DoCommand.
 102          */
 103         static void DoCommandReturnGroupID(ScriptInstance *instance);
 104
 105         /**
 106          * Return a GoalID reply for a DoCommand.
 107          */
 108         static void DoCommandReturnGoalID(ScriptInstance *instance);
 109
 110         /**
 111          * Return a StoryPageID reply for a DoCommand.
 112          */
 113         static void DoCommandReturnStoryPageID(ScriptInstance *instance);
 114
 115         /**
 116          * Return a StoryPageElementID reply for a DoCommand.
 117          */
 118         static void DoCommandReturnStoryPageElementID(ScriptInstance *instance);
 119
 120         /**
 121          * Get the controller attached to the instance.
 122          */
 123         class ScriptController *GetController() { return controller; }
 124
 125         /**
 126          * Return the "this script died" value
 127          */
 128         inline bool IsDead() const { return this->is_dead; }
 129
 130         /**
 131          * Call the script Save function and save all data in the savegame.
 132          */
 133         void Save();
 134
 135         /**
 136          * Don't save any data in the savegame.
 137          */
 138         static void SaveEmpty();
 139
 140         /**
 141          * Load data from a savegame and store it on the stack.
 142          * @param version The version of the script when saving, or -1 if this was
 143          *  not the original script saving the game.
 144          */
 145         void Load(int version);
 146
 147         /**
 148          * Load and discard data from a savegame.
 149          */
 150         static void LoadEmpty();
 151
 152         /**
 153          * Suspends the script for the current tick and then pause the execution
 154          * of script. The script will not be resumed from its suspended state
 155          * until the script has been unpaused.
 156          */
 157         void Pause();
 158
 159         /**
 160          * Checks if the script is paused.
 161          * @return true if the script is paused, otherwise false
 162          */
 163         bool IsPaused();
 164
 165         /**
 166          * Resume execution of the script. This function will not actually execute
 167          * the script, but set a flag so that the script is executed my the usual
 168          * mechanism that executes the script.
 169          */
 170         void Unpause();
 171
 172         /**
 173          * Get the number of operations the script can execute before being suspended.
 174          * This function is safe to call from within a function called by the script.
 175          * @return The number of operations to execute.
 176          */
 177         SQInteger GetOpsTillSuspend();
 178
 179         /**
 180          * DoCommand callback function for all commands executed by scripts.
 181          * @param result The result of the command.
 182          * @param tile The tile on which the command was executed.
 183          * @param p1 p1 as given to DoCommandPInternal.
 184          * @param p2 p2 as given to DoCommandPInternal.
 185          */
 186         void DoCommandCallback(const CommandCost &result, TileIndex tile, uint32 p1, uint32 p2);
 187
 188         /**
 189          * Insert an event for this script.
 190          * @param event The event to insert.
 191          */
 192         void InsertEvent(class ScriptEvent *event);
 193
 194         /**
 195          * Check if the instance is sleeping, which either happened because the
 196          *  script executed a DoCommand, executed this.Sleep() or it has been
 197          *  paused.
 198          */
 199         bool IsSleeping() { return this->suspend != 0; }
 200
 201 protected:
 202         class Squirrel *engine;               ///< A wrapper around the squirrel vm.
 203         const char *versionAPI;               ///< Current API used by this script.
 204
 205         /**
 206          * Register all API functions to the VM.
 207          */
 208         virtual void RegisterAPI();
 209
 210         /**
 211          * Load squirrel scripts to emulate an older API.
 212          * @param api_version: API version to load scripts for
 213          * @param dir Subdirectory to find the scripts in
 214          * @return true iff script loading should proceed
 215          */
 216         bool LoadCompatibilityScripts(const char *api_version, Subdirectory dir);
 217
 218         /**
 219          * Tell the script it died.
 220          */
 221         virtual void Died();
 222
 223         /**
 224          * Get the callback handling DoCommands in case of networking.
 225          */
 226         virtual CommandCallback *GetDoCommandCallback() = 0;
 227
 228         /**
 229          * Load the dummy script.
 230          */
 231         virtual void LoadDummyScript() = 0;
 232
 233 private:
 234         class ScriptController *controller;   ///< The script main class.
 235         class ScriptStorage *storage;         ///< Some global information for each running script.
 236         SQObject *instance;                   ///< Squirrel-pointer to the script main class.
 237
 238         bool is_started;                      ///< Is the scripts constructor executed?
 239         bool is_dead;                         ///< True if the script has been stopped.
 240         bool is_save_data_on_stack;           ///< Is the save data still on the squirrel stack?
 241         int suspend;                          ///< The amount of ticks to suspend this script before it's allowed to continue.
 242         bool is_paused;                       ///< Is the script paused? (a paused script will not be executed until unpaused)
 243         Script_SuspendCallbackProc *callback; ///< Callback that should be called in the next tick the script runs.
 244
 245         /**
 246          * Call the script Load function if it exists and data was loaded
 247          *  from a savegame.
 248          */
 249         bool CallLoad();
 250
 251         /**
 252          * Save one object (int / string / array / table) to the savegame.
 253          * @param vm The virtual machine to get all the data from.
 254          * @param index The index on the squirrel stack of the element to save.
 255          * @param max_depth The maximum depth recursive arrays / tables will be stored
 256          *   with before an error is returned.
 257          * @param test If true, don't really store the data but only check if it is
 258          *   valid.
 259          * @return True if the saving was successful.
 260          */
 261         static bool SaveObject(HSQUIRRELVM vm, SQInteger index, int max_depth, bool test);
 262
 263         /**
 264          * Load all objects from a savegame.
 265          * @return True if the loading was successful.
 266          */
 267         static bool LoadObjects(HSQUIRRELVM vm);
 268 };
 269
 270 #endif /* SCRIPT_INSTANCE_HPP */