Limits and sandbox

The sandbox

Scripts run in an embedded QuickJS-ng engine, which supports modern JavaScript (ES2023). It isn’t a browser or Node.js. A script can use:

• the ECMAScript standard library: Math, JSON, Map, Set, typed arrays, promises and so on;
• the modlumi and console globals.

It has no file system, network, timers (setTimeout) or process access. The only file a script can write is a PNG through view.writeImage.

Asynchronous code

Promises and async functions work, and so does top-level await. A script finishes when its module and all pending promise jobs have settled. Because there are no timers or I/O, there’s nothing to wait for from outside the script. A rejected promise that isn’t handled fails the run, and so does a top-level await that never settles.

Operation bodies must be synchronous, so do the async work first and then change the model.

Stopping a script

Scripts run synchronously and pause the interface while they run.

• Scripts started from the app, including console inputs, stop after 60 seconds, or after 20 seconds in the browser preview, where a busy tab can’t respond at all.
• In the desktop app, press Esc to stop a script sooner. After a moment, the window title shows this hint.
• Scripts run with --run-script have no time limit. Pass --script-timeout SECONDS to set one. A script that runs at startup runs before the window appears, so stop it with --script-timeout or Ctrl+C.

Stopping ends the run with an error that try/catch and finally blocks can’t intercept. An operation that was in progress is rolled back, and operations that already committed are kept. A stop takes effect only while JavaScript is running, so a single long model edit, such as a large extrusion, finishes first.

When a console input is stopped, the console starts over: variables and functions from earlier inputs are gone. This makes sure no unfinished work from the stopped input runs later.

Memory

The JavaScript memory of a run is limited to 1 GiB. Allocating more throws a catchable InternalError: out of memory, which fails the run if you don’t catch it. Model geometry is stored separately and doesn’t count toward the limit.

Not available yet

The API is young and grows with Modlumi. Today it doesn’t include:

• creating faces, groups or components directly (draw closed outlines with addEdges to create faces);
• editing materials;
• interactive tools, menus or dialogs;
• reading or writing files other than PNG export.