Advanced / Scene · guide

Scene — types & SceneBuilder

Current Apexify.js 6.0.0 documentation for Scene — types & SceneBuilder.

apexify.jsRuntime: nodeCURRENTSince 6.0.0

SceneRenderInput

Used by renderScene, renderSceneToGIF, and renderSceneToVideoFrames.

Field	Type	Notes
`width`	`number`	Positive root width in pixels.
`height`	`number`	Positive root height in pixels.
`background`	`SceneBackground` = `Omit<CanvasConfig, "width" \| "height">`	Paint configuration only; root dimensions come exclusively from `width` / `height`.
`layers`	`SceneLayer[]`	Deterministic bottom → top paint order.

SceneRenderResult is a PNG Buffer.

SceneRenderOptions

Passed to renderScene / SceneBuilder.render and through GIF/video helpers as sceneRender.

Field	Behavior
`validate`	Deprecated compatibility property. Safety validation is mandatory; this value is ignored and cannot disable validation.
`maxSurfaceDepth`	Optional stricter nesting cap. It may not exceed the configured runtime `maxSceneDepth` (default 32).
`resolveAssetRefs`	`renderScene` / scene→GIF / scene→video default true. `SceneBuilder.render` defaults false unless you opt in.

There is no trusted-input validation bypass. Call painter.validateSceneRenderInput(input, options?) when you want an explicit preflight before a larger workflow; the renderer validates again at its own boundary.

1import { ApexPainter } from "apexify.js";2 3const painter = new ApexPainter();4const input = { width: 800, height: 600, layers: [] };5 6painter.validateSceneRenderInput(input, { maxSurfaceDepth: 8 });7await painter.renderScene(input);

Validation covers dimensions, aggregate scene pixel budget, total layers/surfaces/images/text/charts/remote assets, total text content, nested depth, image/text domain validation, finite transforms, and opacity ranges.

SceneBuilder

createScene() returns a mutable builder around scene descriptions with copy-on-ingress and snapshot isolation.

When you pass a background, layer object, nested array/object, or Buffer into the builder, the builder captures an isolated composition copy. Later mutation of the caller-owned value does not silently change the builder.

Background

Method	Returns	Role
`setBackground(bg)`	`this`	Replace the root background with a copied value.
`clearBackground()`	`this`	Remove the root background.

Stack editing

Method	Returns	Role
`addLayer(layer)`	`this`	Append one copied layer.
`addLayers(layers)`	`this`	Append copied layers in order.
`insertLayer(index, layer)`	`this`	Insert at an exact valid index. `index === layerCount` appends.
`insertLayers(index, layers)`	`this`	Insert several layers preserving order.
`insertBefore(index, layer)`	`this`	Insert directly below the layer currently at `index`.
`insertAfter(index, layer)`	`this`	Insert directly above the layer currently at `index`.
`replaceLayer(index, layer)`	`this`	Replace exactly one layer.
`replaceLayers(layers)`	`this`	Replace the whole stack.
`removeLayer(index)`	`this`	Remove exactly one layer.
`moveLayer(fromIndex, toIndex)`	`this`	Reorder one layer.
`clearLayers()`	`this`	Empty the stack.

Invalid indices throw ApexifyInputError; indices are not silently clamped.

Snapshot & render

Method	Returns	Role
`toRenderInput()`	`SceneRenderInput`	Deep composition snapshot, including copied Buffers. Mutating it does not mutate the builder.
`render(options?)`	`Promise<Buffer>`	Renders a fresh isolated snapshot. `$` asset resolution is opt-in on the builder.

Read-only builder properties: width, height, and layerCount.

createScene overloads

Config object

1const builder = painter.createScene({2  width: 1920,3  height: 1080,4  background: { colorBg: "#020617" },5  layers: [6    {7      type: "text",8      texts: { text: "Title", x: 80, y: 100, fontSize: 72, color: "#f8fafc" },9    },10  ],11});12 13const png = await builder.render();

Width + height

1const png = await painter2  .createScene(800, 600)3  .setBackground({ colorBg: "#f1f5f9" })4  .addLayers([5    { type: "text", texts: { text: "Step 1", x: 24, y: 40, fontSize: 28, color: "#0f172a" } },6    { type: "text", texts: { text: "Step 2", x: 24, y: 90, fontSize: 20, color: "#334155" } },7  ])8  .render();

Passing only numeric width is invalid; numeric construction requires both width and height.

Editor-style ordering example

1const card = painter.createScene(400, 300).setBackground({ colorBg: "#0f172a" });2 3card.addLayer({4  type: "text",5  texts: { text: "Back", x: 8, y: 20, fontSize: 12, color: "#94a3b8" },6});7card.insertBefore(0, {8  type: "text",9  texts: { text: "Watermark", x: 200, y: 260, fontSize: 11, color: "#64748b" },10});11card.insertAfter(0, {12  type: "text",13  texts: { text: "Middle", x: 80, y: 80, fontSize: 14, color: "#e2e8f0" },14});15card.moveLayer(2, 0);16card.replaceLayer(1, {17  type: "text",18  texts: { text: "Replacement", x: 80, y: 120, fontSize: 14, color: "#fff" },19});20 21await card.render();

Every render recomposites the current stack; stack methods edit descriptions/order rather than caching a partially painted raster.

toRenderInput() → other workflows

1import type { SceneRenderInput } from "apexify.js";2 3const builder = painter4  .createScene({ width: 1080, height: 1080, background: { colorBg: "#111827" } })5  .addLayers([]);6 7const input: SceneRenderInput = builder.toRenderInput();8 9const png = await painter.renderScene(input);10// await painter.renderSceneToGIF(input, { options: { ... } });11// await painter.renderSceneToVideoFrames(input, { options: { ... } });

#SceneRenderInput

#SceneRenderOptions

#SceneBuilder

##Background

##Stack editing

##Snapshot & render

#createScene overloads

##Config object

##Width + height

#Editor-style ordering example

#toRenderInput() → other workflows

Related guides and reference

Next steps