World Building
Import / Export
Compendium exchange files let you seed a realm's compendium with entities and relationships before play begins, or carry lore from one realm to another.
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 V3 files also create the relationships between them. Existing entities with the same ID are updated in place rather than duplicated.
Exchange files come in three 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.
All versions share the same envelope fields. The version field determines which additional fields are required.
version
Must be the string "3".
entities
Array of entity objects. Each entity requires id, type, name, description, notes, and accessIds.
{
"version": "3",
"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
},
{
"id": "ent_02",
"type": "city",
"name": "Ashenveil",
"description": "A fortified city built into the cliffside overlooking the Ember Sea.",
"notes": null,
"accessIds": null
}
]
}relationships
Array of relationship objects. Each requires id, fromEntityId, toEntityId, type, and accessIds. The fromEntityId and toEntityId must reference ids defined in the entities array.
{
"version": "3",
"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
},
{
"id": "ent_02",
"type": "city",
"name": "Ashenveil",
"description": "A fortified city built into the cliffside overlooking the Ember Sea.",
"notes": null,
"accessIds": null
},
{
"id": "ent_03",
"type": "faction",
"name": "The Iron Accord",
"description": "A coalition of merchant guilds that secretly controls the city's trade routes.",
"notes": null,
"accessIds": null
}
],
"relationships": [
{
"id": "rel_01",
"fromEntityId": "ent_01",
"toEntityId": "ent_02",
"type": "resides_in",
"accessIds": null
},
{
"id": "rel_02",
"fromEntityId": "ent_01",
"toEntityId": "ent_03",
"type": "affiliated_with",
"accessIds": null
}
]
}notes
Array of realm-level note objects. Each note requires id, name, text, and accessIds. Set accessIds to null to give all realm members access, or provide a list of user IDs to restrict visibility.
{
"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"]
}
]
}The type field on each entity must be one of the values below.
Character
| Type | Description |
|---|---|
| character | A named individual: player character, NPC, or historical figure. |
| creature | A non-humanoid being, monster, or animal. |
| species | A biological species or lineage. |
| race | A cultural or racial group of humanoids. |
Location
| Type | Description |
|---|---|
| city | A large, populous urban settlement. |
| town | A mid-sized settlement with established trade. |
| village | A small rural community. |
| settlement | A generic inhabited place that does not fit other location types. |
| region | A broad geographic area such as a kingdom or province. |
| territory | Land claimed or controlled by a specific faction. |
| landmark | A notable fixed point of interest. |
| natural_feature | A geographic feature: mountain, forest, river, etc. |
| ruin | The remnants of a destroyed or abandoned place. |
Organization
| Type | Description |
|---|---|
| faction | A political or ideological group. |
| guild | A trade or craft organization. |
| political_body | A governing council, senate, or ruling body. |
| cult | A secretive religious or devotional group. |
| religion | A formalized faith or spiritual tradition. |
| merchant | A trading enterprise or merchant company. |
| army | An organized military force. |
| clan | A kinship group or extended family unit. |
| dynasty | A ruling lineage across generations. |
| sanctuary | A protected organization offering refuge. |
| military | A generic military organization or branch. |
| residence | A noble house, estate, or household. |
Item
| Type | Description |
|---|---|
| weapon | A named weapon or class of weapons. |
| magic | A spell, enchantment, or magical effect. |
| heirloom | An item passed down through a family or lineage. |
| relic | A sacred or historically significant object. |
| tool | A practical implement or instrument. |
| artifact | A powerful or unique constructed object. |
| consumable | A potion, food, or other single-use item. |
| item | A generic item that does not fit other item types. |
Event
| Type | Description |
|---|---|
| battle | A military engagement or skirmish. |
| disaster | A catastrophic event: plague, flood, collapse. |
| upheaval | A political or social revolution or shift. |
| festival | A celebration or recurring cultural ceremony. |
| meeting | A significant gathering or summit. |
| treaty | A formal agreement between parties. |
| event | A generic historical or in-world event. |
Misc
| Type | Description |
|---|---|
| vehicle | A ship, carriage, airship, or other transport. |
| map | A chart, diagram, or navigational document. |
| letter | A written correspondence or message. |
| currency | A coin, token, or monetary system. |
| law | A decree, edict, or legal code. |
| document | A manuscript, contract, or official record. |
| resource | A natural or manufactured material resource. |
| technology | An invention, technique, or technological system. |
| unknown | Type is not yet determined. |
Establishment
| Type | Description |
|---|---|
| shop | A retail store or vendor stall. |
| marketplace | A market district or trading post. |
| temple | A place of worship. |
| business | A generic commercial establishment. |
| archive | A library, records hall, or repository of knowledge. |
| treasury | A vault or financial institution. |
| healing_center | A hospital, apothecary, or healing house. |
| political_center | A courthouse, palace, or seat of governance. |
| academy | A school, university, or training institution. |
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).
Organizational
| Type | Description |
|---|---|
| member_of | Subject belongs to the object organization. |
| affiliated_with | Subject has a loose association with the object. |
| parent_of | Subject is a parent organization of the object. |
| governs | Subject holds authority over the object. |
| regulated_by | Subject is subject to rules or oversight from the object. |
Locational
| Type | Description |
|---|---|
| resides_in | Subject lives or is based in the object location. |
| exists_within | Subject is physically contained inside the object. |
| found_in | Subject can be found or encountered in the object location. |
| operates_within | Subject conducts its activities in the object location. |
| adjacent_to | Subject and object are neighboring locations. |
| located_near | Subject is in the general vicinity of the object. |
| travels_to | Subject moves toward or visits the object. |
Ownership
| Type | Description |
|---|---|
| owns | Subject has legal or recognized ownership of the object. |
| possesses | Subject currently holds or carries the object. |
| has | Subject has a general association or attribute tied to the object. |
Social
| Type | Description |
|---|---|
| ally_of | Subject and object are in a cooperative relationship. |
| enemy_of | Subject and object are in active opposition. |
| competes_with | Subject and object are rivals. |
| trades_with | Subject and object exchange goods or services. |
| influences | Subject has sway over the object's behavior or decisions. |
| seeks | Subject is pursuing or searching for the object. |
Employment
| Type | Description |
|---|---|
| employs | Subject has hired the object. |
| serves | Subject works for or is loyal to the object. |
| leads | Subject is in charge of the object. |
| commands | Subject has direct authority over the object. |
Commerce
| Type | Description |
|---|---|
| creates | Subject produces or manufactures the object. |
| accepts | Subject accepts the object as payment or offering. |
| purchases | Subject buys or has bought the object. |
General
| Type | Description |
|---|---|
| associated_with | A catch-all for any meaningful connection not covered by other types. |
Entities, relationships, and notes each support visibility fields.
accessIds (entities & relationships)
An array of player user IDs who can view this entity or relationship. Set to null to make it visible to all realm members. When importing, these IDs must correspond to existing users in the realm.
notes (entity field)
A free-text field on each entity for private Gamelord notes. These are not visible to players even if accessIds is null. Set to null to omit.
accessIds (notes array)
Each entry in the top-level notes array has its own accessIds field. Set to null to give all realm members access to that note, or provide a list of user IDs to restrict it. Notes are imported as-is and are not linked to any specific session.
A complete V3 exchange file with three entities, two relationships, two notes, and selective access control throughout.
{
"version": "3",
"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"]
},
{
"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
},
{
"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
}
],
"relationships": [
{
"id": "rel_01",
"fromEntityId": "ent_kael",
"toEntityId": "ent_ironhold",
"type": "resides_in",
"accessIds": null
},
{
"id": "rel_02",
"fromEntityId": "ent_kael",
"toEntityId": "ent_ashen",
"type": "member_of",
"accessIds": ["player_marlowe", "player_britta"]
}
],
"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"]
}
]
}