Eve library

Hathor Domain - Developer Guide

Guide

Revision 1

On this page

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#

text
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#

bash
# 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:

bash
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:

text
libs/hathor/database/prisma/migrations/
  20260111231616_init/migration.sql
  migration_lock.toml

4. Install Dependencies#

bash
pnpm install

5. Seed the Database#

bash
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.

bash
# 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 management
  • version.service.ts - Version control for worlds
  • query.service.ts - World state queries
  • world-graph.service.ts - Graph-based world relationships
  • merge.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.

bash
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 graphs
  • dialogue.service.ts - Dialogue trees with conditions/effects
  • quest.service.ts - Quest definitions with objectives
  • validation.service.ts - Cross-reference validation

Simulation Worker#

Processes simulation jobs that advance world state over time ticks.

bash
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 models
  • executeTick(job, tickNumber, currentDate, signal) - Process one time step
  • takeSnapshot(job, tickNumber) - Capture world state at a point in time
  • compileOutput(job, ticks, snapshots, events, duration) - Compile results
  • cleanup(job) - Release resources

Tick intervals: hour, day, week, month, year

Workbench (React Web UI)#

A React SPA for world visualization and management.

bash
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#

bash
pnpm nx run-many --target=build --projects=tag:scope:hathor

Build Individual Projects#

bash
# 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#

bash
# 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:

typescript
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#

bash
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#

bash
# 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.

  1. Define the template data structure with world settings, initial entities, and simulation parameters.

  2. Add the template to the seed script (libs/hathor/database/prisma/seed.ts).

  3. Create a template endpoint in the world-api if templates should be selectable via the API.

  4. Add validation rules in libs/hathor/validation/ for any template-specific constraints.

  5. If the template includes pre-built lore, integrate with the lore compiler (libs/hathor/lore-compiler/) for consistency validation.

Adding a New Simulation Type#

  1. Create a new worker in apps/hathor/simulation-worker/src/workers/:

    typescript
    import { 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
      }
    }
    
  2. Add the simulation type to the SimulationType type definition in apps/hathor/simulation-worker/src/types/index.ts.

  3. Register the worker in apps/hathor/simulation-worker/src/workers/index.ts.

  4. Add the worker to the worker pool in api/worker-pool.ts.

  5. 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.

  1. Create an exporter in libs/hathor/narrative/src/export/:

    typescript
    import type {
      NarrativeExporter,
      ExportOptions,
      ExportResult,
    } from './types.js';
    
    export class TwineExporter implements NarrativeExporter {
      export(storyGraph: StoryGraph, options: ExportOptions): ExportResult {
        // Convert story graph to Twine format
      }
    }
    
  2. Register the exporter in exporter-factory.ts.

  3. Existing exporters for reference:

    • yarn-exporter.ts - Yarn Spinner format
    • ink-exporter.ts - Inkle's Ink format
    • json-exporter.ts - Generic JSON format

Integrating LLM NPCs#

The libs/hathor/llm-npc/ library provides LLM-powered NPC dialogue.

  1. Define NPC personality, knowledge, and behavior in the NPC configuration.
  2. 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.
  3. 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_URL is 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-bus can 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 JobQueue in 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; check signal.aborted in tick loops
  • The tick interval must match the job's tickInterval setting
  • 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.toml for 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.ts for 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