Scriptor global functions

Aside of creating scripts in code through new Scriptor(...), the library offers some global functions to make your life even more easier.

Loading Scripts From File(s)

scriptor_from_file

This function loads a script file into memory and registers it with Scriptor.
The script has not been compiled yet!
The Scriptor instance is returned, so you may very well used it like
scriptor_from_file(yourname, yourfile, yourowner).compile();

/// @func	scriptor_from_file(_name, _filename, _owner = undefined)
/// @desc	Loads a scriptor file synchronously. The returnvalue is the Scriptor instance.
///		NOTE: A sync file access BLOCKS until it is finished, so you better use this only
///		during loading screens!
function scriptor_from_file(_name, _filename, _owner = undefined) {

scriptor_read_script_tree_async

This is one of the power horses of the Scriptor library.
The function reads an entire file tree of scripts asynchronously in one go into memory and registers them.
The scripts will be also compiled when they are loaded!

The default folder read is the SCRIPTOR_ROOT_FOLDER you have set in the Scriptor_Configuration file in the __GAME_SETUP__ folder of the project.

You may set a _file_task_callback, which will be invoked for every single file found and it will receive the FileAsyncWorker from raptor as argument, so you may add .on_finished(...) callbacks to each of those tasks to hook on every loaded file, when it is completed (and compiled).

An example, of how to use this to create load/compile success- and error-messages could look like:
(Please note, that the .on_finished callback of the file task is a standard callback from raptor's async file system, so you receive two arguments: The scripts' source code, as it was a normal file read and a data object, where the .name property is set to the script name, that this source code belongs to)

scriptor_read_script_tree_async(function(_task) {
	_task
	.on_finished(function(source_code, data) {
		ilog($"--- Script {data.name} loaded successfully");
	})
	.on_failed(GlobalFileReadError);
});

/// @func	scriptor_read_script_tree_async(_file_task_callback = undefined, _folder = SCRIPTOR_ROOT_FOLDER)
/// @desc	Reads an entire tree of scriptor files (SCRIPTOR_FILE_EXTENSION) recursively.
///		Each script file is loaded and compiled in one go.
///		You receive a struct as return value but keep in mind, that this struct will
///		be filled async across several frames until all files are loaded and compiled,
///		but you may use it to store it in some global variable if you need access to all
///		scripts in one place, if they are not self-registering with the broker.
///		If you use only self-registering scripts, you may as well ignore the return value.
function scriptor_read_script_tree_async(_folder, _file_task_callback = undefined) {

Run an Existing Script

Loading scripts is not everything, and you are not forced to use the The Scriptor Broker for all your scripts.

Therefore, scriptor_run has been added to the library, to allow you to launch any script any time and optionally specify a bound owner for this execution.

Note

The script name to launch is the file name of the script.
So, if your script is in the SCRIPTOR_ROOT_FOLDER and is named "myscript.scriptor", you will send myscript as name.
The script name reflects also the folder structure, so, a script located in "SCRIPTOR_ROOT_FOLDER/monsters/attack.scriptor" will have monsters/attack as script name.

scriptor_exists

/// @func	scriptor_exists(_name)
/// @desc	Returns, whether a script with the specified name exists
function scriptor_exists(_name) {

scriptor_run

/// @func	scriptor_run(_name, _owner = undefined, _arguments = undefined)
/// @desc	Runs a loaded scriptor script by its name with an optional owner to bind to.
///		Returns the exit code of the script.
///		The _arguments parameter may either be an array of values, that will be forwarded
///		as { args: } struct to the script, or any struct you choose. It will be forwarded
///		1:1 to the script
function scriptor_run(_name, _owner = undefined, _arguments = undefined) {

scriptor_try_run

/// @func	scriptor_try_run(_name, _owner = undefined)
/// @desc	Combines "scriptor_exists" and "scriptor_run" by running the script
///		only, if it exists (and returns its value). Otherwise, undefined is returned.
///		The _arguments parameter may either be an array of values, that will be forwarded
///		as { args: } struct to the script, or any struct you choose. It will be forwarded
///		1:1 to the script
function scriptor_try_run(_name, _owner = undefined, _arguments = undefined) {

scriptor_remove_script

/// @func	scriptor_remove_script(_name)
/// @desc	Removes a script from the loaded scripts list
///		Returns true, if the script was found and removed, otherwise false
function scriptor_remove_script(_name) {