Skip to content

3D scenes ​

A stage3d block is a 3D scene written as data: things to place, and a timeline of what they do. There are no model files to find and no code to trust, so it's easy to reword, and easy for an agent to write. It suits explainers, stories and stylised product shots.

Add a Stage3d block to a scene. It fills the whole picture, and any other blocks in the scene sit on top of it.

A first scene ​

Someone walks across the street, then dances:

json
{
  "type": "stage3d",
  "world": { "light": "day", "background": "#9cc488", "floor": "#93c07a" },
  "camera": { "view": "isometric", "target": [0, 1, 0], "size": 14 },
  "actors": [
    { "kind": "road", "id": "road", "position": [0, 0, 3] },
    { "kind": "tree", "id": "tree", "position": [5, 0, -3] },
    { "kind": "person", "id": "amina", "position": [-6, 0, 3], "scale": 1.3 }
  ],
  "timeline": [
    { "at": 0, "actor": "amina", "seconds": 4, "ease": "linear", "move": [1, 0, -1] },
    { "at": 4, "actor": "amina", "clip": "dance" }
  ]
}

Everything happens on the timeline, and each entry says when, to what, and what changes. A person walks to wherever you move them, faces the way they're going, and stands when they arrive.

The scene lasts until its last entry ends, or longer if its voice line is longer. To hold a pose or a dance, give the camera or an actor an entry that ends later.

Actors ​

KindWhat it isIts own fields
box, cylinder, cone, sphere, discPlain shapessize or radius and height, plus a surface
latheA shape spun around its axis: bottles, cans, vasesprofile, optional label, plus a surface
personA person with real bonesshirt, trousers, skin, hair
carA car whose wheels turn and door openscolor
buildingA building with columns and a door. Its origin is on the ground at the doorlabel, color, roof
road, tree, lampSceneryroad has length and width
modelA .glb file in the project's media/ folderpath

A surface is color, rough, metal, coat for a glossy top coat, and glow. Every actor also has an id, position, rotate in degrees, scale and hidden.

Heights use y, so [x, y, z] with y going up. A box or cylinder is centered on its position.

A product ​

A lathe spins a list of [radius, height] points into a shape. Its label wraps around it, and it's drawn with the project's fonts:

json
{
  "kind": "lathe",
  "id": "bottle",
  "color": "#4a1d07",
  "rough": 0.07,
  "coat": 1,
  "profile": [[0, 0], [0.92, 0], [1, 0.1], [1, 2.5], [0.56, 3.55], [0.4, 3.85], [0.4, 4.4], [0, 4.4]],
  "label": { "text": "SAMPLE", "sub": "A line about it", "y": 1.45, "height": 1.6 }
}

Use "light": "studio" for product shots. It's what gives glossy surfaces something to reflect.

For a product people need to recognise, use a real model file. A shape from a list of points shows the idea, not the exact product.

Timeline ​

FieldWhat it does
atWhen it starts, in seconds
actorAn actor's id, or camera
secondsHow long it takes. Leave it out for an instant change
easelinear, in, out or inout
moveGo to this position
rotate, scaleTurn to this many degrees, or grow to this size
openA building's or car's door: 0 is shut, 1 is open
showtrue or false
clipPlay an animation
speedClip speed: 0.5 is half speed
facefalse keeps a moving actor facing the way it was
target, size, fovFor the camera: what it looks at, and how much fits

A person's clips are walk, stand and dance. A walk's speed matches the move, so the feet keep pace with the ground. A clip with seconds stops when they're up, and one without keeps playing. A model's clips are whatever its file holds, and if you ask for one it doesn't have, the error lists the ones it does.

Camera ​

FieldDefaultWhat it does
viewisometricisometric keeps lines parallel, for that clean, nearly 2D look. perspective is like a real lens
position, target[21, 21, 25], [0, 1, 0]Where it is, and what it looks at
size15Isometric: how many world units tall the 16:9 picture is. Smaller is closer
fov30Perspective: the lens angle at 16:9
tallZoom1How much closer to get in 9:16

Other shapes keep the width of the 16:9 picture, so nothing is cut off the sides of a tall frame. That leaves subjects small, so set tallZoom to about 2 for TikTok, Reels and Shorts, then check that what matters is still in the picture.

World ​

FieldDefaultWhat it does
lightdayday, night or studio
background#9cc488The color behind everything
gradient[top, bottom] colors, in place of the background
floorA floor color; leave it out for no floor
exposure1Overall brightness
shadowReach24How far from the target shadows reach. Keep it near the size of your scene, for sharper shadows

Real models ​

Upload a .glb to media/, and use it as a model actor. It has to be self-contained: with its textures embedded, not in separate files. Models with their own animations can play them with clip.

Check a model's licence before you publish. Some, like Mixamo's, can be used in your videos, but community answers say the raw files can't be shared, so don't commit them to a public repository.

Good to know ​

  • It's plain data. A stage3d block runs no project code, so unlike a custom scene there's nothing to trust. A .glb can only load itself and what's embedded in it, so a shared model can't make your machine contact anything else.
  • Renders need WebGL. That's normally your GPU. A render fails with a message if it can't start, or if a model can't load.
  • Every frame comes from the time alone, so the same moment always draws the same picture, in preview and in the render.
  • The look is stylised. For photoreal shots, render in a tool like Blender. Formercial doesn't have a video block yet to bring that footage in.

Released under the Apache License 2.0.