wiki:ScriptingDocumentation/ScriptingEvents

Scripting Events

Specification:
<Event eventID=”” state=””>

<Trigger1/>
<Trigger2/>

<Action1/>
<Action2/>

</Event>

eventID

[Required, String] This string is used to reference the event.

state

[Optional, String] This string defines if the event starts in an ‘inactive’ or ‘active’ state. If not present, the event defaults to ‘active’.

Scripting Events are defined by a number (0+) of conditional triggers and a list of sequentially executed actions. All Scripting Events are considered active once the Scripting System finishes loading. When all of an active scripting event’s Triggers are satisfied, the linked actions will execute. Once action execution has started, the Scripting Event is considered inactive and will not trigger, even if all of its Triggers are satisfied. Triggers define under what conditions the Scripting Event activates. Only when all Triggers are simultaneously satisfied will the Scripting Event trigger. Note that an event with zero Triggers will always be triggered when checked (effectively an implied ‘Automatic’ Trigger).

Event States

Active

The Scripting System checks this Scripting Event every frame to see if all of its associated Triggers are true. If they are, the Scripting System triggers the event, starts executing the actions and changes the Scripting Event’s state to Executing. Deactivating this Scripting Event changes its state to Inactive in the following frame (This means the Scripting Event may still be triggered in the current frame). . Activating it has no effect other than generating a console warning.

Executing

This Scripting Event is currently executing, it is not checked by the Scripting System at all. On starting execution, the Scripting Event’s target end state will be set as Inactive. Once the Scripting Event finishes executing all of its Actions its state will change to Transitioning. Attempts to activate or deactivate a Scripting Event that is in this state will be blocked and queued. Aborting an Executing Scripting Event will move it to the Transitioning state immediately.

Inactive

Once in the Inactive state, the Scripting System no longer checks this Scripting Event at all, but it retains a reference to it. Activating this Scripting Event changes its state to Active in the following frame. Attempts to deactivate it result in no effect other than generating a console warning.

Transitioning

A special state that a Scripting Event is placed in for the duration of the frame in which it is changing between certain states. If a Scripting Event intends to go directly from Active to Inactive or vice versa it will be in the Transitioning state until the end of the current frame at which point it finishes its transition and ends in the destination state. A Transitioning Scripting Event cannot be triggered as well as blocks and queues all activate and deactivate requests exactly like the Executing state.

Error Levels

Error levels can be set on both the Scripting Event and individual Actions. Setting the error level in the Scripting Event sets that error level for all Actions in the Scripting Event. Individual Actions may have an error level specifically set on them that overrides the error level set by the Scripting Event. Setting the error level of a specific Action will cause only that specific Action the throw errors differently without affecting any other Actions in the event. The error levels and their effects are as follows:

error

Default value if no specific error level is set. At this level the Scripting System will throw a Javascript Error that contains a description of the error. This will generally cause the program to crash/halt unless it is otherwise caught. This setting is recommended for Actions that are expected to always succeed or for making sure you notice any Actions that do fail.

warn

At this level the Scripting System will print out the information about the error to the console but will otherwise continue running normally. This setting is recommended for when you expect/know an Action might/will fail but do not want it to interfere with what you are currently working on.

ignore

At this level the Scripting System silently ignores the problem, no message is generated and the Scripting System continues on as normal. This setting is recommended for when you know an Action can/will fail, but its failure will not impact either the Scripting System or the accompanying program.

Note that this setting only impacts non-critical errors; critical errors will always behave as the ‘error’ level above. Critical errors are limited to errors whose presence absolutely prevents the Scripting System from continuing to run. The vast majority of these can be classified are parsing/syntax errors. Also, while called a Scripting System, the language behaves like a compiled language, any parsing/syntax errors will be thrown when the scripting file is loaded into the Scripting System.