Handling Events¶

Scripts in our game engine can listen to a variety of events that are mostly direct wrappers of JavaScript events such as keyboard and pointer interactions. To listen to these events, scripts must register a callback function using the event system provided by the engine.

Registering Event Listeners¶

To register an event listener, scripts should include the listener registration within an initialization function and add a callback function. Here is how you can define and register event listeners:

Registering an event listener within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('eventname', function(e)
        print('Event was triggered: ' .. e.type)
    end)
end

return MyEntity

Event Details¶

Below are the various events a script can listen to, along with the details of the parameters that each event object contains, and example usages structured correctly.

Pointer Events¶

pointerdown¶

Triggered when a pointer is pressed down over an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer
button	Button pressed

Example usage of pointerdown event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointerdown', function(event)
        print("Pointer down at (" .. event.x .. ", " .. event.y .. ") with button " .. event.button)
    end)
end

return MyEntity

pointerclick¶

Triggered when a pointer is clicked over an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer
button	Button clicked

Example usage of pointerclick event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointerclick', function(event)
        print("Pointer clicked at (" .. event.x .. ", " .. event.y .. ") with button " .. event.button)
    end)
end

return MyEntity

pointerdoubleclick¶

Triggered on a double click of a pointer over an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer
button	Button double-clicked

Example usage of pointerdoubleclick event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointerdoubleclick', function(event)
        print("Pointer double-clicked at (" .. event.x .. ", " .. event.y .. ") with button " .. event.button)
    end)
end

return MyEntity

pointermove¶

Triggered when a pointer is moved over an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer
movementX	Movement on the x axis since last event
movementY	Movement on the y axis since last event

Example usage of pointermove event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointermove', function(event)
        print("Pointer moved to (" .. event.x .. ", " .. event.y .. ")")
    end)
end

return MyEntity

wheel¶

Triggered when the mouse wheel is scrolled over an element.

Field	Description
type	Type of the event
deltaX	Horizontal scroll amount
deltaY	Vertical scroll amount
deltaMode	Unit of measurement for scroll

Example usage of wheel event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('wheel', function(event)
        print("Wheel scrolled with deltaX: " .. event.deltaX .. ", deltaY: " .. event.deltaY .. ", mode: " .. event.deltaMode)
    end)
end

return MyEntity

pointerout¶

Triggered when a pointer is moved out of an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer

Example usage of pointerout event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointerout', function(event)
        print("Pointer moved out of element at (" .. event.x .. ", " .. event.y .. ")")
    end)
end

return MyEntity

pointerleave¶

Triggered when a pointer leaves the boundaries of an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer

Example usage of pointerleave event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointerleave', function(event)
        print("Pointer left the element at (" .. event.x .. ", " .. event.y .. ")")
    end)
end

return MyEntity

pointerup¶

Triggered when a pointer is released over an element.

Field	Description
type	Type of the event
x	X-coordinate of the pointer
y	Y-coordinate of the pointer
button	Button released

Example usage of pointerup event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pointerup', function(event)
        print("Pointer up at (" .. event.x .. ", " .. event.y .. ") with button " .. event.button)
    end)
end

return MyEntity

Keyboard Events¶

keydown¶

Triggered when a key is pressed down.

Field	Description
type	Type of the event
altKey	Whether the Alt key was pressed
code	Code of the key pressed
ctrlKey	Whether the Control key was pressed
isComposing	Whether the key is in composing mode
key	Character of the key pressed
location	Location of the key on the keyboard
metaKey	Whether the Meta key was pressed
repeat	Whether the key press is a repeat
shiftKey	Whether the Shift key was pressed

Example usage of keydown event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('keydown', function(event)
        print("Key " .. event.key .. " pressed with code " .. event.code)
    end)
end

return MyEntity

keyup¶

Triggered when a key is released.

Field	Description
type	Type of the event
altKey	Whether the Alt key was pressed
code	Code of the key pressed
ctrlKey	Whether the Control key was pressed
isComposing	Whether the key is in composing mode
key	Character of the key pressed
location	Location of the key on the keyboard
metaKey	Whether the Meta key was pressed
repeat	Whether the key press is a repeat
shiftKey	Whether the Shift key was pressed

Example usage of keyup event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('keyup', function(event)
        print("Key " .. event.key .. " released with code " .. event.code)
    end)
end

return MyEntity

Other Events¶

pick¶

Triggered when a picking operation intersects with objects in the scene.

Field	Description
type	Type of the event
intersections	Details of the intersected objects

Example usage of pick event within an init function¶

local Events = require 'engine/events'
local Tools = require 'engine/tools'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('pick', function(event)
        print("Pick event with intersections: " .. Tools.dump(event.intersections))
    end)
end

return MyEntity

physicsCollisions¶

Triggered when a physics collision occurs.

Field	Description
type	Type of the event
data	An array of objects with fields “object1” and “object2” which are IDs which can be used to retrieve the object

Example usage of physicsCollisions event within an init function¶

local Events = require 'engine/events'
local Tools = require 'engine/tools'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('physicsCollisions', function(event)
        print("Collision detected between objects: " .. Tools.dump(event.data))
    end)
end

return MyEntity

variableChanged¶

Triggered when a variable of a variable set is changed

Field	Description
type	Type of the event
set	Name of the changed variable set
name	Name of the variable
value	Its new value

Example usage of pick event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity:init()
    Events.on('variableChanged', function(e)
      print("Variable was changed: " .. e.set .. "/" .. e.name .. " -> " .. e.value)
    end)
end

return MyEntity