Eve library

Hathor -- Product Features

Guide

Revision 1

On this page

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

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
PDF 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 lifecycle
  • listWorlds() -- Browse worlds with pagination and filtering
  • getVersion() / listVersions() -- Version management
  • createBranch() / listBranches() -- Branch management
  • createMergeRequest() / getMergeRequest() / updateMergeRequest() -- Merge workflow
  • addEntity() / updateEntity() / removeEntity() -- Entity management
  • getRelationships() / findConnectedEntities() -- Graph queries

12.2 Narrative Resource#

Manage story content:

  • createStoryGraph() / getStoryGraph() / updateStoryGraph() / deleteStoryGraph() -- Story graph CRUD
  • createQuest() / getQuest() / updateQuest() / deleteQuest() -- Quest CRUD
  • createDialogue() / getDialogue() / updateDialogue() / deleteDialogue() -- Dialogue CRUD
  • listStoryGraphs() / listQuests() / listDialogues() -- Browsing with pagination

12.3 Simulation Resource#

Run and query simulations:

  • submitJob() -- Start a simulation (economy, politics, culture, scenario)
  • getJobStatus() -- Check simulation progress
  • getResults() -- Retrieve simulation results
  • listJobs() -- 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 error
  • NetworkError -- Connection failures
  • TimeoutError -- Request timeouts
  • AbortError -- Cancelled requests
  • NotFoundError -- Resource not found
  • ValidationError -- Invalid data
  • UnauthorizedError / ForbiddenError -- Auth issues
  • ConflictError -- Version conflicts
  • RateLimitError -- 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 PDF
Quests Yes Yes Yes -- -- --
Dialogues Yes Yes Yes -- -- --
NPCs Yes Yes Yes -- -- --
Stories -- -- -- Yes Yes Yes
World data Yes Yes Yes -- -- --