DocsStudio

Objects and templates

An object is a thing in your scene with a place of its own: a lantern, a fish, a ball. It's made of the scene's layers, it can move, turn and grow, it can have a body that falls and bounces, and the scene's logic can find it, spawn more like it and tell it what to do. In Studio, the objects are in the Outliner and their settings on the right.

Try it: Vent Garden (objects from templates, with physics).

Most scenes don't need objects. Layers and their settings do a lot on their own. Objects are for scenes where things behave: a swarm that follows the pointer, lanterns you click to light, balls that bounce off each other.

The scene's logic calls them motes (Mote, scene.motes), and a template a mote class.

Layers and objects

A layer draws something. An object says where that something is and what it is.

Make an object of a layer and the layer is bound to the object. Move the object and the layer goes with it; turn it and the layer turns; destroy it and the layer is hidden. One object can hold several layers (a lantern's glass and its glow), each bound as one of its components.

A template is a reusable object you place copies of: Lantern, Spark, Fish. Every object made from a template behaves the same way, because the template's logic says how. An object with no template is a plain object: a place for its layers, that the logic can still find and move.

Objects in Studio

The objects are listed in the Outliner, on the left of Studio, under Objects (above the layers, once the scene has an object or a template). Each shows its name and its template. Click one to pick it; double-click to rename it. Right-click one for Rename, Duplicate, Delete and Add an object…. Deleting an object leaves its layers, as ordinary layers.

Make an object

Add an object…, or the + on the Objects row in the Outliner (with the pointer over it), offers:

• Of the picked layer: an object of the layer picked in the Outliner, standing where the layer's middle is, so nothing on the screen moves.
• Place one of the scene's templates, with where it comes from: an object made from that template.

A layer's own menu (right-click it in the Outliner) has Make an object of it too, which is how a scene's first object is made, and Make a template of it. The command palette has both, and Place for each template.

An object's settings

Pick an object in the Outliner and its settings show on the right, where a layer's would. At the top is its name and template, and that it's picked in the Outliner; under it:

• Its id (what the logic finds it by), with Duplicate and Delete. Deleting an object takes it out, but its layers stay, as ordinary layers.
• Name and Template.
• Across and Down: where it stands, in the scene's own pixels from the top left (1920 by 1080 unless the scene is set to another size). Turn and Size. Change these and its layers move, turn and grow with it.
• Tags: words to find it by, with commas between. The logic can find every object with a tag.
• Components: the layers bound to it. Bind a layer binds one of the scene's layers; the cross beside one unbinds it.
• Has a body: the physics moves it (next section).
• Its template's properties, when the template has some you can set: a lantern's brightness, a fish's speed.

Pick a layer, or Scene, and the settings show that instead.

Bodies

Turn on Has a body and the object takes part in the physics: it falls, bounces, and is pushed. Its settings:

• Moves: By itself (gravity and knocks move it), Never (a wall or a floor) or Where it's put (the logic moves it, and it pushes others out of the way).
• Shape: Circle, Box or Capsule, with Radius, or Width and Height, in pixels.
• Bounce, Friction and Weight.
• Never turns: it slides and falls but stays upright.

The logic can push a body, set its speed, and hear when two bodies start or stop touching.

Templates

Add an object… offers three kinds of template.

• Made of layers: right-click a layer in the Outliner and pick Make a template of it. That layer becomes the template's: it's hidden while the scene plays, and each object placed of the template in Studio, or spawned by the logic, gets a copy of it. Place a few and each has a layer of its own, named after it.
• Drawn as a graph: a class drawn in the Event graph, in a scene whose logic is TypeScript.
• Written in the script: a class written in the scene's TypeScript and marked as one you can place.

A template drawn or written can have properties, and they show in the object's settings for you to set object by object. The templates kept in your library are in Assets › Library › Templates.

What the logic can do with objects

The scene's logic, as a graph or as code, can:

• find a mote by name or id, every mote of a class, or every mote with a tag
• spawn a mote of a class (with copies of its template layers), and destroy one
• move, nudge, turn and size a mote at once, or glide it somewhere over a few seconds
• hear when a mote is clicked, when the pointer comes over it or leaves, or when two motes' bodies start or stop touching
• push a mote's body, give it a force or a turning push, put it to sleep, or cast a ray and find the first body it meets
• join two motes' bodies (as one, on a hinge, a slider, a spring or a rope) and let them go again, and change the gravity (2D and 3D)
• tag and untag a mote, attach one to another, and let the pointer drag one

In code, a class extends Mote and has onStart, onTick(dt), onClicked and onHit for things that happen to it:

import { Mote, register } from "motion";

class Lantern extends Mote {
    onTick(dt: number): void {
        this.addRotation(40 * dt);
    }
}
register(Lantern, "Lantern");

A class that extends Stage is made once, when the scene starts, to set it up: spawning a swarm, say. It has everything stage has (finding, spawning, rays, gravity, joints), and hears onStart, onTick(dt) and onSettingsChanged(props) when the wallpaper's settings change.

import { Mote, Stage, DragComponent, register, stage, scene } from "motion";

class Lantern extends Mote {
    drag = new DragComponent("drag", this);
    onDragEnd(): void { this.applyImpulse({ x: 0, y: -200 }); }
}
class Room extends Stage {
    onStart(): void {
        const hook = stage.byName("Hook")!, lantern = stage.byName("Lantern")!;
        stage.join(lantern, hook, { kind: "rope", length: 120 });
    }
    onSettingsChanged(props: Record<string, any>): void {
        stage.setGravity({ x: props.wind ?? 0, y: 980 });
    }
}
register(Lantern, "Lantern");
register(Room, "Room");

A mote without a body (or one that's been destroyed) does nothing when it's pushed, and the console says so once. A joint goes with either of its bodies. In a graph, the nodes include Spawn Mote, Move Mote To, On Mote Clicked, On Mote Hovered, Add Tag and Attach Mote under Motes, and Make Joint, Add Force, Set Gravity and On Motes Stop Touching under Physics. Logic as code, Logic as a graph and the scripting reference have the rest.

A Web project page can ask the motes things too: their names, a property, a method of their class, where they are.

The scene's settings for its logic and physics

Pick Scene at the top of the Outliner. Under Script:

• Script timing: Script ticks a second, how often the logic runs (0, the default, is each frame; a slow scene of a few objects can tick 10 or 20 times a second and cost less), and Script's budget a frame (ms), how long the logic may take each frame. When it takes longer, Motion runs it less often.
• Physics: Gravity (2D, down), the pull on 2D bodies in pixels a second a second (980 is about Earth's at the usual size; below 0 they rise), Gravity (2D, right), a pull to the side, like a wind or a current (below 0 it pulls to the left), and Gravity (3D, up), the pull on 3D bodies in metres a second a second (-9.81 is Earth's).

While the preview plays, the bar under it shows how many objects and bodies there are, amber when the logic is over its budget; hold the pointer over it for how long a tick takes and whether it runs each frame or every few frames.

Last changed 2 November 2026. Something wrong here? Tell us.