Skip to content

Your first script

Write, run, check and save a script that reads the scene and changes it.

This page writes two small scripts. The first reads your scene and prints what it finds. The second adds a layer with a drawing held for twelve frames.

Open the Script view

  1. Open a scene.
  2. Choose Script from the Window menu.

The code box already holds an example. Its first lines are these.

// Every layer, what kind it is and how many drawings it has.
const scene = await buhayin.scene()
for (const row of scene.rows) print(row.name, row.kind, row.drawings?.length ?? 0)

Run a script that reads

  1. Choose Run, or press Cmd+Return in the code box.
  2. Read the Output group. It shows one line for each layer: its name, its kind and how many drawings it holds.

buhayin.scene() gives you the whole scene as plain data. Its rows are the Timeline's layers, top first. The next page lists everything in it.

If the code has a mistake, choose Check Syntax. It says whether the code parses and takes you to the line where it stopped.

Run a script that changes the scene

Replace the code with this.

const name = "Ball"
const result = await buhayin.edit([
  { kind: "addLayer", name },
  { kind: "expose", layer: name, frame: 1, drawing: "1" },
  { kind: "setHold", layer: name, frame: 1, length: 12 },
])
print("Added " + name)

Choose Run. A layer called Ball appears in the Timeline with an empty drawing named 1 held from frame 1 to frame 12.

What the script does:

  1. addLayer adds a layer with the name you gave it.
  2. expose shows drawing 1 on frame 1 of that layer. A drawing name that does not exist yet makes a new, empty drawing.
  3. setHold holds the drawing shown on frame 1 for twelve frames.

The three edits in one list are one undo step. A name an earlier edit made can be used by a later one in the same list.

Press Cmd+Z. The layer goes, because the whole list was one step.

If an edit cannot be made, buhayin.edit throws an error whose message says which edit failed and why. The run stops and shows that message. Edits made before the failing call stay.

Use where you are

buhayin.layer is the name of the current layer, and buhayin.frame is the current frame. This script hides the current layer.

await buhayin.edit({ kind: "showLayer", layer: buhayin.layer, shown: false })
print("Hid " + buhayin.layer)

Keep a script

  1. Type a name in the Name box.
  2. Choose Save.

The script now appears in the Saved list, on every window, for every scene. Export File writes it as a file ending in .buhayin-script.js, and Import File… brings one in.

Find the edits

The edits a script can make are the same ones for every kind of change in the scene: layers, drawings, timing, keys, colours, rigs, sound, the storyboard and more. The Reference group of the Script view lists them with their arguments, and Help > Extended Scripting Interface Documentation… opens it.

The next pages list every call a script can make, grouped by what it does.