Eve library

Veilborn Chronicles Migration to Hathor

Guide

Revision 1

On this page

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:

  1. Preserve all game mechanics and data
  2. Enable version-controlled world states
  3. Provide scalable simulation infrastructure
  4. Support AI-driven automated balance testing
  5. Integrate with Hathor's narrative system

Estimated timeline: 10-12 weeks with dedicated development effort.