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 files also create the relationships between them. Existing entities with the same ID are updated in place rather than duplicated.
Exchange files come in two versions. V1 supports entities only and is suitable for simple lore drops. V2 adds a relationships array for richer world graphs.
Both versions share the same envelope fields. The version field determines which additional fields are required.
version
Must be the string "2".
entities
Array of entity objects. Each entity requires id, type, name, description, notes, and accessIds.
{
"version": "2",
"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": "2",
"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
}
]
}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. |
Both entities and relationships have two optional visibility fields.
accessIds
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
A free-text field on entities for private Gamelord notes. Notes are not visible to players even if accessIds is null. Set to null to omit.
A complete V2 exchange file with three entities, two relationships, and selective access control on one entity and one relationship.
{
"version": "2",
"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"]
}
]
}