Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | Static Private Member Functions | Private Attributes | Friends

# ScriptInstance Class Reference

Runtime information about a script like a pointer to the squirrel vm and the current state. More...

`#include <script_instance.hpp>`

Inheritance diagram for ScriptInstance:

## Public Member Functions
| ScriptInstance (const char *APIName)
| Create a new script.
void | Initialize (const char *main_script, const char *instance_name, CompanyID company)
| Initialize the script and prepare it for its first run.
virtual int | GetSetting (const char *name)=0
| Get the value of a setting of the current instance.
virtual class ScriptInfo * | FindLibrary (const char *library, int version)=0
| Find a library.
void | Continue ()
| A script in multiplayer waits for the server to handle his DoCommand.
void | GameLoop ()
| Run the GameLoop of a script.
void | CollectGarbage () const
| Let the VM collect any garbage.
class ScriptStorage * | GetStorage ()
| Get the storage of this script.
void * | GetLogPointer ()
| Get the log pointer of this script.
class ScriptController * | GetController ()
| Get the controller attached to the instance.
bool | IsDead () const
| Return the "this script died" value.
void | Save ()
| Call the script Save function and save all data in the savegame.
void | Load (int version)
| Load data from a savegame and store it on the stack.
void | Pause ()
| Suspends the script for the current tick and then pause the execution of script.
bool | IsPaused ()
| Checks if the script is paused.
void | Unpause ()
| Resume execution of the script.
SQInteger | GetOpsTillSuspend ()
| Get the number of operations the script can execute before being suspended.
void | DoCommandCallback (const CommandCost &result, TileIndex tile, uint32 p1, uint32 p2)
| DoCommand callback function for all commands executed by scripts.
void | InsertEvent (class ScriptEvent *event)
| Insert an event for this script.
bool | IsSleeping ()
| Check if the instance is sleeping, which either happened because the script executed a DoCommand, executed this.Sleep() or it has been paused.
## Static Public Member Functions
static void | DoCommandReturn (ScriptInstance *instance)
| Return a true/false reply for a DoCommand.
static void | DoCommandReturnVehicleID (ScriptInstance *instance)
| Return a VehicleID reply for a DoCommand.
static void | DoCommandReturnSignID (ScriptInstance *instance)
| Return a SignID reply for a DoCommand.
static void | DoCommandReturnGroupID (ScriptInstance *instance)
| Return a GroupID reply for a DoCommand.
static void | DoCommandReturnGoalID (ScriptInstance *instance)
| Return a GoalID reply for a DoCommand.
static void | SaveEmpty ()
| Don't save any data in the savegame.
static void | LoadEmpty ()
| Load and discard data from a savegame.
## Protected Member Functions
virtual void | RegisterAPI ()
| Register all API functions to the VM.
bool | LoadCompatibilityScripts (const char *api_version, Subdirectory dir)
| Load squirrel scripts to emulate an older API.
virtual void | Died ()
| Tell the script it died.
virtual CommandCallback * | GetDoCommandCallback ()=0
| Get the callback handling DoCommands in case of networking.
virtual void | LoadDummyScript ()=0
| Load the dummy script.
## Protected Attributes
class Squirrel * | engine
| A wrapper around the squirrel vm.
const char * | versionAPI
| Current API used by this script.
## Private Member Functions
bool | CallLoad ()
| Call the script Load function if it exists and data was loaded from a savegame.
## Static Private Member Functions
static bool | SaveObject (HSQUIRRELVM vm, SQInteger index, int max_depth, bool test)
| Save one object (int / string / array / table) to the savegame.
static bool | LoadObjects (HSQUIRRELVM vm)
| Load all objects from a savegame.
## Private Attributes
class ScriptController * | controller
| The script main class.
class ScriptStorage * | storage
| Some global information for each running script.
SQObject * | instance
| Squirrel-pointer to the script main class.
bool | is_started
| Is the scripts constructor executed?
bool | is_dead
| True if the script has been stopped.
bool | is_save_data_on_stack
| Is the save data still on the squirrel stack?
int | suspend
| The amount of ticks to suspend this script before it's allowed to continue.
bool | is_paused
| Is the script paused? (a paused script will not be executed until unpaused).
Script_SuspendCallbackProc * | callback
| Callback that should be called in the next tick the script runs.
## Friends
class | ScriptObject
class | ScriptController

## Detailed Description

Runtime information about a script like a pointer to the squirrel vm and the current state.

Definition at line 25 of file script_instance.hpp.

## Member Function Documentation

void ScriptInstance::Continue | ( |  | ) |

A script in multiplayer waits for the server to handle his DoCommand.

It keeps waiting for this until this function is called.

Definition at line 142 of file script_instance.cpp.

References suspend.

Referenced by CcGame().

void ScriptInstance::DoCommandCallback | ( | const CommandCost & | result,
|  | TileIndex | tile,
|  | uint32 | p1,
|  | uint32 | p2 |
| ) |  |  |

DoCommand callback function for all commands executed by scripts.

Parameters:

  | result | The result of the command.
  | tile | The tile on which the command was executed.
  | p1 | p1 as given to DoCommandPInternal.
  | p2 | p2 as given to DoCommandPInternal.

Definition at line 671 of file script_instance.cpp.

References CommandCost::Failed(), CommandCost::GetCost(), CommandCost::GetErrorMessage(), and CommandCost::Succeeded().

Referenced by CcGame().

virtual class ScriptInfo* ScriptInstance::FindLibrary | ( | const char * | library,
|  | int | version |
| ) |  |  | `[pure virtual]`

Find a library.

Parameters:

  | library | The library name to find.
  | version | The version the library should have.

Returns:
  The library if found, NULL otherwise.

Implemented in AIInstance, and GameInstance.

SQInteger ScriptInstance::GetOpsTillSuspend | ( |  | ) |

Get the number of operations the script can execute before being suspended.

This function is safe to call from within a function called by the script.

Returns:
  The number of operations to execute.

Definition at line 666 of file script_instance.cpp.

References engine, and Squirrel::GetOpsTillSuspend().

virtual int ScriptInstance::GetSetting | ( | const char * | name | ) | `[pure virtual]`

Get the value of a setting of the current instance.

Parameters:

  | name | The name of the setting.

Returns:
  the value for the setting, or -1 if the setting is not known.

Implemented in AIInstance, and GameInstance.

void ScriptInstance::Initialize | ( | const char * | main_script,
|  | const char * | instance_name,
|  | CompanyID | company |
| ) |  |  |

Initialize the script and prepare it for its first run.

Parameters:

  | main_script | The full path of the script to load.
  | instance_name | The name of the instance out of the script to load.
  | company | Which company this script is serving.

Definition at line 67 of file script_instance.cpp.

References controller, Squirrel::CreateClassInstance(), Died(), engine, Script_FatalError::GetErrorMessage(), instance, is_dead, Squirrel::IsSuspended(), LoadDummyScript(), Squirrel::LoadScript(), RegisterAPI(), Squirrel::ResumeError(), Squirrel::SetGlobalPointer(), and Squirrel::ThrowError().

void ScriptInstance::InsertEvent | ( | class ScriptEvent * | event | ) |

Insert an event for this script.

Parameters:

  | event | The event to insert.

Definition at line 685 of file script_instance.cpp.

Referenced by Game::NewEvent().

bool ScriptInstance::IsPaused | ( |  | ) |

Checks if the script is paused.

Returns:
  true if the script is paused, otherwise false

Definition at line 539 of file script_instance.cpp.

References is_paused.

Referenced by Game::IsPaused(), and AIDebugWindow::OnPaint().

void ScriptInstance::Load | ( | int | version | ) |

Load data from a savegame and store it on the stack.

Parameters:

  | version | The version of the script when saving, or -1 if this was not the original script saving the game.

Definition at line 610 of file script_instance.cpp.

References engine, Squirrel::GetVM(), is_save_data_on_stack, LoadEmpty(), LoadObjects(), and SlObject().

Referenced by Game::Load(), and AI::Load().

bool ScriptInstance::LoadCompatibilityScripts | ( | const char * | api_version,
|  | Subdirectory | dir |
| ) |  |  | `[protected]`

Load squirrel scripts to emulate an older API.

Parameters:

  | api_version,: | API version to load scripts for
  | dir | Subdirectory to find the scripts in

Returns:
  true iff script loading should proceed

Definition at line 109 of file script_instance.cpp.

References DEBUG, engine, FileExists(), FOR_ALL_SEARCHPATHS, lastof, Squirrel::LoadScript(), seprintf(), and ttd_strlcat().

Referenced by GameInstance::RegisterAPI(), and AIInstance::RegisterAPI().

bool ScriptInstance::LoadObjects | ( | HSQUIRRELVM | vm | ) | `[static, private]`

Load all objects from a savegame.

Returns:
  True if the loading was successful.

Definition at line 544 of file script_instance.cpp.

References SlArray(), SlObject(), SQSL_ARRAY, SQSL_ARRAY_TABLE_END, SQSL_BOOL, SQSL_INT, SQSL_NULL, SQSL_STRING, and SQSL_TABLE.

Referenced by Load(), and LoadEmpty().

void ScriptInstance::Pause | ( |  | ) |

Suspends the script for the current tick and then pause the execution of script.

The script will not be resumed from its suspended state until the script has been unpaused.

Definition at line 525 of file script_instance.cpp.

References _settings_game, Squirrel::DecreaseOps(), engine, Squirrel::GetVM(), is_paused, GameSettings::script, and ScriptSettings::script_max_opcode_till_suspend.

Referenced by Game::Pause().

bool ScriptInstance::SaveObject | ( | HSQUIRRELVM | vm,
|  | SQInteger | index,
|  | int | max_depth,
|  | bool | test |
| ) |  |  | `[static, private]`

Save one object (int / string / array / table) to the savegame.

Parameters:

  | vm | The virtual machine to get all the data from.
  | index | The index on the squirrel stack of the element to save.
  | max_depth | The maximum depth recursive arrays / tables will be stored with before an error is returned.
  | test | If true, don't really store the data but only check if it is valid.

Returns:
  True if the saving was successful.

Definition at line 330 of file script_instance.cpp.

References SlArray(), and SlObject().

Referenced by Save().

void ScriptInstance::Unpause | ( |  | ) |

Resume execution of the script.

This function will not actually execute the script, but set a flag so that the script is executed my the usual mechanism that executes the script.

Definition at line 534 of file script_instance.cpp.

References is_paused.

Referenced by Game::Unpause().

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

- src/script/script_instance.hpp
- src/script/script_instance.cpp