Skip to content
Modlumi Docs

Getting started

Modlumi scripts are JavaScript. Modlumi runs them in its own built-in JavaScript engine, so you don’t need to install anything to run a script. Everything a script needs is on the global modlumi namespace: get the open model from modlumi.activeModel, then read or edit it.

Scripting is available in the Modlumi desktop app and in the browser preview. Running script files from the command line and exporting images need the desktop app.

Write a script

Section titled “Write a script”

Create a file called outline.js:

outline.js
// Draws a one-meter square; closing the outline creates a face.
const model = modlumi.activeModel;
model.operation("Draw outline", () => {
  model.entities.addEdges([[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0, 0, 0]]);
});
console.log(`The model has ${model.entities.length} elements`);

A few things to notice:

  • modlumi.activeModel is the model the script runs against.
  • Every edit happens inside model.operation(name, () => { ... }). The operation becomes one step in Edit → Undo. See Operations and undo.
  • Coordinates are in meters. Use modlumi.mm() or modlumi.inches() to convert other units.

Run it

Section titled “Run it”

In Modlumi, choose File → Run Script… and pick outline.js. The square appears in the model, and the console.log output appears in Window → Script Console.

To try something without a file, paste any example from these guides into the script console, or write it in Window → Script Editor. You can also run scripts from the command line, with or without a window. See Running scripts.

Completion and type checking

Section titled “Completion and type checking”

Modlumi publishes type declarations for its API, so your editor can complete names, show documentation and catch mistakes before you run anything. Put two files next to your scripts:

Both also ship with Modlumi: on Windows in C:\Program Files\modlumi\scripting\types, and on Linux and macOS in share/modlumi/types inside the installation. Use the declarations that match your Modlumi version, so new API members show up in your editor. The API reference on this site is generated from the same file. Editors such as Visual Studio Code pick up tsconfig.json and modlumi.d.ts automatically, also for plain JavaScript files.

You can also write scripts in TypeScript. Modlumi runs JavaScript, so install TypeScript and compile the folder first:

Terminal window
npx tsc

The compiler checks every script against modlumi.d.ts and writes the JavaScript to dist/, so outline.ts becomes dist/outline.js. Run npx tsc --watch while you work, so the .js files stay up to date every time you save.

Next steps

Section titled “Next steps”