Scene#

Type: object

A scene is a distinct, sequential segment of the movie. Scenes play in the order they appear in the parent movie's scenes array. Scenes cannot overlap in time. Each scene holds its own elements, optional transition, and local variables.

Properties#

background-color#

Background color of the scene. Hexadecimal value (e.g. #FF0000) or transparent.

cache#

If true, a previously rendered version of this scene is reused when its inputs match. If false, the scene is rendered from scratch.

comment#

Free-form note attached to the scene. Ignored by the renderer.

condition#

Expression evaluated at render time. The scene is included only if the expression is truthy. Empty strings and falsy values cause the scene to be skipped.

duration#

Scene duration in seconds. -1 makes the scene as long as needed to contain all its elements.

elements#

Elements rendered inside the scene. Stacking order in the array determines layering — later items render on top.

Array items#

Each item is one of the element types defined in Element. The discriminator is the type field.

id#

Unique identifier for the scene. Auto-generated when omitted.

import#

ID of another scene to import. Imported scenes are merged into the current scene by appending their elements array. Useful with templates.

iterate#

Name of a movie-level variable holding an array of objects. Before expressions are evaluated, the scene is duplicated once per array item. Each item's own fields are added to the copy's local variables as flat names — an item { "name": "Kitchen" } is read as {{ name }}, not {{ item.name }} — together with three automatic variables:

• iteration — 1-based counter, incremented once per visited array position.
• first_iteration — true on the copy for the first position of the range.
• last_iteration — true on the copy for the last position of the range.

Used to generate slideshow-style sequences from data.

Dot notation reaches an array nested inside an object variable, e.g. "product.images". The path is walked from the movie's variables until an array is found.

Things worth knowing:

• iterate also works on elements, both inside scene.elements and in the movie-level elements array — not just on scenes.
• Array items that are not objects produce no copy. An array of plain strings or numbers (["a", "b"]) expands to zero scenes, and the scene disappears from the movie with no error. Mixed arrays still advance the iteration counter for the skipped positions, so the counter is not necessarily consecutive.
• An empty array removes the scene from the movie entirely.
• A variable that is missing, or that does not resolve to an array, fails the render with "iterate" property in scene #N does not point to an array variable in global variables.
• Every copy keeps the template's id. All copies of a scene share the same identifier, so an id cannot be used to address one specific iteration.
• There is no iterate-as property and no item scope; adding one fails with Property 'iterate-as' is not allowed.
• last_iteration never fires when iterate-step skips the final position. With 10 items and "iterate-step": 2 the last copy is item 9, not item 10, so no copy is flagged as last.
• Iterating a whole array has no practical limit. Sub-ranges do: when iterate-from / iterate-to select fewer than 100 items, iteration stops at array position 100, so a narrow range beginning past position 100 of a long array produces no copies at all.

iterate-from#

First array item to iterate, 1-based and inclusive. A negative value counts from the end of the array (-2 is the second-to-last item). Values of 0 or lower are treated as 1. Must be lower than iterate-to, otherwise the render fails with iterate-from must be lower than iterate-to. Only used when iterate is set.

iterate-step#

Number of array items to advance between iterations — 2 takes every other item. Values lower than 1 are treated as 1. Only used when iterate is set.

iterate-to#

Last array item to iterate, 1-based and exclusive: the item at this position is not included. Defaults to one past the end of the array, so the whole array is iterated. A negative value counts from the end of the array. Only used when iterate is set.

For example, "iterate-from": 2 with "iterate-to": 5 renders items 2, 3 and 4.

preload#

Assets to fetch or generate before this scene's elements render. Same shape as movie.preload.

transition#

Transition between this scene and the next.

This object contains the following properties:

• type: (string, optional) — Transition family. Currently xfade. Default xfade.
• style: (string, optional) — Transition style. Default fade. Examples: fade, wipeleft, slideup, circleopen, dissolve, pixelize, …
• duration: (number, optional) — Length of the transition in seconds.

variables#

Scene-local variables. Names follow the same rules as movie.variables. Local variables override parent (movie) values inside the scene.