Events API

Nodes respond to clicks, hovers, and collisions. Write handler code that runs when events fire.

Try it

title: "Click to change color"
description: "Click the shape to cycle through colors"
nodes:
  - type: RECT, name: "Box", x: 200, y: 200, w: 100, h: 100, fill: "#3498DB", cornerRadius: 8
events:
  - node: "Box", event: "click", code: "this.rotation = this.rotation + 45"
tools_visible: [select, play]
ui_visible: [properties, formulas]

Available events

Event objects

Mouse events

event.target    // VNode — the node that was interacted with
event.x         // number — pointer X in world coordinates
event.y         // number — pointer Y in world coordinates
event.offsetX   // number — pointer X relative to node (lazy)
event.offsetY   // number — pointer Y relative to node (lazy)
event.button    // number — 0=left, 1=middle, 2=right
event.ctrlKey   // boolean
event.shiftKey  // boolean

offsetX/offsetY are lazy — computed only when accessed (avoids matrix inversion when not needed).

Collide event

event.target          // VNode — the other node in the collision
event.targetId        // string — name of the other node
event.collider        // string — name of this node's collider
event.targetCollider  // string — name of the other node's collider
event.normal          // {x, y} — contact surface normal
event.point           // {x, y} — contact point in world coordinates

Autocomplete for event properties

Type event. in the code editor — autocomplete shows properties specific to the current event type:

• Mouse events: target, x, y, offsetX, offsetY, button, ctrlKey, shiftKey, stopPropagation
• Collide: target, targetId, collider, targetCollider, normal, point
• event.target.: all VNode properties (x, y, width, etc.)
• event.normal.: x, y
• event.point.: x, y

Writing event handlers

In the properties panel

1. Select a node
2. Find the "Events" section in the properties panel
3. Click "Add Event"
4. Choose the event type from the dropdown
5. Write your handler code in the code editor

Handler syntax

Event handlers are compiled as statement blocks. this refers to the owning node. event provides event data.

// Simple: rotate on click
this.rotation += 15

// Conditional: destroy on bullet collision
if (event.target.is("bullet")) {
  this.destroy()
}

// Complex: track clicks and change behavior
this.clickCount = (this.clickCount || 0) + 1
if (this.clickCount >= 3) {
  this.destroy()
}

Calling methods from events

// Call a method defined on this node
this.reset()

// Call a method on another node
Ball.launch()

Methods

User-defined functions on nodes. Like events but callable from anywhere.

Defining a method

1. In the code editor, switch the action dropdown from an event to "Methods"
2. Click "Add Method"
3. Name it (e.g., "reset")
4. Write the method body

// Method "reset" on Ball node
this.x = 200
this.y = 300
this.velocityX = 0
this.velocityY = 0

Calling methods

// From an event handler
this.reset()           // call on self
Ball.reset()           // call on another node

// From a formula (side effect — use sparingly)
// Methods are better called from events

Event bubbling

Mouse events bubble through the node hierarchy. A click on a child inside a frame also fires the frame's click handler. Use event.stopPropagation() to stop bubbling.

// On a child node — stop the event from reaching the parent
event.stopPropagation()
this.opacity = 0.5

Compilation

Event handlers compile with the event compile mode:

1. Parse — handler body parsed as JavaScript statements
2. Transform — node references → ctx.resolve(), method calls → ctx.callMethod()
3. Source maps — inline VLQ-encoded maps with sourceURL label per event
4. Wrap — function receives (self, ctx, event)

Compile errors log to console with line and column information. If compilation fails, the previous working handler is removed — broken code never runs.

Code editor shortcuts

→ Formulas API → Physics API → Nodes