Skip to content

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

Model and entities

modlumi.activeModel is the Model the script runs against. From it you reach everything else:

Property Contents
model.entities Elements at the model root
model.activeEntities Elements of the context being edited, such as an open group
model.selection The current selection
model.definitions All group and component definitions
model.materials All materials
model.layers All layers, as the Layers panel lists them
model.activeView A view for image export
model.scenes Saved views, as the Scenes panel lists them

Everything stored in the model is an Entity. Iterating an Entities collection yields its elements: edges, faces, groups, component instances and guides. Every entity has a type property naming its class, so a switch can tell them apart:

const model = modlumi.activeModel;
for (const entity of model.entities) {
switch (entity.type) {
case "Edge":
console.log("Edge", entity.length, "m");
break;
case "Face":
console.log("Face", entity.area, "m²");
break;
case "Group":
case "ComponentInstance":
console.log("Container", entity.name || entity.definition.name);
break;
}
}

instanceof works too, for example entity instanceof modlumi.Face. To get all elements of one type, use ofType:

const faces = modlumi.activeModel.entities.ofType("Face");
console.log(`${faces.length} faces`);

Collections have a length, can be iterated, and support at(index), which counts from the end for negative indices, and toArray(). Iteration works on a snapshot, so editing the model inside the loop doesn’t change what the loop visits. Vertices aren’t elements; get them from entities.vertices or from an edge’s start and end.

Each model entity is represented by one object, so ===, Set and Map work as identity. Every entity also has an entityId that stays the same across undo and redo. An edit can delete an entity, for example when a face is replaced. Check isDeleted or isValid before using an entity you kept from earlier.

A Face is bounded by loops: one outerLoop and one loop per hole. Each Loop lists its edges in order. The EdgeUse objects in edgeUses also tell you which way the loop runs along each edge:

for (const face of modlumi.activeModel.entities.ofType("Face")) {
const corners = face.outerLoop.edgeUses.map((use) => use.start.position);
console.log(`Face with ${corners.length} corners and ${face.loops.length - 1} holes`);
}

Edges drawn by a curve tool belong to a Curve, or to an ArcCurve with a center and radius for arcs and circles. edge.curve returns it, or null.

A Group or ComponentInstance places a ComponentDefinition in its parent with a transformation. The definition’s entities use their own local coordinates. Multiply by the transformation to get coordinates in the parent:

/**
* @param {modlumi.Entities} entities
* @param {modlumi.Transformation} toWorld
*/
function walk(entities, toWorld, depth = 0) {
const indent = " ".repeat(depth);
for (const entity of entities) {
if (entity.type === "Group" || entity.type === "ComponentInstance") {
console.log(indent + (entity.name || entity.definition.name));
walk(entity.definition.entities, toWorld.multiply(entity.transformation), depth + 1);
} else if (entity.type === "Edge") {
const start = toWorld.multiply(entity.start.position);
console.log(`${indent}edge from ${start}`);
}
}
}
walk(modlumi.activeModel.entities, new modlumi.Transformation());

Measurements such as edge.length and face.area are in the entity’s own context; they don’t include the containers above it.

All instances of a component share one definition, so editing the definition’s entities changes every instance. Renaming a definition renames it for all instances, while instance.name names only that container. Groups have a name of their own too.

entities.addGroup(elements) moves elements into a new group, and entities.addComponent(elements, name) into a new component definition with one instance. Faces take their boundary edges along. Without elements, addGroup() returns an empty group. Geometry drawn into its entities doesn’t merge with anything outside it:

const model = modlumi.activeModel;
const post = model.operation("Post", () => {
const group = model.entities.addGroup();
group.entities.addRectangle([0, 0, 0], 0.1, 0.1).extrude(2);
group.name = "Post";
return group;
});
console.log(post.entities.ofType("Face").length); // 6

A Guide is a construction point or an infinite construction line, like the ones the Measure tool places. Guides don’t form faces. isPoint tells them apart; a guide line has a position on the line and a direction. entities.addGuidePoint(position) and entities.addGuideLine(position, direction) create them.

A Text label is pinned to a point and shows its text at point plus leader, or stays at a screenPosition on the screen. A LinearDimension shows the length between its start and end, with its dimension line moved by offset. Its text overrides the label, with <> standing for the length. Both follow vertices they sit on when an edit moves them.

const model = modlumi.activeModel;
model.operation("Annotate", () => {
const entities = model.activeEntities;
entities.addDimension([0, 0, 0], [2.4, 0, 0], [0, -0.5, 0], "Width <>");
entities.addText("Door", [1, 0, 2], [0.5, 0, 0.5]);
entities.addScreenText("Ground floor", { x: 0.05, y: 0.05 });
});

Edges, faces, groups and component instances have hidden and visible properties for their own hidden flag. Changing them requires an operation:

const model = modlumi.activeModel;
model.operation("Hide selected", () => {
for (const entity of model.selection) {
entity.hidden = true;
}
});

Hiding a group hides everything in it without changing its definition. A hidden layer also hides what’s on it, without changing hidden. To check whether an element is actually visible, including hidden groups above it and hidden layers, pass its path from the model root to model.isDrawingElementVisible().

model.selection is the selection in the window. Changing it doesn’t need an operation and isn’t part of undo. You can only select drawing elements in the active editing context:

const model = modlumi.activeModel;
model.selection.clear();
for (const face of model.activeEntities.ofType("Face")) {
if (face.area > 1.0) {
model.selection.add(face);
}
}
console.log(`Selected ${model.selection.length} faces larger than 1 m²`);

Material objects have a name, a color with r, g, b and a components from 0 to 1, and an optional texture. Faces, edges, groups and instances have a material, which on a face covers both of its sides. Each is null when nothing is applied.

Inside an operation, scripts add and remove materials, change them, and assign them to faces, groups and instances:

const model = modlumi.activeModel;
model.operation("Paint the floor", () => {
const oak = model.addMaterial("Oak", { color: { r: 0.62, g: 0.45, b: 0.28 } });
for (const face of model.activeEntities.ofType("Face")) {
if (face.normal && face.normal.z > 0.99) {
face.material = oak;
}
}
oak.name = "Floor oak";
});

A texture is the bytes of a PNG or JPEG file and the size of one repeat in meters: material.texture = { image, width: 0.5, height: 0.5 }. Assign null to remove it. Removing a material with model.removeMaterial() shows the default or inherited appearance again wherever it was used.

Materials also have a physically based surface, which shows in PBR shading: metallic and roughness, each from 0 to 1, and image maps of the kinds "metallic", "roughness", "normal" and "opacity", read with material.getMap(kind) and set with material.setMap(kind, image), or null to remove one. These need the "materialSurface" plugin feature.

const model = modlumi.activeModel;
model.operation("Brushed steel", () => {
const steel = model.addMaterial("Steel", { color: { r: 0.56, g: 0.57, b: 0.58 } });
steel.metallic = 1;
steel.roughness = 0.35;
});

A Layer groups drawing elements for showing and hiding, as in the Layers panel. Each has a name, a color and visible. Every drawing element has a layer, which is null on the default layer. The default layer has no Layer object and is always shown. Layers only change what shows: geometry on different layers still connects.

Inside an operation, scripts add and remove layers, change them, and put elements on them:

const model = modlumi.activeModel;
model.operation("Put furniture on a layer", () => {
const furniture = model.getLayer("Furniture") ?? model.addLayer("Furniture");
for (const instance of model.entities.ofType("ComponentInstance")) {
instance.layer = furniture;
}
furniture.visible = false;
});

Hiding a layer hides the faces, edges, guides and annotations on it, and every group and instance on it with everything inside. model.removeLayer() moves what was on the layer to the default layer. These need the "layers" plugin feature.

model.scenes lists the model’s scenes in the order of the Scenes panel, including the ones a SketchUp file came with. Each is a frozen Scene with a name and a Camera. Scenes have no identity of their own: methods take a scene’s position in model.scenes, and editing one returns the scene as it is now.

Inside an operation, scripts add, change and remove scenes. Each operation is one undo step, however many scenes it changes:

const model = modlumi.activeModel;
model.operation("Add views", () => {
const front = new modlumi.Camera([0, -20, 1.5], [0, 0, 1.5]);
model.addScene("Front", front);
model.updateScene(0, { name: "Street" });
model.removeScene(model.scenes.length - 1);
});

updateScene(index, { name, camera }) keeps what it isn’t given. Names can’t be empty. Scenes added by scripts only save a camera; the layers a scene shows and hides are set in the Scenes panel, and updateScene keeps them. moveScene(index, newIndex) puts a scene in another place, as dragging it in the Scenes panel does, and shifts the scenes between by one; it needs the "sceneOrder" plugin feature.

To show a scene, give its camera to the image export view with model.activeView.camera = scene.camera, or, from a plugin, to the desktop viewport.