Reading and editing the scene
buhayin.scene, node, attribute, context, drawing, bounds and edit, with undo groups.
Every call on this page is async: await it. Reads give back plain data you can search and loop over. Changes go through buhayin.edit.
Where the editor was
buhayin.frame // the frame the playhead was on when the run began, from 1
buhayin.layer // the current layer's name
buhayin.fps // frames a secondThese three are fixed for the run. To read where the editor is now, call buhayin.context().
buhayin.context()
await buhayin.context() // { frame, layer, fps }Gives the same three values as they are now.
const here = await buhayin.context()
print("On frame " + here.frame + " of " + here.layer)Reading the scene
buhayin.scene(frame?)
await buhayin.scene(frame?)The scene as data. With frame (from 1) the attributes are read on that frame, otherwise on the frame the run began on. A frame below 1 throws.
const scene = await buhayin.scene()
print(scene.name, scene.length + " frames at " + scene.fps + " fps")What it holds:
| Field | What it is |
|---|---|
name, length, fps | The scene's name, its length in frames and its frame rate. |
resolution | { width, height }. |
range | The playback range as { from, to }, or null for the whole scene. |
projection | "perspective" or "orthographic". |
chart | The field chart: aspect, units (across, down, deep) and centre. |
fov | null, or { fit: "vertical" }, or { fit: "custom", angle }. |
bitDepth | "rgba8", "rgba16" or "rgbaFloat". |
colourSpaces | null, or { working, texture, convertPalettes }. |
markers | The ruler's scene markers: { start, length, colour, name, note }. |
cables | The cables of the Node view: { group, from, out, to, port }. |
rows | The Timeline's layers, top first, groups among them. See below. |
palette | The colours: { name, colour, gradient? }. |
board | null, or a storyboard's panels and shots. |
resolutions | The named resolutions Buhayin ships, with the one in use marked current. |
waypoints, backdrops, functions, paths | The Node view's waypoints and backdrops, the kind of each function column, and the paths with their points. |
Each entry of rows is a layer or group:
| Field | What it holds |
|---|---|
name | The name edits use for the row. When two share a name this is the end of its path. |
kind | What it is: drawing, peg, group, sound, 3D model and so on. |
parent | The row it hangs from. |
enabled, locked | The eye and the lock. |
at | Where its node sits in the Node view, { x, y }. |
attributes | Its numbers, switches and choices by dotted key, such as "offset.x", as they are on the frame read. |
keys | Its keys by attribute: { frame, value, motion }. |
cells | The runs of its drawing column: { drawing, from, to }. |
drawings | Every drawing it holds: { name, marks }. |
columnMarkers | Its column markers. |
colour | #rrggbb, or null for its type's own. |
A sound row has name, kind, parent and clips only. A clip is { sound, from, to }. If another row has the same name, the row has nameShared: true.
No id is in the answer. You refer to a row by its name.
buhayin.node(name, frame?)
await buhayin.node(name, frame?)One row by name, or null when there is none. It is scene() with a search for you.
const body = await buhayin.node("Body")
if (body) print(body.attributes["offset.x"])buhayin.attribute(name, key, frame?)
await buhayin.attribute(name, key, frame?)One value of one row, or null when the row has no such key. It throws "There is no row called ..." when the row is not there.
const opacity = await buhayin.attribute("Shadow", "opacity")buhayin.drawing(layer, which)
await buhayin.drawing(layer, { frame: 12 })
await buhayin.drawing(layer, { drawing: "A", art: "line" })A drawing's name and its marks, as an edit takes them. Name the drawing by the frame it shows or by its name. art limits the answer to one of the drawing's four art layers: "underlay", "colour", "line" or "overlay". Colours come back by their names in the palette, so you can change the marks and send them back in an edit. A face made of lines is left out.
This is the cheap way to read one drawing. scene() lists only how many marks each drawing holds.
buhayin.bounds(layer, frame, which)
await buhayin.bounds(layer, frame, { drawing?, art?, marks? })A box round a drawing, round one art layer of it, or round each mark named in marks. box is in the drawing's own units. sceneBox is in the scene on that frame, and null where the layer draws nothing. At most 10,000 marks may be named.
const b = await buhayin.bounds("Body", 1)
print(b.sceneBox)Changing the scene
buhayin.edit(edits)
await buhayin.edit(oneEdit)
await buhayin.edit([firstEdit, secondEdit])Makes one edit, or a list, as one undo step. Each edit is an object with a kind and that kind's arguments. A list holds at most 200 edits. A name an earlier edit made, such as a new layer or a new drawing, can be used by a later one in the same list.
It gives back { summary }, a description of what was done. When an edit cannot be made it throws, and the message names the edit by its position and kind and says why. An argument that does not fit the schema, or a kind that does not exist, is refused before anything changes.
await buhayin.edit({ kind: "showLayer", layer: "Shadow", shown: false })
await buhayin.edit([
{ kind: "addLayer", name: "Dust" },
{ kind: "expose", layer: "Dust", frame: 1, drawing: "1" },
])The edits cover everything the editor changes: layers, drawings and their marks, timing, keys, colours and palettes, rigs, sound, movies, the camera, the storyboard and more. Their names and arguments are listed in the Reference group of the Script view.
A bitmap edit paints into the layer's pixels. One edit is refused in a script: recolourBitmap on a single mark, because it would make a picture a run cannot keep.
buhayin.drawingTools.erode(args)
await buhayin.drawingTools.erode({ layer, frame, thickness?, flatten? })Takes a band off along the outline of a drawing's colour. It is the erode edit, in one call.
Grouping edits into one undo step
Separate edit calls are separate undo steps. To make several into one, wrap them.
await buhayin.beginUndoRedoAccum()
await buhayin.edit({ kind: "addLayer", name: "A" })
await buhayin.edit({ kind: "addLayer", name: "B" })
await buhayin.endUndoRedoAccum()- Between the two calls the edits are applied to a copy of the scene that your script reads. The outermost
endUndoRedoAccumcommits them as one step. buhayin.cancelUndoRedoAccum()drops them.- A group holds at most 10,000 edits. A group still open when the run ends or stops is committed.
- If you change the scene yourself while a group is open, the commit is refused as a whole and the run ends with an error that says so.
buhayin.undo(steps?) and buhayin.redo(steps?)
await buhayin.undo(steps?) // { steps }
await buhayin.redo(steps?)Take back, or put back, the steps this script made. They never touch a step you made yourself: when the step on top of the history is not the script's own, they do nothing. A group counts as one step. Neither works inside an undo group.
Asking
buhayin.ask(question)
await buhayin.ask({ title, text, choices })Asks you to pick one of choices, which is one to 100 strings of up to 2,000 letters. It gives the choice you picked, or null when you cancel. Waiting for your answer does not count against the script's time.
const pick = await buhayin.ask({ title: "Layers", text: "Delete hidden layers?", choices: ["Delete", "Keep"] })
if (pick !== "Delete") returnThe command line has no window, so ask there throws an error and the script stops.