Block API

The engine.block API provides all block manipulation methods — CRUD, properties, layout, hierarchy, and more.

Lifecycle

const id = engine.block.create("graphic"); // BlockType
engine.block.destroy(id);
engine.block.duplicate(id); // returns new block id
engine.block.exists(id); // boolean

Type & Kind

engine.block.getType(id);       // "graphic" | "text" | "image" | "page" | ...
engine.block.getKind(id);       // e.g. "circle", "arrow"
engine.block.setKind(id, "rect");

Hierarchy

engine.block.appendChild(parentId, childId);
engine.block.removeChild(parentId, childId);
engine.block.getParent(id);     // number | null
engine.block.getChildren(id);   // number[]

Groups

const groupId = engine.block.group([shapeId, textId]);
engine.block.addToGroup(groupId, badgeId);
engine.block.removeFromGroup(groupId, textId);
engine.block.refitGroupBounds(groupId);
const released = engine.block.ungroup(groupId);

See Groups API for nested context and coordinate behavior.

Selection

engine.block.select(id);
engine.block.setSelected(id, true);
engine.block.isSelected(id);
engine.block.findAllSelected(); // number[]
engine.block.deselectAll();

const unsubscribeSelection = engine.block.onSelectionChanged((ids) => { /* ... */ });
const unsubscribeDoubleClick = engine.block.onBlockDoubleClick((blockId) => { /* ... */ });

Query

engine.block.findAll();             // all page, graphic, text, image, and scene blocks
engine.block.findByType("graphic"); // by BlockType
engine.block.findByKind("circle");  // by kind string
engine.block.findAllProperties(id); // all property keys
engine.block.getName(id);
engine.block.setName(id, "My Shape");

const snapshot = engine.block.getSnapshot(id); // ReadonlyBlockData | null

findAll() includes nested matching blocks but not groups or internal sub-blocks. Use findByType("group") when groups are needed.

Snapshots are deep-cloned and deeply readonly. Mutating a returned object never changes engine state. setName is command-backed and undoable.

Properties

Typed getters and setters for block properties:

// Getters
engine.block.getFloat(id, "transform/position/x");
engine.block.getString(id, "text/fontFamily");
engine.block.getBool(id, "appearance/visible");
engine.block.getColor(id, "fill/color");
engine.block.getProperty(id, key); // generic

// Setters
engine.block.setFloat(id, "transform/position/x", 100);
engine.block.setString(id, "text/fontFamily", "Inter");
engine.block.setBool(id, "appearance/visible", true);
engine.block.setColor(id, "fill/color", { r: 1, g: 0, b: 0, a: 1 });
engine.block.setProperty(id, key, value);

Layout

engine.block.setPosition(id, x, y);
engine.block.getPosition(id); // { x, y }
engine.block.setSize(id, w, h);
engine.block.getSize(id);     // { width, height }
engine.block.setRotation(id, 45);
engine.block.getRotation(id);
engine.block.setOpacity(id, 0.5);
engine.block.getOpacity(id);
engine.block.setVisible(id, false);
engine.block.isVisible(id);

Z-ordering

engine.block.bringForward(id);
engine.block.sendBackward(id);
engine.block.bringToFront(id);
engine.block.sendToBack(id);

Alignment

engine.block.alignToPage(id, "center"); // "left" | "center" | "right" | "top" | "middle" | "bottom"

Fill

engine.block.supportsFill(id);
engine.block.hasFill(id);
engine.block.setFillEnabled(id, true);
engine.block.isFillEnabled(id);
engine.block.setFillSolidColor(id, { r: 1, g: 0, b: 0, a: 1 });
engine.block.getFillSolidColor(id);
engine.block.changeFillKind(id, "gradient");
engine.block.setFillGradient(id, gradient);
engine.block.changeFillKind(id, "image");
engine.block.setFillImage(id, imageFill);
engine.block.updateFillImage(id, { rotation: 90 });

Fill kinds are color, gradient, and image. See Graphics API for gradient and image-fill contracts.

Stroke

engine.block.supportsStroke(id);
engine.block.setStrokeEnabled(id, true);
engine.block.isStrokeEnabled(id);
engine.block.setStrokeColor(id, { r: 0, g: 0, b: 0, a: 1 });
engine.block.getStrokeColor(id);
engine.block.setStrokeWidth(id, 2);
engine.block.getStrokeWidth(id);
engine.block.setStrokeGradient(id, linearGradient);
engine.block.getStrokeGradient(id);
engine.block.setStrokeGradient(id, null); // keep solid fallback

Shadow

engine.block.supportsShadow(id);
engine.block.setShadowEnabled(id, true);
engine.block.isShadowEnabled(id);
engine.block.setShadowColor(id, { r: 0, g: 0, b: 0, a: 0.3 });
engine.block.setShadowOffsetX(id, 4);
engine.block.setShadowOffsetY(id, 4);
engine.block.setShadowBlur(id, 8);

Shapes

const shapeId = engine.block.createShape("rect");
engine.block.setShape(graphicId, shapeId);
engine.block.getShape(graphicId);
engine.block.supportsShape(graphicId);
engine.block.hasShape(graphicId);
engine.block.setShapeGeometry(graphicId, { type: "star", points: 8, innerDiameter: 0.4 });

// Convenience: create a graphic with shape + fill in one call
engine.block.addShape(pageId, "ellipse", "color", x, y, w, h);

See Graphics API for SVG paths and validation.

Effects

const effectId = engine.block.createEffect("adjustments");
engine.block.appendEffect(blockId, effectId);
engine.block.getEffects(blockId);     // number[]
engine.block.removeEffect(blockId, 0); // by index
engine.block.setEffectEnabled(effectId, true);
engine.block.isEffectEnabled(effectId);

// Adjustments
engine.block.setAdjustmentValue(effectId, "brightness", 0.2);
engine.block.getAdjustmentValue(effectId, "brightness");
engine.block.getAdjustmentValues(effectId); // all params

Text

const textId = engine.block.addText(pageId, x, y, w, h, "Hello");
engine.block.getTextContent(textId);
engine.block.getTextRuns(textId);
engine.block.setTextStyle(textId, 0, 5, { fontSize: 24, fill: "#ff0000" });
engine.block.setTextAlign(textId, "center");
engine.block.setTextGradient(textId, 0, 5, gradient);
engine.block.setTextCurve(textId, 180, "up");
engine.block.setTextAutoWidth(textId, true);
engine.block.setTextBackground(textId, { enabled: true, geometry: "frame" });

See Text API for range updates, highlights, backgrounds, caret geometry, curves, and null-clear semantics.

Image

engine.block.addImage(pageId, src, x, y, w, h, origW, origH);

Crop

engine.block.supportsCrop(id);
engine.block.hasCrop(id);
engine.block.resetCrop(id);
engine.block.applyCropRatio(id, 16 / 9);
engine.block.flipCropHorizontal(id);
engine.block.flipCropVertical(id);
engine.block.setCropAspectRatioLocked(id, true);

Page

engine.block.setPageDimensions(pageId, 1920, 1080);
engine.block.getPageDimensions(pageId);
engine.block.setPageFillColor(pageId, { r: 1, g: 1, b: 1, a: 1 });
engine.block.setPageImageSrc(pageId, "/photo.jpg");
engine.block.setPageMarginsEnabled(pageId, true);
engine.block.setPageMargins(pageId, 20, 20, 20, 20);