src/script/squirrel.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 squirrel.hpp defines the Squirrel class */
   9
  10 #ifndef SQUIRREL_HPP
  11 #define SQUIRREL_HPP
  12
  13 #include <squirrel.h>
  14
  15 /** The type of script we're working with, i.e. for who is it? */
  16 enum class ScriptType {
  17         AI, ///< The script is for AI scripts.
  18         GS, ///< The script is for Game scripts.
  19 };
  20
  21 struct ScriptAllocator;
  22
  23 class Squirrel {
  24         friend class ScriptAllocatorScope;
  25
  26 private:
  27         typedef void (SQPrintFunc)(bool error_msg, const std::string &message);
  28
  29         HSQUIRRELVM vm;          ///< The VirtualMachine instance for squirrel
  30         void *global_pointer;    ///< Can be set by who ever initializes Squirrel
  31         SQPrintFunc *print_func; ///< Points to either nullptr, or a custom print handler
  32         bool crashed;            ///< True if the squirrel script made an error.
  33         int overdrawn_ops;       ///< The amount of operations we have overdrawn.
  34         const char *APIName;     ///< Name of the API used for this squirrel.
  35         std::unique_ptr<ScriptAllocator> allocator; ///< Allocator object used by this script.
  36
  37         /**
  38          * The internal RunError handler. It looks up the real error and calls RunError with it.
  39          */
  40         static SQInteger _RunError(HSQUIRRELVM vm);
  41
  42         /**
  43          * Get the API name.
  44          */
  45         const char *GetAPIName() { return this->APIName; }
  46
  47         /** Perform all initialization steps to create the engine. */
  48         void Initialize();
  49         /** Perform all the cleanups for the engine. */
  50         void Uninitialize();
  51
  52 protected:
  53         /**
  54          * The CompileError handler.
  55          */
  56         static void CompileError(HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column);
  57
  58         /**
  59          * The RunError handler.
  60          */
  61         static void RunError(HSQUIRRELVM vm, const SQChar *error);
  62
  63         /**
  64          * If a user runs 'print' inside a script, this function gets the params.
  65          */
  66         static void PrintFunc(HSQUIRRELVM vm, const std::string &s);
  67
  68         /**
  69          * If an error has to be print, this function is called.
  70          */
  71         static void ErrorPrintFunc(HSQUIRRELVM vm, const std::string &s);
  72
  73 public:
  74         Squirrel(const char *APIName);
  75         ~Squirrel();
  76
  77         /**
  78          * Get the squirrel VM. Try to avoid using this.
  79          */
  80         HSQUIRRELVM GetVM() { return this->vm; }
  81
  82         /**
  83          * Load a script.
  84          * @param script The full script-name to load.
  85          * @return False if loading failed.
  86          */
  87         bool LoadScript(const std::string &script);
  88         bool LoadScript(HSQUIRRELVM vm, const std::string &script, bool in_root = true);
  89
  90         /**
  91          * Load a file to a given VM.
  92          */
  93         SQRESULT LoadFile(HSQUIRRELVM vm, const std::string &filename, SQBool printerror);
  94
  95         /**
  96          * Adds a function to the stack. Depending on the current state this means
  97          *  either a method or a global function.
  98          */
  99         void AddMethod(const char *method_name, SQFUNCTION proc, uint nparam = 0, const char *params = nullptr, void *userdata = nullptr, int size = 0);
 100
 101         /**
 102          * Adds a const to the stack. Depending on the current state this means
 103          *  either a const to a class or to the global space.
 104          */
 105         void AddConst(const char *var_name, int value);
 106
 107         /**
 108          * Adds a const to the stack. Depending on the current state this means
 109          *  either a const to a class or to the global space.
 110          */
 111         void AddConst(const char *var_name, uint value) { this->AddConst(var_name, (int)value); }
 112
 113         /**
 114          * Adds a const to the stack. Depending on the current state this means
 115          *  either a const to a class or to the global space.
 116          */
 117         void AddConst(const char *var_name, bool value);
 118
 119         /**
 120          * Adds a class to the global scope. Make sure to call AddClassEnd when you
 121          *  are done adding methods.
 122          */
 123         void AddClassBegin(const char *class_name);
 124
 125         /**
 126          * Adds a class to the global scope, extending 'parent_class'.
 127          * Make sure to call AddClassEnd when you are done adding methods.
 128          */
 129         void AddClassBegin(const char *class_name, const char *parent_class);
 130
 131         /**
 132          * Finishes adding a class to the global scope. If this isn't called, no
 133          *  class is really created.
 134          */
 135         void AddClassEnd();
 136
 137         /**
 138          * Resume a VM when it was suspended via a throw.
 139          */
 140         bool Resume(int suspend = -1);
 141
 142         /**
 143          * Resume the VM with an error so it prints a stack trace.
 144          */
 145         void ResumeError();
 146
 147         /**
 148          * Tell the VM to do a garbage collection run.
 149          */
 150         void CollectGarbage();
 151
 152         void InsertResult(bool result);
 153         void InsertResult(int result);
 154         void InsertResult(uint result) { this->InsertResult((int)result); }
 155
 156         /**
 157          * Call a method of an instance, in various flavors.
 158          * @return False if the script crashed or returned a wrong type.
 159          */
 160         bool CallMethod(HSQOBJECT instance, const char *method_name, HSQOBJECT *ret, int suspend);
 161         bool CallMethod(HSQOBJECT instance, const char *method_name, int suspend) { return this->CallMethod(instance, method_name, nullptr, suspend); }
 162         bool CallStringMethod(HSQOBJECT instance, const char *method_name, std::string *res, int suspend);
 163         bool CallIntegerMethod(HSQOBJECT instance, const char *method_name, int *res, int suspend);
 164         bool CallBoolMethod(HSQOBJECT instance, const char *method_name, bool *res, int suspend);
 165
 166         /**
 167          * Check if a method exists in an instance.
 168          */
 169         bool MethodExists(HSQOBJECT instance, const char *method_name);
 170
 171         /**
 172          * Creates a class instance.
 173          * @param vm The VM to create the class instance for
 174          * @param class_name The name of the class of which we create an instance.
 175          * @param real_instance The instance to the real class, if it represents a real class.
 176          * @param instance Returning value with the pointer to the instance.
 177          * @param release_hook Optional param to give a release hook.
 178          * @param prepend_API_name Optional parameter; if true, the class_name is prefixed with the current API name.
 179          * @return False if creating failed.
 180          */
 181         static bool CreateClassInstanceVM(HSQUIRRELVM vm, const std::string &class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name = false);
 182
 183         /**
 184          * Exactly the same as CreateClassInstanceVM, only callable without instance of Squirrel.
 185          */
 186         bool CreateClassInstance(const std::string &class_name, void *real_instance, HSQOBJECT *instance);
 187
 188         /**
 189          * Get the real-instance pointer.
 190          * @note This will only work just after a function-call from within Squirrel
 191          *  to your C++ function.
 192          */
 193         static bool GetRealInstance(HSQUIRRELVM vm, SQUserPointer *ptr) { return SQ_SUCCEEDED(sq_getinstanceup(vm, 1, ptr, nullptr)); }
 194
 195         /**
 196          * Get the Squirrel-instance pointer.
 197          * @note This will only work just after a function-call from within Squirrel
 198          *  to your C++ function.
 199          */
 200         static bool GetInstance(HSQUIRRELVM vm, HSQOBJECT *ptr, int pos = 1) { sq_getclass(vm, pos); sq_getstackobj(vm, pos, ptr); sq_pop(vm, 1); return true; }
 201
 202         /**
 203          * Convert a Squirrel-object to a string.
 204          */
 205         static const char *ObjectToString(HSQOBJECT *ptr) { return sq_objtostring(ptr); }
 206
 207         /**
 208          * Convert a Squirrel-object to an integer.
 209          */
 210         static int ObjectToInteger(HSQOBJECT *ptr) { return sq_objtointeger(ptr); }
 211
 212         /**
 213          * Convert a Squirrel-object to a bool.
 214          */
 215         static bool ObjectToBool(HSQOBJECT *ptr) { return sq_objtobool(ptr) == 1; }
 216
 217         /**
 218          * Sets a pointer in the VM that is reachable from where ever you are in SQ.
 219          *  Useful to keep track of the main instance.
 220          */
 221         void SetGlobalPointer(void *ptr) { this->global_pointer = ptr; }
 222
 223         /**
 224          * Get the pointer as set by SetGlobalPointer.
 225          */
 226         static void *GetGlobalPointer(HSQUIRRELVM vm) { return ((Squirrel *)sq_getforeignptr(vm))->global_pointer; }
 227
 228         /**
 229          * Set a custom print function, so you can handle outputs from SQ yourself.
 230          */
 231         void SetPrintFunction(SQPrintFunc *func) { this->print_func = func; }
 232
 233         /**
 234          * Throw a Squirrel error that will be nicely displayed to the user.
 235          */
 236         void ThrowError(const std::string_view error) { sq_throwerror(this->vm, error); }
 237
 238         /**
 239          * Release a SQ object.
 240          */
 241         void ReleaseObject(HSQOBJECT *ptr) { sq_release(this->vm, ptr); }
 242
 243         /**
 244          * Tell the VM to remove \c amount ops from the number of ops till suspend.
 245          */
 246         static void DecreaseOps(HSQUIRRELVM vm, int amount);
 247
 248         /**
 249          * Did the squirrel code suspend or return normally.
 250          * @return True if the function suspended.
 251          */
 252         bool IsSuspended();
 253
 254         /**
 255          * Find out if the squirrel script made an error before.
 256          */
 257         bool HasScriptCrashed();
 258
 259         /**
 260          * Set the script status to crashed.
 261          */
 262         void CrashOccurred();
 263
 264         /**
 265          * Are we allowed to suspend the squirrel script at this moment?
 266          */
 267         bool CanSuspend();
 268
 269         /**
 270          * How many operations can we execute till suspension?
 271          */
 272         SQInteger GetOpsTillSuspend();
 273
 274         /**
 275          * Completely reset the engine; start from scratch.
 276          */
 277         void Reset();
 278
 279         /**
 280          * Get number of bytes allocated by this VM.
 281          */
 282         size_t GetAllocatedMemory() const noexcept;
 283 };
 284
 285
 286 extern ScriptAllocator *_squirrel_allocator;
 287
 288 class ScriptAllocatorScope {
 289         ScriptAllocator *old_allocator;
 290
 291 public:
 292         ScriptAllocatorScope(const Squirrel *engine)
 293         {
 294                 this->old_allocator = _squirrel_allocator;
 295                 /* This may get called with a nullptr engine, in case of a crashed script */
 296                 _squirrel_allocator = engine != nullptr ? engine->allocator.get() : nullptr;
 297         }
 298
 299         ~ScriptAllocatorScope()
 300         {
 301                 _squirrel_allocator = this->old_allocator;
 302         }
 303 };
 304
 305 #endif /* SQUIRREL_HPP */