Elements

The six kinds, the manifest, parameters, and element new and test.

An element is a piece your agent writes once and any film can use: a sky, a set of labels, a prop in the world, a camera move, a table of data. It lives in your project, in elements/<name>/, and syncs with the film. It is yours to use in your films; what the library does with reusable pieces is on The library.

The six kinds

sky
Light on the sky over home: an aurora, a moonrise, a haze after sunset.
overlay
Graphics over the frame: labels, a lower third, a chart.
world
Things standing in the home world: lanterns on a promenade, boats at moorings.
shot
A camera move: an orbit, a rise.
data
A table with its sources, which a film reads from.
sound
One layer of a channel’s score, with a role: a bed, a pulse, an accent, a rise, a texture or a resolve. The library plays a 12-second preview.

Kind	What it is
`sky`	Light on the sky over home: an aurora, a moonrise, a haze after sunset.
`overlay`	Graphics over the frame: labels, a lower third, a chart.
`world`	Things standing in the home world: lanterns on a promenade, boats at moorings.
`shot`	A camera move: an orbit, a rise.
`data`	A table with its sources, which a film reads from.
`sound`	One layer of a channel’s score, with a role: a bed, a pulse, an accent, a rise, a texture or a resolve. The library plays a 12-second preview.

Make one

Terminal, in the project folder

npx clipwright-studio element new paper-lanterns --kind world

That makes elements/paper-lanterns/ from a template that works as it is. Names are lowercase words joined by hyphens, 3 to 40 characters. An element of your own with the same name as a library element wins in your films, and the check tells you so.

The manifest

Every element has an element.json: its name, kind, version, title (3 to 60 characters), one-line description (10 to 200), up to eight tags, its parameters, and the moments to test it at. A data element also lists its sources, which are required.

elements/paper-lanterns/element.json

{
  "api": 1,
  "name": "paper-lanterns",
  "kind": "world",
  "version": "1.0.0",
  "title": "Paper lanterns",
  "description": "Lanterns strung along the promenade, lit at dusk.",
  "tags": ["festival", "night", "light"],
  "params": {
    "count": { "type": "integer", "min": 1, "max": 200, "default": 40 },
    "glow": { "type": "number", "min": 0, "max": 1, "default": 0.8, "track": true }
  },
  "test": [{ "at": 2 }, { "at": 6, "params": { "count": 120 } }]
}

Parameters

A parameter is what a film can change: number, integer, bool, color, vec2, vec3, choice or text. Every one has a default, and may have a range, a unit and a description. At most 24 per element. Mark a number or colour "track": true and a film can change it over time instead of giving one value.

A film uses an element in one line, and the check names any parameter that is unknown or out of range:

film.js

elements: { 'paper-lanterns': { count: 60 } }
move: element('slow-orbit', { radius: 80 })
const peaks = table('tallest-peaks')

Test it

Terminal

npx clipwright-studio element test paper-lanterns

This runs your element in a short test film on this machine’s GPU, at the moments the manifest names. It draws test/sheet.jpg so you can look at it, and checks that it draws the same twice, does not flicker, stays in its place and is quick enough. The results go in test/checks.json.

NextThe library