Formulas

A formula is an expression bound to one property. Instead of a number, the field holds a rule, and the property follows it: when anything the rule reads changes, the property updates.

Try it

Draw a star and name it Star. Click its Rotation field, type =, and write:

// Star.rotation
time * 90

Press Play. The star turns 90 degrees every second. Stop, and it goes back to where it was. Now bind x to the cursor in the same way:

// Star.x
mouse.x

Writing one

Type = in a number field and the field becomes an editor. Write an expression and press Enter. The field shows the computed value with an fx badge. A line under the editor shows the result while you type, or the error.

A formula is one expression. It returns a value and changes nothing. To remove it, clear the text: the field keeps the number it was showing.

While a formula is bound, the field is locked. You cannot type into it, drag it on the canvas or set it from the panel. Remove the formula first.

Pointing at things

// Shadow.x
Ball.x + 20
// Label.opacity
this.opacity * parent.opacity
  • Ball.x — a property of the layer named Ball. Use the name from the layer list.
  • this — the node the formula sits on.
  • parent — the node it is nested in.
  • Tag.brick — every node tagged brick. Tag.brick.length counts them and Tag.brick[0].x reads the first. When a tagged node is added or destroyed, formulas reading the tag update.

Properties are named by their schema keys, the same ones every node page in this reference lists. Width is w, height is h, not width and height. Properties you added to a component are read the same way: Hero.speed.

An unknown name is an error: Unknown identifier 'Ball'.

Paint properties

Fills and strokes are addressed by index, then the part of the paint:

// Orb.fills[0].color.h
time * 60
  • fills[0].opacity — the paint's opacity.
  • fills[0].color.r, .g, .b, .a — red, green, blue and alpha, 0 to 1. r, g, b and a alone work too.
  • fills[0].color.h, .s, .v — hue, saturation and value.
  • fills[0].color.lab.l, .lab.a, .lab.b, or .L, .C, .H for OKLCH.
  • fills[0].color.hex — the colour as text.
  • fills[0].stops[1].position — a gradient stop.
  • fills[0].params.speed — a parameter of a shader fill. See Shaders.

strokes[0] works the same way. Several formulas on one fill, one per channel, are fine.

Units

A formula reads and writes what the property stores, which can differ from what the panel shows.

  • rotation and skew are in degrees.
  • Every other angle is in radians, so sin and cos take them as they are.
  • Ratios and percentages are 0 to 1. The panel shows 0 to 100%, the formula sees 0.5.
  • Positions and sizes are pixels.

The formula popup lists the unit next to each property.

Special variables

  • mouse — the pointer. mouse.x and mouse.y are in canvas coordinates, mouse.down is true while a button is held, mouse.button says which (0 left, 1 middle, 2 right).
  • keys — held keys. keys.Space is true while Space is down. Names are the browser's key names, so keys.a and keys.A (Shift) are different, and arrows are keys.ArrowLeft.
  • time — seconds since Play started.
  • frame — frames since Play started, from 0.
  • dt — seconds since the previous frame, about 0.016 at 60 fps.
  • input — device channels by dotted name: input.pointer.pressure, input.pad0.LeftStick.x. A channel nobody has sent reads 0. Only formulas reading that channel update when it moves.
  • Tag — tagged nodes, above.
  • Audio — the sound system while the scene plays: Audio.play(file), Audio.stopAll().
  • console — console.log(...) writes to the browser console (F12). Use it in events and methods.
  • event — the data of the event that ran the code. Only events have it; each event page lists its fields.

time, frame and dt are the clock of Play. A formula reading them runs every frame.

Also available: PI, E, Math, JSON, Number, String, Array, Object, Date and the usual parsing and timer functions. The functions made for formulas are on Formula functions: sin, clamp, lerp, distance, delay and the rest.

Operators

  • Arithmetic: + - * / % and **.
  • Comparison: == != < > <= >=.
  • Logic: && || !.
  • Choice: condition ? a : b.
// Door.opacity
Player.x > Door.x - 100 ? 1 : 0.3

Formula, event, method

The same language runs in three places.

  • Formula — one expression on a property. Assignments are an error: Formulas cannot contain assignments.
  • Event — code that runs when something happens: a click, a collision, each frame. Statements, if, loops and variables work, and so does assigning to properties.
  • Method — named code on a node that events and formulas call: Hero.reset().
// Ball: on click
this.x += 10
Shadow.x = this.x + 20

Event and method code writes to properties. It does not bind them, so the property stays editable. See Events.

Order and cycles

You do not order formulas. A formula runs after the formulas it reads:

// Middle.y
Source.y + 30
// Output.y
Middle.y + 30

Move Source and Middle, then Output, update in one pass. A formula reading two things that both changed runs once.

A formula that depends on itself, directly or through others, is rejected:

// Ball.x
Wall.x + 10

If Wall.x is a formula reading Ball.x, the second one fails with Circular dependency and the chain that closes the loop. The first keeps working.

Numbers without =

A number field does arithmetic on its own, once, and keeps the result. No =, no binding.

  • 200 + 50% with 200 in the field gives 300. A % means that share of the current value.
  • 100% - 20px gives 180.
  • (100 + 50) * 2 gives 300.
  • .5 * 400 gives 200.

Operators are + - * / and brackets. A value that is not valid arithmetic is ignored. For anything that should keep updating, use =.

When it goes wrong

  • The line under the editor shows the error while you type: an unknown name, an assignment in a formula, a syntax mistake, a cycle.
  • A formula that fails to compile replaces the old one, and the old one stops running.
  • A rejected cycle is reported the same way, with the chain of properties that closes the loop.

See also

Formo

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