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#
text
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 for detailed local development setup.