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:

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

Unregistering Event Listeners

In most cases, event listeners do not need to be manually unregistered.

Listeners registered through the engine event system are automatically cleaned up when the behaviour is destroyed. This means you can safely register listeners in init() without worrying about memory leaks or undesired callbacks.

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

Touch Events

touchstart

Triggered when one or more fingers touch the screen.

Field	Description
type	Type of the event
altKey	Whether the Alt key was pressed
ctrlKey	Whether the Control key was pressed
metaKey	Whether the Meta key was pressed
shiftKey	Whether the Shift key was pressed
touches	List of all current touches
changedTouches	List of touches that changed in this event

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

function MyBehaviour:init()
    Events.on('touchstart', function(event)
        print("Touch started with " .. #event.changedTouches .. " touch(es)")
    end)
end

return MyBehaviour

touchend

Triggered when one or more fingers are removed from the screen.

Field	Description
type	Type of the event
altKey	Whether the Alt key was pressed
ctrlKey	Whether the Control key was pressed
metaKey	Whether the Meta key was pressed
shiftKey	Whether the Shift key was pressed
touches	List of all current touches
changedTouches	List of touches that changed in this event

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

function MyBehaviour:init()
    Events.on('touchend', function(event)
        print("Touch ended. Remaining touches: " .. #event.touches)
    end)
end

return MyBehaviour

touchcancel

Triggered when a touch event is interrupted or cancelled, such as by a system alert.

Field	Description
type	Type of the event
altKey	Whether the Alt key was pressed
ctrlKey	Whether the Control key was pressed
metaKey	Whether the Meta key was pressed
shiftKey	Whether the Shift key was pressed
touches	List of all current touches
changedTouches	List of touches that changed in this event

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

function MyBehaviour:init()
    Events.on('touchcancel', function(event)
        print("Touch was cancelled due to system interruption.")
    end)
end

return MyBehaviour

touchmove

Triggered when a finger moves across the screen.

Field	Description
type	Type of the event
altKey	Whether the Alt key was pressed
ctrlKey	Whether the Control key was pressed
metaKey	Whether the Meta key was pressed
shiftKey	Whether the Shift key was pressed
touches	List of all current touches
changedTouches	List of touches that changed in this event

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

function MyBehaviour:init()
    Events.on('touchmove', function(event)
        for _, touch in ipairs(event.changedTouches) do
            print("Moved touch ID " .. touch.identifier .. " to (" .. touch.clientX .. ", " .. touch.clientY .. ")")
        end
    end)
end

return MyBehaviour

Touch Object

Each touch-related event includes one or more Touch objects in the touches and changedTouches arrays. Each Touch represents a single point of contact on the touch surface.

Field	Description
identifier	A unique ID for this touch point
x	X coordinate of the touch relative to the viewport
y	Y coordinate of the touch relative to the viewport
radiusX	Returns the X radius of the ellipse that most closelycircumscribes the area of contact with the screen
radiusY	Returns the Y radius of the ellipse that most closely circumscribes the area of contact with the screen
rotationAngle	Returns the angle (in degrees) that the ellipse described by radiusX and radiusY must be rotated, clockwise to most accurately cover the area of contact between the user and the surface.
force	Returns the amount of pressure being applied to the surface by the user, as a float between 0.0 (no pressure) and 1.0 (maximum pressure)

Events.on('touchstart', function(event)
    for _, touch in ipairs(event.changedTouches) do
        print("Touch " .. touch.identifier .. " at position (" .. touch.clientX .. ", " .. touch.clientY .. ")")
    end
end)

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

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

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

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

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour

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

local Events = require 'engine/events'

local MyBehaviour = Class.new(Behaviour)

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

return MyBehaviour