OpenTTD Source 20241224-master-gf74b0cf984
Squirrel Class Reference

Public Member Functions

 Squirrel (const char *APIName)
 
HSQUIRRELVM GetVM ()
 Get the squirrel VM.
 
bool LoadScript (const std::string &script)
 Load a script.
 
bool LoadScript (HSQUIRRELVM vm, const std::string &script, bool in_root=true)
 
SQRESULT LoadFile (HSQUIRRELVM vm, const std::string &filename, SQBool printerror)
 Load a file to a given VM.
 
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.
 
void AddConst (const char *var_name, int value)
 Adds a const to the stack.
 
void AddConst (const char *var_name, uint value)
 Adds a const to the stack.
 
void AddConst (const char *var_name, bool value)
 Adds a const to the stack.
 
void AddClassBegin (const char *class_name)
 Adds a class to the global scope.
 
void AddClassBegin (const char *class_name, const char *parent_class)
 Adds a class to the global scope, extending 'parent_class'.
 
void AddClassEnd ()
 Finishes adding a class to the global scope.
 
bool Resume (int suspend=-1)
 Resume a VM when it was suspended via a throw.
 
void ResumeError ()
 Resume the VM with an error so it prints a stack trace.
 
void CollectGarbage ()
 Tell the VM to do a garbage collection run.
 
void InsertResult (bool result)
 
void InsertResult (int result)
 
void InsertResult (uint result)
 
bool CallMethod (HSQOBJECT instance, const char *method_name, HSQOBJECT *ret, int suspend)
 Call a method of an instance, in various flavors.
 
bool CallMethod (HSQOBJECT instance, const char *method_name, int suspend)
 
bool CallStringMethod (HSQOBJECT instance, const char *method_name, std::string *res, int suspend)
 
bool CallIntegerMethod (HSQOBJECT instance, const char *method_name, int *res, int suspend)
 
bool CallBoolMethod (HSQOBJECT instance, const char *method_name, bool *res, int suspend)
 
bool MethodExists (HSQOBJECT instance, const char *method_name)
 Check if a method exists in an instance.
 
bool CreateClassInstance (const std::string &class_name, void *real_instance, HSQOBJECT *instance)
 Exactly the same as CreateClassInstanceVM, only callable without instance of Squirrel.
 
void SetGlobalPointer (void *ptr)
 Sets a pointer in the VM that is reachable from where ever you are in SQ.
 
void SetPrintFunction (SQPrintFunc *func)
 Set a custom print function, so you can handle outputs from SQ yourself.
 
void ThrowError (const std::string_view error)
 Throw a Squirrel error that will be nicely displayed to the user.
 
void ReleaseObject (HSQOBJECT *ptr)
 Release a SQ object.
 
bool IsSuspended ()
 Did the squirrel code suspend or return normally.
 
bool HasScriptCrashed ()
 Find out if the squirrel script made an error before.
 
void CrashOccurred ()
 Set the script status to crashed.
 
bool CanSuspend ()
 Are we allowed to suspend the squirrel script at this moment?
 
SQInteger GetOpsTillSuspend ()
 How many operations can we execute till suspension?
 
void Reset ()
 Completely reset the engine; start from scratch.
 
size_t GetAllocatedMemory () const noexcept
 Get number of bytes allocated by this VM.
 

Static Public Member Functions

static bool CreateClassInstanceVM (HSQUIRRELVM vm, const std::string &class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name=false)
 Creates a class instance.
 
static bool GetRealInstance (HSQUIRRELVM vm, SQUserPointer *ptr)
 Get the real-instance pointer.
 
static bool GetInstance (HSQUIRRELVM vm, HSQOBJECT *ptr, int pos=1)
 Get the Squirrel-instance pointer.
 
static const char * ObjectToString (HSQOBJECT *ptr)
 Convert a Squirrel-object to a string.
 
static int ObjectToInteger (HSQOBJECT *ptr)
 Convert a Squirrel-object to an integer.
 
static bool ObjectToBool (HSQOBJECT *ptr)
 Convert a Squirrel-object to a bool.
 
static void * GetGlobalPointer (HSQUIRRELVM vm)
 Get the pointer as set by SetGlobalPointer.
 
static void DecreaseOps (HSQUIRRELVM vm, int amount)
 Tell the VM to remove amount ops from the number of ops till suspend.
 

Static Protected Member Functions

static void CompileError (HSQUIRRELVM vm, const SQChar *desc, const SQChar *source, SQInteger line, SQInteger column)
 The CompileError handler.
 
static void RunError (HSQUIRRELVM vm, const SQChar *error)
 The RunError handler.
 
static void PrintFunc (HSQUIRRELVM vm, const std::string &s)
 If a user runs 'print' inside a script, this function gets the params.
 
static void ErrorPrintFunc (HSQUIRRELVM vm, const std::string &s)
 If an error has to be print, this function is called.
 

Private Types

typedef void() SQPrintFunc(bool error_msg, const std::string &message)
 

Private Member Functions

const char * GetAPIName ()
 Get the API name.
 
void Initialize ()
 Perform all initialization steps to create the engine.
 
void Uninitialize ()
 Perform all the cleanups for the engine.
 

Static Private Member Functions

static SQInteger _RunError (HSQUIRRELVM vm)
 The internal RunError handler.
 

Private Attributes

HSQUIRRELVM vm
 The VirtualMachine instance for squirrel.
 
void * global_pointer
 Can be set by who ever initializes Squirrel.
 
SQPrintFunc * print_func
 Points to either nullptr, or a custom print handler.
 
bool crashed
 True if the squirrel script made an error.
 
int overdrawn_ops
 The amount of operations we have overdrawn.
 
const char * APIName
 Name of the API used for this squirrel.
 
std::unique_ptr< ScriptAllocatorallocator
 Allocator object used by this script.
 

Friends

class ScriptAllocatorScope
 

Detailed Description

Definition at line 23 of file squirrel.hpp.

Member Typedef Documentation

◆ SQPrintFunc

typedef void() Squirrel::SQPrintFunc(bool error_msg, const std::string &message)
private

Definition at line 27 of file squirrel.hpp.

Constructor & Destructor Documentation

◆ Squirrel()

Squirrel::Squirrel ( const char *  APIName)

Definition at line 513 of file squirrel.cpp.

◆ ~Squirrel()

Squirrel::~Squirrel ( )

Definition at line 728 of file squirrel.cpp.

Member Function Documentation

◆ _RunError()

SQInteger Squirrel::_RunError ( HSQUIRRELVM  vm)
staticprivate

The internal RunError handler.

It looks up the real error and calls RunError with it.

Definition at line 252 of file squirrel.cpp.

References RunError(), and vm.

Referenced by Initialize().

◆ AddClassBegin() [1/2]

void Squirrel::AddClassBegin ( const char *  class_name)

Adds a class to the global scope.

Make sure to call AddClassEnd when you are done adding methods.

Definition at line 313 of file squirrel.cpp.

References vm.

Referenced by AILibrary::RegisterAPI(), and GameLibrary::RegisterAPI().

◆ AddClassBegin() [2/2]

void Squirrel::AddClassBegin ( const char *  class_name,
const char *  parent_class 
)

Adds a class to the global scope, extending 'parent_class'.

Make sure to call AddClassEnd when you are done adding methods.

Definition at line 322 of file squirrel.cpp.

References Debug, and vm.

◆ AddClassEnd()

void Squirrel::AddClassEnd ( )

Finishes adding a class to the global scope.

If this isn't called, no class is really created.

Definition at line 337 of file squirrel.cpp.

References vm.

Referenced by AILibrary::RegisterAPI(), and GameLibrary::RegisterAPI().

◆ AddConst() [1/3]

void Squirrel::AddConst ( const char *  var_name,
bool  value 
)

Adds a const to the stack.

Depending on the current state this means either a const to a class or to the global space.

Definition at line 304 of file squirrel.cpp.

References vm.

◆ AddConst() [2/3]

void Squirrel::AddConst ( const char *  var_name,
int  value 
)

Adds a const to the stack.

Depending on the current state this means either a const to a class or to the global space.

Definition at line 295 of file squirrel.cpp.

References vm.

◆ AddConst() [3/3]

void Squirrel::AddConst ( const char *  var_name,
uint  value 
)
inline

Adds a const to the stack.

Depending on the current state this means either a const to a class or to the global space.

Definition at line 111 of file squirrel.hpp.

References AddConst().

Referenced by AddConst().

◆ AddMethod()

void Squirrel::AddMethod ( const char *  method_name,
SQFUNCTION  proc,
uint  nparam = 0,
const char *  params = nullptr,
void *  userdata = nullptr,
int  size = 0 
)

◆ CallBoolMethod()

bool Squirrel::CallBoolMethod ( HSQOBJECT  instance,
const char *  method_name,
bool *  res,
int  suspend 
)

Definition at line 450 of file squirrel.cpp.

◆ CallIntegerMethod()

bool Squirrel::CallIntegerMethod ( HSQOBJECT  instance,
const char *  method_name,
int *  res,
int  suspend 
)

Definition at line 441 of file squirrel.cpp.

◆ CallMethod() [1/2]

bool Squirrel::CallMethod ( HSQOBJECT  instance,
const char *  method_name,
HSQOBJECT *  ret,
int  suspend 
)

Call a method of an instance, in various flavors.

Returns
False if the script crashed or returned a wrong type.

Definition at line 398 of file squirrel.cpp.

References allocator, crashed, Debug, IsSuspended(), and vm.

Referenced by ScriptInstance::GameLoop(), ScriptInfo::GetSettings(), and ScriptInstance::Save().

◆ CallMethod() [2/2]

bool Squirrel::CallMethod ( HSQOBJECT  instance,
const char *  method_name,
int  suspend 
)
inline

Definition at line 161 of file squirrel.hpp.

◆ CallStringMethod()

bool Squirrel::CallStringMethod ( HSQOBJECT  instance,
const char *  method_name,
std::string *  res,
int  suspend 
)

Definition at line 432 of file squirrel.cpp.

◆ CanSuspend()

bool Squirrel::CanSuspend ( )

Are we allowed to suspend the squirrel script at this moment?

Definition at line 801 of file squirrel.cpp.

◆ CollectGarbage()

void Squirrel::CollectGarbage ( )

Tell the VM to do a garbage collection run.

Definition at line 392 of file squirrel.cpp.

References vm.

Referenced by ScriptInstance::CollectGarbage().

◆ CompileError()

void Squirrel::CompileError ( HSQUIRRELVM  vm,
const SQChar *  desc,
const SQChar *  source,
SQInteger  line,
SQInteger  column 
)
staticprotected

The CompileError handler.

Definition at line 204 of file squirrel.cpp.

References crashed, Debug, print_func, and vm.

Referenced by Initialize().

◆ CrashOccurred()

void Squirrel::CrashOccurred ( )

Set the script status to crashed.

Definition at line 796 of file squirrel.cpp.

References crashed.

Referenced by ScriptInstance::Save().

◆ CreateClassInstance()

bool Squirrel::CreateClassInstance ( const std::string &  class_name,
void *  real_instance,
HSQOBJECT *  instance 
)

Exactly the same as CreateClassInstanceVM, only callable without instance of Squirrel.

Definition at line 507 of file squirrel.cpp.

References CreateClassInstanceVM(), and vm.

Referenced by ScriptInstance::Initialize().

◆ CreateClassInstanceVM()

bool Squirrel::CreateClassInstanceVM ( HSQUIRRELVM  vm,
const std::string &  class_name,
void *  real_instance,
HSQOBJECT *  instance,
SQRELEASEHOOK  release_hook,
bool  prepend_API_name = false 
)
static

Creates a class instance.

Parameters
vmThe VM to create the class instance for
class_nameThe name of the class of which we create an instance.
real_instanceThe instance to the real class, if it represents a real class.
instanceReturning value with the pointer to the instance.
release_hookOptional param to give a release hook.
prepend_API_nameOptional parameter; if true, the class_name is prefixed with the current API name.
Returns
False if creating failed.

Definition at line 459 of file squirrel.cpp.

References Debug, GetAPIName(), and vm.

Referenced by CreateClassInstance().

◆ DecreaseOps()

void Squirrel::DecreaseOps ( HSQUIRRELVM  vm,
int  amount 
)
static

Tell the VM to remove amount ops from the number of ops till suspend.

Definition at line 781 of file squirrel.cpp.

References vm.

Referenced by ScriptInstance::Pause().

◆ ErrorPrintFunc()

void Squirrel::ErrorPrintFunc ( HSQUIRRELVM  vm,
const std::string &  s 
)
staticprotected

If an error has to be print, this function is called.

Definition at line 219 of file squirrel.cpp.

References print_func, and vm.

Referenced by RunError().

◆ GetAllocatedMemory()

size_t Squirrel::GetAllocatedMemory ( ) const
noexcept

Get number of bytes allocated by this VM.

Definition at line 197 of file squirrel.cpp.

References allocator.

◆ GetAPIName()

const char * Squirrel::GetAPIName ( )
inlineprivate

Get the API name.

Definition at line 45 of file squirrel.hpp.

References APIName.

Referenced by CreateClassInstanceVM(), and LoadFile().

◆ GetGlobalPointer()

static void * Squirrel::GetGlobalPointer ( HSQUIRRELVM  vm)
inlinestatic

Get the pointer as set by SetGlobalPointer.

Definition at line 226 of file squirrel.hpp.

References vm.

Referenced by ScriptInfo::Constructor().

◆ GetInstance()

static bool Squirrel::GetInstance ( HSQUIRRELVM  vm,
HSQOBJECT *  ptr,
int  pos = 1 
)
inlinestatic

Get the Squirrel-instance pointer.

Note
This will only work just after a function-call from within Squirrel to your C++ function.

Definition at line 200 of file squirrel.hpp.

References vm.

Referenced by ScriptInfo::Constructor(), SQConvert::DefSQAdvancedNonStaticCallback(), and SQConvert::DefSQNonStaticCallback().

◆ GetOpsTillSuspend()

SQInteger Squirrel::GetOpsTillSuspend ( )

How many operations can we execute till suspension?

Definition at line 807 of file squirrel.cpp.

Referenced by ScriptInstance::GetOpsTillSuspend().

◆ GetRealInstance()

static bool Squirrel::GetRealInstance ( HSQUIRRELVM  vm,
SQUserPointer *  ptr 
)
inlinestatic

Get the real-instance pointer.

Note
This will only work just after a function-call from within Squirrel to your C++ function.

Definition at line 193 of file squirrel.hpp.

References vm.

◆ GetVM()

HSQUIRRELVM Squirrel::GetVM ( )
inline

◆ HasScriptCrashed()

bool Squirrel::HasScriptCrashed ( )

Find out if the squirrel script made an error before.

Definition at line 791 of file squirrel.cpp.

References crashed.

Referenced by ScriptInstance::GameLoop(), and ScriptInstance::Save().

◆ Initialize()

void Squirrel::Initialize ( )
private

Perform all initialization steps to create the engine.

Definition at line 519 of file squirrel.cpp.

References _RunError(), CompileError(), crashed, global_pointer, overdrawn_ops, print_func, PrintFunc(), squirrel_register_global_std(), and vm.

Referenced by Reset().

◆ InsertResult() [1/3]

void Squirrel::InsertResult ( bool  result)

Definition at line 759 of file squirrel.cpp.

◆ InsertResult() [2/3]

void Squirrel::InsertResult ( int  result)

Definition at line 770 of file squirrel.cpp.

◆ InsertResult() [3/3]

void Squirrel::InsertResult ( uint  result)
inline

Definition at line 154 of file squirrel.hpp.

◆ IsSuspended()

bool Squirrel::IsSuspended ( )

Did the squirrel code suspend or return normally.

Returns
True if the function suspended.

Definition at line 786 of file squirrel.cpp.

Referenced by CallMethod(), ScriptInstance::GameLoop(), ScriptInstance::Initialize(), and ScriptInstance::Save().

◆ LoadFile()

SQRESULT Squirrel::LoadFile ( HSQUIRRELVM  vm,
const std::string &  filename,
SQBool  printerror 
)

Load a file to a given VM.

Definition at line 621 of file squirrel.cpp.

References AI_DIR, AI_LIBRARY_DIR, FioFOpenFile(), GAME_DIR, GAME_LIBRARY_DIR, GetAPIName(), and vm.

◆ LoadScript() [1/2]

bool Squirrel::LoadScript ( const std::string &  script)

Load a script.

Parameters
scriptThe full script-name to load.
Returns
False if loading failed.

Definition at line 723 of file squirrel.cpp.

References LoadScript().

Referenced by ScriptScanner::AddFile(), ScriptInstance::Initialize(), ScriptInstance::LoadCompatibilityScripts(), LoadScript(), and SquirrelStd::require().

◆ LoadScript() [2/2]

bool Squirrel::LoadScript ( HSQUIRRELVM  vm,
const std::string &  script,
bool  in_root = true 
)

Definition at line 699 of file squirrel.cpp.

◆ MethodExists()

bool Squirrel::MethodExists ( HSQOBJECT  instance,
const char *  method_name 
)

◆ ObjectToBool()

static bool Squirrel::ObjectToBool ( HSQOBJECT *  ptr)
inlinestatic

Convert a Squirrel-object to a bool.

Definition at line 215 of file squirrel.hpp.

◆ ObjectToInteger()

static int Squirrel::ObjectToInteger ( HSQOBJECT *  ptr)
inlinestatic

Convert a Squirrel-object to an integer.

Definition at line 210 of file squirrel.hpp.

◆ ObjectToString()

static const char * Squirrel::ObjectToString ( HSQOBJECT *  ptr)
inlinestatic

Convert a Squirrel-object to a string.

Definition at line 205 of file squirrel.hpp.

◆ PrintFunc()

void Squirrel::PrintFunc ( HSQUIRRELVM  vm,
const std::string &  s 
)
staticprotected

If a user runs 'print' inside a script, this function gets the params.

Definition at line 267 of file squirrel.cpp.

References print_func, and vm.

Referenced by Initialize().

◆ ReleaseObject()

void Squirrel::ReleaseObject ( HSQOBJECT *  ptr)
inline

Release a SQ object.

Definition at line 241 of file squirrel.hpp.

Referenced by ScriptInstance::Died(), and ScriptInstance::ReleaseSQObject().

◆ Reset()

void Squirrel::Reset ( )

Completely reset the engine; start from scratch.

Definition at line 753 of file squirrel.cpp.

References Initialize(), and Uninitialize().

Referenced by ScriptScanner::ResetEngine().

◆ Resume()

bool Squirrel::Resume ( int  suspend = -1)

Resume a VM when it was suspended via a throw.

Definition at line 363 of file squirrel.cpp.

References allocator, crashed, overdrawn_ops, and vm.

Referenced by ScriptInstance::GameLoop().

◆ ResumeError()

void Squirrel::ResumeError ( )

Resume the VM with an error so it prints a stack trace.

Definition at line 385 of file squirrel.cpp.

References crashed, and vm.

Referenced by ScriptInstance::GameLoop(), ScriptInstance::Initialize(), and ScriptInstance::Save().

◆ RunError()

void Squirrel::RunError ( HSQUIRRELVM  vm,
const SQChar *  error 
)
staticprotected

The RunError handler.

Definition at line 230 of file squirrel.cpp.

References ErrorPrintFunc(), print_func, and vm.

Referenced by _RunError().

◆ SetGlobalPointer()

void Squirrel::SetGlobalPointer ( void *  ptr)
inline

Sets a pointer in the VM that is reachable from where ever you are in SQ.

Useful to keep track of the main instance.

Definition at line 221 of file squirrel.hpp.

Referenced by ScriptInstance::Initialize(), and ScriptScanner::ResetEngine().

◆ SetPrintFunction()

void Squirrel::SetPrintFunction ( SQPrintFunc *  func)
inline

Set a custom print function, so you can handle outputs from SQ yourself.

Definition at line 231 of file squirrel.hpp.

Referenced by ScriptInstance::ScriptInstance().

◆ ThrowError()

void Squirrel::ThrowError ( const std::string_view  error)
inline

Throw a Squirrel error that will be nicely displayed to the user.

Definition at line 236 of file squirrel.hpp.

Referenced by ScriptInfo::AddLabels(), ScriptInfo::AddSetting(), ScriptInfo::CheckMethod(), ScriptInstance::GameLoop(), ScriptInstance::Initialize(), and ScriptInstance::Save().

◆ Uninitialize()

void Squirrel::Uninitialize ( )
private

Perform all the cleanups for the engine.

Definition at line 733 of file squirrel.cpp.

References allocator.

Referenced by Reset().

Friends And Related Symbol Documentation

◆ ScriptAllocatorScope

friend class ScriptAllocatorScope
friend

Definition at line 24 of file squirrel.hpp.

Field Documentation

◆ allocator

std::unique_ptr<ScriptAllocator> Squirrel::allocator
private

Allocator object used by this script.

Definition at line 35 of file squirrel.hpp.

Referenced by CallMethod(), GetAllocatedMemory(), Resume(), and Uninitialize().

◆ APIName

const char* Squirrel::APIName
private

Name of the API used for this squirrel.

Definition at line 34 of file squirrel.hpp.

Referenced by GetAPIName().

◆ crashed

bool Squirrel::crashed
private

True if the squirrel script made an error.

Definition at line 32 of file squirrel.hpp.

Referenced by CallMethod(), CompileError(), CrashOccurred(), HasScriptCrashed(), Initialize(), MethodExists(), Resume(), and ResumeError().

◆ global_pointer

void* Squirrel::global_pointer
private

Can be set by who ever initializes Squirrel.

Definition at line 30 of file squirrel.hpp.

Referenced by Initialize().

◆ overdrawn_ops

int Squirrel::overdrawn_ops
private

The amount of operations we have overdrawn.

Definition at line 33 of file squirrel.hpp.

Referenced by Initialize(), and Resume().

◆ print_func

SQPrintFunc* Squirrel::print_func
private

Points to either nullptr, or a custom print handler.

Definition at line 31 of file squirrel.hpp.

Referenced by CompileError(), ErrorPrintFunc(), Initialize(), PrintFunc(), and RunError().

◆ vm


The documentation for this class was generated from the following files: