Entity
A flexible, game-agnostic entity representation for tabletop RPG content.
Entity serves as the core data model for representing various game elements such as characters,
monsters, items, spells and others across multiple game systems.
| Property | Type | Required | Description |
|---|---|---|---|
id |
string |
Yes | The unique identifier for this entity. A UUID string automatically generated when the entity is created. This serves as the primary key in the Realm database. |
kind |
string |
No | The category of this entity. Represents the broad classification of what this entity is within the game system. Examples: "Character" - Player characters; "Monster" - Creatures and adversaries |
system |
string |
Yes | The game system this entity belongs to. Identifies which game system or ruleset this entity is designed for. Should be lowercased. Examples: "dnd5e"; "pf2e" |
name |
string |
Yes | The display name of the entity. The primary human-readable identifier shown in the user interface. Examples: "Thorin Ironforge" |
slug |
string |
Yes | A URL-friendly identifier for the entity. A simplified, lowercase version of the name suitable for use in URLs, file paths, or as a readable unique identifier. Examples: "thorin-ironforge" |
type |
string |
No | A subtype classification within the entity’s kind. Provides additional categorization beyond the primary kind field. Usually better to use more generic data attribute Examples: For kind = "Monster": "undead", "dragon", "humanoid" |
descr |
string |
No | The primary description or flavor text for the entity. Contains the main descriptive content, lore, or mechanical description of the entity. This is typically displayed in detail views or tooltips. Usage: Monster descriptions |
notes |
string |
No | User-generated notes or GM notes for the entity. Stores custom annotations, reminders, or campaign-specific information added by users or game masters. Usage: Campaign-specific modifications; GM reminders |
image |
string |
No | The file path to the primary image representation. The main visual asset for the entity, typically a full illustration or detailed artwork. Note: Relative file paths are resolved agains the system/module container. Absolute file paths are resolved against the app’s documents folder. Examples: "monsters/thorin-ironforge.jpg"; "/modules/some-module-id/thorin-ironforge.jpg" |
token |
string |
No | The file path to a battle map token image. A small, typically top-down view image suitable for use on tactical battle maps. Usually circular or square format. Typical Specifications: Square or circular format; 256x256 to 512x512 pixels; Transparent background recommended |
icon |
string |
No | The URL or file path to a small icon representation. A compact icon suitable for list items, status effects, and others.. Should be recognizable at small sizes. Typical Specifications: 32x32 to 128x128 pixels; Simple, clear design; Works at small sizes |
data |
Object |
No | Flexible JSON storage for system-specific or arbitrary structured data. Stores game mechanics, statistics, abilities, and other structured information that doesn’t fit into the standard schema. This enables support for diverse game systems without schema modifications. Usage Examples: Character ability scores and skills; Monster stat blocks; Item properties and effects; Spell components and mechanics Note: The structure of this data varies by system and kind. |
attributes |
Object |
Yes | Dynamic attribute storage supporting various data types. A flexible key-value store for attributes and properties that need to be queryable or frequently accessed. Supports multiple data types through RealmAny. Common Attributes: Custom fields. |
modifiers |
Array<Modifier> | Yes | Active modifiers affecting this entity. A collection of temporary or permanent adjustments to the entity’s statistics, abilities, or behavior. Examples: Equipment bonuses (+2 to AC from armor); Buff/debuff effects (+4 to Strength from spell); Temporary penalties (-2 to attacks from condition) SeeAlso: Modifier |
tags |
Array<string> |
Yes | Custom tags for categorization and filtering. A flexible tagging system allowing users to organize entities with custom labels. Example Tags: "boss", "minion", "elite"; "undead", "fiend", "celestial" |
combatant |
Combatant | No | Combat-specific data linking this entity to an active encounter. When this entity participates in combat, this object stores initiative order, current position, combat state, and other encounter-specific information. Note: This is typically nil when the entity is not in active combat.; SeeAlso: Combatant |
sources |
Array<Source> | Yes | Source attributions for this entity. Tracks which books, supplements, or homebrew collections this entity originated from. Examples: Player’s Handbook; Monster Manual; Custom Homebrew Collection; Third-party supplements SeeAlso: Source |
appVersion |
string |
No | The application version when this entity was created or last modified. Records the app version to support data migration, debugging, and compatibility tracking across app updates. Format: Typically semantic versioning: "1.2.3" Note: Useful for identifying entities created with older versions that may need migration. |
systemVersion |
string |
No | The game system version or ruleset version this entity uses. Records the system version to support data migration, debugging, and compatibility tracking across game system updates. Format: Typically semantic versioning: "1.2.3" Note: Useful for identifying entities created with older system versions that may need migration. |
created |
string (date-time) |
Yes | The date and time when this entity was created. Automatically set to the current date and time when the entity is first instantiated. |
modified |
string (date-time) |
Yes | The date and time when this entity was last modified. Automatically set to the current date and time when the entity is first instantiated. |
Source
Section titled “Source”A citation to a source book or reference document.
Source stores the canonical source identifier and an optional page number.
It is embedded in content models to preserve where imported or authored game
content came from.
| Property | Type | Required | Description |
|---|---|---|---|
name |
string |
No | The canonical source identifier. This value is resolved with sourceToName() when displayed, so stored abbreviations or slugs can be shown as their full source names. |
page |
integer |
No | The page number within the source. |