Import / Export

An exchange file is a plain JSON document you upload through the realm compendium settings. When imported, every entity in the file is added to the compendium; V2 and later files also create the relationships between them. Existing entities with the same ID are updated in place rather than duplicated.

Everything an import adds or changes is recorded in each entity's History as “Import”, so a description an import replaced can be restored. A relationship in the file that you had previously deleted is brought back rather than created again. History itself is not exported.

Exchange files come in four versions. V1 supports entities only and is suitable for simple lore drops. V2 adds a relationships array for richer world graphs. V3 adds a notes array for realm-level notes that carry across imports. V4 adds a quests array, carrying each quest's hook, goal, reward, tags, linked entities, and full step timeline.

Exports can be downloaded as a single JSON file, or as a bundle: a ZIP archive containing the same export.json file alongside one Markdown file per entity (entities/<name>.md) and, as of V4, one per quest (quests/<title>.md) with its hook, goal, reward, and timeline written out as readable text. Only the JSON file is used on import; the Markdown files are for reading outside the platform.

All versions share the same envelope fields. The version field determines which additional fields are required.

{
  "version": "4",
  "exportedAt": "2024-03-01T00:00:00Z",
  "exportedBy": "gamelord@example.com",
  "entities": [
    {
      "id": "ent_01",
      "type": "character",
      "name": "Seraphine Voss",
      "description": "A disgraced knight seeking redemption in the northern wastes.",
      "notes": null,
      "accessIds": null,
      "isPublicToRealm": true
    }
  ]
}

{
  "version": "4",
  "exportedAt": "2024-03-01T00:00:00Z",
  "exportedBy": "gamelord@example.com",
  "entities": [],
  "relationships": [
    {
      "id": "rel_01",
      "fromEntityId": "ent_01",
      "toEntityId": "ent_02",
      "type": "resides_in",
      "accessIds": null,
      "isPublicToRealm": true
    }
  ]
}

{
  "version": "3",
  "exportedAt": "2024-03-01T00:00:00Z",
  "exportedBy": "gamelord@example.com",
  "entities": [],
  "relationships": [],
  "notes": [
    {
      "id": "note_01",
      "name": "Campaign Hook",
      "text": "The vault beneath the temple belongs to The Iron Accord. Its contents have not been catalogued.",
      "accessIds": null
    },
    {
      "id": "note_02",
      "name": "GM Only",
      "text": "Seraphine is a sleeper agent. She does not know it yet.",
      "accessIds": ["gamelord_user_id"]
    }
  ]
}

{
  "version": "4",
  "exportedAt": "2024-03-01T00:00:00Z",
  "exportedBy": "gamelord@example.com",
  "entities": [],
  "relationships": [],
  "notes": [],
  "quests": [
    {
      "id": "quest_01",
      "title": "The Silver Locket",
      "hook": "A merchant offers coin for a locket lost in the sewers.",
      "goalTitle": "Recover the locket",
      "goalDescription": "Bring the locket back to the merchant.",
      "rewardTitle": "50 gold",
      "rewardDescription": "Paid on delivery.",
      "mechanic": "fetch",
      "motive": "wealth",
      "source": "commission",
      "isPublicToRealm": true,
      "entityIds": ["ent_01"],
      "accessIds": null,
      "steps": [
        {
          "id": "step_01",
          "type": "discovery",
          "note": "The party learned the locket fell through a grate on Mill Street.",
          "createdAt": 1716550000000
        }
      ]
    }
  ]
}

The type field on each entity must be one of the values below.

The type field on each relationship must be one of the values below. Relationships are directional: fromEntityId is the subject and toEntityId is the object (e.g. Seraphine resides_in Ashenveil).

A V4 quest's mechanic, motive, and source fields, and each step's type field, must be one of the values below, or null for the quest-level tags.

A quest's status is not stored in the file. It comes from the steps: a quest with no steps is proposed, a quest with steps is active, and the latest ending step decides whether it is completed, failed, or abandoned.

Entities, relationships, notes, and quests each support visibility fields.

A complete V4 exchange file with three entities, two relationships, two notes, and a quest with its step timeline, with realm-wide visibility and selective access control throughout.

{
  "version": "4",
  "exportedAt": "2024-06-15T12:00:00Z",
  "exportedBy": "worldbuilder@example.com",
  "entities": [
    {
      "id": "ent_kael",
      "type": "character",
      "name": "Kael Dawnspire",
      "description": "A former war mage who now sells information out of a cramped tower in the merchant district.",
      "notes": "Knows about the vault beneath the old temple. Owes a debt to the thieves guild.",
      "accessIds": ["player_marlowe", "player_britta"],
      "isPublicToRealm": false
    },
    {
      "id": "ent_ironhold",
      "type": "city",
      "name": "Ironhold",
      "description": "A sprawling trade hub built around a collapsed volcano, now home to the largest smithing guilds on the continent.",
      "notes": null,
      "accessIds": null,
      "isPublicToRealm": true
    },
    {
      "id": "ent_ashen",
      "type": "guild",
      "name": "The Ashen Circle",
      "description": "A secretive mage guild operating out of Ironhold, specializing in fire-based transmutation.",
      "notes": null,
      "accessIds": null,
      "isPublicToRealm": false
    }
  ],
  "relationships": [
    {
      "id": "rel_01",
      "fromEntityId": "ent_kael",
      "toEntityId": "ent_ironhold",
      "type": "resides_in",
      "accessIds": null,
      "isPublicToRealm": true
    },
    {
      "id": "rel_02",
      "fromEntityId": "ent_kael",
      "toEntityId": "ent_ashen",
      "type": "member_of",
      "accessIds": ["player_marlowe", "player_britta"],
      "isPublicToRealm": false
    }
  ],
  "notes": [
    {
      "id": "note_01",
      "name": "Campaign Hook",
      "text": "The vault beneath the old temple belongs to The Ashen Circle. Kael knows the combination but will not give it freely.",
      "accessIds": null
    },
    {
      "id": "note_02",
      "name": "GM Secret",
      "text": "The Ashen Circle is actively searching for Kael. He has three days before they find him.",
      "accessIds": ["player_marlowe"]
    }
  ],
  "quests": [
    {
      "id": "quest_vault",
      "title": "Open the Temple Vault",
      "hook": "Kael offers the vault's combination in exchange for safe passage out of Ironhold.",
      "goalTitle": "Reach the vault",
      "goalDescription": "Get Kael past The Ashen Circle's watchers and into the vault beneath the old temple.",
      "rewardTitle": "The vault's contents",
      "rewardDescription": "Whatever The Ashen Circle has been hiding beneath the temple.",
      "mechanic": "escort",
      "motive": "wealth",
      "source": "request",
      "isPublicToRealm": true,
      "entityIds": ["ent_kael", "ent_ashen", "ent_ironhold"],
      "accessIds": null,
      "steps": [
        {
          "id": "step_01",
          "type": "discovery",
          "note": "Kael admits the vault belongs to The Ashen Circle.",
          "createdAt": 1718452800000
        },
        {
          "id": "step_02",
          "type": "complication",
          "note": "Ashen Circle watchers are posted at every gate out of the merchant district.",
          "createdAt": 1718456400000
        }
      ]
    }
  ]
}