# @hathor - Worldbuilding & Narrative Engine

Hathor is Oshun's worldbuilding engine, managing story structures, world
simulation, NPC AI, and narrative systems for games and interactive media.

## Overview

| Aspect              | Description               |
| ------------------- | ------------------------- |
| **Domain**          | Worldbuilding & Narrative |
| **Scope Tag**       | `scope:hathor`            |
| **API Port**        | 4004                      |
| **Database Schema** | `hathor`                  |

## Capabilities

- **World Management**: Create and manage detailed fictional worlds
- **Character Systems**: NPCs with AI-driven dialogue and behavior
- **Quest Design**: Non-linear quest graphs and story branching
- **Timeline Management**: Historical events and causality
- **Faction Dynamics**: Political relationships and conflicts
- **World Simulation**: Economic, political, and ecological systems
- **Lore Compilation**: Export to game engine formats

## Libraries

```
libs/hathor/
├── client/              # TypeScript client for other domains
├── database/            # Prisma schema & utilities
├── domain-models/       # Core domain models
│   ├── world/           # World definitions
│   ├── timeline/        # Historical events
│   └── faction/         # Political entities
├── narrative/           # Narrative structures
│   ├── quest/           # Quest graphs
│   ├── dialogue/        # Dialogue trees
│   └── story-arc/       # Story progression
├── simulation/          # World state simulation
│   ├── economy/         # Economic systems
│   ├── politics/        # Political dynamics
│   └── ecology/         # Environmental systems
├── theory/              # Framework definitions
├── llm-npc/             # NPC dialogue generation
├── lore-compiler/       # Engine artifact export
├── pre-production/      # Pre-production tools
├── validation/          # Consistency checking
├── sophia-integration/  # Research grounding
└── event-handlers/      # Event subscriptions
```

## Quick Start

### Using the Client

```typescript
import { createHathorClient } from '@hathor/client';

const hathor = createHathorClient({
  baseUrl: process.env.HATHOR_API_URL || 'http://localhost:4004',
});

// Create a world
const world = await hathor.worlds.create({
  name: 'Veilborn',
  genre: 'dark_fantasy',
  description: 'A realm where shadows hold ancient secrets',
});

// Add a character
const npc = await hathor.characters.create({
  worldId: world.id,
  name: 'Elder Morvain',
  role: 'quest_giver',
  personality: {
    traits: ['wise', 'mysterious', 'cautious'],
    voice: 'gravelly and slow',
  },
});

// Generate dialogue
const dialogue = await hathor.dialogue.generate({
  characterId: npc.id,
  context: 'Player asks about the ancient prophecy',
  mood: 'ominous',
});
```

### Running Locally

```bash
# Start Hathor API
nx serve hathor-api

# Run tests
nx test @hathor/client

# Build all Hathor libraries
nx run-many --target=build --projects=tag:scope:hathor
```

## API Endpoints

| Method | Endpoint                 | Description             |
| ------ | ------------------------ | ----------------------- |
| POST   | `/v1/worlds`             | Create world            |
| GET    | `/v1/worlds/:id`         | Get world details       |
| PUT    | `/v1/worlds/:id`         | Update world            |
| POST   | `/v1/worlds/:id/publish` | Publish world version   |
| POST   | `/v1/characters`         | Create character        |
| POST   | `/v1/quests`             | Create quest            |
| POST   | `/v1/dialogue/generate`  | Generate NPC dialogue   |
| POST   | `/v1/simulation/tick`    | Run simulation tick     |
| POST   | `/v1/export`             | Export to engine format |

## Events

| Event                         | Description              |
| ----------------------------- | ------------------------ |
| `hathor.world.created`        | New world created        |
| `hathor.world.published`      | World version published  |
| `hathor.character.created`    | NPC created              |
| `hathor.quest.created`        | Quest defined            |
| `hathor.simulation.completed` | Simulation tick finished |
| `hathor.dialogue.generated`   | AI dialogue generated    |

## Configuration

```bash
# Required
HATHOR_DATABASE_URL=postgresql://...?schema=hathor
REDIS_URL=redis://localhost:6379

# AI (for NPC dialogue)
OPENAI_API_KEY=sk-...

# Sophia integration (for lore grounding)
SOPHIA_API_URL=http://localhost:4003
```

## World Model

```typescript
interface World {
  id: string;
  name: string;
  genre: WorldGenre;
  description: string;
  settings: WorldSettings;
  entities: {
    characters: Character[];
    locations: Location[];
    factions: Faction[];
    items: Item[];
  };
  timeline: TimelineEvent[];
  rules: WorldRules;
}
```

## Local Development

Start the full development environment:

```bash
# Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose -f docker/docker-compose.dev.yml up -d

# Run database migrations
pnpm nx run @hathor/database:prisma:migrate:dev

# Start the World API
pnpm nx serve hathor-world-api
```

See [CLAUDE.md](/CLAUDE.md) for detailed local development setup.

## Related Documentation

- [API Reference](/docs/api/hathor/)
- [Worldbuilding Guide](/docs/guides/worldbuilding.md)
- [NPC AI Configuration](/docs/guides/npc-ai.md)
- [Cross-Domain Integration](/docs/guides/cross-domain-integration.md)
