In this article, we'll take a look at ScriptENGINE Events and how you can create your own.

ScriptENGINE events realize the Publisher-Subscriber Design Pattern to connect an unlimited number of subscribers to a single publisher while keeping the two entities completely decoupled. So a publisher can publish an event without knowing who or how many subscribers are interested in the event.

We use the IEvents interface to subscribe to ScriptENGINE events so that we can perform specific processing when certain things occur. For example, when a user presses a GUI button we may want to exit the program, or load a 3D world etc. The IEvents interface also allows us to create user-defined events.

 

View the Demo Code

The demos are included in the ScriptENGINE SDK. Now's a great time to get the ScriptENGINE SDK from our website (including the SciTE code editor, Programmer's Reference and ScriptENGINE Demos).

Navigate to the ScriptENGINE SDK/[Events] Handling logger messages folder for the example.

Open the world.e76script in the SciTE code editor. We will be referring to the world.e76script for the rest of this article.

 

The ScriptENGINE Demo Framework

The ScriptENGINE Demos are run using the runDemo.e76script framework code in the ScriptENGINE SDK/Demos folder.

 

Subscribing to Events

Subscribe to the ScriptENGINE Logger event:

subLog = IEvents:subscribeLog('OnLog')

• OnLog is the name of a globally defined Lua function that we have defined. The ScriptENGINE will call this functions whenever a logging event occurs.
• The subLog return value is later used to unsubscribe to the event and stop the ScriptENGINE from firing our callback function.

Subscribe to the ScriptENGINE Tick event:

subTick = IEvents:subscribeTickPeriodic('OnRotateCube', 1000)

• OnRotateCube is the callback function name.
• 1000 defines how often the callback is fired (in milliseconds).

 

 

Creating Subscriber Callback Functions

For every subscriber there must be a global Lua function defined that the ScriptENGINE can callwhen the relevant event occurs. Each event subscriber callback function has different parameters passed to it by the ScriptENGINE specific to the event.

The ScriptENGINE Programmer's Reference includes the callback function signatures that you should use to receive your callbacks on the IEvents page.

The callback function signatures are also pre-loaded into the SciTE code editor. Go to the  Edit->Insert Abbreviation menu to get a list of all the ScriptENGINE callback functions.

Define the Logger Subscriber Callback Function:

function OnLog(logString, userData)

Define the Tick Subscriber Callback Function:

function OnRotateCube(currentTime, lastTime, isWindowActive, userData)

 

Tick the ScriptENGINE processing Loop

Events will only start to be processed after the ScriptENGINE is ticked using the IApp:tick() function OR by placing it into a processing loop using IApp:run(). All the ScriptENGINE components including the graphics, physics, network and sound will fire any relevant events to your subscriber callback functions.

In the ScriptENGINE demo, the IApp:run() is actually called by the runDemo.e76script. This shared code has been extracted into one script and used by all the demos.

 

Unsubscribing to Events

Make sure that you unsubscribe when you're finished handling an event.

Unsubscribe to the events:

IEvents:unsubscribe(subLog);

IEvents:unsubscribe(subTick);

Notice that we must supply the subscriber identifier as returned from the IEvents:subscribe...() function.

 

Creating your own Events

Navigate to the ScriptENGINE SDK/[Events] Defining your own events folder for the user-defined events example. The important functions to look are the IEvents:subscribeUserEvent() and IEvents:publishUserEvent() function.

 

The ScriptENGINE Programmer's Reference

We recommend reading about the IEvents Interface in the Programmer's Reference which includes more information on subscribing to events.

We also suggest taking a look at the Events Examples supplied in the Programmer' Reference.