Skip to content

Building a Distributable Adventure Module for Click Adventure

Jump to bottom
Bruno Calado edited this page Jun 3, 2026 · 1 revision

Building a Distributable Adventure Module for Click Adventure

This guide walks you through creating a Foundry VTT module that packages a complete Click Adventure campaign — nodes, links, images, macros, and scenes — in a way that works seamlessly with the Export / Import feature.

How the Export / Import System Works

Click Adventure stores the adventure graph (nodes, links, connections) as a world setting. The Export action serialises selected groups to a .json file. The Import action reads that file in a different world and recreates everything, including the Foundry Scenes for each node.

When resolving external references on import, the system follows this priority order:

Reference type Resolution order
Macros 1. Compendium UUID → 2. World macro ID → 3. World macro name
Linked scenes Scene name lookup in the target world
Images Path is used as-is — the file must exist at that path

This means that if you structure your module correctly, a GM can install it and import the adventure JSON with zero manual reconnection work.

Module Folder Structure

A well-structured Click Adventure module looks like this:

my-adventure/
├── module.json
├── adventures/
│   └── my-adventure.json        ← the exported Click Adventure JSON
├── assets/
│   ├── backgrounds/
│   │   ├── forest-entrance.webp
│   │   ├── old-tavern.webp
│   │   └── dungeon-gate.webp
│   └── hud/
│       └── adventure-orb.webp   ← optional custom HUD button image
├── packs/
│   ├── macros.db                ← compendium with all macros used in the adventure
│   └── scenes.db                ← compendium with linked scenes (optional)
└── scripts/
    └── (any module scripts)

Images

Rule: always store images inside your module folder

All node background images must live inside your module's directory so their paths resolve correctly in any world that has the module installed.

✅  modules/my-adventure/assets/backgrounds/tavern.webp
❌  worlds/my-world/scenes/tavern.webp

Paths starting with modules/ are resolved relative to the Foundry data root and are valid in every world. Paths starting with worlds/ are local to the world where they were created and will be broken after import.

Supported formats

Foundry accepts .webp, .png, .jpg, .jpeg, .gif, .avif, .svg, .mp4, and .webm. WebP is recommended for static backgrounds (smaller file size, alpha support). WebM is recommended for animated backgrounds.

Naming convention

Use kebab-case filenames with no spaces or special characters. Foundry's file picker handles spaces, but they can cause issues in some hosting environments.

Macros

Rule: put every macro in a compendium inside your module

Macros referenced in Click Adventure nodes are stored by ID. When you export an adventure, the system also saves the macro's name as a fallback. On import, the resolver tries the stored UUID first; if that fails it searches for a world macro with the same name.

The safest and most portable approach is to ship all macros in a compendium pack inside your module:

  1. Create a macro compendium in your module's module.json:
"packs": [
  {
    "name": "macros",
    "label": "My Adventure — Macros",
    "path": "packs/macros.db",
    "type": "Macro",
    "ownership": { "PLAYER": "OBSERVER", "ASSISTANT": "OWNER" }
  }
]

  1. Add your macros to the compendium.

  2. In Click Adventure's Node Configuration, drag the macro from the compendium directly onto the macro drop zone. Foundry imports it to the world automatically and the UUID is stored in the graph data.

  3. When you export the adventure, the UUID (Compendium.my-adventure.macros.xxxxx) is written into the JSON. Any world that installs your module will resolve it directly — no name matching needed.

When UUID resolution is enough

If the importing world has your module installed, the UUID resolves on its own. The name fallback only activates when the module is absent or the UUID cannot be found. Always prefer compendium macros over world macros in a distributable module.

Macro content and portability

The export file does not include macro source code, only the reference. This means your macros remain under version control inside your module and are always up to date with whatever is in the compendium.

Linked Scenes

Nodes in Click Adventure can have linked scenes — arbitrary Foundry scenes shown to players as a sub-view inside a node (for example, a detailed battle map reached from a location node).

On export, linked scenes are stored by scene name. On import, the system searches game.scenes for a scene with the same name. Two options:

Option A — Scenes in a compendium (recommended)

Ship the linked scenes in a compendium inside your module, the same way you would for macros. Instruct the GM to import the scenes from the compendium into the world before running the adventure import. After import the name lookup finds them.

"packs": [
  {
    "name": "scenes",
    "label": "My Adventure — Scenes",
    "path": "packs/scenes.db",
    "type": "Scene"
  }
]

Note: unlike macros, Foundry cannot use a Scene from a compendium directly as a linked scene — it must exist in the world. That is why you ship scenes in a compendium and the GM imports them first.

Option B — Document the scene names

If you prefer not to ship scenes, document the required scene names in your module's README. The GM creates or renames scenes to match, and the import finds them by name. This approach requires more manual setup.

What happens when a linked scene is not found

The import completes successfully. The linked scene entry is set to null and a warning is printed to the browser console listing every missing scene by name. The GM can reconnect them manually in Node Configuration after the import.

Preparing the Adventure JSON

  1. Build the adventure in Click Adventure in your development world.
  2. Go to Configure Settings → Click Adventure → Export / Import…
  3. Select the groups you want to distribute.
  4. Click Export — a .json file downloads automatically.
  5. Place the file in your module's adventures/ folder (or anywhere logical).
  6. Document in your README that the GM must use Import and point to this file.

Resetting "once" macros before export

Macros configured with Execute: Once track whether they have already fired. The export automatically resets that flag (executedOnce: false) so every importer starts with a clean slate — you do not need to reset them manually before exporting.

module.json Checklist

{
  "id": "my-adventure",
  "title": "My Adventure",
  "relationships": {
    "requires": [
      {
        "id": "click-adventure",
        "type": "module",
        "compatibility": { "minimum": "0.0.2" }
      }
    ]
  },
  "packs": [
    {
      "name": "macros",
      "label": "My Adventure — Macros",
      "path": "packs/macros.db",
      "type": "Macro"
    },
    {
      "name": "scenes",
      "label": "My Adventure — Scenes",
      "path": "packs/scenes.db",
      "type": "Scene"
    }
  ]
}

Always declare click-adventure as a required dependency so Foundry warns the GM if it is not installed.

GM Installation Workflow

Document the following steps in your module's README so GMs know what to do:

  1. Install and enable your module and the Click Adventure module.
  2. If your module ships linked scenes, import them from the compendium into the world.
  3. Go to Configure Settings → Click Adventure → Export / Import…
  4. Click Choose file…, select the .json file from your module's adventures/ folder.
  5. Select the groups to import and click Import.
  6. The adventure is ready — scenes are created automatically.

Quick Reference

What Where to put it Why
Background images modules/my-adventure/assets/ Path resolves in any world
Macros Module compendium (packs/macros.db) UUID resolves without name matching
Linked scenes Module compendium (packs/scenes.db) GM imports first; name lookup works
Adventure graph adventures/my-adventure.json Shipped with module, imported by GM

Clone this wiki locally