Hathor is the Worldbuilding & Narrative domain. It provides tools for creating, simulating, and managing fictional worlds, including narrative systems (story graphs, dialogues, quests), world simulation (economy, politics, culture), and pre-production tools. Hathor generates living worlds with emergent behavior.
Prerequisites#
Required Software#
| Software | Minimum Version | Purpose |
|---|---|---|
| Node.js | >= 20.0.0 | Runtime for all Hathor services |
| pnpm | >= 9.0.0 | Package manager (monorepo workspace) |
| Docker | >= 24.0 | Infrastructure (PostgreSQL, Redis) |
| TypeScript | ^6.0.3 | Type checking and compilation |
Optional#
| Software | Purpose |
|---|---|
| Neo4j | Knowledge graph for world entity relations |
| Redis | Job queues for simulation workers |
Project Structure#
apps/hathor/
world-api/ # World state management, versioning, queries, merge operations
narrative-api/ # Story graphs, dialogues, quests, validation
simulation-worker/ # Background simulation workers (economy, politics, culture)
workbench/ # React web UI for world management and visualization
libs/hathor/
client/ # TypeScript SDK (@hathor/client)
database/ # Prisma schema and generated client (@hathor/database)
domain-models/ # Core domain model types
event-handlers/ # Cross-domain event handler setup
event-publisher/ # Cross-domain event publisher
llm-npc/ # LLM-powered NPC dialogue and behavior
lore-compiler/ # Lore consistency validation and compilation
narrative/ # Narrative export formats (Yarn, Ink, JSON)
pre-production/ # Pre-production planning tools
simulation/ # Simulation engine and models
sophia-integration/ # Sophia domain integration for research
theory/ # Narrative theory, cinematography, MDA framework
validation/ # World data validation rules
Simulation Workers#
The simulation worker runs specialized sub-workers:
| Worker | File | Purpose |
|---|---|---|
| Economy Worker | economy-worker.ts |
Trade, markets, resource flow |
| Politics Worker | politics-worker.ts |
Factions, diplomacy, governance |
| Culture Worker | culture-worker.ts |
Traditions, art, language drift |
| Scenario Worker | scenario-worker.ts |
What-if scenario simulations |
All workers extend BaseWorker which provides the simulation loop, heartbeat,
health monitoring, and job processing lifecycle.
Local Development Setup#
1. Start Infrastructure#
# Core services (PostgreSQL + Redis)
docker compose -f docker/docker-compose.dev.yml up -d
# Optional: Neo4j for world entity graphs
docker compose -f docker/docker-compose.dev.yml --profile graph up -d
2. Set Environment Variables#
| Variable | Default | Used By |
|---|---|---|
HATHOR_DATABASE_URL |
(from root .env) |
database lib |
REDIS_URL |
redis://localhost:6379 |
event bus, queues |
PORT |
3000 |
world-api |
HOST |
localhost |
world-api |
NEO4J_URL |
bolt://localhost:7687 |
knowledge graph |
3. Database Setup (Prisma)#
Hathor has a full Prisma migration setup with an initial migration:
cd libs/hathor/database
# Generate the Prisma client
npx prisma generate
# Run migrations (applies existing migrations)
npx prisma migrate dev
# Or push schema directly for rapid iteration
npx prisma db push
The migration history is at:
libs/hathor/database/prisma/migrations/
20260111231616_init/migration.sql
migration_lock.toml
4. Install Dependencies#
pnpm install
5. Seed the Database#
cd libs/hathor/database
npx tsx prisma/seed.ts # Standard world data
npx tsx prisma/seed-test.ts # Test fixtures
Running Services#
World API#
The central API for world state management. Built with Hono and Zod OpenAPI. Supports world creation, versioning, graph queries, and merge operations.
# Development (hot reload)
cd apps/hathor/world-api
pnpm dev # tsx watch src/index.ts
# Via Nx
pnpm nx serve @hathor/world-api
API routes:
/worlds- World CRUD operations/versions- World version management (branching, tagging)/query- Semantic queries against world state/merge- Merge world branches with conflict resolution
Key services:
world.service.ts- World CRUD and state managementversion.service.ts- Version control for worldsquery.service.ts- World state queriesworld-graph.service.ts- Graph-based world relationshipsmerge.service.ts- Branch merging with conflict detection
Rate limiting is enabled via middleware/rate-limit.ts.
Narrative API#
Manages story graphs, dialogues, quests, and narrative validation.
pnpm nx serve @hathor/narrative-api
API routes:
/story-graphs- Story graph CRUD and traversal/dialogues- Dialogue tree management/quests- Quest definition and state tracking/validation- Lore consistency validation
Key services:
story-graph.service.ts- Branching narrative graphsdialogue.service.ts- Dialogue trees with conditions/effectsquest.service.ts- Quest definitions with objectivesvalidation.service.ts- Cross-reference validation
Simulation Worker#
Processes simulation jobs that advance world state over time ticks.
pnpm nx serve @hathor/simulation-worker
The worker provides:
- A job queue (
queue/job-queue.ts) for managing simulation jobs - A worker pool (
api/worker-pool.ts) for running multiple workers - An API (
api/routes.ts) for submitting and monitoring jobs
Simulation types: economy, politics, culture, scenario, integrated
Each worker type extends BaseWorker and implements:
initialize()- Load domain-specific modelsexecuteTick(job, tickNumber, currentDate, signal)- Process one time steptakeSnapshot(job, tickNumber)- Capture world state at a point in timecompileOutput(job, ticks, snapshots, events, duration)- Compile resultscleanup(job)- Release resources
Tick intervals: hour, day, week, month, year
Workbench (React Web UI)#
A React SPA for world visualization and management.
pnpm nx serve @hathor/workbench
The workbench includes:
- Vite dev server with Tailwind CSS
- Pages: Dashboard, Worlds, Characters, Locations, Factions, Timeline
- API service layer in
src/api/services/
Building#
Build All Hathor Projects#
pnpm nx run-many --target=build --projects=tag:scope:hathor
Build Individual Projects#
# World API (tsc via @nx/js:tsc)
pnpm nx build @hathor/world-api
# Narrative API (tsc via @nx/js:tsc)
pnpm nx build @hathor/narrative-api
# Simulation Worker (tsc via @nx/js:tsc)
pnpm nx build @hathor/simulation-worker
# Workbench (Vite build)
pnpm nx build @hathor/workbench
# Client SDK (tsup)
pnpm nx build @hathor/client
Testing#
Test Runner Configuration#
Hathor uses a mix of Vitest and Jest:
| Project | Runner | Executor |
|---|---|---|
| world-api | Vitest | @nx/vite:test |
| narrative-api | Jest | @nx/jest:jest |
| simulation-worker | Vitest | @nx/vite:test |
| workbench | Vitest | @nx/vite:test |
| database lib | Vitest | @nx/vite:test |
| client lib | Vitest | (tsup project) |
| theory lib | Vitest | @nx/vite:test |
Running Tests#
# All Hathor projects
pnpm nx run-many --target=test --projects=tag:scope:hathor
# Individual projects
pnpm nx test @hathor/world-api
pnpm nx test @hathor/narrative-api
pnpm nx test @hathor/simulation-worker
pnpm nx test @hathor/workbench
pnpm nx test @hathor/database
pnpm nx test @hathor/theory
Testing Simulation Workers#
The simulation workers use AbortController for cancellation. Test workers by
providing a mock JobQueue:
import { JobQueue } from '../queue/job-queue.js';
const queue = new JobQueue();
queue.enqueue({
type: 'economy',
worldId: 'test-world',
input: {
startDate: '2024-01-01',
endDate: '2024-12-31',
tickInterval: 'month',
snapshotInterval: 3,
},
// ... other required fields
});
const worker = new EconomyWorker({ type: 'economy' });
await worker.start(queue);
Linting#
pnpm nx run-many --target=lint --projects=tag:scope:hathor
Database Schema#
The Hathor database (libs/hathor/database/prisma/schema.prisma) uses
PostgreSQL with Prisma ORM. The database URL is HATHOR_DATABASE_URL.
Key model areas:
- Worlds - World definitions, metadata, settings
- Entities - Characters, locations, factions, items, events
- Relations - Typed relationships between world entities
- Versions - World version control (branches, tags, commits)
- Simulations - Simulation run records, snapshots, events
- Narratives - Story graphs, dialogue trees, quest definitions
Prisma Workflow#
# After schema changes
cd libs/hathor/database
# Generate client
npx prisma generate
# Create migration
npx prisma migrate dev --name describe_your_change
# Apply in production
npx prisma migrate deploy
# Reset (destructive)
npx prisma migrate reset
Common Development Tasks#
Creating a New World Template#
World templates provide starting configurations for new worlds.
-
Define the template data structure with world settings, initial entities, and simulation parameters.
-
Add the template to the seed script (
libs/hathor/database/prisma/seed.ts). -
Create a template endpoint in the world-api if templates should be selectable via the API.
-
Add validation rules in
libs/hathor/validation/for any template-specific constraints. -
If the template includes pre-built lore, integrate with the lore compiler (
libs/hathor/lore-compiler/) for consistency validation.
Adding a New Simulation Type#
-
Create a new worker in
apps/hathor/simulation-worker/src/workers/:typescriptimport { BaseWorker, type BaseWorkerConfig } from './base-worker.js'; export class ReligionWorker extends BaseWorker { protected async initialize(): Promise<void> { // Load religion simulation models } protected async executeTick( job: SimulationJob, tickNumber: number, currentDate: Date, signal: AbortSignal ): Promise<{ events: Event[]; metrics: Record<string, unknown> }> { // Simulate one time step of religious dynamics return { events: [], metrics: {} }; } protected async takeSnapshot( job: SimulationJob, tickNumber: number ): Promise<string> { // Capture state snapshot, return snapshot ID return `snapshot-${tickNumber}`; } protected async compileOutput( job, ticks, snapshots, events, duration ): Promise<SimulationOutput> { // Compile final simulation report return { /* ... */ }; } protected async cleanup(job: SimulationJob): Promise<void> { // Release resources } } -
Add the simulation type to the
SimulationTypetype definition inapps/hathor/simulation-worker/src/types/index.ts. -
Register the worker in
apps/hathor/simulation-worker/src/workers/index.ts. -
Add the worker to the worker pool in
api/worker-pool.ts. -
Update the simulation library (
libs/hathor/simulation/) with domain models for the new simulation type.
Adding a New Narrative Export Format#
The narrative library (libs/hathor/narrative/) supports exporting to multiple
formats.
-
Create an exporter in
libs/hathor/narrative/src/export/:typescriptimport type { NarrativeExporter, ExportOptions, ExportResult, } from './types.js'; export class TwineExporter implements NarrativeExporter { export(storyGraph: StoryGraph, options: ExportOptions): ExportResult { // Convert story graph to Twine format } } -
Register the exporter in
exporter-factory.ts. -
Existing exporters for reference:
yarn-exporter.ts- Yarn Spinner formatink-exporter.ts- Inkle's Ink formatjson-exporter.ts- Generic JSON format
Integrating LLM NPCs#
The libs/hathor/llm-npc/ library provides LLM-powered NPC dialogue.
- Define NPC personality, knowledge, and behavior in the NPC configuration.
- The LLM NPC system uses the NPC's world context (from the world-api) and narrative state (from the narrative-api) to generate contextual dialogue.
- Integration with the Sophia domain (via
libs/hathor/sophia-integration/) provides research knowledge to NPC responses.
Debugging Tips#
World API Not Starting#
- Check that PostgreSQL is running and
HATHOR_DATABASE_URLis correct - Verify Prisma client is generated:
npx prisma generate - The world-api uses Hono with
@hono/zod-openapi; validation errors appear in response bodies - Check that
@oshun/event-buscan connect to Redis
Narrative Validation Failures#
- The validation service checks lore consistency across story graphs
- Cross-reference errors indicate conflicting world facts
- Check the story graph for orphaned nodes (unreachable from root)
- Dialogue trees must have valid condition expressions
Simulation Worker Issues#
- Workers process jobs from the
JobQueuein a polling loop (1-second interval) - Jobs are matched to workers by
SimulationType - Workers report health via
getHealth()(memory usage, uptime, job counts) - Cancellation uses
AbortController; checksignal.abortedin tick loops - The tick interval must match the job's
tickIntervalsetting - Snapshot frequency is controlled by
snapshotInterval(every N ticks)
Database Migration Issues#
- Migrations are in
libs/hathor/database/prisma/migrations/ - If migrations are out of sync:
npx prisma migrate reset(destructive) - For schema drift:
npx prisma db push --accept-data-loss(development only) - Check the
migration_lock.tomlfor provider consistency
Workbench Build Issues#
- The workbench uses Vite with Tailwind CSS
- Test setup is in
src/test/setup.ts - API mock data is available in
src/api/mock-data.tsfor offline development - The workbench includes API services for all domain resources:
worlds,characters,factions,locations,timeline,dashboard
Performance Considerations#
- Simulation ticks yield control every 100 iterations (
await sleep(0)) - Snapshot intervals should be tuned for memory usage vs. granularity
- The world-api includes rate limiting middleware
- Version branching creates copies of world state; monitor database size
- The merge service handles conflict detection; review merge conflicts before accepting