Getting started with scripting

The Script Console runs JavaScript macros against the project you have open. Open it from the Script Console dock, type a macro, and press Run (or Ctrl+Return).

Hello, world

console.log("This project has " + world.entityIds().length + " entities.");

The output appears in the console's output area. console.log, console.warn, and console.error are the only I/O the sandbox exposes — a script cannot touch the filesystem, the network, or launch processes.

Reading the project

The world global is your handle on the open project. Reads return plain JavaScript values:

// Every character's Role field.
world.entities()
     .filter(function (e) { return e.category === "Characters"; })
     .forEach(function (e) {
         console.log(e.name + ": " + world.field(e.id, "Role"));
     });

Changing the project — one undo step

Every write goes through the undo stack, and the whole macro is a single undo step: run a macro that creates ten entities, and one Ctrl+Z removes all ten. Each write returns whether it succeeded.

// Give every entity that has no Summary a placeholder one.
world.entityIds().forEach(function (id) {
    if (world.field(id, "Summary") === "") {
        world.setField(id, "Summary", "(to be written)");
    }
});

Where to go next

• The full world reference lists every method with its signature and return type.
• The built-in macros are ready-made examples you can load, run, and adapt.
• A runaway macro is stopped by a time budget, so an accidental infinite loop cannot hang the app. """