This class represents the angelscript scripting interface. More...

#include <ScriptEngine.h>

Inheritance diagram for RoR::ScriptEngine:

Public Member Functions
	ScriptEngine ()

	~ScriptEngine ()

ScriptUnitID_t	loadScript (Ogre::String filename, ScriptCategory category=ScriptCategory::TERRAIN, ActorPtr associatedActor=nullptr, std::string buffer="")
	Loads a script. More...

void	unloadScript (ScriptUnitID_t unique_id)
	Unloads a script. More...

void	framestep (Ogre::Real dt)
	Calls the script's framestep function to be able to use timed things inside the script. More...

void	setForwardScriptLogToConsole (bool doForward)

void	triggerEvent (scriptEvents eventnum, int arg1=0, int arg2ex=0, int arg3ex=0, int arg4ex=0, std::string arg5ex="", std::string arg6ex="", std::string arg7ex="", std::string arg8ex="")
	triggers an event; Not to be used by the end-user. More...

void	setEventsEnabled (bool val)

ScriptRetCode_t	executeString (Ogre::String command)
	executes a string (useful for the console) More...

void	queueStringForExecution (const Ogre::String command)
	Queues a string for execution. More...

ScriptRetCode_t	addFunction (const Ogre::String &arg, const ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Adds a global function to the script. More...

ScriptRetCode_t	functionExists (const Ogre::String &arg, const ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Checks if a global function exists. More...

ScriptRetCode_t	deleteFunction (const Ogre::String &arg, const ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Deletes a global function from the script. More...

ScriptRetCode_t	addVariable (const Ogre::String &arg, const ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Adds a global variable to the script. More...

ScriptRetCode_t	variableExists (const Ogre::String &arg, const ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Adds a global variable to the script. More...

ScriptRetCode_t	deleteVariable (const Ogre::String &arg, const ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Deletes a global variable from the script. More...

ScriptRetCode_t	getVariable (const Ogre::String &varName, void *ref, int typeID, ScriptUnitID_t nid=SCRIPTUNITID_DEFAULT)
	Retrieves a global variable from any running script. More...

AngelScript::asIScriptFunction *	getFunctionByDeclAndLogCandidates (ScriptUnitID_t nid, GetFuncFlags_t flags, const std::string &funcName, const std::string &fmtFuncDecl)
	Finds a function by full declaration, and if not found, finds candidates by name and logs them to Angelscript.log. More...

int	fireEvent (std::string instanceName, float intensity)

void	envokeCallback (int functionId, eventsource_t *source, NodeNum_t nodenum=NODENUM_INVALID, int type=0)

void	forwardExceptionAsScriptEvent (const std::string &from)
	Forwards useful info from C++ `try{}catch{}` exceptions to script in the form of game event. More...

AngelScript::asIScriptEngine *	getEngine ()

void	messageLogged (const Ogre::String &message, Ogre::LogMessageLevel lml, bool maskDebug, const Ogre::String &logName, bool &skipThisMessage)

bool	scriptUnitExists (ScriptUnitID_t unique_id)

ScriptUnit &	getScriptUnit (ScriptUnitID_t unique_id)

ScriptUnitMap const &	getScriptUnits () const

Protected Member Functions
Housekeeping
void	init ()
	This function initialzies the engine and registeres all types. More...

Ogre::String	composeModuleName (Ogre::String const &scriptName, ScriptCategory origin, ScriptUnitID_t id)
	Packs name + important info to one string, for logging and reporting purposes. More...

int	setupScriptUnit (int unit_id)
	Helper for `loadScript()`, does the actual building without worry about unit management. More...

bool	prepareContextAndHandleErrors (ScriptUnitID_t nid, int asFunctionID)
	Helper for executing any script function/snippet; does `asIScriptContext::Prepare()` and reports any error. More...

int	executeContextAndHandleErrors (ScriptUnitID_t nid)
	Helper for executing any script function/snippet; registers Line/Exception callbacks (on demand) and set currently executed NID; The `asIScriptContext::Prepare()` and setting args must be already done. More...

ScriptRetCode_t	validateScriptModule (const ScriptUnitID_t nid, AngelScript::asIScriptModule *&out_mod)
	Helper for all manipulations with functions/variables; ensures the script unit exists and is fully set up. More...

Script diagnostics
void	msgCallback (const AngelScript::asSMessageInfo *msg)
	Optional (but very recommended!) callback providing diagnostic info when things fail to start (most notably script errors). More...

void	lineCallback (AngelScript::asIScriptContext *ctx)
	Optional callback which receives diagnostic info for every executed statement. More...

void	exceptionCallback (AngelScript::asIScriptContext *ctx)
	Optional callback invoked when the script critically fails, allowing debugging. More...

Protected Attributes
AngelScript::asIScriptEngine *	engine
	instance of the scripting engine More...

AngelScript::asIScriptContext *	context
	context in which all scripting happens More...

Ogre::Log *	scriptLog

GameScript	m_game_script

ScriptUnitMap	m_script_units

ScriptUnitID_t	m_terrain_script_unit = SCRIPTUNITID_INVALID

ScriptUnitID_t	m_currently_executing_script_unit = SCRIPTUNITID_INVALID

scriptEvents	m_currently_executing_event_trigger = SE_NO_EVENTS

bool	m_events_enabled = true
	Hack to enable fast shutdown without cleanup. More...

InterThreadStoreVector< Ogre::String >	stringExecutionQueue
	The string execution queue. More...

Friends
class	GameScript

Detailed Description

This class represents the angelscript scripting interface.

It can load and execute scripts.

Authors: Thomas Fischer (thomas{AT}rigsofrods{DOT}com)

Definition at line 175 of file ScriptEngine.h.

Constructor & Destructor Documentation

◆ ScriptEngine()

ScriptEngine::ScriptEngine ( )

Definition at line 97 of file ScriptEngine.cpp.

◆ ~ScriptEngine()

ScriptEngine::~ScriptEngine ( )

Definition at line 106 of file ScriptEngine.cpp.

Member Function Documentation

◆ addFunction()

ScriptRetCode_t ScriptEngine::addFunction	(	const Ogre::String &	arg,
		const ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Adds a global function to the script.

Parameters

arg	A declaration for the function.
nid	The script unit ID to act upon - by default the terrain script.

Definition at line 519 of file ScriptEngine.cpp.

◆ addVariable()

ScriptRetCode_t ScriptEngine::addVariable	(	const Ogre::String &	arg,
		const ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Adds a global variable to the script.

Parameters

arg	A declaration for the variable.

Definition at line 624 of file ScriptEngine.cpp.

◆ composeModuleName()

String ScriptEngine::composeModuleName	(	Ogre::String const &	scriptName,
		ScriptCategory	origin,
		ScriptUnitID_t	id
	)

protected

Packs name + important info to one string, for logging and reporting purposes.

Definition at line 823 of file ScriptEngine.cpp.

◆ deleteFunction()

ScriptRetCode_t ScriptEngine::deleteFunction	(	const Ogre::String &	arg,
		const ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Deletes a global function from the script.

Parameters

arg	A declaration for the function.

Definition at line 581 of file ScriptEngine.cpp.

◆ deleteVariable()

ScriptRetCode_t ScriptEngine::deleteVariable	(	const Ogre::String &	arg,
		const ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Deletes a global variable from the script.

Parameters

arg	A declaration for the variable.

Definition at line 656 of file ScriptEngine.cpp.

◆ envokeCallback()

void ScriptEngine::envokeCallback	(	int	functionId,
		eventsource_t *	source,
		NodeNum_t	nodenum = `NODENUM_INVALID`,
		int	type = `0`
	)

Definition at line 462 of file ScriptEngine.cpp.

◆ exceptionCallback()

void ScriptEngine::exceptionCallback ( AngelScript::asIScriptContext * ctx )

protected

Optional callback invoked when the script critically fails, allowing debugging.

https://www.angelcode.com/angelscript/sdk/docs/manual/doc_call_script_func.html#doc_call_script_4

Definition at line 234 of file ScriptEngine.cpp.

◆ executeContextAndHandleErrors()

int ScriptEngine::executeContextAndHandleErrors ( ScriptUnitID_t nid )

protected

Helper for executing any script function/snippet; registers Line/Exception callbacks (on demand) and set currently executed NID; The asIScriptContext::Prepare() and setting args must be already done.

Returns: 0 on success, anything else on error.

Definition at line 278 of file ScriptEngine.cpp.

◆ executeString()

ScriptRetCode_t ScriptEngine::executeString ( Ogre::String command )

executes a string (useful for the console)

Parameters

command string to execute

Definition at line 502 of file ScriptEngine.cpp.

◆ fireEvent()

int ScriptEngine::fireEvent	(	std::string	instanceName,
		float	intensity
	)

Definition at line 432 of file ScriptEngine.cpp.

◆ forwardExceptionAsScriptEvent()

void ScriptEngine::forwardExceptionAsScriptEvent ( const std::string & from )

Forwards useful info from C++ try{}catch{} exceptions to script in the form of game event.

AngelScript doesn't have exceptions in this sense (in AS jargon, 'Exception' means basically 'panic' as in Lua/Rust...) and most exceptions this game encounters (Ogre::Exception) are trivially recoverable, so it doesn't make sense to panic AngelScript when they happen.

Definition at line 247 of file ScriptEngine.cpp.

◆ framestep()

void ScriptEngine::framestep ( Ogre::Real dt )

Calls the script's framestep function to be able to use timed things inside the script.

Parameters

dt	time passed since the last call to this function in seconds

Definition at line 403 of file ScriptEngine.cpp.

◆ functionExists()

ScriptRetCode_t ScriptEngine::functionExists	(	const Ogre::String &	arg,
		const ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Checks if a global function exists.

Parameters

arg	A declaration for the function.

Definition at line 568 of file ScriptEngine.cpp.

◆ getEngine()

AngelScript::asIScriptEngine* RoR::ScriptEngine::getEngine ( )

inline

Definition at line 291 of file ScriptEngine.h.

◆ getFunctionByDeclAndLogCandidates()

asIScriptFunction * ScriptEngine::getFunctionByDeclAndLogCandidates	(	ScriptUnitID_t	nid,
		GetFuncFlags_t	flags,
		const std::string &	funcName,
		const std::string &	fmtFuncDecl
	)

Finds a function by full declaration, and if not found, finds candidates by name and logs them to Angelscript.log.

Returns: Angelscript function on success, null on error.

Definition at line 759 of file ScriptEngine.cpp.

◆ getScriptUnit()

ScriptUnit & ScriptEngine::getScriptUnit ( ScriptUnitID_t unique_id )

Definition at line 1102 of file ScriptEngine.cpp.

◆ getScriptUnits()

ScriptUnitMap const& RoR::ScriptEngine::getScriptUnits ( ) const

inline

Definition at line 303 of file ScriptEngine.h.

◆ getVariable()

ScriptRetCode_t ScriptEngine::getVariable	(	const Ogre::String &	varName,
		void *	ref,
		int	typeID,
		ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Retrieves a global variable from any running script.

Definition at line 676 of file ScriptEngine.cpp.

◆ init()

void ScriptEngine::init ( )

protected

This function initialzies the engine and registeres all types.

Definition at line 119 of file ScriptEngine.cpp.

◆ lineCallback()

void ScriptEngine::lineCallback ( AngelScript::asIScriptContext * ctx )

protected

Optional callback which receives diagnostic info for every executed statement.

https://www.angelcode.com/angelscript/sdk/docs/manual/classas_i_script_context.html#ae2747f643bf9a07364f922c460ef57dd

Definition at line 216 of file ScriptEngine.cpp.

◆ loadScript()

ScriptUnitID_t ScriptEngine::loadScript	(	Ogre::String	filename,
		ScriptCategory	category = `ScriptCategory::TERRAIN`,
		ActorPtr	associatedActor = `nullptr`,
		std::string	buffer = `""`
	)

Loads a script.

Parameters

filename	'.as' file or '.gadget' file to load; if buffer is supplied, this is only a display name.
category	How to treat the script?
associatedActor	Only for category ACTOR
buffer	String with full script body; if empty, a file will be loaded as usual.

Returns: Unique ID of the script unit (because one script file can be loaded multiple times).

Definition at line 828 of file ScriptEngine.cpp.

◆ messageLogged()

void ScriptEngine::messageLogged	(	const Ogre::String &	message,
		Ogre::LogMessageLevel	lml,
		bool	maskDebug,
		const Ogre::String &	logName,
		bool &	skipThisMessage
	)

Definition at line 113 of file ScriptEngine.cpp.

◆ msgCallback()

void ScriptEngine::msgCallback ( const AngelScript::asSMessageInfo * msg )

protected

Optional (but very recommended!) callback providing diagnostic info when things fail to start (most notably script errors).

Definition at line 197 of file ScriptEngine.cpp.

◆ prepareContextAndHandleErrors()

bool ScriptEngine::prepareContextAndHandleErrors	(	ScriptUnitID_t	nid,
		int	asFunctionID
	)

protected

Helper for executing any script function/snippet; does asIScriptContext::Prepare() and reports any error.

Returns: true on success, false on error.

Definition at line 365 of file ScriptEngine.cpp.

◆ queueStringForExecution()

void ScriptEngine::queueStringForExecution ( const Ogre::String command )

Queues a string for execution.

Use this when you want to execute a script statement from another thread.

Parameters

command string to queue for execution

See also: executeString

Definition at line 497 of file ScriptEngine.cpp.

◆ scriptUnitExists()

bool ScriptEngine::scriptUnitExists ( ScriptUnitID_t unique_id )

Definition at line 1096 of file ScriptEngine.cpp.

◆ setEventsEnabled()

void RoR::ScriptEngine::setEventsEnabled ( bool val )

inline

Definition at line 215 of file ScriptEngine.h.

◆ setForwardScriptLogToConsole()

void ScriptEngine::setForwardScriptLogToConsole ( bool doForward )

Definition at line 1084 of file ScriptEngine.cpp.

◆ setupScriptUnit()

int ScriptEngine::setupScriptUnit ( int unit_id )

protected

Helper for loadScript(), does the actual building without worry about unit management.

Returns: 0 on success, anything else on error.

Definition at line 910 of file ScriptEngine.cpp.

◆ triggerEvent()

void ScriptEngine::triggerEvent	(	scriptEvents	eventnum,
		int	arg1 = `0`,
		int	arg2ex = `0`,
		int	arg3ex = `0`,
		int	arg4ex = `0`,
		std::string	arg5ex = `""`,
		std::string	arg6ex = `""`,
		std::string	arg7ex = `""`,
		std::string	arg8ex = `""`
	)

triggers an event; Not to be used by the end-user.

Runs either eventCallbackEx(), if registered, or eventCallback(), if registered, in this order.

Definition at line 781 of file ScriptEngine.cpp.

◆ unloadScript()

void ScriptEngine::unloadScript ( ScriptUnitID_t unique_id )

Unloads a script.

Parameters

unique_id The script unit ID as returned by loadScript()

Definition at line 1066 of file ScriptEngine.cpp.

◆ validateScriptModule()

ScriptRetCode_t ScriptEngine::validateScriptModule	(	const ScriptUnitID_t	nid,
		AngelScript::asIScriptModule *&	out_mod
	)

protected

Helper for all manipulations with functions/variables; ensures the script unit exists and is fully set up.

Returns: see RoR::ScriptRetCode ~ 0 on success, negative number on error.

Definition at line 385 of file ScriptEngine.cpp.

◆ variableExists()

ScriptRetCode_t ScriptEngine::variableExists	(	const Ogre::String &	arg,
		const ScriptUnitID_t	nid = `SCRIPTUNITID_DEFAULT`
	)

Adds a global variable to the script.

Parameters

arg	A declaration for the variable.

Definition at line 640 of file ScriptEngine.cpp.

Friends And Related Function Documentation

◆ GameScript

friend class GameScript

friend

Definition at line 177 of file ScriptEngine.h.

Field Documentation

◆ context

AngelScript::asIScriptContext* RoR::ScriptEngine::context

protected

context in which all scripting happens

Definition at line 369 of file ScriptEngine.h.

◆ engine

AngelScript::asIScriptEngine* RoR::ScriptEngine::engine

protected

instance of the scripting engine

Definition at line 368 of file ScriptEngine.h.

◆ m_currently_executing_event_trigger

scriptEvents RoR::ScriptEngine::m_currently_executing_event_trigger = SE_NO_EVENTS

protected

Definition at line 375 of file ScriptEngine.h.

◆ m_currently_executing_script_unit

ScriptUnitID_t RoR::ScriptEngine::m_currently_executing_script_unit = SCRIPTUNITID_INVALID

protected

Definition at line 374 of file ScriptEngine.h.

◆ m_events_enabled

bool RoR::ScriptEngine::m_events_enabled = true

protected

Hack to enable fast shutdown without cleanup.

Definition at line 376 of file ScriptEngine.h.

◆ m_game_script

GameScript RoR::ScriptEngine::m_game_script

protected

Definition at line 371 of file ScriptEngine.h.

◆ m_script_units

ScriptUnitMap RoR::ScriptEngine::m_script_units

protected

Definition at line 372 of file ScriptEngine.h.

◆ m_terrain_script_unit

ScriptUnitID_t RoR::ScriptEngine::m_terrain_script_unit = SCRIPTUNITID_INVALID

protected

Definition at line 373 of file ScriptEngine.h.

◆ scriptLog

Ogre::Log* RoR::ScriptEngine::scriptLog

protected

Definition at line 370 of file ScriptEngine.h.

◆ stringExecutionQueue

InterThreadStoreVector<Ogre::String> RoR::ScriptEngine::stringExecutionQueue

protected

The string execution queue.

See also: queueStringForExecution

Definition at line 378 of file ScriptEngine.h.

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

source/main/scripting/ScriptEngine.h
source/main/scripting/ScriptEngine.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ScriptEngine()

◆ ~ScriptEngine()

Member Function Documentation

◆ addFunction()

◆ addVariable()

◆ composeModuleName()

◆ deleteFunction()

◆ deleteVariable()

◆ envokeCallback()

◆ exceptionCallback()

◆ executeContextAndHandleErrors()

◆ executeString()

◆ fireEvent()

◆ forwardExceptionAsScriptEvent()

◆ framestep()

◆ functionExists()

◆ getEngine()

◆ getFunctionByDeclAndLogCandidates()

◆ getScriptUnit()

◆ getScriptUnits()

◆ getVariable()

◆ init()

◆ lineCallback()

◆ loadScript()

◆ messageLogged()

◆ msgCallback()

◆ prepareContextAndHandleErrors()

◆ queueStringForExecution()

◆ scriptUnitExists()

◆ setEventsEnabled()

◆ setForwardScriptLogToConsole()

◆ setupScriptUnit()

◆ triggerEvent()

◆ unloadScript()

◆ validateScriptModule()

◆ variableExists()

Friends And Related Function Documentation

◆ GameScript

Field Documentation

◆ context

◆ engine

◆ m_currently_executing_event_trigger

◆ m_currently_executing_script_unit

◆ m_events_enabled

◆ m_game_script

◆ m_script_units

◆ m_terrain_script_unit

◆ scriptLog

◆ stringExecutionQueue