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 | Suspend ()
| Reduces the number of opcodes the script have left to zero.
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, or executed this.Sleep().
## 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.
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.
## 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.
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 24 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 118 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 633 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 628 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 65 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 647 of file script_instance.cpp.

Referenced by Game::NewEvent().

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 572 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::LoadObjects | ( | HSQUIRRELVM | vm | ) | `[static, private]`

Load all objects from a savegame.

Returns:
  True if the loading was successful.

Definition at line 506 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().

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 305 of file script_instance.cpp.

References SlArray(), and SlObject().

Referenced by Save().

void ScriptInstance::Suspend | ( |  | ) |

Reduces the number of opcodes the script have left to zero.

Unless the script is in a state where it cannot suspend it will be suspended for the reminder of the current tick. This function is safe to call from within a function called by the script.

Definition at line 500 of file script_instance.cpp.

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

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

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