From 1aeeb1c02845ffb7f3f1dc29983d4254cdefaac2 Mon Sep 17 00:00:00 2001
From: csmartdalton <csmartdalton@users.noreply.github.com>
Date: Tue, 31 Mar 2026 01:31:33 +0000
Subject: [PATCH] Update scripting API documentation

---
 docs.json                                     |  11 +-
 .../api-reference/artboards/focus-event.mdx   |  14 ++
 .../api-reference/artboards/key-phase.mdx     |   4 +
 .../artboards/keyboard-event.mdx              |  39 ++++
 .../artboards/listener-context.mdx            | 177 ++++++++++++++++++
 .../api-reference/artboards/none-event.mdx    |   7 +
 .../api-reference/artboards/pointer-event.mdx |   5 +
 .../api-reference/artboards/pointer-type.mdx  |   4 +
 .../artboards/reported-event.mdx              |   7 +
 .../api-reference/artboards/text-input.mdx    |  14 ++
 .../artboards/view-model-change.mdx           |   7 +
 .../interfaces/listener-action.mdx            |  38 +++-
 12 files changed, 325 insertions(+), 2 deletions(-)
 create mode 100644 scripting/api-reference/artboards/focus-event.mdx
 create mode 100644 scripting/api-reference/artboards/key-phase.mdx
 create mode 100644 scripting/api-reference/artboards/keyboard-event.mdx
 create mode 100644 scripting/api-reference/artboards/listener-context.mdx
 create mode 100644 scripting/api-reference/artboards/none-event.mdx
 create mode 100644 scripting/api-reference/artboards/pointer-type.mdx
 create mode 100644 scripting/api-reference/artboards/reported-event.mdx
 create mode 100644 scripting/api-reference/artboards/text-input.mdx
 create mode 100644 scripting/api-reference/artboards/view-model-change.mdx

diff --git a/docs.json b/docs.json
index 093df59d..9564ad0d 100644
--- a/docs.json
+++ b/docs.json
@@ -266,10 +266,19 @@
                 "pages": [
                   "scripting/api-reference/artboards/animation",
                   "scripting/api-reference/artboards/artboard",
+                  "scripting/api-reference/artboards/focus-event",
+                  "scripting/api-reference/artboards/key-phase",
+                  "scripting/api-reference/artboards/keyboard-event",
+                  "scripting/api-reference/artboards/listener-context",
                   "scripting/api-reference/artboards/node-data",
                   "scripting/api-reference/artboards/node-read-data",
+                  "scripting/api-reference/artboards/none-event",
                   "scripting/api-reference/artboards/pointer-event",
-                  "scripting/api-reference/artboards/view-model"
+                  "scripting/api-reference/artboards/pointer-type",
+                  "scripting/api-reference/artboards/reported-event",
+                  "scripting/api-reference/artboards/text-input",
+                  "scripting/api-reference/artboards/view-model",
+                  "scripting/api-reference/artboards/view-model-change"
                 ]
               },
               {
diff --git a/scripting/api-reference/artboards/focus-event.mdx b/scripting/api-reference/artboards/focus-event.mdx
new file mode 100644
index 00000000..fd1c4046
--- /dev/null
+++ b/scripting/api-reference/artboards/focus-event.mdx
@@ -0,0 +1,14 @@
+---
+title: FocusEvent
+---
+
+Represents a Focus event data
+
+
+## Fields
+
+### `isFocus`
+
+Whether the element gained or lost focus
+
+
diff --git a/scripting/api-reference/artboards/key-phase.mdx b/scripting/api-reference/artboards/key-phase.mdx
new file mode 100644
index 00000000..8a9073c3
--- /dev/null
+++ b/scripting/api-reference/artboards/key-phase.mdx
@@ -0,0 +1,4 @@
+---
+title: KeyPhase
+---
+
diff --git a/scripting/api-reference/artboards/keyboard-event.mdx b/scripting/api-reference/artboards/keyboard-event.mdx
new file mode 100644
index 00000000..0075f66b
--- /dev/null
+++ b/scripting/api-reference/artboards/keyboard-event.mdx
@@ -0,0 +1,39 @@
+---
+title: KeyboardEvent
+---
+
+Represents a keyboard interaction.
+
+
+## Fields
+
+### `key`
+
+The pressed key
+
+
+### `shift`
+
+Whether the shift modifier is pressed.
+
+
+### `control`
+
+Whether the control modifier is pressed.
+
+
+### `alt`
+
+Whether the alt modifier is pressed.
+
+
+### `meta`
+
+Whether the meta modifier is pressed.
+
+
+### `phase`
+
+Phase of the keyboard event (down, repeat or up).
+
+
diff --git a/scripting/api-reference/artboards/listener-context.mdx b/scripting/api-reference/artboards/listener-context.mdx
new file mode 100644
index 00000000..32f27eff
--- /dev/null
+++ b/scripting/api-reference/artboards/listener-context.mdx
@@ -0,0 +1,177 @@
+---
+title: ListenerContext
+---
+
+Represents the context of a listener perform action
+
+
+## Methods
+
+### `isPointerEvent`
+
+{/* isPointerEvent: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isPointerEvent() -> boolean
+```
+</div>
+
+returns true if the perform action was invoked through a pointer event
+
+
+### `isKeyboardEvent`
+
+{/* isKeyboardEvent: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isKeyboardEvent() -> boolean
+```
+</div>
+
+returns true if the perform action was invoked through a keyboard event
+
+
+### `isTextInput`
+
+{/* isTextInput: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isTextInput() -> boolean
+```
+</div>
+
+returns true if the perform action was invoked through a text input
+
+
+### `isFocus`
+
+{/* isFocus: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isFocus() -> boolean
+```
+</div>
+
+returns true if the perform action was invoked through a focus change
+
+
+### `isReportedEvent`
+
+{/* isReportedEvent: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isReportedEvent() -> boolean
+```
+</div>
+
+returns true if the perform action was invoked through a Rive event
+
+
+### `isViewModelChange`
+
+{/* isViewModelChange: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isViewModelChange() -> boolean
+```
+</div>
+
+returns true if the perform action was invoked through a view model change
+
+
+### `isNone`
+
+{/* isNone: (self: ListenerContext) -> boolean */}
+<div class="signature">
+```lua
+isNone() -> boolean
+```
+</div>
+
+returns true if the perform action is none of the known types
+
+
+### `asPointerEvent`
+
+{/* asPointerEvent: (self: ListenerContext) -> PointerEvent? */}
+<div class="signature">
+```lua
+asPointerEvent() -> PointerEvent?
+```
+</div>
+
+returns a pointer event if context is of type pointer event, null otherwise
+
+
+### `asKeyboardEvent`
+
+{/* asKeyboardEvent: (self: ListenerContext) -> KeyboardEvent? */}
+<div class="signature">
+```lua
+asKeyboardEvent() -> KeyboardEvent?
+```
+</div>
+
+returns a keyboard event if context is of type keyboard event, null otherwise
+
+
+### `asTextInput`
+
+{/* asTextInput: (self: ListenerContext) -> TextInput? */}
+<div class="signature">
+```lua
+asTextInput() -> TextInput?
+```
+</div>
+
+returns a text input event if context is of type text input event, null otherwise
+
+
+### `asFocus`
+
+{/* asFocus: (self: ListenerContext) -> FocusEvent? */}
+<div class="signature">
+```lua
+asFocus() -> FocusEvent?
+```
+</div>
+
+returns a focus event event if context is of type focus event, null otherwise
+
+
+### `asReportedEvent`
+
+{/* asReportedEvent: (self: ListenerContext) -> ReportedEvent? */}
+<div class="signature">
+```lua
+asReportedEvent() -> ReportedEvent?
+```
+</div>
+
+returns a reported event if context is of type reported evnet, null otherwise
+
+
+### `asViewModelChange`
+
+{/* asViewModelChange: (self: ListenerContext) -> ViewModelChange? */}
+<div class="signature">
+```lua
+asViewModelChange() -> ViewModelChange?
+```
+</div>
+
+returns a view model change if context is of type view model, null otherwise
+
+
+### `asNone`
+
+{/* asNone: (self: ListenerContext) -> NoneEvent? */}
+<div class="signature">
+```lua
+asNone() -> NoneEvent?
+```
+</div>
+
+returns a noop event if context is of type none, null otherwise
+
+
diff --git a/scripting/api-reference/artboards/none-event.mdx b/scripting/api-reference/artboards/none-event.mdx
new file mode 100644
index 00000000..5c5c0c17
--- /dev/null
+++ b/scripting/api-reference/artboards/none-event.mdx
@@ -0,0 +1,7 @@
+---
+title: NoneEvent
+---
+
+Represents a reported event
+
+
diff --git a/scripting/api-reference/artboards/pointer-event.mdx b/scripting/api-reference/artboards/pointer-event.mdx
index aae23ed6..37ae3dc6 100644
--- a/scripting/api-reference/artboards/pointer-event.mdx
+++ b/scripting/api-reference/artboards/pointer-event.mdx
@@ -17,6 +17,11 @@ The position of the pointer in local coordinates.
 The unique identifier for the pointer.
 
 
+### `type`
+
+The type of event (pointerDown, pointerUp, click, pointerEnter, pointerMove, etc).
+
+
 ## Constructors
 
 ### `new`
diff --git a/scripting/api-reference/artboards/pointer-type.mdx b/scripting/api-reference/artboards/pointer-type.mdx
new file mode 100644
index 00000000..aaf2dc14
--- /dev/null
+++ b/scripting/api-reference/artboards/pointer-type.mdx
@@ -0,0 +1,4 @@
+---
+title: PointerType
+---
+
diff --git a/scripting/api-reference/artboards/reported-event.mdx b/scripting/api-reference/artboards/reported-event.mdx
new file mode 100644
index 00000000..97f7bc77
--- /dev/null
+++ b/scripting/api-reference/artboards/reported-event.mdx
@@ -0,0 +1,7 @@
+---
+title: ReportedEvent
+---
+
+Represents a reported event
+
+
diff --git a/scripting/api-reference/artboards/text-input.mdx b/scripting/api-reference/artboards/text-input.mdx
new file mode 100644
index 00000000..57c341be
--- /dev/null
+++ b/scripting/api-reference/artboards/text-input.mdx
@@ -0,0 +1,14 @@
+---
+title: TextInput
+---
+
+Represents a Text input data
+
+
+## Fields
+
+### `text`
+
+The text passed as input
+
+
diff --git a/scripting/api-reference/artboards/view-model-change.mdx b/scripting/api-reference/artboards/view-model-change.mdx
new file mode 100644
index 00000000..c289f28f
--- /dev/null
+++ b/scripting/api-reference/artboards/view-model-change.mdx
@@ -0,0 +1,7 @@
+---
+title: ViewModelChange
+---
+
+Represents a View model change data
+
+
diff --git a/scripting/api-reference/interfaces/listener-action.mdx b/scripting/api-reference/interfaces/listener-action.mdx
index 74bd0aeb..ff76a4ff 100644
--- a/scripting/api-reference/interfaces/listener-action.mdx
+++ b/scripting/api-reference/interfaces/listener-action.mdx
@@ -40,7 +40,7 @@ end
 
 ### `perform`
 
-{/* perform: (self: T, pointerEvent: PointerEvent) -> () */}
+{/* perform: ((self: T, pointerEvent: PointerEvent) -> ())? */}
 <div class="signature">
 ```lua
 perform(self: T, pointerEvent: PointerEvent) -> ()
@@ -49,6 +49,7 @@ perform(self: T, pointerEvent: PointerEvent) -> ()
 
 Called when the associated [State Machine Listener](/editor/state-machine/listeners) is triggered.
 This method includes a [PointerEvent](/scripting/api-reference/artboards/pointer-event) parameter containing details about the triggering interaction.
+**Deprecated.** Prefer `performAction` with [ListenerContext](/scripting/api-reference/artboards/listener-context); this overload may be removed.
 ```lua highlight={9,10,11,17}
 type MyListenerAction = {}
 
@@ -71,3 +72,38 @@ end
 ```
 
 
+### `performAction`
+
+{/* performAction: ((self: T, listenerContext: ListenerContext) -> ())? */}
+<div class="signature">
+```lua
+performAction(self: T, listenerContext: ListenerContext) -> ()
+```
+</div>
+
+Called when the associated [State Machine Listener](/editor/state-machine/listeners) is triggered.
+This method includes a [ListenerContext](/scripting/api-reference/artboards/listener-context) parameter containing details about the triggering interaction.
+```lua highlight={9,10,11,17}
+type MyListenerAction = {}
+
+function init(self: MyListenerAction, context: Context): boolean
+  return true
+end
+
+-- Add your transition logic here.
+-- `evaluate` is fired every frame while the transition is active.
+-- Returning false prevents a transition, true allows a transition.
+function performAction(self: MyListenerAction, listenerContext: ListenerContext)
+  return true
+end
+
+-- Return a factory function that Rive uses to build the Listener Action instance.
+return function(): ListenerAction<MyListenerAction>
+  return {
+    init = init,
+    performAction = performAction,
+  }
+end
+```
+
+