We want certain changes to occur when certain events happen. The player clicks a button, and this runs some script that makes a change to the game state. We do this using the action tag.

     <!-- When the player clicks the object, the JS function DoSomething() is called. -->
     <object name="whatever">
          <action on="Press"><![CDATA[
              DoSomething();
          ]]></action>
     </object>

This next example is an "evil hack" which can be used to set the function call for an object's action from JS. For example, to call the function DoSomething(), passing the parameters SomeParam1, SomeParam2, and SomeParam3, when the player clicks a control called SomeObject:

     SomeObject.onPress = function (m, n, o)
                          {
                             return function() 
                             {
                                 DoSomething (m, n, o); 
                             }
                          } (SomeParam1, SomeParam2, SomeParam3);

Key: Italicised title means property is mandatory.

on

The most important property of <action /> is the on="" property. Here we specify a string reference to the kind of action that must occur in order to run the encapsulated script.

Just like with object properties, there are the base ones, and the extended ones.

Base Actions

The base actions are generic and can be used by any object regardless of type.

Load

Executed when the control object is first initialised at startup. Often used to perform special configuration or initialisation of an object.

MouseEnter

Only called once when entering an object.

MouseLeave

Opposite to MouseEnter.

MouseLeftPress

Called the instance the left mouse button is pressed.

MouseLeftRelease

Opposite to MouseLeftPress.

MouseMove

Called when the cursor is moving while hovering the object.

Progress

This is a special action fired when g_Progress and/or g_LoadDescription are updated during the loading of a game session.

Tick

Event occurs each game 'tick'. Use for objects that need to be constantly refreshed. It's best to find any possible alternative to a tick event, as it will cause slowdown of game processing.

Update

Called when a property has been updated.

Extended Actions

These actions are type specific. Check an object's documentation to see which extended actions are available.

Press

Executed when the object is triggered (such as when the user clicks a button, presses enter in a text field, or presses a button's hotkey). Properties like sprite_pressed and text_pressed are used during this action.

SelectionChange

Used for objects like List and Drop-down when the selection is changed. As of now, setting the selection to what it already is, will still trigger the action.

Tab

Executed when the "Tab" key is pressed on an input field (for things like autocomplete).

file

An optional "file" property can be used to run a script from a separate file, rather than using inline script or a function call.

  <action on="Press" file="scriptfile1.js" />

Using both the file property and an inline script will concatenate the inline script to the file script.