$ Variables

Scriptor offers some built-in variables. Their name starts with a $ dollar character. This might look familiar to you, if you know the php language.

There are three $variables, each of them has a specific meaning and scope, when they are available.

$args

There are two ways, how a scriptor script gets executed:

• Explicitly by invoking the scriptor_run(...) global function or by calling yourscript.run(...) when you hold a script reference in a variable.
• Implicitly through a Callback event or a Self-Registering Script through the broker or when you register a script as callback for an event or state through the #script-command in RichJson.

Explicit Execution

Let's look at the signatures of the two ways to execute a script explicitly through a gml call:

The global scriptor_run function

function scriptor_run(_name, _owner = undefined, _arguments = undefined) {

The .run method of a script when you have a reference to it in a variable:

run = function(_new_owner = undefined, _arguments = undefined)

Both functions offer an _arguments parameter. There are four possible things you can send as _arguments:

_arguments	in the script as	description
undefined nothing, skip the parameter	$args	If you omit the _arguments then $args is an empty array.
"Hello World" (any single value)	$args	The length of $args is 1, holding the value.
[ 1, 2, 3 ] (an array)	$args	$args holds a copy of the array, like [ 1, 2, 3 ]. It is NOT the case, that $args[0] holds the array! Send a 3-member-array and $args will have 3 members.
{ foo: "bar" } (a struct)	foo == "bar"	If you supply a struct, the struct is copied directly to the script's variables pool. This way you can even use kind of named arguments, as each of the struct members is available as variable in the running script.

Implicit Execution

When a subsystem of raptor, like [RichJson}(https://github.com/coldrockgames/doc-rich-json/wiki) or the Broker invoke a script, they will never use the struct-variant as shown above. You will always have the arguments available in $args.

Some Examples:

A Click Handler in RichJson

{
  "#ui:some_control": {
    "on_left_click": "#script:ui/my_click_handler",
  }
}

The $args in my_click_handler will hold 1 value: the sender of the event, as defined in the clickable controls of the raptor wiki's UI subsystem documentation.

A State Handler in RichJson

{
  "SomeObject.SomeFlavor": {
    "#states:combat_states": [
      { "name": "ev:mouse_enter", "on_enter": "#script:combat/hover_over" },
    ]
  }
}

The $args will hold three values, data, prev_state, prev_result as defined in the callback definition of on_enter in the StateMachine callbacks documentation of raptor.

$bc

The name bc is the abbreviation for broadcast.

When you script gets invoked through the The Scriptor Broker, because it is self registering, then you can access a variable called $bc.

This variable holds the broadcast that has been received and it's structure is identically to the "bc" argument, a broadcast receiver gets.

Member	Datatype	Contains
uniqueid	int	Every broadcast has a uniqueid. It's a numeric value, unique for each send call, counting up
handled	bool	Initialized with false. Set it to true, to mark this broadcast as being done. The send loop will abort then and stop sending this broadcast to the remaining recipients
from	instance	The sender of this broadcast
title	string	The string you set as title argument to the send method
data	struct	Any custom data struct you supplied to the send method

$res

This special variable is available after you return from a gosub sub routine. It contains the value returned by the sub routine.

Here is a small example:

var str = "Hello "
gosub get_the_world
str += $res
// str now contains "Hello World"
return

:get_the_world
return "World"