Skip to content

Vibe coding a plugin? Teach your agent Modlumi first. Works with Claude Code, Codex, Cursor and more.

Model

The document the script runs against. Get it from activeModel.

readonly activeEntities: Entities

The entities of the context being edited, such as an open group.


readonly activePath: readonly (ComponentInstance | Group)[]

The groups and instances being edited, from the model root down; empty at the root.


readonly activeTransformation: Transformation

Maps the coordinates of activeEntities to world coordinates: the transformations of activePath multiplied together.


readonly activeView: View

The view for image export.


readonly definitions: readonly ComponentDefinition[]

All component and group definitions, including ones nothing uses any more, such as a group’s after it was erased or exploded, until Model.purgeUnused removes them. Group definitions have empty names.


readonly entities: Entities

The entities at the model root.


readonly layers: readonly Layer[]

All layers, in the order they were added; the default layer isn’t one. Needs the "layers" feature.


readonly materials: readonly Material[]

All materials.


readonly scenes: readonly Scene[]

The model’s scenes, in the order the Scenes panel lists them. Show one in the desktop window with Viewport.setCamera, or render it by assigning its camera to View.camera. Needs the "scenes" feature.

const model = modlumi.activeModel;
for (const scene of model.scenes) {
model.activeView.camera = scene.camera;
model.activeView.writeImage(`${scene.name}.png`);
}

readonly selection: Selection

The current selection.


readonly units: UnitSettings

How the model shows lengths.

addLayer(name, options?): Layer

Adds a visible layer, gray by default, inside Model.operation. Throws RangeError for color components outside 0 to 1. Needs the "layers" feature.

string

Color | { a?: number; b: number; g: number; r: number; }

Layer


addMaterial(name, options?): Material

Adds a material, white by default, with an optional texture, inside Model.operation. Throws RangeError for color components outside 0 to 1 or a texture that isn’t a PNG or JPEG file.

string

Color | { a?: number; b: number; g: number; r: number; }

Texture | null

Material


addScene(name, camera): Scene

Adds a scene at the end of scenes inside Model.operation and returns it. Throws RangeError for an empty name.

string

Camera

Scene

const front = new modlumi.Camera([0, -20, 1.5], [0, 0, 1.5]);
model.operation("Add scene", () => model.addScene("Front", front));

formatArea(squareMeters): string

Formats an area in square meters in the model’s units, such as "6.000 m²".

number

string


formatLength(meters): string

Formats a length in meters the way the model shows lengths, such as "1.200 m".

number

string


formatVolume(cubicMeters): string

Formats a volume in cubic meters in the model’s units, such as "2.000 m³".

number

string


getLayer(name): Layer | null

Returns the first layer named name, or null. Needs the "layers" feature.

string

Layer | null


getMaterial(name): Material | null

Returns the first material named name, or null. Names needn’t be unique, so plugins that add materials by name look them up first: model.getMaterial("Oak") ?? model.addMaterial("Oak", { color }). Needs the "materialLookup" feature.

string

Material | null


isDrawingElementVisible(path, options?): boolean

Whether an element is visible, taking hidden ancestors into account. path lists the element’s ancestors from the model root down to the element itself.

readonly DrawingElement[]

VisibilityOptions

boolean


moveScene(index, newIndex): Scene

Moves the scene at index in scenes to newIndex inside Model.operation, as dragging it in the Scenes panel does, and returns it. The scenes between shift over by one. Throws RangeError when either index has no scene. Needs the "sceneOrder" feature.

number

number

Scene

// Put the last scene first.
model.operation("Move scene", () => model.moveScene(model.scenes.length - 1, 0));

operation<T>(name, body): T

Runs body as one named undo step and returns its result. Every edit must happen inside an operation. A thrown error, or any failed edit inside body (even when caught), rolls the whole operation back. Empty operations add no undo step. Operations can’t be nested, and body must be synchronous.

In a panel’s, dialog’s or Properties section’s draw, the operations that apply changes the user makes while holding one widget, such as dragging a slider or typing into a text field, join one undo step: the first operation of the drag names it, and later ones add to it, so one undo goes back to before the drag. Releasing the widget, or changing another one, starts a new step, as does anything else that changes the model in between, such as an undo during the drag.

T

string

() => T

T


parseLength(text): number | null

Reads a length the way the measurements box does, such as "1.2m", "18cm", "7\"" or "5' 3 1/2\"", and returns it in meters. A number without a unit is in the model’s UnitSettings.lengthUnit. Returns null for text that isn’t a length.

string

number | null


purgeUnused(): object

Removes component definitions that no group or instance reachable from the model root uses, with their contents, and then materials and layers nothing left uses. Call it inside Model.operation. Returns how many of each went; layers needs the "layers" feature.

object

readonly definitions: number

readonly layers: number

readonly materials: number


raytest(origin, direction, options?): RayHit | null

Casts a ray from origin along direction, both in world coordinates, through the whole model, and returns the nearest face it hits from either side, or null. Hidden faces and faces in hidden groups and instances are skipped unless includeHidden is set. Faces on hidden layers, or in groups and instances on them, are always skipped.

Point3dLike

Vector3dLike

boolean

RayHit | null


redo(): void

Redoes the last undone operation. Not allowed inside an operation.

void


removeLayer(layer): void

Removes a layer inside Model.operation. Everything on it moves to the default layer. Needs the "layers" feature.

Layer

void


removeMaterial(material): void

Removes a material inside Model.operation. Faces, groups and instances that use it show their default or inherited appearance again.

Material

void


removeScene(index): void

Removes the scene at index in scenes inside Model.operation; later scenes move up one. Throws RangeError for an index without a scene.

number

void


undo(): void

Undoes the last operation. Not allowed inside an operation.

void


updateScene(index, changes): Scene

Renames a scene, saves another camera to it, or both, inside Model.operation, and returns the scene as it is now. index is the scene’s position in scenes. Throws RangeError for an index without a scene or an empty name.

number

SceneChanges

Scene