Events and methods

An event is a piece of code that runs when something happens to a node: it is clicked, the pointer enters it, a frame passes, it hits another body. A method is code you name yourself and call from events, formulas or other methods. Both live on the node and both can change any property in the scene.

Try it

Draw a rectangle and name it Box. In the properties panel open Events, press + and choose click. In the code field type:

// Box: on click
this.rotation += 15

Press Play and click the box: it turns 15 degrees on every click. Stop brings it back.

Now turn the counting into a method. Under Methods add one called spin with the argument deg, and write its body:

// Box: method spin(deg)
this.rotation += deg

Change the click event to call it. Any other node can call it too:

// Box: on click
this.spin(15)
// Button: on click
Box.spin(90)

What an event can contain

An event body is a list of statements, not a single expression like a formula. It can assign to properties, declare locals, branch and loop:

// Box: on click
let step = event.shiftKey ? 90 : 15
if (this.rotation > 300) {
  this.rotation = 0
} else {
  this.rotation += step
}
for (const b of Tag.brick) b.opacity = 0.5
  • this is the node that owns the handler. Box.rotation and this.rotation are the same value.
  • event is what happened. Its fields depend on the event, listed below.
  • Other nodes are reached by name, as in a formula: Ball.x, Tag.brick, parent, mouse, keys, time, dt.
  • Assigning to a property (this.x = 5) changes it, and every formula that reads it updates.
  • Units are the ones code uses: rotation is in degrees, opacity is 0 to 1.

Events run only while the scene plays. In the editor, outside Play, nothing fires. If the code has an error, the previous working version is dropped, so broken code never runs, and the error is shown on the node.

Pointer events

All pointer events put the same fields on event:

  • x, y — pointer position in the scene.
  • offsetX, offsetY — pointer position relative to the node.
  • target — the node the handler is running on.
  • originalTarget — the deepest node under the pointer.
  • button — 0 left, 1 middle, 2 right.
  • ctrlKey, shiftKey, altKey, metaKey — modifier keys held.
  • stopPropagation() — stop the event from going up to the parents.

The events:

  • click — the pointer went down and came up on the same deepest node.
  • dblclick — a second click on the same node within half a second. Its click runs first.
  • mousedown, mouseup — a button went down or up over the node.
  • mousemove — the pointer moved over the node.
  • mouseenter, mouseleave — the pointer moved onto the node or off it. Each fires once per crossing.
  • pointerdown, pointerup, pointermove, pointerenter, pointerleave — the same moments under the pointer names. Both names fire, so use either.

Bubbling

click, dblclick, mousedown, mouseup, mousemove and their pointer names bubble. The deepest node under the pointer gets the event first, then its parent, then the parent's parent, up to the top. A button inside a card inside a panel runs the button's handler, then the card's, then the panel's.

// Button: on click
event.stopPropagation()
this.opacity = 0.5

After stopPropagation() no parent handler runs. While the event goes up, event.target is the node whose handler is running and event.originalTarget stays the node that was hit.

mouseenter and mouseleave do not bubble. When the pointer moves from the card onto a button inside it, only the button gets mouseenter, because the card was already entered. When it leaves the card from inside the button, the button and the card both get mouseleave.

tick

tick runs once per frame on every node that has the handler, while the scene plays. event holds three numbers:

  • dt — seconds since the last frame.
  • time — seconds since Play.
  • frame — frames since Play.
// Ship: on tick
this.x += 120 * event.dt

Multiply by dt and the speed stays the same on slow and fast screens.

collide

collide is available on a node that has the Physics module. It runs once, at the moment two bodies start touching, on both of them. Each handler sees the other one:

// Ball: on collide
if (event.target.is('brick')) {
  event.target.destroy()
}
  • target — the other node.
  • targetId — its id.
  • collider, targetCollider — the names of the two colliders that touched.
  • normal — the direction of the contact surface, { x, y }, from the point of view of the node that runs the handler. The other node sees it flipped.
  • point — where they touched, { x, y }.

List: itemClick

A List node has one more event. itemClick runs when any item of the list is clicked. It takes three values instead of one:

  • event — the click, as above.
  • item — the item that was clicked.
  • data — the record the item was pushed with, or null.
// Cards: on itemClick
if (item.opacity < 1) Cards.remove(item)
else item.opacity = 0.5

One handler serves every item, however many there are. The list itself also has methods (push, remove, clear, shuffle, move); see List.

Your own methods

A method is a named block of code on a node. Add it under Methods in the properties panel: a name, optional arguments, a body. Call it with a dot, from any event or method:

// Ball: method launch(speed, angle)
this.x = 100
this.y = 400
this.physics.velocity.x = Math.cos(angle) * speed
this.physics.velocity.y = Math.sin(angle) * speed
// Ball: on click
this.launch(300, 0.8)
// Cannon: on tick
if (keys.Space) Ball.launch(300, 0.8)
  • this.name(...) calls a method of the same node, Ball.name(...) one of another node.
  • Arguments are positional and named in the method's header. An argument you leave out is undefined.
  • Inside a method this is the node the method belongs to, not the caller.
  • A method can call other methods.
  • clone() copies the methods and events along with the node.

Methods every node has

These work on any node, from an event or a method:

  • is(typeOrTag) — true if the node has this type ('RECT') or this tag ('brick'). Tags are set in the properties panel and found with Tag.brick.
  • destroy() — marks the node for removal. It stays valid until the end of the frame, so the rest of the handler can still read it.
  • clone() — makes a copy next to the original and returns it, with its formulas, events and methods. While the scene plays, the copy runs them.
  • appendChild(child), removeChild(child), insertBefore(node, ref), replaceChildren(...nodes), insertAdjacentElement(position, node) — move nodes in and out of a container, as in the browser's DOM.
  • on(name, fn), off(name, fn), fire(name, ...args) — listeners of your own. fire calls every function added with on under that name, passing the arguments along. It does not run a handler written in the Events section.
// Gun: on click
const b = Bullet.clone()
b.x = this.x
b.y = this.y

Some node types add their own: play and stopPlayback on a component instance, play and stop on a skeleton, play, stop, pause and resume on audio. They are described with clips, in Clips and timeline control.

What is not there yet

  • A component's own declared events are not covered here: this page does not describe how to fire them.

See also

Formo

The browser studio where drawings become animations, toys, and games. Your files, nothing to install.