Script

Script

A set of JavaScript functions that can be invoked by the engine. Script
objects (currently) don't actually extend this class. This class serves to
document the shape of a script object and as a home for script related
static helper functions.

Scripts come in two varieties: Engine and Custom. Engine scripts are defined
using code included with the engine. Custom scripts are defined using code
loaded from a resource.

Script.create can be used to create script objects for engine scripts or
using any function that returns an object like the one described here. The
object may or may not actually extend Script.

Script.load and Script.update are used by the ScriptComponentHandler and
MachineHandler to load and configure the script objects referenced by
ScriptComponent and ScriptAction configuration data, respectively. Both
Engine and Custom scripts can be referenced by this configuration. This
"instance" configuration also contains the "args" used when invoking script
functions.

Custom script objects created by ScriptHandler don't extend this class and
there is no way for them to do so (but that may change in the future).
ScriptHandler uses a ScriptProxy object to represent the custom script.

ScriptComponent and ScriptAction register their script objects with the
ScriptSystem, which is responsible for actually invoking the script's
functions at the right times.

Script parameter UX in the editor requires some special handling. The
script objects themselves are loaded in the engine inside the canvas iframe
and that is where the available parameters are discovered via the extensions
metadata. Whenever this metadata changes the UX needs to be told about that
change. This is done by emitting a "sumerian.scriptExternals" message on the
SystemBus.

Constructor

new Script()

Initialize a new Script object

Members

alwaysRun

Determines if the script is run only when the world is running, or if
the script runs even while the world is stopped or paused. Always run
scripts are used by the editor for the edit camera.

context

The "ctx" parameter passed to script functions. These are created by
ScriptSystem.

enabled

Determines if script functions will be called.

externals

Metadata describing the script

parameters

The "args" parameter passed to script functions.

Methods

(static) clone()

Creates a new script object that calls the same script functions as an
existing script object but that has independent args, context, and enabled
state. However, the context will be null initially, as a new context will
be created when the script component is setup.

(static) create(key, options) → {Script}

Creates an instance of an engine script that can be used with a
ScriptComponent or ScriptAction (except there are currently no engine
scripts that are intended to be used as ScriptActions).

Parameters:
Name Type Description
key string | function

A registered engine script name or an engine
script factory function.

options object

Optional. The initial parameters used for the script.

(static) load(config, loadObject, options) → {Script}

Uses script instance config data to create a script object.

Parameters:
Name Type Description
config object

An object with the following properties:

Properties
Name Type Description
scriptRef string

Script id.

options object

Parameter values.

loadObject function

The function used to load resources.

options Object

(static) makeScriptError()

Attempts to convert an Error object thrown when executing custom script
code into an object that can be displayed by the ui via an
sumerian.scriptError message.

(static) update(script, config, loadObject, options)

Updates a script object to reflect changes to it's instance configuration
data.

Parameters:
Name Type Description
script Script

An object previously returned by load.

config object

An object as documented for load.

loadObject function

The function used to load resources.

options object

The options used when doing the update.