Extensions

Extensions add new commands to Terrafold. An extension can add menu items and toolbar buttons, build geometry, read the model, store its own data on groups and components, react to changes and draw simple guides in the viewport.

Extensions are small scripts written in Rhai, a simple scripting language with a syntax similar to JavaScript and Rust. They run in a sandbox: a broken or hostile extension can't crash or hang Terrafold, read your files or reach the network.

Install an extension

An extension is a folder with a manifest file, extension.toml, and one or more scripts. People usually share it as a .zip of that folder.

1. Choose Extensions ▸ Extension Manager.
2. Click Install… and pick the .zip file, or the extension.toml file inside an extension folder.
3. The extension appears in the list and its commands appear under Extensions ▸ extension name. Commands with a toolbar button also appear on the Extensions ribbon tab.

Before installing, Terrafold checks the archive and the manifest. It refuses unknown settings, unknown permissions, and extensions that need a newer version of Terrafold, with a message in the Extension Manager.

Manage extensions

The Extension Manager lists every installed extension with its details, permissions, commands, errors and log. From there you can:

• enable or disable an extension with its check box,
• Reload an extension after you edit its script,
• uninstall an extension.

Folders that can't be loaded are listed with the reason.

Permissions

The manifest lists the permissions an extension needs, and the Extension Manager shows them. Without any permission, an extension can only look at the model, change the selection and the camera, register commands and draw in the viewport.

An extension never gets access to files elsewhere on your computer, and it can't open, save or close your model, run undo or redo, or start long renders.

Every extension command is a single step you can undo with Edit ▸ Undo, however much it changes. If a command fails or runs too long, everything it changed is rolled back.

The sandbox doesn't stop an extension with modify_model from making edits you didn't want, and an extension can show misleading text. Install extensions only from people you trust.

Where extensions are stored

Installed extensions live in the extensions folder of Terrafold's data folder, one folder per extension:

See Preferences for more about the data folder.

The browser version has the Script Console, but you can't install extensions there.

The example extensions

Two example extensions show what extensions can do:

• Stair Generator (permission modify_model) adds Extensions ▸ Stair Generator ▸ Make Stairs and a toolbar button. It builds a straight flight of stairs as one group named "Stairs" and remembers the number of steps, the rise, the tread and the width on the group.
• Count Components (permission write_files) counts the copies of every component, saves the count as a CSV file in its data/ folder, and outlines the selected groups and components in the viewport.

The Script Console

Window ▸ Script Console runs Rhai code directly, with the same commands extensions use. It is a quick way to automate a repetitive task or try out an idea. For example:

run("rectangle", #{ corner: [0, 0, 0], size: ["2m", "1m"] });
model_info().counts

Variables are kept between runs. Each run is one step you can undo. The console can change the model, but it can't read or write files.

Write your own extension

A minimal extension is a folder with two files. The manifest, extension.toml:

id = "reviewed"
name = "Reviewed"
version = "0.1.0"
author = "You"
license = "MIT"
min_app_version = "0.1.0"
entry = "main.rhai"
permissions = ["modify_model"]

And the script, main.rhai, which registers a command when the extension loads:

command(#{ id: "mark", label: "Mark Selection as Reviewed", toolbar: true, run: "mark" });

fn mark(params) {
    let n = 0;
    for id in selection() {
        if id.starts_with("i") {
            set_attribute(id, "reviewed", "done", true);
            n += 1;
        }
    }
    if n == 0 { throw "select groups or components first"; }
    n
}

Install it with the Extension Manager, select a group, and choose Extensions ▸ Reviewed ▸ Mark Selection as Reviewed.

Scripts can run any Terrafold command with run, read the selection, entities, materials, tags and bounds, store attributes, react to events such as a changed selection, and draw lines and points in the viewport. Lengths can be written in any unit, such as "2m" or "7'6\"".

Try an extension from the command line

terrafold-cli extension runs an extension on a model without installing it, and prints a report with the result, any error and the log:

terrafold-cli extension --sample --dir stair_generator --invoke make_stairs --params '{"steps": 8}' --out stairs.tfo

Syntax and runtime errors are reported with their line and position.