ScriptSystem

ScriptSystem

Executes script component scripts. Also provides support for executing
scripts from other components, such as the script actions supported by the
state machine component.

Scripts can be added to the system using ScriptSystem#addScript.
Script components add their scripts to the system if/when the component is
added to an entity and the entity is added to the world.

When a script is added to the system, the script's functions will be called
as follows:

  • If the world is running or paused the script's setup function will be
    called when the script is added. Otherwise the setup function will be
    called when the world is started.

  • While the world is running (not paused or stopped) the script's
    fixedUpdate, update, and lastUpdate functions will be called when the
    world calls the system's fixedUpdate and process functions.

  • The script's cleanup function will be called when the world is stopped,
    or if the script is removed while the world is running or paused.

The script may have an alwaysRun property, and if this property is true
the world's run state is ignored, resulting in the following behavior:

  • The script's setup function is called when the script is added.

  • The script's start/pause/resume/stop function is called when the world
    is started/paused/resumed/stopped.

  • The script's fixedUpdate, update, and lastUpdate functions are always
    called.

  • The script's cleanup function is called when the script is removed.

Other script functions can be called as needed using {@link
ScriptSystem#callScriptFunction}.

Constructor

new ScriptSystem()

Members

_isRunning :boolean

Tracks the world's play state.

_scripts :Set.<Script>

The scripts that have been registered with the system. Iterating a Set
returns the contents in insertion order. We depend on this part of the
Set contract to insure that scripts are called in the correct order.

When a scene is loaded, a parent entity will always be added before its
children entities. The order that a given entity's children are added is
the order they were added to the parent entity (which is fairly arbitary,
they are kept in a "sorted set" but the UI doesn't provide a way to
reorder them). When editing, the scene is re-loaded in this order each
time the scene is played.

We maintain one big set of scripts as an optimization vs looping over
all script components and then over all the scripts in each of those
coponents. Future optimizations may include keeping seperate sets for
each of the script's update functions, elminating checks inside the
call loops. We can even look at the source of the function provided by
the script and only add it to the set if the script actually does
something in the function.

_wasStarted :boolean

True when the world has started playing and not yet stoped.

_worldContext :object

The base context for every script.

passive :boolean

This system is always active.

priority :number

This system has a low priority. Scripts generally need to run after most
other systems, but they do run before the state machine. Note that
script actions run at the state machine system's priority, not at this
system's priority.

Methods

(static) _createWorldContext() → {object}

Create the context object shared by every script.

_handleScriptError()

Writes script errors to the JavaScript console and sends SystemBus
message that causes the error to be displayed in the script editor if it
is present.

_resetScriptData()

Resets the shared script context worldData object to its inital (empty)
state.

addScript(entity, script, propertiesopt)

Adds a script to the system. A new context object is created for the
script and assigned to the script's context property. The script's setup
function is called if the world is not stopped, or if the script has an
alwaysRun property that is true.

Parameters:
Name Type Attributes Description
entity Entity

The entity associated with the script.

script Script

The script object (doesn't have to extend Script).

properties object <optional>

An object whos properties will be copied to
the created context object.

callScriptFunction(script, fn)

Calls a script function with the correct arguments and error handling. The
provided function is always called, it doesn't matter if the world is
running or not. The caller of this function is responsible for ensuring
that the function exist on the script.

Parameters:
Name Type Description
script Script

A script object.

fn function

The function
that will be called.

If an error occurs, an "sumerian.scriptError" SystemBus message is emitted.

clear()

Clears this system. Once this method is called this instanceof of the
system is unusable.

createScriptContext(entity, propertiesopt) → {object}

Creates a script context object. Such objects are passed to script
functions as the ctx parameter.

Script context objects are composed of "world", "entity", and "script"
parts. The world part is shared by every context object, the entity part
is shared by every context object associated with a given entity, and the
script part is private to the script itself.

Object prototypes are used to create these compond objects. The object
returned is the script level context object. That object's prototype is the
entity level object context, and that object's prototype is the world level
context object.

Parameters:
Name Type Attributes Description
entity Entity

The entity associated with the context.

properties object <optional>

An object whos properties will be copied to
the created context object.

deleted(entity)

Detaches the script system from script components.

Parameters:
Name Type Description
entity Entity

The entity that has been removed.

fixedUpdate()

Called when a fixedUpdate should be done. Calls fixedUpdate on all scripts
if the world is running, or only on alwaysRun scripts if the world is
paused or stopped.

inserted(entity)

Attaches the script system to script components.

Parameters:
Name Type Description
entity Entity

The entity that has been added.

pause()

Called when the world is paused. Calls pause on all scripts that have a pause function

process()

Called when an update should be done. Calls update and lateUpdate on all
scripts if the world is running, or only on alwaysRun scripts if the world
is paused or stopped.

removeScript(script)

Removes a script from the system. The script's cleanup function is called
if the world is not stopped, or if the script has an alwaysRun property
that is true.

Parameters:
Name Type Description
script Script

A script object previously passed to addScript.

resume()

Called when the world is resumed. Calls resume on all scripts that have a resume function

start()

Called when the world starts executing. Calls setup on scripts, or start on
alwaysRun scripts.

stop()

Called when the world is stopped. Calls cleanup on scripts, or stop on
alwaysRun scripts. Also resets the script data for the world and all
entities.