OpenTTD Source: src/script/squirrel.hpp Source File

OpenTTD Source 13.2.1

squirrel.hpp
Go to the documentation of this file.
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
10 #ifndef SQUIRREL_HPP
11 #define SQUIRREL_HPP
12
13 #include <squirrel.h>
14
16 enum ScriptType {
17 ST_AI,
18 ST_GS,
19 };
20
21 struct ScriptAllocator;
22
23 class Squirrel {
24 friend class ScriptAllocatorScope;
25
26 private:
27 typedef void (SQPrintFunc)(bool error_msg, const SQChar *message);
28
29 HSQUIRRELVM vm;
30 void *global_pointer;
31 SQPrintFunc *print_func;
32 bool crashed;
33 int overdrawn_ops;
34 const char *APIName;
35 std::unique_ptr<ScriptAllocator> allocator;
36
40 static SQInteger _RunError(HSQUIRRELVM vm);
41
45 const char *GetAPIName() { return this->APIName; }
46
48 void Initialize();
50 void Uninitialize();
51
52 protected:
56 static void CompileError(HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column);
57
61 static void RunError(HSQUIRRELVM vm, const SQChar *error);
62
66 static void PrintFunc(HSQUIRRELVM vm, const SQChar *s, ...) WARN_FORMAT(2, 3);
67
71 static void ErrorPrintFunc(HSQUIRRELVM vm, const SQChar *s, ...) WARN_FORMAT(2, 3);
72
73 public:
74 Squirrel(const char *APIName);
75 ~Squirrel();
76
80 HSQUIRRELVM GetVM() { return this->vm; }
81
87 bool LoadScript(const char *script);
88 bool LoadScript(HSQUIRRELVM vm, const char *script, bool in_root = true);
89
93 SQRESULT LoadFile(HSQUIRRELVM vm, const char *filename, SQBool printerror);
94
99 void AddMethod(const char *method_name, SQFUNCTION proc, uint nparam = 0, const char *params = nullptr, void *userdata = nullptr, int size = 0);
100
105 void AddConst(const char *var_name, int value);
106
111 void AddConst(const char *var_name, uint value) { this->AddConst(var_name, (int)value); }
112
117 void AddConst(const char *var_name, bool value);
118
123 void AddClassBegin(const char *class_name);
124
129 void AddClassBegin(const char *class_name, const char *parent_class);
130
135 void AddClassEnd();
136
140 bool Resume(int suspend = -1);
141
145 void ResumeError();
146
150 void CollectGarbage();
151
152 void InsertResult(bool result);
153 void InsertResult(int result);
154 void InsertResult(uint result) { this->InsertResult((int)result); }
155
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 CallStringMethodStrdup(HSQOBJECT instance, const char *method_name, const char **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
169 bool MethodExists(HSQOBJECT instance, const char *method_name);
170
181 static bool CreateClassInstanceVM(HSQUIRRELVM vm, const char *class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name = false);
182
186 bool CreateClassInstance(const char *class_name, void *real_instance, HSQOBJECT *instance);
187
193 static bool GetRealInstance(HSQUIRRELVM vm, SQUserPointer *ptr) { return SQ_SUCCEEDED(sq_getinstanceup(vm, 1, ptr, nullptr)); }
194
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
205 static const char *ObjectToString(HSQOBJECT *ptr) { return sq_objtostring(ptr); }
206
210 static int ObjectToInteger(HSQOBJECT *ptr) { return sq_objtointeger(ptr); }
211
215 static bool ObjectToBool(HSQOBJECT *ptr) { return sq_objtobool(ptr) == 1; }
216
221 void SetGlobalPointer(void *ptr) { this->global_pointer = ptr; }
222
226 static void *GetGlobalPointer(HSQUIRRELVM vm) { return ((Squirrel *)sq_getforeignptr(vm))->global_pointer; }
227
231 void SetPrintFunction(SQPrintFunc *func) { this->print_func = func; }
232
236 void ThrowError(const char *error) { sq_throwerror(this->vm, error); }
237
241 void ReleaseObject(HSQOBJECT *ptr) { sq_release(this->vm, ptr); }
242
246 static void DecreaseOps(HSQUIRRELVM vm, int amount);
247
252 bool IsSuspended();
253
257 bool HasScriptCrashed();
258
262 void CrashOccurred();
263
267 bool CanSuspend();
268
272 SQInteger GetOpsTillSuspend();
273
277 void Reset();
278
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 */
Squirrel::PrintFunc
static void PrintFunc(HSQUIRRELVM vm, const SQChar *s,...) WARN_FORMAT(2
If a user runs 'print' inside a script, this function gets the params.
Definition: squirrel.cpp:282
Squirrel::SetPrintFunction
void SetPrintFunction(SQPrintFunc *func)
Set a custom print function, so you can handle outputs from SQ yourself.
Definition: squirrel.hpp:231
Squirrel::ObjectToString
static const char * ObjectToString(HSQOBJECT *ptr)
Convert a Squirrel-object to a string.
Definition: squirrel.hpp:205
Squirrel::GetAPIName
const char * GetAPIName()
Get the API name.
Definition: squirrel.hpp:45
Squirrel::CanSuspend
bool CanSuspend()
Are we allowed to suspend the squirrel script at this moment?
Definition: squirrel.cpp:835
ScriptType
ScriptType
The type of script we're working with, i.e.
Definition: squirrel.hpp:16
ST_AI
@ ST_AI
The script is for AI scripts.
Definition: squirrel.hpp:17
Squirrel::AddClassBegin
void AddClassBegin(const char *class_name)
Adds a class to the global scope.
Definition: squirrel.cpp:336
ScriptAllocator
In the memory allocator for Squirrel we want to directly use malloc/realloc, so when the OS does not ...
Definition: squirrel.cpp:39
Squirrel::GetVM
HSQUIRRELVM GetVM()
Get the squirrel VM.
Definition: squirrel.hpp:80
Squirrel::Reset
void Reset()
Completely reset the engine; start from scratch.
Definition: squirrel.cpp:787
Squirrel::GetInstance
static bool GetInstance(HSQUIRRELVM vm, HSQOBJECT *ptr, int pos=1)
Get the Squirrel-instance pointer.
Definition: squirrel.hpp:200
Squirrel::vm
HSQUIRRELVM vm
The VirtualMachine instance for squirrel.
Definition: squirrel.hpp:29
Squirrel::CreateClassInstanceVM
static bool CreateClassInstanceVM(HSQUIRRELVM vm, const char *class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name=false)
Creates a class instance.
Definition: squirrel.cpp:483
Squirrel::GetOpsTillSuspend
SQInteger GetOpsTillSuspend()
How many operations can we execute till suspension?
Definition: squirrel.cpp:841
Squirrel::GetRealInstance
static bool GetRealInstance(HSQUIRRELVM vm, SQUserPointer *ptr)
Get the real-instance pointer.
Definition: squirrel.hpp:193
Squirrel::Initialize
void Initialize()
Perform all initialization steps to create the engine.
Definition: squirrel.cpp:545
Squirrel
Definition: squirrel.hpp:23
Squirrel::global_pointer
void * global_pointer
Can be set by who ever initializes Squirrel.
Definition: squirrel.hpp:30
Squirrel::ObjectToInteger
static int ObjectToInteger(HSQOBJECT *ptr)
Convert a Squirrel-object to an integer.
Definition: squirrel.hpp:210
Squirrel::HasScriptCrashed
bool HasScriptCrashed()
Find out if the squirrel script made an error before.
Definition: squirrel.cpp:825
Squirrel::LoadScript
bool LoadScript(const char *script)
Load a script.
Definition: squirrel.cpp:757
Squirrel::AddClassEnd
void AddClassEnd()
Finishes adding a class to the global scope.
Definition: squirrel.cpp:360
Squirrel::overdrawn_ops
int overdrawn_ops
The amount of operations we have overdrawn.
Definition: squirrel.hpp:33
Squirrel::ThrowError
void ThrowError(const char *error)
Throw a Squirrel error that will be nicely displayed to the user.
Definition: squirrel.hpp:236
Squirrel::Uninitialize
void Uninitialize()
Perform all the cleanups for the engine.
Definition: squirrel.cpp:767
ScriptAllocatorScope
Definition: squirrel.hpp:288
Squirrel::SetGlobalPointer
void SetGlobalPointer(void *ptr)
Sets a pointer in the VM that is reachable from where ever you are in SQ.
Definition: squirrel.hpp:221
ST_GS
@ ST_GS
The script is for Game scripts.
Definition: squirrel.hpp:18
Squirrel::ErrorPrintFunc
static void static void ErrorPrintFunc(HSQUIRRELVM vm, const SQChar *s,...) WARN_FORMAT(2
If an error has to be print, this function is called.
Definition: squirrel.cpp:226
Squirrel::GetGlobalPointer
static void * GetGlobalPointer(HSQUIRRELVM vm)
Get the pointer as set by SetGlobalPointer.
Definition: squirrel.hpp:226
Squirrel::GetAllocatedMemory
size_t GetAllocatedMemory() const noexcept
Get number of bytes allocated by this VM.
Definition: squirrel.cpp:202
Squirrel::CallMethod
bool CallMethod(HSQOBJECT instance, const char *method_name, HSQOBJECT *ret, int suspend)
Call a method of an instance, in various flavors.
Definition: squirrel.cpp:421
Squirrel::ObjectToBool
static bool ObjectToBool(HSQOBJECT *ptr)
Convert a Squirrel-object to a bool.
Definition: squirrel.hpp:215
Squirrel::AddConst
void AddConst(const char *var_name, int value)
Adds a const to the stack.
Definition: squirrel.cpp:318
Squirrel::allocator
std::unique_ptr< ScriptAllocator > allocator
Allocator object used by this script.
Definition: squirrel.hpp:35
Squirrel::ResumeError
void ResumeError()
Resume the VM with an error so it prints a stack trace.
Definition: squirrel.cpp:408
Squirrel::CreateClassInstance
bool CreateClassInstance(const char *class_name, void *real_instance, HSQOBJECT *instance)
Exactly the same as CreateClassInstanceVM, only callable without instance of Squirrel.
Definition: squirrel.cpp:533
Squirrel::CollectGarbage
void CollectGarbage()
Tell the VM to do a garbage collection run.
Definition: squirrel.cpp:415
Squirrel::MethodExists
bool MethodExists(HSQOBJECT instance, const char *method_name)
Check if a method exists in an instance.
Definition: squirrel.cpp:368
Squirrel::AddMethod
void AddMethod(const char *method_name, SQFUNCTION proc, uint nparam=0, const char *params=nullptr, void *userdata=nullptr, int size=0)
Adds a function to the stack.
Definition: squirrel.cpp:301
Squirrel::CrashOccurred
void CrashOccurred()
Set the script status to crashed.
Definition: squirrel.cpp:830
Squirrel::crashed
bool crashed
True if the squirrel script made an error.
Definition: squirrel.hpp:32
Squirrel::AddConst
void AddConst(const char *var_name, uint value)
Adds a const to the stack.
Definition: squirrel.hpp:111
Squirrel::RunError
static void RunError(HSQUIRRELVM vm, const SQChar *error)
The RunError handler.
Definition: squirrel.cpp:244
_squirrel_allocator
ScriptAllocator * _squirrel_allocator
In the memory allocator for Squirrel we want to directly use malloc/realloc, so when the OS does not ...
Definition: squirrel.cpp:193
Squirrel::Resume
bool Resume(int suspend=-1)
Resume a VM when it was suspended via a throw.
Definition: squirrel.cpp:386
error
void CDECL error(const char *s,...)
Error handling for fatal non-user errors.
Definition: openttd.cpp:134
Squirrel::APIName
const char * APIName
Name of the API used for this squirrel.
Definition: squirrel.hpp:34
Squirrel::ReleaseObject
void ReleaseObject(HSQOBJECT *ptr)
Release a SQ object.
Definition: squirrel.hpp:241
Squirrel::IsSuspended
bool IsSuspended()
Did the squirrel code suspend or return normally.
Definition: squirrel.cpp:820
Squirrel::print_func
SQPrintFunc * print_func
Points to either nullptr, or a custom print handler.
Definition: squirrel.hpp:31
Squirrel::CompileError
static void CompileError(HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column)
The CompileError handler.
Definition: squirrel.cpp:209
Squirrel::DecreaseOps
static void DecreaseOps(HSQUIRRELVM vm, int amount)
Tell the VM to remove amount ops from the number of ops till suspend.
Definition: squirrel.cpp:815
Squirrel::LoadFile
SQRESULT LoadFile(HSQUIRRELVM vm, const char *filename, SQBool printerror)
Load a file to a given VM.
Definition: squirrel.cpp:647
Squirrel::_RunError
static SQInteger _RunError(HSQUIRRELVM vm)
The internal RunError handler.
Definition: squirrel.cpp:267