# Hathor -- Product Features

> **Canonical source:** the canonical features document for this domain is
> [`deep-dive/features.md`](./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     |
| 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            | --       | --  | --  |
