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 177 of file 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, int32_t associatedNetUid=-1, std::string buffer="")

void	unloadScript (ScriptUnitID_t unique_id)

void	unloadBotByUid (int32_t bot_net_uid)

void	framestep (Ogre::Real dt)

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="")

void	setEventsEnabled (bool val)

ScriptRetCode_t	executeString (Ogre::String command)

void	queueStringForExecution (const Ogre::String command)

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

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

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

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

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

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

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

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

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)

AngelScript::asIScriptEngine *	getEngine ()

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

void	SLOG (const char *msg)

void	SLOG (std::string msg)

bool	scriptUnitExists (ScriptUnitID_t unique_id)

ScriptUnit &	getScriptUnit (ScriptUnitID_t unique_id)

ScriptUnitID_t	getTerrainScriptUnit () const

ScriptUnitID_t	getCurrentlyExecutingScriptUnit () const

ScriptUnitMap const &	getScriptUnits () const

Protected Member Functions
Housekeeping
void	init ()

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

int	setupScriptUnit (int unit_id)

bool	prepareContextAndHandleErrors (ScriptUnitID_t nid, int asFunctionID)

int	executeContextAndHandleErrors (ScriptUnitID_t nid)

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

Script diagnostics
void	msgCallback (const AngelScript::asSMessageInfo *msg)

void	lineCallback (AngelScript::asIScriptContext *ctx)

void	exceptionCallback (AngelScript::asIScriptContext *ctx)

Protected Attributes
AngelScript::asIScriptEngine *	engine

AngelScript::asIScriptContext *	context

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

InterThreadStoreVector< Ogre::String >	stringExecutionQueue

Friends
class	GameScript

Constructor & Destructor Documentation

◆ ScriptEngine()

ScriptEngine::ScriptEngine ( )

Definition at line 99 of file ScriptEngine.cpp.

◆ ~ScriptEngine()

ScriptEngine::~ScriptEngine ( )

Definition at line 108 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 538 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 643 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 842 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 600 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 675 of file ScriptEngine.cpp.

◆ envokeCallback()

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

Definition at line 481 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 250 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 294 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 521 of file ScriptEngine.cpp.

◆ fireEvent()

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

Definition at line 451 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 263 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 422 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 587 of file ScriptEngine.cpp.

◆ getCurrentlyExecutingScriptUnit()

ScriptUnitID_t RoR::ScriptEngine::getCurrentlyExecutingScriptUnit ( ) const

inline

Returns: SCRIPTUNITID_INVALID if none is executing right now.

Definition at line 310 of file ScriptEngine.h.

◆ getEngine()

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

inline

Definition at line 299 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 778 of file ScriptEngine.cpp.

◆ getScriptUnit()

ScriptUnit & ScriptEngine::getScriptUnit ( ScriptUnitID_t unique_id )

Definition at line 1154 of file ScriptEngine.cpp.

◆ getScriptUnits()

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

inline

Definition at line 311 of file ScriptEngine.h.

◆ getTerrainScriptUnit()

ScriptUnitID_t RoR::ScriptEngine::getTerrainScriptUnit ( ) const

inline

Returns: SCRIPTUNITID_INVALID if none exists.

Definition at line 309 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 695 of file ScriptEngine.cpp.

◆ init()

void ScriptEngine::init ( )

protected

This function initialzies the engine and registeres all types.

Definition at line 121 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 232 of file ScriptEngine.cpp.

◆ loadScript()

ScriptUnitID_t ScriptEngine::loadScript	(	Ogre::String	filename,
		ScriptCategory	category = `ScriptCategory::TERRAIN`,
		ActorPtr	associatedActor = `nullptr`,
		int32_t	associatedNetUid = `-1`,
		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
associatedNetUid	Only for category AI_BOT
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 847 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 115 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 213 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 384 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 516 of file ScriptEngine.cpp.

◆ scriptUnitExists()

bool ScriptEngine::scriptUnitExists ( ScriptUnitID_t unique_id )

Definition at line 1148 of file ScriptEngine.cpp.

◆ setEventsEnabled()

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

inline

Definition at line 223 of file ScriptEngine.h.

◆ setForwardScriptLogToConsole()

void ScriptEngine::setForwardScriptLogToConsole ( bool doForward )

Definition at line 1136 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 941 of file ScriptEngine.cpp.

◆ SLOG() [1/2]

void RoR::ScriptEngine::SLOG ( const char * msg )

inline

Replacement of macro.

Definition at line 304 of file ScriptEngine.h.

◆ SLOG() [2/2]

void RoR::ScriptEngine::SLOG ( std::string msg )

inline

Replacement of macro.

Definition at line 305 of file ScriptEngine.h.

◆ 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 800 of file ScriptEngine.cpp.

◆ unloadBotByUid()

void ScriptEngine::unloadBotByUid ( int32_t bot_net_uid )

Helper for ServerScriptEngine - requests unloading the AI_BOT script.

Definition at line 1119 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 1097 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 404 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 659 of file ScriptEngine.cpp.

Friends And Related Symbol Documentation

◆ GameScript

friend class GameScript

friend

Definition at line 179 of file ScriptEngine.h.

Field Documentation

◆ context

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

protected

context in which all scripting happens

Definition at line 377 of file ScriptEngine.h.

◆ engine

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

protected

instance of the scripting engine

Definition at line 376 of file ScriptEngine.h.

◆ m_currently_executing_event_trigger

scriptEvents RoR::ScriptEngine::m_currently_executing_event_trigger = SE_NO_EVENTS

protected

Definition at line 383 of file ScriptEngine.h.

◆ m_currently_executing_script_unit

ScriptUnitID_t RoR::ScriptEngine::m_currently_executing_script_unit = SCRIPTUNITID_INVALID

protected

Definition at line 382 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 384 of file ScriptEngine.h.

◆ m_game_script

GameScript RoR::ScriptEngine::m_game_script

protected

Definition at line 379 of file ScriptEngine.h.

◆ m_script_units

ScriptUnitMap RoR::ScriptEngine::m_script_units

protected

Definition at line 380 of file ScriptEngine.h.

◆ m_terrain_script_unit

ScriptUnitID_t RoR::ScriptEngine::m_terrain_script_unit = SCRIPTUNITID_INVALID

protected

Definition at line 381 of file ScriptEngine.h.

◆ scriptLog

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

protected

Definition at line 378 of file ScriptEngine.h.

◆ stringExecutionQueue

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

protected

The string execution queue.

See also: queueStringForExecution

Definition at line 386 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

Description

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Constructor & Destructor Documentation

◆ ScriptEngine()

◆ ~ScriptEngine()

Member Function Documentation

◆ addFunction()

◆ addVariable()

◆ composeModuleName()

◆ deleteFunction()

◆ deleteVariable()

◆ envokeCallback()

◆ exceptionCallback()

◆ executeContextAndHandleErrors()

◆ executeString()

◆ fireEvent()

◆ forwardExceptionAsScriptEvent()

◆ framestep()

◆ functionExists()

◆ getCurrentlyExecutingScriptUnit()

◆ getEngine()

◆ getFunctionByDeclAndLogCandidates()

◆ getScriptUnit()

◆ getScriptUnits()

◆ getTerrainScriptUnit()

◆ getVariable()

◆ init()

◆ lineCallback()

◆ loadScript()

◆ messageLogged()

◆ msgCallback()

◆ prepareContextAndHandleErrors()

◆ queueStringForExecution()

◆ scriptUnitExists()

◆ setEventsEnabled()

◆ setForwardScriptLogToConsole()

◆ setupScriptUnit()

◆ SLOG() [1/2]

◆ SLOG() [2/2]

◆ triggerEvent()

◆ unloadBotByUid()

◆ unloadScript()

◆ validateScriptModule()

◆ variableExists()

Friends And Related Symbol 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