Skip to content

Sensors

The Sensors API provides pollable access to mobile device orientation and acceleration. Use it when you want to read the latest sensor values on demand (for example in update), without registering your own event listeners.

The engine continuously listens for browser device orientation and motion events and caches the most recent reading. Until at least one reading arrives, getOrientation / getAcceleration return nil and the corresponding has* helpers return false.

On some platforms (notably iOS) the user must grant motion/orientation permission before data is available. Desktop browsers typically do not provide these sensors.

For per-sample callbacks, see the deviceorientation and devicemotion events in Handling Events.

Usage

To use this module, add the following require at the top of your script:

local Sensors = require 'engine/sensors'

Reference

__init

static __init()

Initialize the sensors module and install event hooks.

hasOrientation

static hasOrientation()

Returns true if at least one device orientation reading has been received.

Returns

  • boolean

hasAcceleration

static hasAcceleration()

Returns true if at least one device acceleration reading has been received.

Returns

  • boolean

getOrientation

static getOrientation()

Get the latest device orientation.

Angles follow the browser Device Orientation API: - `alpha`: rotation around the Z axis (0–360), compass heading when available - `beta`: rotation around the X axis (-180–180), front-to-back tilt - `gamma`: rotation around the Y axis (-90–90), left-to-right tilt

Returns

  • table|nil: alpha, beta, gamma }` in degrees, or nil if no data yet

Example

local Sensors = require 'engine/sensors'
local orientation = Sensors.getOrientation()
if orientation then
    print(orientation.alpha, orientation.beta, orientation.gamma)
end

getAcceleration

static getAcceleration()

Get the latest device acceleration including gravity, in m/s².

The vector follows the browser Device Motion API coordinate system (device axes, not world axes). When the device is flat on a table, z is typically around ±9.8.

Returns

  • Vector3|nil: including gravity, or nil if no data yet

Example

local Sensors = require 'engine/sensors'
local acc = Sensors.getAcceleration()
if acc then
    print(acc.x, acc.y, acc.z)
end

getState

static getState()

Get the full cached sensor state.

Returns

  • table: orientation = { available, alpha, beta, gamma }, acceleration = { available, x, y, z } }`

Examples

local Sensors = require 'engine/sensors'
local Behaviour = require 'engine/behaviour'
local Class = require 'engine/class'

local TiltBehaviour = Class.new(Behaviour)

function TiltBehaviour:update(dt)
    local orientation = Sensors.getOrientation()
    if not orientation then
        return
    end

    -- beta: front/back tilt, gamma: left/right tilt (degrees)
    local transform = self.node:getTransform()
    transform:rotateTo(orientation.beta or 0, 0, -(orientation.gamma or 0))
    self.node:setTransform(transform)
end

return TiltBehaviour

local Sensors = require 'engine/sensors'
local Console = require 'engine/console'

function update(dt)
    if not Sensors.hasAcceleration() then
        return
    end

    local acc = Sensors.getAcceleration()
    Console.log(string.format("acc: %.2f, %.2f, %.2f", acc.x, acc.y, acc.z))
end