Events

APIs for pointer interactions and listener-trigger payloads.

Runtime baseline

This page reflects the June 4, 2026 compatibility baseline: public npm runtime line 2.37.8, with source pins tracked in Runtime Compatibility Baseline.

---

PointerEvent

Pointer interaction event data.

Constructor

PointerEvent.new(id, position)

Creates a new PointerEvent. Used for forwarding events to nested artboards.

PointerEvent.new(id: number, position: Vector): PointerEvent

Example:

-- Forward event to nested artboard
local childPos = transformToChildSpace(event.position)
local childEvent = PointerEvent.new(event.id, childPos)

Attributes

Attribute	Type	Description
position	Vector	Local coordinates
id	number	Pointer ID (for multitouch)
type	string	Event type (pointerDown, pointerUp, pointerMove, pointerExit, pointerEnter, click, pointerDrag, unknown)
previousPosition	Vector	Previous pointer position (when available)
timeStamp	number	Event timestamp (seconds)

Methods

event:hit(isTranslucent?)

Marks the event as handled. If isTranslucent is true, the event may continue to propagate through translucent hit targets.

event:hit()              -- Standard: stops propagation
event:hit(true)          -- Translucent: may continue through

Example:

function pointerDown(self, event: PointerEvent)
    if isInBounds(event.position) then
        self.pressed = true
        event:hit()
    end
end

---

ListenerContext

ListenerAction scripts receive listenerContext via:

function performAction(self: MyAction, listenerContext: ListenerContext)
    -- inspect event kind with is... methods
end

Type Guards

• listenerContext:isPointerEvent()
• listenerContext:isKeyboardEvent()
• listenerContext:isTextInput()
• listenerContext:isFocus()
• listenerContext:isReportedEvent()
• listenerContext:isViewModelChange()
• listenerContext:isGamepad()
• listenerContext:isNone()

Typed Accessors

• listenerContext:asPointerEvent(): PointerEvent?
• listenerContext:asKeyboardEvent(): KeyboardInvocation?
• listenerContext:asTextInput(): TextInputInvocation?
• listenerContext:asFocus(): FocusInvocation?
• listenerContext:asReportedEvent(): ReportedEventInvocation?
• listenerContext:asViewModelChange(): ViewModelChangeInvocation?
• listenerContext:asGamepad(): GamepadInvocation?
• listenerContext:asNone(): NoneInvocation?

Safe Branching Example

function performAction(self: MyAction, listenerContext: ListenerContext)
    if listenerContext:isPointerEvent() then
        local evt = listenerContext:asPointerEvent()
        if evt then
            print("pointer:", evt.type, evt.position.x, evt.position.y)
        end
    elseif listenerContext:isKeyboardEvent() then
        local evt = listenerContext:asKeyboardEvent()
        if evt then
            print("keyboard:", evt.key, evt.phase)
        end
    elseif listenerContext:isTextInput() then
        local evt = listenerContext:asTextInput()
        if evt then
            print("text:", evt.text)
        end
    elseif listenerContext:isGamepad() then
        local evt = listenerContext:asGamepad()
        if evt then
            print("gamepad:", evt.deviceId, evt.buttonMask, evt.axis0)
        end
    end
end

---

KeyboardInvocation

Keyboard payload exposed via listenerContext:asKeyboardEvent().

Field	Type	Description
key	number	Key code
shift	boolean	Shift modifier active
control	boolean	Control modifier active
alt	boolean	Alt modifier active
meta	boolean	Meta/Command modifier active
phase	"down" | "repeat" | "up"	Key phase

---

TextInputInvocation

Text input payload exposed via listenerContext:asTextInput().

Field	Type	Description
text	string	Committed text input

---

FocusInvocation

Focus payload exposed via listenerContext:asFocus().

Field	Type	Description
isFocus	boolean	true when focus gained, false when focus lost

---

ReportedEventInvocation

listenerContext:asReportedEvent() is available, but payload exposure is currently limited in this runtime baseline.

• Confirmed field: delaySeconds
• Treat additional reported-event fields as compatibility-sensitive until validated in a newer baseline.

---

ViewModelChangeInvocation

listenerContext:asViewModelChange() is available, but payload detail is currently minimal in this baseline (type presence + branching support).

---

GamepadInvocation

Gamepad payload exposed via listenerContext:asGamepad().

Field	Type	Description
deviceId	number	Runtime gamepad device ID
buttonMask	number	Bitmask of pressed buttons
axis0	number	Primary analog axis value

---

NoneInvocation

Fallback event shape for unsupported/unknown listener invocations.

• Check with listenerContext:isNone()
• Access with listenerContext:asNone()

---

Trigger

See Data & Input: Trigger for the Trigger type reference, and Trigger Inputs for the full usage guide.

Knowledge Check

Q:What is the safest pattern for accessing listener event payloads?

Q:Which GamepadInvocation field is currently exposed in ListenerContext payloads?

Next Steps

• Continue to Assets
• Verify surface status in Runtime Compatibility Baseline
• Need a refresher? Review Quick Reference