OpenTTD Source: Squirrel Class Reference

OpenTTD Source 12.2

Public Member Functions | Static Public Member Functions | Static Protected Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | Friends
Squirrel Class Reference

## Public Member Functions
| Squirrel (const char *APIName)
HSQUIRRELVM | GetVM ()
| Get the squirrel VM. More...
bool | LoadScript (const char *script)
| Load a script. More...
bool | LoadScript (HSQUIRRELVM vm, const char *script, bool in_root=true)
SQRESULT | LoadFile (HSQUIRRELVM vm, const char *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. More...
void | AddConst (const char *var_name, int value)
| Adds a const to the stack. More...
void | AddConst (const char *var_name, uint value)
| Adds a const to the stack. More...
void | AddConst (const char *var_name, bool value)
| Adds a const to the stack. More...
void | AddClassBegin (const char *class_name)
| Adds a class to the global scope. More...
void | AddClassBegin (const char *class_name, const char *parent_class)
| Adds a class to the global scope, extending 'parent_class'. More...
void | AddClassEnd ()
| Finishes adding a class to the global scope. More...
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. More...
bool | CallMethod (HSQOBJECT instance, const char *method_name, int suspend)
bool | CallStringMethodStrdup (HSQOBJECT instance, const char *method_name, const char **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 char *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. More...
void | SetPrintFunction (SQPrintFunc *func)
| Set a custom print function, so you can handle outputs from SQ yourself.
void | ThrowError (const char *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. More...
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 char *class_name, void *real_instance, HSQOBJECT *instance, SQRELEASEHOOK release_hook, bool prepend_API_name=false)
| Creates a class instance. More...
static bool | GetRealInstance (HSQUIRRELVM vm, SQUserPointer *ptr)
| Get the real-instance pointer. More...
static bool | GetInstance (HSQUIRRELVM vm, HSQOBJECT *ptr, int pos=1)
| Get the Squirrel-instance pointer. More...
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 SQChar *s,...) WARN_FORMAT(2
| If a user runs 'print' inside a script, this function gets the params.
static void static void | ErrorPrintFunc (HSQUIRRELVM vm, const SQChar *s,...) WARN_FORMAT(2
| If an error has to be print, this function is called.

## Private Types
typedef void() | SQPrintFunc(bool error_msg, const SQChar *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. More...

## 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< ScriptAllocator > | allocator
| Allocator object used by this script.

## Friends
class | ScriptAllocatorScope

## Detailed Description

Definition at line 23 of file squirrel.hpp.

## 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 267 of file squirrel.cpp.

References RunError(), and vm.

## ◆ 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 336 of file squirrel.cpp.

References vm.

Referenced by GameLibrary::RegisterAPI(), and AILibrary::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 345 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 360 of file squirrel.cpp.

References vm.

Referenced by GameLibrary::RegisterAPI(), and AILibrary::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 327 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 318 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`
| ) |  |

Adds a function to the stack.

Depending on the current state this means either a method or a global function.

Definition at line 301 of file squirrel.cpp.

References vm.

Referenced by DefSQClass< CL, ST >::DefSQAdvancedMethod(), DefSQClass< CL, ST >::DefSQAdvancedStaticMethod(), DefSQClass< CL, ST >::DefSQMethod(), DefSQClass< CL, ST >::DefSQStaticMethod(), AIInfo::RegisterAPI(), GameInfo::RegisterAPI(), GameLibrary::RegisterAPI(), AILibrary::RegisterAPI(), squirrel_register_global_std(), and squirrel_register_std().

## ◆ CallMethod()

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 421 of file squirrel.cpp.

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

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

## ◆ CreateClassInstanceVM()

bool Squirrel::CreateClassInstanceVM | ( | HSQUIRRELVM | vm,
|  | const char * | class_name,
|  | void * | real_instance,
|  | HSQOBJECT * | instance,
|  | SQRELEASEHOOK | release_hook,
|  | bool | prepend_API_name = `false`
| ) |  |
| static

Creates a class instance.

Parameters

  vm | The VM to create the class instance for
  class_name | The name of the class of which we create an instance.
  real_instance | The instance to the real class, if it represents a real class.
  instance | Returning value with the pointer to the instance.
  release_hook | Optional param to give a release hook.
  prepend_API_name | Optional parameter; if true, the class_name is prefixed with the current API name.

Returns
  False if creating failed.

Definition at line 483 of file squirrel.cpp.

References Debug, GetAPIName(), seprintf(), and vm.

Referenced by CreateClassInstance().

## ◆ 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().

## ◆ 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

Get the squirrel VM.

Try to avoid using this.

Definition at line 80 of file squirrel.hpp.

References vm.

Referenced by ScriptInstance::CallLoad(), ScriptInstance::GameLoop(), ScriptInstance::Load(), AIInstance::LoadDummyScript(), ScriptInstance::Pause(), RegisterGameTranslation(), ScriptInstance::Save(), and squirrel_register_std().

## ◆ IsSuspended()

bool Squirrel::IsSuspended | ( |  | ) |

Did the squirrel code suspend or return normally.

Returns
  True if the function suspended.

Definition at line 810 of file squirrel.cpp.

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

## ◆ LoadScript()

bool Squirrel::LoadScript | ( | const char * | script | ) |

Load a script.

Parameters

  script | The full script-name to load.

Returns
  False if loading failed.

Definition at line 753 of file squirrel.cpp.

Referenced by ScriptInstance::Initialize().

## ◆ 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().

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

- src/script/squirrel.hpp
- src/script/squirrel.cpp