Executive Summary#
This document outlines the migration plan for Lilith's Veilborn game services (veilborn-core and veilborn-strategy) to Hathor's world simulation platform. The migration preserves all game mechanics while leveraging Hathor's versioning, narrative, and simulation capabilities.
Total Codebase: ~76K LOC
- veilborn-core: 40,849 LOC
- veilborn-strategy: 35,346 LOC
Estimated Effort: 10-12 weeks
1. Source Systems Overview#
veilborn-core#
Core game mechanics including:
- Character System: 12 Paths, 5 Resonance types, Thread abilities, Awakenings
- Combat System: Hex-grid, Tide initiative, action economy, dice pools
- World Systems: Tri-planar territory control, ley lines, supply routes
- Narrative (Weave): Graph-based story threads, nodes, connections
- Game State: Phase/turn management, undo/redo, snapshots
veilborn-strategy#
Five interconnected strategy game modes:
- Veil War: Tri-planar territory control (foundation)
- Resonance Wars: Poker-like simultaneous action combat
- Eternal Game: Go-like influence projection
- Echoes of Fate: Temporal reasoning with prophecies
- Weave Conspiracy: Social deduction with hidden agendas
Plus sophisticated AI systems:
- 5 difficulty tiers (Novice → Grandmaster)
- 5 personality types (Aggressive, Defensive, etc.)
- Balance testing framework with tournaments
2. Migration Mapping#
Entity Mapping#
| Veilborn | Hathor |
|---|---|
| Character | Entity (type: character) |
| Faction | Entity (type: faction) |
| Territory | Entity (type: location) |
| Weave Thread | Story Arc |
| Weave Node | Story Beat / Event Entity |
| Game Session | World Version |
| Campaign | World |
System Mapping#
| Veilborn System | Hathor Integration |
|---|---|
| Combat | Scenario Simulation Worker |
| Territory Control | Politics Simulation Worker |
| Weave Graph | Narrative API (Story Graphs) |
| AI Opponents | Simulation Parameters |
| Balance Testing | Batch Job Processing |
3. Phased Migration Plan#
Phase 1: Data Foundation (Weeks 1-2)#
- Create Hathor entity schemas for Veilborn data
- Build character → entity migration scripts
- Build faction → entity migration scripts
- Build territory → location migration scripts
- Implement resonance system as entity properties
- Create database migration tools with rollback
Phase 2: Narrative System (Weeks 2-3)#
- Map Weave threads to Hathor story arcs
- Map Weave nodes to story beats/events
- Implement quest objective mapping
- Create dialogue tree integration
- Build trigger/effect system for beats
Phase 3: Simulation Workers (Weeks 3-5)#
- Create VeilWarScenarioWorker
- Create ResonanceWarsWorker
- Create EternalGameWorker
- Create EchoesOfFateWorker (temporal)
- Create WeaveConspiracyWorker
- Implement difficulty parameter system
- Add simulation output processors
Phase 4: AI System (Weeks 4-5)#
- Port difficulty tiers to simulation parameters
- Migrate personality system
- Implement AI decision logging
- Build AI tournament system as batch jobs
- Create pattern tracking on aggregated results
Phase 5: Testing & Validation (Week 6)#
- Data integrity validation
- Replay recorded game sessions
- AI behavior consistency tests
- Performance benchmarking
- Migration rollback testing
4. Technical Details#
Character Entity Schema#
typescript
// Hathor Entity for Veilborn Character
{
type: 'character',
name: string,
properties: {
path: PathName,
resonance: {
clarity: number,
flow: number,
presence: number,
root: number,
void: number
},
stats: {
vitality: number,
will: number,
presence: number,
instinct: number,
attunement: number,
cognition: number
},
veilPoints: number,
level: number,
experience: number
}
}
Territory as Location Entity#
typescript
{
type: 'location',
name: string,
properties: {
territoryType: 'heartland' | 'borderland' | 'wasteland' | 'sacred_site' | 'nexus',
position: { x: number, y: number },
control: {
material: { faction: string, strength: number },
resonance: { faction: string, strength: number },
void: { faction: string, strength: number }
},
supplyStatus: 'supplied' | 'foraging' | 'starving',
leyLineType?: 'minor' | 'major' | 'primal' | 'confluence'
}
}
Veil War Simulation Job#
typescript
{
type: 'scenario',
subtype: 'veil_war',
input: {
territories: Territory[],
armies: Army[],
supplyRoutes: SupplyRoute[],
aiParams: {
evaluationDepth: number,
randomnessFactor: number,
mistakeChance: number,
planningHorizon: number
}
},
tickInterval: 'day',
snapshotInterval: 1
}
5. Risk Mitigation#
| Risk | Mitigation |
|---|---|
| State explosion | Snapshot intervals, worker limits |
| AI consistency | Deterministic RNG with seeds |
| Performance degradation | Spatial indexing, incremental updates |
| Weave complexity | Arc/beat hierarchy, lazy loading |
| Migration failures | Dual-write validation, rollback |
6. Success Criteria#
Must-Have#
- All character data migrated with stat integrity
- All faction/territory data accessible via Hathor APIs
- Weave system functional in story graphs
- Simulation workers process game mode logic
- AI personality system preserved
Should-Have#
- Balance testing pipeline automated
- Real-time multiplayer via Hathor
- Performance matching original
- Complete audit trail
Nice-to-Have#
- Enhanced territory visualization
- Expanded balance metrics
- Advanced AI analytics
7. Dependencies#
Required Before Migration#
- Hathor Database Schema complete ✓
- Hathor Client SDK complete ✓
- Hathor Sophia Integration complete ✓
- Simulation Worker infrastructure ✓
External Dependencies#
- PostgreSQL database provisioned
- Worker queue (Redis/Bull) configured
- Monitoring/alerting in place
Conclusion#
The Veilborn game engine represents a substantial codebase (76K LOC) with sophisticated mechanics that map well to Hathor's architecture. The migration will:
- Preserve all game mechanics and data
- Enable version-controlled world states
- Provide scalable simulation infrastructure
- Support AI-driven automated balance testing
- Integrate with Hathor's narrative system
Estimated timeline: 10-12 weeks with dedicated development effort.