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

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

Example usage of touchstart event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

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

return MyEntity

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

Example usage of touchend event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

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

return MyEntity

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

Example usage of touchcancel event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

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

return MyEntity

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

Example usage of touchmove event within an init function¶

local Events = require 'engine/events'

local MyEntity = Class.new(Entity)

function MyEntity: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 MyEntity

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)

Example of accessing touch object data¶

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

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