# Veilborn Chronicles SDK Guide

> _Building applications with the Veilborn Chronicles SDK._

This guide covers advanced SDK usage, architecture patterns, and best practices.

---

## SDK Architecture

### Module Structure

```
@veilborn/core
├── character/          # Character creation and management
│   ├── templates       # Character templates
│   ├── validation      # Validation rules
│   └── leveling        # Progression system
├── combat/             # Combat system
│   ├── hex             # Hex grid utilities
│   ├── initiative      # Tide initiative
│   └── actions         # Combat actions
├── abilities/          # Ability system
│   ├── targeting       # Targeting patterns
│   ├── effects         # Status effects
│   └── environmental   # Environmental hazards
├── state/              # Game state management
│   ├── session         # Session lifecycle
│   ├── undo            # Undo/redo system
│   └── sync            # State synchronization
├── multiplayer/        # Multiplayer features
│   ├── rooms           # Room management
│   ├── connections     # WebSocket handling
│   └── communication   # Chat, dice, emotes
├── paths/              # Path definitions
└── types/              # TypeScript definitions
```

### Import Patterns

```typescript
// Import everything
import * as Veilborn from '@veilborn/core';

// Import specific modules
import { createCharacterFromTemplate } from '@veilborn/core/character';
import { CombatManager, hexDistance } from '@veilborn/core/combat';
import { MultiplayerService } from '@veilborn/core/multiplayer';

// Import types
import type {
  Character,
  GameSession,
  HexCoord,
  PathName,
} from '@veilborn/core/types';
```

---

## Type System

### Core Interfaces

```typescript
// Character types
interface Character {
  id: string;
  name: string;
  path: PathName;
  awakening: string;
  level: number;
  experience: number;
  resonances: ResonanceValues;
  derivedStats: DerivedStats;
  abilities: Ability[];
  inventory: Item[];
  background: Background;
  notes: string;
  createdAt: string;
  updatedAt: string;
}

interface ResonanceValues {
  clarity: number;
  flow: number;
  presence: number;
  root: number;
  void: number;
}

interface DerivedStats {
  health: ResourcePool;
  veilPoints: ResourcePool;
  defense: number;
  initiative: number;
  movement: number;
  resonancePool: number;
}

interface ResourcePool {
  current: number;
  max: number;
}
```

### Combat Types

```typescript
interface Combatant {
  id: string;
  name: string;
  team: Team;
  position: HexCoord;
  stats: CombatStats;
  conditions: StatusEffectInstance[];
  actionsRemaining: number;
  movementRemaining: number;
}

interface HexCoord {
  q: number; // Column (axial coordinate)
  r: number; // Row (axial coordinate)
}

type Team = 'player' | 'enemy' | 'neutral';

interface CombatStats {
  health: number;
  maxHealth: number;
  defense: number;
  attack: number;
  movement: number;
  initiative: number;
}
```

### Session Types

```typescript
interface GameSession {
  id: string;
  name: string;
  mode: GameMode;
  players: Player[];
  state: GameState;
  weave: WeaveState;
  createdAt: string;
  updatedAt: string;
}

interface GameState {
  phase: GamePhase;
  round: number;
  turn: number;
  activePlayerId: string | null;
  history: GameAction[];
}

type GamePhase = 'setup' | 'playing' | 'paused' | 'completed';
type GameMode = 'rpg' | 'wargame' | 'hybrid';
```

### Multiplayer Types

```typescript
interface Room {
  id: string;
  code: string;
  name: string;
  hostId: string;
  players: Map<string, Player>;
  config: RoomConfig;
  gameState: MultiplayerGameState | null;
  createdAt: string;
  updatedAt: string;
  status: RoomStatus;
}

interface RoomConfig {
  maxPlayers: number;
  allowSpectators: boolean;
  isPrivate: boolean;
  password?: string;
  turnTimeLimit?: number;
  autoSave: boolean;
  replayEnabled: boolean;
}

type RoomStatus = 'lobby' | 'playing' | 'paused' | 'ended';
```

---

## Factory Functions

### Character Factory

```typescript
import { CharacterFactory } from '@veilborn/core';

const factory = new CharacterFactory();

// Create from template
const character = factory.create({
  name: 'Kelis',
  path: 'weaver',
  awakening: 'probability_touched',
  resonanceAllocation: { clarity: 5, flow: 7, presence: 4, root: 3, void: 6 },
  backgroundChoice: 'gambler',
  startingAbilities: ['probability_shift', 'thread_sight'],
});

// Create quick character for testing
const testChar = factory.createQuick('Test Hero', 'champion');

// Create from saved data
const loaded = factory.fromJSON(savedCharacterJson);

// Clone with modifications
const clone = factory.clone(character, { name: 'Kelis Clone' });
```

### Combat Factory

```typescript
import { CombatFactory } from '@veilborn/core';

const combat = CombatFactory.create({
  gridSize: { width: 20, height: 15 },
  terrain: generateTerrain(),
  tideEnabled: true,
  environmentalEffects: [],
});

// Create combatant from character
const combatant = CombatFactory.combatantFromCharacter(
  character,
  { q: 5, r: 5 },
  'player'
);

// Create enemy from template
const enemy = CombatFactory.combatantFromTemplate('rift_hound', {
  q: 10,
  r: 8,
});
```

### Session Factory

```typescript
import { SessionFactory } from '@veilborn/core';

// Create new campaign
const session = SessionFactory.createCampaign(
  'The Veiled Conspiracy',
  'gm-user-id',
  { mode: 'rpg' }
);

// Create one-shot
const oneShot = SessionFactory.createOneShot('Quick Adventure', 'gm-user-id');

// Load from save
const loaded = SessionFactory.load(savedSessionJson);
```

---

## Builder Pattern

### Character Builder

```typescript
import { CharacterBuilder } from '@veilborn/core';

const character = new CharacterBuilder()
  .name('Kelis the Wanderer')
  .path('weaver')
  .awakening('probability_touched')
  .resonance('clarity', 5)
  .resonance('flow', 7)
  .resonance('presence', 4)
  .resonance('root', 3)
  .resonance('void', 6)
  .background('gambler')
  .ability('probability_shift')
  .ability('thread_sight')
  .item('deck_of_fate')
  .note('Traveling merchant with a mysterious past')
  .build();
```

### Combat Builder

```typescript
import { CombatBuilder } from '@veilborn/core';

const combat = new CombatBuilder()
  .grid(20, 15)
  .terrain([
    { coord: { q: 5, r: 5 }, type: 'difficult' },
    { coord: { q: 10, r: 10 }, type: 'elevation', height: 2 },
  ])
  .combatant({
    id: 'player-1',
    name: 'Hero',
    team: 'player',
    position: { q: 2, r: 2 },
    stats: defaultPlayerStats,
  })
  .combatant({
    id: 'enemy-1',
    name: 'Rift Hound',
    team: 'enemy',
    position: { q: 15, r: 10 },
    stats: riftHoundStats,
  })
  .environmentalEffect({
    id: 'fire-zone',
    name: 'Burning Ground',
    hexes: [
      { q: 8, r: 8 },
      { q: 9, r: 8 },
    ],
    onEnter: { damage: 2, statusEffect: 'burning' },
  })
  .enableTide()
  .build();
```

---

## Middleware Pattern

### Action Middleware

```typescript
import { CombatManager, ActionMiddleware } from '@veilborn/core';

// Logging middleware
const loggingMiddleware: ActionMiddleware = (action, next) => {
  console.log(`Action: ${action.type}`, action);
  const result = next(action);
  console.log(`Result:`, result);
  return result;
};

// Validation middleware
const validationMiddleware: ActionMiddleware = (action, next) => {
  const validation = validateAction(action);
  if (!validation.valid) {
    return { success: false, error: validation.errors.join(', ') };
  }
  return next(action);
};

// Animation middleware
const animationMiddleware: ActionMiddleware = async (action, next) => {
  const result = next(action);
  await playAnimation(action.type, action);
  return result;
};

// Apply middleware
const combat = new CombatManager({
  middleware: [loggingMiddleware, validationMiddleware, animationMiddleware],
});
```

### State Middleware

```typescript
import { GameStateManager, StateMiddleware } from '@veilborn/core';

// Autosave middleware
const autosaveMiddleware: StateMiddleware = (session, changeType, next) => {
  const result = next(session, changeType);
  if (result.valid) {
    scheduleAutosave(result.session);
  }
  return result;
};

// Analytics middleware
const analyticsMiddleware: StateMiddleware = (session, changeType, next) => {
  const result = next(session, changeType);
  trackEvent('state_change', { type: changeType });
  return result;
};

const stateManager = new GameStateManager(session, {
  middleware: [autosaveMiddleware, analyticsMiddleware],
});
```

---

## Plugin System

### Creating Plugins

```typescript
import { VeilbornPlugin, PluginContext } from '@veilborn/core';

interface MyPluginConfig {
  enableFeature: boolean;
  customOption: string;
}

const myPlugin: VeilbornPlugin<MyPluginConfig> = {
  name: 'my-plugin',
  version: '1.0.0',

  install(context: PluginContext, config: MyPluginConfig) {
    // Register custom abilities
    context.abilities.register({
      id: 'custom_ability',
      name: 'Custom Ability',
      // ... ability definition
    });

    // Register custom effects
    context.effects.register({
      id: 'custom_effect',
      name: 'Custom Effect',
      // ... effect definition
    });

    // Hook into events
    context.events.on('combat:start', (combat) => {
      console.log('Combat started with plugin');
    });

    // Add middleware
    context.middleware.add('action', (action, next) => {
      // Custom action processing
      return next(action);
    });
  },

  uninstall(context: PluginContext) {
    // Cleanup
  },
};

// Use the plugin
import { Veilborn } from '@veilborn/core';

const game = new Veilborn({
  plugins: [[myPlugin, { enableFeature: true, customOption: 'value' }]],
});
```

### Built-in Plugins

```typescript
import {
  DiceRollerPlugin,
  AnimationPlugin,
  SoundPlugin,
  PersistencePlugin,
} from '@veilborn/core/plugins';

const game = new Veilborn({
  plugins: [
    [DiceRollerPlugin, { animation: true }],
    [AnimationPlugin, { duration: 500 }],
    [SoundPlugin, { volume: 0.5 }],
    [PersistencePlugin, { storage: 'localStorage', key: 'veilborn' }],
  ],
});
```

---

## Event System

### Event Types

```typescript
// Character events
type CharacterEvents = {
  'character:created': (character: Character) => void;
  'character:levelup': (character: Character, newLevel: number) => void;
  'character:abilityGained': (character: Character, ability: Ability) => void;
  'character:damaged': (
    character: Character,
    amount: number,
    source: string
  ) => void;
  'character:healed': (
    character: Character,
    amount: number,
    source: string
  ) => void;
};

// Combat events
type CombatEvents = {
  'combat:start': (combatants: Combatant[]) => void;
  'combat:end': (winner: Team | null) => void;
  'combat:turnStart': (combatant: Combatant) => void;
  'combat:turnEnd': (combatant: Combatant) => void;
  'combat:action': (action: CombatAction, result: ActionResult) => void;
  'combat:movement': (
    combatant: Combatant,
    from: HexCoord,
    to: HexCoord
  ) => void;
  'combat:effectApplied': (
    target: Combatant,
    effect: StatusEffectInstance
  ) => void;
  'combat:effectRemoved': (target: Combatant, effectId: string) => void;
};

// Session events
type SessionEvents = {
  'session:created': (session: GameSession) => void;
  'session:phaseChanged': (session: GameSession, newPhase: GamePhase) => void;
  'session:playerJoined': (session: GameSession, player: Player) => void;
  'session:playerLeft': (session: GameSession, playerId: string) => void;
  'session:saved': (session: GameSession) => void;
  'session:loaded': (session: GameSession) => void;
};
```

### Event Handling

```typescript
import { EventEmitter } from '@veilborn/core';

const events = new EventEmitter<CombatEvents>();

// Subscribe to events
events.on('combat:start', (combatants) => {
  console.log(`Combat started with ${combatants.length} combatants`);
});

events.on('combat:action', (action, result) => {
  if (result.damage) {
    playDamageAnimation(action.targetId, result.damage);
  }
});

// One-time listener
events.once('combat:end', (winner) => {
  showVictoryScreen(winner);
});

// Remove listener
const unsubscribe = events.on('combat:turnStart', handleTurnStart);
// Later...
unsubscribe();

// Emit events
events.emit('combat:start', [combatant1, combatant2]);
```

---

## Serialization

### Custom Serializers

```typescript
import { Serializer, registerSerializer } from '@veilborn/core';

// Custom date serializer
registerSerializer('Date', {
  serialize: (date: Date) => date.toISOString(),
  deserialize: (str: string) => new Date(str),
});

// Custom Map serializer
registerSerializer('Map', {
  serialize: (map: Map<any, any>) => Array.from(map.entries()),
  deserialize: (entries: [any, any][]) => new Map(entries),
});

// Use with session
const json = Serializer.stringify(session);
const loaded = Serializer.parse<GameSession>(json);
```

### Version Migration

```typescript
import { Migrator, Migration } from '@veilborn/core';

const migrations: Migration[] = [
  {
    version: 2,
    up: (data) => {
      // Add new field
      data.characters.forEach((c) => {
        c.newField = 'default';
      });
      return data;
    },
    down: (data) => {
      // Remove field
      data.characters.forEach((c) => {
        delete c.newField;
      });
      return data;
    },
  },
  {
    version: 3,
    up: (data) => {
      // Rename field
      data.characters.forEach((c) => {
        c.resonanceValues = c.resonances;
        delete c.resonances;
      });
      return data;
    },
  },
];

const migrator = new Migrator(migrations);

// Migrate old save data
const oldSave = loadOldSave(); // version 1
const migrated = migrator.migrate(oldSave, 3);
```

---

## Performance Optimization

### Object Pooling

```typescript
import { ObjectPool } from '@veilborn/core';

// Create pool for hex coordinates
const hexPool = new ObjectPool<HexCoord>(
  () => ({ q: 0, r: 0 }), // Factory
  (hex) => {
    hex.q = 0;
    hex.r = 0;
  }, // Reset
  100 // Initial size
);

// Use pooled objects
const hex = hexPool.acquire();
hex.q = 5;
hex.r = 10;
// ... use hex
hexPool.release(hex);

// Batch operations
const hexes = hexPool.acquireMultiple(50);
// ... use hexes
hexPool.releaseMultiple(hexes);
```

### Memoization

```typescript
import { memoize, memoizeWithExpiry } from '@veilborn/core';

// Simple memoization
const getPathAbilities = memoize((pathName: PathName) => {
  return PATHS[pathName].abilities;
});

// Memoization with expiry
const getValidMoves = memoizeWithExpiry(
  (combatantId: string, position: HexCoord) => {
    return calculateValidMoves(combatantId, position);
  },
  5000 // 5 second cache
);

// Clear cache
getValidMoves.clear();
```

### Lazy Loading

```typescript
import { lazy, LazyModule } from '@veilborn/core';

// Lazy load heavy modules
const combatModule = lazy(() => import('@veilborn/core/combat'));
const multiplayerModule = lazy(() => import('@veilborn/core/multiplayer'));

// Use when needed
async function startCombat() {
  const { CombatManager } = await combatModule();
  const combat = new CombatManager();
  // ...
}
```

---

## Testing Utilities

### Test Fixtures

```typescript
import { TestFixtures } from '@veilborn/core/testing';

// Create test character
const character = TestFixtures.character({
  path: 'seer',
  level: 5,
});

// Create test combat
const combat = TestFixtures.combat({
  playerCount: 2,
  enemyCount: 3,
});

// Create test session
const session = TestFixtures.session({
  playerCount: 4,
  phase: 'playing',
});

// Create test room
const room = TestFixtures.room({
  playerCount: 3,
  status: 'playing',
});
```

### Mock Services

```typescript
import { MockMultiplayerService, MockWebSocket } from '@veilborn/core/testing';

// Mock multiplayer for testing
const mockMultiplayer = new MockMultiplayerService();

// Simulate player joining
mockMultiplayer.simulateJoin('player-1', 'Test Player');

// Simulate action
mockMultiplayer.simulateAction('player-1', 'ability_use', {
  abilityId: 'fireball',
  targetHex: { q: 5, r: 5 },
});

// Simulate disconnection
mockMultiplayer.simulateDisconnect('player-1');
```

### Assertion Helpers

```typescript
import { expect } from 'vitest';
import { matchers } from '@veilborn/core/testing';

// Add custom matchers
expect.extend(matchers);

// Use custom matchers
expect(character).toBeValidCharacter();
expect(combat).toHaveActiveCombatant('player-1');
expect(session).toBeInPhase('playing');
expect(hex1).toBeAdjacentTo(hex2);
expect(ability).toTargetHexes([
  { q: 5, r: 5 },
  { q: 6, r: 5 },
]);
```

---

## Error Handling

### Error Types

```typescript
import {
  VeilbornError,
  ValidationError,
  CombatError,
  StateError,
  MultiplayerError,
} from '@veilborn/core';

try {
  createCharacter(invalidTemplate);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.errors);
  } else if (error instanceof CombatError) {
    console.error('Combat error:', error.message);
  } else if (error instanceof StateError) {
    console.error('State error:', error.message);
  } else if (error instanceof MultiplayerError) {
    console.error('Multiplayer error:', error.code, error.message);
  } else {
    throw error;
  }
}
```

### Error Recovery

```typescript
import { withRetry, withFallback, withTimeout } from '@veilborn/core';

// Retry on failure
const result = await withRetry(() => submitAction(action), {
  maxAttempts: 3,
  delay: 1000,
});

// Fallback on failure
const state = await withFallback(
  () => fetchRemoteState(),
  () => getLocalState()
);

// Timeout
const response = await withTimeout(
  () => longOperation(),
  5000,
  'Operation timed out'
);
```

---

## Best Practices

### 1. Immutable State

```typescript
// Good: Create new objects
function updateHealth(combatant: Combatant, delta: number): Combatant {
  return {
    ...combatant,
    stats: {
      ...combatant.stats,
      health: Math.max(0, combatant.stats.health + delta),
    },
  };
}

// Bad: Mutate existing objects
function updateHealthBad(combatant: Combatant, delta: number) {
  combatant.stats.health += delta; // Don't do this!
}
```

### 2. Type Safety

```typescript
// Good: Use strict types
function getPath(name: PathName): Path {
  return PATHS[name];
}

// Bad: Use any
function getPathBad(name: any) {
  return PATHS[name]; // No type checking!
}
```

### 3. Error Boundaries

```typescript
// Good: Handle errors gracefully
function performAction(action: CombatAction): ActionResult {
  const validation = validateAction(action);
  if (!validation.valid) {
    return { success: false, errors: validation.errors };
  }

  try {
    return executeAction(action);
  } catch (error) {
    return { success: false, error: error.message };
  }
}
```

### 4. Resource Cleanup

```typescript
// Good: Clean up subscriptions
const unsubscribe = stateManager.subscribe(handleChange);
// Later...
unsubscribe();

// Good: Clean up timers
const timer = turnManager.startTurnTimer(roomId, 60000);
// Later...
turnManager.clearTurnTimer(roomId);
```

---

_For API reference, see [API Reference](01-api-reference.md)_ _For integration
examples, see [Integration Guide](02-integration-guide.md)_
