Extension API

Build for Divine.

Systems and modules are packages: a pack.json, facet files, and a script when you want one. The same pack runs in Studio, on your server, and on ours.

Your first module Open the app

IQuick start

Three steps to a module.

A module is a folder. Write two files, load it in Studio.

  1. Make a pack.json

    The manifest names the pack, its role, what it extends, and the permissions it asks for.

    pack.jsonJSON
    {
  "schemaVersion": 1,
  "id": "my-first-module",
  "role": "module",
  "extends": "*",
  "script": "./main.js",
  "permissions": ["ui"]
}

  2. Write main.js

    A script is an ES module that takes the api object and registers what it adds.

    main.jsJavaScript
    api.hooks.on("pack.enabled", (p) => api.log("active in", p.worldId))

  3. Load it in Studio

    Zip the folder, import it in Studio, and the GM enables it with the permissions you declared.

    The full walkthrough

IIThe shape of it

How it fits together.

Four ideas carry the rest of these docs.

Systems and modules

A system is the base ruleset of a world: sheets, conditions, calendar, dice, initiative, vitals, currency. A module sits on top and adds to it, and a world can enable as many as it likes.

The pack chain

Content resolves in order: the system first, then each enabled module in the order the GM set. Merging depends on the facet, so a later characterSheet replaces the earlier one while conditions merge by id.

Facets and scripts

Facets are JSON: sheets, conditions, calendars, dice, catalogs and twenty more, with no code at all. Scripts are ES modules that register behaviour through the api object when configuration is not enough.

Permissions and the sandbox

Third-party scripts run in an isolated frame with no access to cookies, storage or the host page, and every call is checked. A pack gets exactly the permissions it declared, such as read-world or send-chat, and nothing can ask to be trusted.

System Module I Module II More modules Your world Later wins
Fig. iThe pack chain

The GM sets the order. Each facet merges in that order, so the last pack to declare one wins.

IIIThe library

Where everything lives.