Canonical source: the canonical features document for this domain is
deep-dive/features.md, rendered in the docs center. This file is its operational companion (service topology, APIs, schemas, runtime detail) — reconciled by linking, not duplicated (§2, §13).
Worldbuilding, Narrative Design, and World Simulation Platform
Hathor is the creative heart of the Oshun ecosystem for anyone who builds fictional worlds. It provides everything needed to design, populate, simulate, validate, and export interactive worlds -- from the geography and climate of a fantasy continent, through its economies, politics, and cultures, all the way to the quests, dialogues, and AI-driven NPCs that bring the world to life.
Executive Summary#
Hathor serves world builders, game designers, narrative designers, screenwriters, and creative directors. It covers the full lifecycle of a fictional world:
- World Modeling -- Define every aspect of a world: geography, climate, civilizations, factions, economies, legal systems, cultures, religions, timelines, characters, and locations with rich, structured data.
- Narrative Design -- Author interactive narratives with quest systems, branching dialogue trees, non-linear story graphs, and in-game journal/codex systems. Export to Ink, Yarn Spinner, and JSON.
- World Simulation -- Run economic, political, and cultural simulations that evolve your world over time. Generate scenarios, test interventions, and analyze emergent dynamics.
- NPC Intelligence -- Create LLM-powered NPCs with personality (Big Five + Enneagram), emotions, memory (short-term + long-term), world awareness, goal-driven behavior, and generated dialogue. Integrate with NVIDIA ACE, Inworld AI, and Convai.
- Lore Validation -- Automatically check your world for timeline inconsistencies, causal paradoxes, taxonomy violations, and contradictions.
- Lore Compilation -- Compile world content into engine-ready formats for Unreal Engine, Unity, Godot, and Blender, or into screenplay formats (Fountain, Final Draft, PDF) for film production.
- Pre-Production Tools -- Chronicle document parsing, visual storyboarding, narrative structure analysis, and project management with built-in checklists.
- Game Design Theory -- MDA framework analysis, narrative structure templates, beat sheets, cinematography planning, and character arc design.
- Git-Like Versioning -- Branch, merge, and version your entire world with conflict resolution and merge requests.
- Research Grounding -- Connect your world lore to real research sources via Sophia integration for historically and culturally grounded worldbuilding.
- Visual Workbench -- A web application for visual world creation with pages for worlds, characters, factions, locations, timelines, and world editing.
- TypeScript SDK -- Full programmatic access to World, Narrative, and Simulation APIs.
1. World Modeling#
1.1 World Configuration#
Every world begins with a top-level configuration:
| Setting | Options |
|---|---|
| Genre | Fantasy, Science Fiction, Historical, Mythology, Contemporary, Horror, Post-Apocalyptic, Steampunk |
| Scope | Small, Medium, Large, Epic, Cosmic |
| Technology Level | Primitive, Stone Age, Bronze Age, Iron Age, Medieval, Renaissance, Industrial, Modern, Advanced |
| Magic Level | None, Low, Medium, High, Pervasive |
| Status | Draft, Active, Archived, Deleted |
1.2 Geography#
Define the physical landscape of your world:
- Terrain types -- Mountains, forests, deserts, plains, tundra, swamps, oceans, rivers, islands, and custom terrain
- Climate systems -- Temperature zones, precipitation patterns, seasonal cycles, and weather events
- Biomes -- Ecological regions with flora and fauna associations
- Natural features -- Volcanoes, caves, waterfalls, canyons, and other landmarks
- Maps -- Regional and continental organization with nested locations
1.3 Factions#
Create political and social groups:
| Faction Attribute | Description |
|---|---|
| Type | Kingdom, Empire, Republic, Tribe, Guild, Religious Order, Criminal Organization, etc. |
| Hierarchy | Leadership structure with ranks and roles |
| Ideology | Core beliefs, values, and goals |
| Relations | Alliances, rivalries, treaties, and wars with other factions |
| Territory | Controlled locations and borders |
| Resources | Economic assets and trade goods |
| Military | Armed forces composition and strength |
1.4 Economy#
Model your world's economic systems:
- Resources -- Commodities with rarity, categories, and production sources
- Currencies -- Monetary systems with exchange rates
- Markets -- Trading hubs with supply, demand, and pricing
- Trade routes -- Connections between markets with distance, risk, and profitability
- Guilds -- Economic organizations controlling industries
- Trade agreements -- Bilateral and multilateral economic treaties
1.5 Legal Systems#
Define the laws of the land:
- Legal codes with rules and penalties
- Enforcement structures (guards, courts, arbitration)
- Crime categories and severity levels
- Jurisdictional boundaries
- Legal traditions (common law, civil law, religious law, custom)
1.6 Culture#
Capture cultural richness:
- Traditions -- Customs, ceremonies, and rites of passage
- Art forms -- Music, literature, visual arts, performance
- Social structures -- Class systems, kinship, gender roles
- Belief systems -- Religious and philosophical traditions
- Languages -- Naming conventions, common phrases, linguistic families
- Cuisine -- Food traditions and culinary practices
- Architecture -- Building styles and construction traditions
1.7 Characters#
Design inhabitants of your world:
| Character Aspect | Details |
|---|---|
| Identity | Name, aliases, species, age, gender |
| Attributes | Physical traits, abilities, skills |
| Backstory | Origin, formative events, motivations |
| Relationships | Family, allies, enemies, romantic interests |
| Faction | Allegiance, rank, role within faction |
| Status | Alive, dead, missing, unknown |
| Location | Current whereabouts, home, frequent locations |
1.8 Locations#
Define places in your world:
- Settlements -- Cities, towns, villages, camps with population and governance
- Buildings -- Individual structures with function, architecture, and inhabitants
- Natural locations -- Wilderness areas, caves, forests, bodies of water
- Dungeons -- Adventure locations with rooms, encounters, and treasures
- Realms -- Planar or dimensional spaces beyond the physical world
- Nesting -- Locations can contain other locations for hierarchical world design
1.9 Timelines#
Track the history of your world:
- Eras -- Named periods with start and end dates
- Events -- Historical occurrences with date, location, and participants
- Chronological ordering -- Automatic timeline sorting and visualization
- Event chains -- Cause-and-effect sequences linking events
- Character lifespans -- Birth, death, and key life events tied to the timeline
2. Narrative Design#
2.1 Quest System#
Design interactive quests with:
| Quest Element | Description |
|---|---|
| Objectives | Tasks the player must complete (collect, kill, escort, explore, talk, craft, discover, defend, solve, deliver) |
| Prerequisites | Quests, items, or conditions required before the quest becomes available |
| Branching | Multiple paths through the quest based on player choices |
| Rewards | Items, currency, experience, reputation, or custom rewards |
| Categories | Main story, side quest, faction quest, daily, event, hidden, tutorial |
| Priority | Low, medium, high, critical |
| Status | Available, active, completed, failed, abandoned |
2.2 Dialogue System#
Author branching conversations:
- Dialogue trees -- Hierarchical conversation structures with speaker attribution
- Player choices -- Multiple response options at each dialogue node
- Conditions -- Show or hide dialogue options based on game state, faction reputation, item possession, or quest progress
- Variable substitution -- Insert character names, item names, and other dynamic content into dialogue text
- Node types -- Entry, NPC speech, player choice, action, condition check, random selection, exit
- Speaker attribution -- Every line tracks who is speaking
2.3 Story Graph#
Design non-linear narratives:
| Node Type | Purpose |
|---|---|
| START | Entry point of the story |
| SCENE | A narrative scene with description and events |
| CHOICE | A branching point where the player makes a decision |
| CONDITION | An automatic branch based on game state evaluation |
| ACTION | A game-world action triggered by the story |
| END | A conclusion point (there can be multiple endings) |
- Arcs -- Directed connections between nodes with conditions and consequences
- State transitions -- Track and modify narrative state as the player progresses
- Multiple endings -- Design branching conclusions based on accumulated choices
2.4 Journal and Codex System#
In-game knowledge management for players:
- Journal entries -- Chronological log of events, discoveries, and quest updates
- Codex entries -- Encyclopedia-style articles about world lore, characters, factions, and locations
- Discovery tracking -- Entries unlock as the player explores and progresses
- Player notes -- Allow players to add their own annotations
- Category organization -- Group entries by topic, region, or faction
2.5 Narrative Export#
Export narrative content to industry-standard formats:
| Format | Engine/Tool | Use Case |
|---|---|---|
| Ink | Inkle Ink/Inky | Interactive fiction, branching stories |
| Yarn Spinner | Yarn Spinner | Unity dialogue systems |
| JSON | Any | Custom engines and tools |
3. World Simulation#
3.1 Economy Simulation#
Run dynamic economic simulations:
- Market simulation -- Supply and demand dynamics, price fluctuations, market specialization
- Trade route modeling -- Route profitability analysis, distance costs, risk factors, capacity limits
- Resource flow -- Production, consumption, stockpiling, and scarcity events
- Guild dynamics -- Guild influence on markets, price controls, trade monopolies
- Economic events -- Famines, windfalls, trade embargoes, natural disasters
- Snapshots -- Capture and compare economic states over time
- Analysis -- Trade network analysis, market comparisons, economic health indicators
3.2 Politics Simulation#
Simulate political dynamics:
- Faction relations -- Dynamic alliance, rivalry, and neutrality calculations
- Conflict resolution -- War, negotiation, and diplomacy outcomes
- Leader behavior -- Personality-driven leader decisions and succession
- Alliance management -- Formation, maintenance, and dissolution of alliances with obligations
- Treaties -- Peace treaties, trade agreements, military pacts with compliance tracking
- Elections -- Electoral processes with candidate campaigns and voter behavior
- Political events -- Coups, rebellions, assassinations, policy changes
3.3 Culture Evolution Simulation#
Watch cultures evolve over time:
- Cultural trait drift -- Gradual change in cultural values and practices
- Cultural contact -- What happens when two cultures meet (exchange, assimilation, conflict)
- Innovation -- New ideas, inventions, and cultural developments
- Subcultures -- Emergence of distinct groups within larger cultures
- Cultural phases -- Growth, flourishing, decline, and renaissance cycles
- Influence networks -- How cultural traits spread between connected groups
- Similarity analysis -- Compare cultures across dimensions
3.4 Scenario Generation#
Generate and explore "what-if" scenarios:
- Configure starting conditions (technology, magic, conflict, geography, climate)
- Advance scenarios through time with simulation ticks
- Apply interventions (events, policy changes, disasters) and observe outcomes
- Analyze results: power balance, economic outlook, cultural trends, conflict risk projections
- Use templates for common scenario types
- Compare multiple scenario branches
3.5 NPC Behavior Trees#
Program NPC behavior with composable tree nodes:
| Node Category | Node Types |
|---|---|
| Leaf | Action, Condition |
| Composite | Sequence, Selector, Parallel, Random Selector |
| Decorator | Inverter, Succeeder, Failer, Repeater, Retry, Limiter, Timeout, Cooldown, Guard |
Pre-built behavior patterns:
- Patrol -- NPC walks between waypoints
- Flee -- NPC runs from threats
- Attack -- NPC engages in combat
- Idle -- NPC performs ambient activities
The behavior tree builder provides a fluent API for composing complex behaviors from simple building blocks.
3.6 Physics Engine#
A built-in physics engine for world simulation:
| Feature | Details |
|---|---|
| Rigid bodies | Mass, velocity, angular velocity, friction, restitution |
| Colliders | Box, sphere, capsule, cylinder, plane, heightmap |
| Constraints | Distance, hinge, ball socket, slider, fixed |
| Force fields | Gravity, wind, buoyancy, drag, explosion, vortex |
| Collision detection | Broad phase and narrow phase with contact manifolds |
| Raycasting | Ray and sphere casting for queries |
| Presets | Earth gravity, Moon gravity, Zero-G |
3.7 State Persistence#
Simulation state is stored and retrievable:
- In-memory, PostgreSQL, and Redis storage backends
- Snapshot capture at any simulation tick
- Domain-specific state stores (economy, politics, culture)
- Cache key management for efficient lookups
- State serialization for import/export
4. LLM-Powered NPC Intelligence#
4.1 Personality System#
Every NPC has a multi-dimensional personality:
Big Five Personality Model:
| Trait | Low Score | High Score |
|---|---|---|
| Openness | Conventional | Curious, creative |
| Conscientiousness | Spontaneous | Organized, diligent |
| Extraversion | Reserved, quiet | Outgoing, energetic |
| Agreeableness | Competitive | Cooperative, kind |
| Neuroticism | Emotionally stable | Anxious, reactive |
Enneagram System (Advanced):
- 9 core types with wing influences
- Tritypes (combination of three types)
- Integration and disintegration paths
BDI Model (Advanced):
- Beliefs -- What the NPC thinks is true
- Desires -- What the NPC wants
- Intentions -- What the NPC plans to do
Speech Patterns:
- Vocabulary level (simple to scholarly)
- Sentence structure preferences
- Verbal tics and catchphrases
- Formality level
- Dialect and accent markers
4.2 Emotional State#
Real-time emotional tracking:
- Core emotions: joy, sadness, anger, fear, surprise, disgust, trust, anticipation
- Emotional intensity (0 to 1 scale)
- Emotional transitions based on events and interactions
- Mood (sustained emotional baseline)
- Emotion history for character consistency
4.3 Memory System#
NPCs remember:
Short-Term Memory:
- Recent conversation turns
- Recent events and interactions
- Attention-weighted recall (more important events remembered better)
- Configurable capacity
Long-Term Memory:
- Important life events
- Relationships with other characters
- Knowledge about the world
- Learned information from conversations
- Memory consolidation (STM to LTM promotion)
- Configurable consolidation strategies
4.4 World Awareness#
NPCs understand their surroundings:
- Current location with spatial awareness
- Knowledge of nearby characters and objects
- Understanding of local faction control
- Awareness of recent events in the area
- Time-of-day and weather awareness
4.5 Dialogue Generation#
Generate contextually appropriate dialogue in real time:
- Personality-consistent speech patterns
- Emotion-influenced tone and word choice
- Memory-informed references to past interactions
- World-aware responses about the environment
- Topic tracking across conversation turns
- Dialogue act classification (greeting, question, statement, farewell)
- Sentiment analysis of player input
- Character consistency checking
4.6 Safety and Guardrails#
Content safety for generated dialogue:
- Content safety filters for inappropriate language
- Appropriateness scoring for in-world context
- Fourth-wall detection (NPC should not break character)
- Lore consistency checking (NPC should not contradict world facts)
- Manipulation detection (detect player attempts to exploit NPC)
- Configurable safety thresholds
4.7 Behavior Control#
Goal-driven NPC behavior:
- Behavior controller -- Schedule-based activity planning
- GOAP (Goal-Oriented Action Planning) -- NPCs formulate plans to achieve goals based on current world state
- HTN (Hierarchical Task Networks) -- Complex task decomposition into subtasks
- Failure recovery -- NPCs adapt when plans fail
- Resource gathering and item manipulation -- NPCs interact with the world
4.8 NPC-to-NPC Conversations#
Autonomous NPC interactions:
- Multi-NPC conversation orchestration
- Turn-taking management
- Topic negotiation between NPCs
- Relationship-aware dialogue
- Conversation goals and outcomes
4.9 Platform Integration#
Connect NPC intelligence to external AI platforms:
| Platform | Features |
|---|---|
| Generic LLM | OpenAI-compatible API, local model support, streaming |
| NVIDIA ACE | Avatar Cloud Engine, blendshape facial animation, Audio2Face, Nemo customization, Riva streaming |
| Inworld AI | Session management, character triggers, knowledge entries, goal setting, state tracking |
| Convai | Session management, action triggers, face data, function calls, guardrails |
4.10 Provider Chain#
Resilient AI provider management:
- Multiple providers in priority order
- Circuit breaker pattern for failing providers
- Automatic failover to healthy providers
- Health monitoring and statistics
- Factory presets: standard chain, game-optimized chain
5. Lore Validation#
5.1 Timeline Validation#
Check your world's history for consistency:
- Chronological ordering verification
- Era boundary overlap detection
- Character lifespan consistency (no events after death)
- Event date range validation
5.2 Causality Validation#
Verify cause-and-effect chains:
- Temporal consistency (effects cannot precede causes)
- Causal chain completeness (no missing links)
- Cycle detection (no circular causality)
5.3 Taxonomy Validation#
Ensure type correctness:
- Entity type checking (characters should not be locations)
- Hierarchy validation (subtypes conform to parent type rules)
- Custom type definition support
5.4 Contradiction Detection#
Find conflicting information:
| Contradiction Type | Example |
|---|---|
| Temporal | Character described as alive and dead at same time |
| Spatial | Character in two places simultaneously |
| Attribute | Character's eye color changes between descriptions |
| Relationship | A is described as B's parent and child |
| State | Door is locked and open at the same time |
5.5 Unified Validation#
Run all four validators in a single pass:
- Configurable fail-fast behavior (stop at first error vs. collect all)
- Per-category issue limits
- Severity classification: info, warning, error
- Timing data per validator
- Unified validation report
6. Lore Compilation#
6.1 Game Engine Compilation#
Compile world content into engine-native formats:
| Target Engine | Output Format | Content Types |
|---|---|---|
| Unreal Engine | Blueprints, DataTables | Quests, dialogues, NPCs, items |
| Unity | C# ScriptableObjects | Quests, dialogues, NPCs, items |
| Godot | GDScript, Resources | Quests, dialogues, NPCs, items |
| Blender | Python scripts | Scene setup, character placement |
6.2 Screenplay Compilation#
Compile stories into film production formats:
| Format | Tool | Features |
|---|---|---|
| Fountain | Any text editor | Industry-standard plain text screenplay format |
| FDX (Final Draft) | Final Draft | Professional screenwriting software format |
| Any viewer | Print-ready screenplay layout |
6.3 Bellona Package Builder#
Create interchange packages for the Bellona build engine:
- Cross-engine asset packaging
- World data, quest data, dialogue data bundled together
- Metadata and manifest generation
- Target engine specification
7. Game Design Theory#
7.1 MDA Framework#
Analyze game design using Mechanics-Dynamics-Aesthetics:
- Mechanics -- Define and catalog game rules and systems
- Dynamics -- Simulate emergent behaviors from mechanic interactions
- Aesthetics -- Evaluate player experience categories (sensation, fantasy, narrative, challenge, fellowship, discovery, expression, submission)
- Feedback loops -- Identify positive and negative feedback loops
- Flow analysis -- Evaluate challenge-skill balance for player engagement
- Experience evaluation -- Score the overall player experience
- Mechanic templates -- Pre-built templates for common game mechanics
7.2 Narrative Theory#
Analyze and design story structures:
| Structure Template | Description |
|---|---|
| Hero's Journey | 12-stage mythological narrative structure |
| Three Act | Setup, confrontation, resolution |
| Five Act | Exposition, rising action, climax, falling action, denouement |
| Kishotenketsu | Japanese four-act structure (intro, development, twist, conclusion) |
| And more... | Additional templates for various narrative traditions |
Features:
- Fabula/Syuzhet decomposition -- Separate story events from their presentation order
- Dramatic irony tracking -- Identify moments where the audience knows more than the characters
- Pacing analysis -- Evaluate narrative tempo and tension curves
- Beat sheet generation -- Create structured beat sheets from story outlines
- Character arc templates -- Pre-built arc patterns (growth, fall, redemption, corruption, etc.)
7.3 Cinematography Planning#
Plan visual storytelling:
- Shot design -- Define shot type, angle, movement, lens, and focus
- Composition analysis -- Rule of thirds, golden ratio, leading lines, framing evaluation
- Lighting design -- Three-point lighting, practical lights, motivated lighting setups
- Color palette analysis -- Color temperature, saturation, mood associations
- Rhythm analysis -- Shot duration patterns and editing rhythm
- Continuity checking -- Ensure visual consistency across shots
- Reference databases -- Cataloged shot types, camera angles, movements, lighting setups, and color scheme effects
8. Pre-Production Tools#
8.1 Chronicle Parser#
Parse structured worldbuilding documents:
- Era headings -- Identify historical period markers
- Event headings -- Identify significant event descriptions
- Speaker attribution -- Identify quoted speech with speaker names
- Document references -- Detect references to other documents
- Title pages -- Parse document front matter
- Inline formatting -- Bold, italic, and other text formatting
- Diagnostics -- Error and warning reporting for malformed documents
8.2 Narrative Structure Analysis#
Analyze narrative documents against structure templates:
- Map story beats to template positions (e.g., Hero's Journey stages)
- Calculate adherence score (how well the story follows the template)
- Identify missing critical beats
- Pacing intensity analysis across the narrative arc
- Built-in templates: Epic Journey, Chronicle, Rise and Fall
8.3 Visual Storyboarding#
Plan stories visually:
- Frames -- Individual storyboard panels with descriptions
- Sequences -- Ordered groups of frames forming scenes
- Layers -- Foreground, midground, background composition
- Camera specs -- Shot type, angle, lens for each frame
- Transitions -- Cut, dissolve, fade, wipe between frames
- Character placement -- Position characters within frames
- Props and effects -- Add objects and visual effects to panels
- Text overlays -- Dialogue, captions, and sound effects
- Timeline linking -- Connect storyboard frames to world timeline events
- Export -- Export storyboards for production use
8.4 Project Management#
Manage worldbuilding projects:
- Phases -- Divide projects into phases (concept, development, refinement, polish)
- Milestones -- Set and track project milestones
- Tasks -- Create tasks with assignments, deadlines, and dependencies
- Dependencies -- Define task ordering and blocking relationships
- Progress tracking -- Automatic progress calculation from task completion
- Project health -- Overall health score based on milestone and task status
- Built-in checklists:
- Character creation checklist
- Location creation checklist
- Faction creation checklist
- Event planning checklist
- Magic system design checklist
- World overview checklist
9. Version Control for Worlds#
9.1 Git-Like Versioning#
Every world supports full version control:
- Versions -- Every change creates a new version with a description of what changed
- Branches -- Create branches to explore alternative world states without affecting the main version
- Merge requests -- Propose merging a branch back into the main world
- Merge approval -- Review and approve or reject merge requests
- Merge execution -- Perform the merge with conflict detection
- Version comparison -- Compare any two versions to see what changed
- Version history -- Full audit trail of every change
9.2 Entity Management Within Versions#
- Add, update, and remove entities within a specific version
- Entity relationships tracked per version
- Relationship mapping across the world graph
- Connected entity discovery
10. Research Grounding (Sophia Integration)#
10.1 Citation Service#
Link world lore to real research sources:
- Search Sophia's research index for relevant sources
- Create citations linking lore elements to source documents
- Verify citations for accuracy
10.2 Research Grounding Service#
Generate world content backed by research:
- Ground world descriptions in verified historical and cultural knowledge
- Discover real-world entities relevant to your world themes
- Suggest relationships between world elements and research sources
10.3 Lore Fact-Checking#
Validate world lore against the research corpus:
- Check individual facts against Sophia's knowledge base
- Batch validation of entire lore sections
- Confidence scoring for each fact check
- Suggestions for corrections when inconsistencies are found
11. Visual Workbench (Web Application)#
11.1 Dashboard#
Overview of your worldbuilding project:
- World count and status summary
- Recent activity feed
- Quick navigation to key areas
- Project health indicators
11.2 Worlds Page#
Browse and manage all your worlds:
- Create new worlds with genre, scope, and technology settings
- View world metadata and status
- Open worlds for editing
- Archive or delete worlds
11.3 World Editor#
The main editing environment:
- Edit world configuration (genre, scope, technology, magic)
- Manage entities within the world
- View the world's version history
- Create and manage branches
- Submit and review merge requests
11.4 Characters Page#
Manage the characters of your worlds:
- Browse all characters with filters
- Create new characters with full attribute sets
- Edit character details, backstory, and relationships
- View character connections on the relationship graph
11.5 Factions Page#
Manage political and social groups:
- Create factions with type, ideology, and leadership
- Define faction relationships (alliance, rivalry, war)
- Track faction territories and resources
- View faction hierarchy and membership
11.6 Locations Page#
Manage the geography of your worlds:
- Create locations with type, description, and coordinates
- Nest locations within other locations (city inside a region)
- View location maps and spatial relationships
- Link locations to factions and characters
11.7 Timeline Page#
Visualize and manage world history:
- Chronological event display
- Era markers and period organization
- Event creation with date, location, and participants
- Timeline navigation and zoom
12. TypeScript SDK#
12.1 World Resource#
Full CRUD and versioning for worlds:
createWorld()/getWorld()/updateWorld()/deleteWorld()-- World lifecyclelistWorlds()-- Browse worlds with pagination and filteringgetVersion()/listVersions()-- Version managementcreateBranch()/listBranches()-- Branch managementcreateMergeRequest()/getMergeRequest()/updateMergeRequest()-- Merge workflowaddEntity()/updateEntity()/removeEntity()-- Entity managementgetRelationships()/findConnectedEntities()-- Graph queries
12.2 Narrative Resource#
Manage story content:
createStoryGraph()/getStoryGraph()/updateStoryGraph()/deleteStoryGraph()-- Story graph CRUDcreateQuest()/getQuest()/updateQuest()/deleteQuest()-- Quest CRUDcreateDialogue()/getDialogue()/updateDialogue()/deleteDialogue()-- Dialogue CRUDlistStoryGraphs()/listQuests()/listDialogues()-- Browsing with pagination
12.3 Simulation Resource#
Run and query simulations:
submitJob()-- Start a simulation (economy, politics, culture, scenario)getJobStatus()-- Check simulation progressgetResults()-- Retrieve simulation resultslistJobs()-- Browse simulation history
12.4 Helper Functions#
Convenience utilities in the SDK:
| Function | Purpose |
|---|---|
getWorldStateSnapshot() |
Capture complete world state at a point in time |
buildRelationshipMap() |
Generate a map of all entity relationships |
findConnectedEntities() |
Find all entities connected to a given entity |
getTimelineRange() |
Get events within a date range |
analyzeFaction() |
Analyze faction strength and relationships |
compareVersions() |
Diff two world versions |
searchWorld() |
Search entities within a world |
generateQuestFromTemplate() |
Generate a quest using a built-in template |
generateQuestChain() |
Generate a series of connected quests |
validateWorldLore() |
Run lore validation |
checkLoreImpact() |
Predict the impact of a lore change |
12.5 Quest Templates#
Built-in quest templates for rapid quest creation:
- Fetch quests (retrieve an item and return)
- Kill quests (defeat enemies)
- Escort quests (protect someone on a journey)
- Investigation quests (gather clues and solve a mystery)
- Defense quests (protect a location from attack)
- Collection quests (gather multiple items)
- Customizable parameters for each template
12.6 Error Handling#
Comprehensive error types:
HathorError-- Base errorNetworkError-- Connection failuresTimeoutError-- Request timeoutsAbortError-- Cancelled requestsNotFoundError-- Resource not foundValidationError-- Invalid dataUnauthorizedError/ForbiddenError-- Auth issuesConflictError-- Version conflictsRateLimitError-- Throttling
13. Cross-Domain Integration#
13.1 Events Published by Hathor#
| Event | Trigger | Consumers |
|---|---|---|
hathor.world.created |
New world created | Analytics, dashboards |
hathor.world.published |
World published for use | Bellona (engine export) |
hathor.element.added |
Entity added to a world | Dashboards, event logs |
hathor.narrative.generated |
Narrative content created | Content pipelines |
hathor.simulation.started |
Simulation job begins | Progress tracking |
hathor.simulation.completed |
Simulation job finishes | Result consumers |
hathor.world.validated |
Validation results available | Quality dashboards |
13.2 Events Consumed by Hathor#
| Source Event | Source Domain | Hathor Action |
|---|---|---|
sophia.document.ingested |
Sophia | Incorporate research documents into world lore |
isis.asset.generated |
Isis | Link generated assets to world entities |
yemaya.project.created |
Yemaya | Synchronize creative projects with world state |
yemaya.character.created |
Yemaya | Incorporate new characters into the world graph |
13.3 Connected Domains#
| Domain | Relationship |
|---|---|
| Sophia | Research grounding, citation linking, lore fact-checking |
| Bellona | Engine compilation, asset packaging, build pipeline |
| Isis | AI-generated assets linked to world entities |
| Yemaya | Creative project synchronization, character sharing |
| Kuanyin | Content moderation for generated narrative |
| Maya | Playable experiences built from Hathor worlds |
Platform Availability#
| Feature | API | SDK | Web UI | CLI |
|---|---|---|---|---|
| World creation and editing | Yes | Yes | Yes | -- |
| Entity management | Yes | Yes | Yes | -- |
| Version control | Yes | Yes | Yes | -- |
| Quest design | Yes | Yes | -- | -- |
| Dialogue authoring | Yes | Yes | -- | -- |
| Story graph design | Yes | Yes | -- | -- |
| Narrative export | -- | Yes | -- | -- |
| Economic simulation | Yes | Yes | -- | -- |
| Political simulation | Yes | Yes | -- | -- |
| Cultural simulation | Yes | Yes | -- | -- |
| Scenario generation | Yes | Yes | -- | -- |
| NPC personality | -- | Yes | -- | -- |
| NPC dialogue generation | -- | Yes | -- | -- |
| Lore validation | -- | Yes | -- | -- |
| Lore compilation | -- | Yes | -- | -- |
| Storyboarding | -- | Yes | -- | -- |
| Project management | -- | Yes | -- | -- |
| MDA analysis | -- | Yes | -- | -- |
| Cinematography planning | -- | Yes | -- | -- |
| Research grounding | -- | Yes | -- | -- |
Feature Comparison: Simulation Engines#
| Capability | Economy | Politics | Culture | Scenario |
|---|---|---|---|---|
| Tick-based simulation | Yes | Yes | Yes | Yes |
| Event generation | Yes | Yes | Yes | Yes |
| State snapshots | Yes | Yes | Yes | Yes |
| Intervention support | Yes | Yes | Yes | Yes |
| Analysis tools | Trade, price | Power, conflict | Similarity, influence | Multi-domain |
| Entity types | Markets, routes, guilds | Factions, leaders, alliances | Traits, contacts, subcultures | Configurable |
| Persistence backends | Memory, PG, Redis | Memory, PG, Redis | Memory, PG, Redis | Memory, PG, Redis |
Feature Comparison: NPC AI Platforms#
| Capability | Generic LLM | NVIDIA ACE | Inworld AI | Convai |
|---|---|---|---|---|
| Text dialogue | Yes | Yes | Yes | Yes |
| Voice synthesis | -- | Yes (Riva) | Yes | Yes |
| Facial animation | -- | Yes (Audio2Face, blendshapes) | -- | Yes (face data) |
| Character triggers | -- | -- | Yes | Yes |
| Knowledge base | -- | Yes (Nemo) | Yes | -- |
| Function calls | -- | -- | -- | Yes |
| Custom guardrails | -- | -- | -- | Yes |
| Local model support | Yes | -- | -- | -- |
| Streaming responses | Yes | Yes (Riva) | Yes | Yes |
| Circuit breaker | Yes (chain) | Yes (chain) | Yes (chain) | Yes (chain) |
Feature Comparison: Lore Compilation Targets#
| Content Type | Unreal Blueprints | Unity C# | Godot GDScript | Fountain | FDX | |
|---|---|---|---|---|---|---|
| Quests | Yes | Yes | Yes | -- | -- | -- |
| Dialogues | Yes | Yes | Yes | -- | -- | -- |
| NPCs | Yes | Yes | Yes | -- | -- | -- |
| Stories | -- | -- | -- | Yes | Yes | Yes |
| World data | Yes | Yes | Yes | -- | -- | -- |