Building applications with the Veilborn Chronicles SDK.
This guide covers advanced SDK usage, architecture patterns, and best practices.
SDK Architecture#
Module Structure#
text
@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 For integration examples, see Integration Guide