Complete reference documentation for the Veilborn Chronicles game engine.
This document provides comprehensive API documentation for the Veilborn Chronicles tabletop RPG system.
Table of Contents#
- Overview
- Core Types
- Character Creation API
- Combat System API
- Abilities API
- Game State API
- Multiplayer API
Overview#
The Veilborn Chronicles engine is built as a modular TypeScript/JavaScript library providing:
- Character Creation: Template-based character generation with point-buy systems
- Combat System: Hex-grid tactical combat with Tide initiative
- Abilities: Status effects, cooldowns, channeling, and environmental hazards
- Game State: Session management with undo/redo and synchronization
- Multiplayer: Real-time WebSocket-based multiplayer support
Installation#
npm install @veilborn/core
Basic Import#
import {
createCharacterFromTemplate,
CombatManager,
MultiplayerService,
GameStateManager,
} from '@veilborn/core';
Core Types#
Resonance Types#
The five fundamental Resonances that define Veilborn abilities:
type ResonanceType = 'clarity' | 'flow' | 'presence' | 'root' | 'void';
| Resonance | Domain | Description |
|---|---|---|
clarity |
Perception, Truth | Seeing through illusion, understanding |
flow |
Change, Time | Transformation, probability, destiny |
presence |
Will, Spirit | Emotional influence, leadership |
root |
Stability, Matter | Physical endurance, grounding |
void |
Emptiness, Shadow | Boundaries, dissolution, stealth |
Path Names#
The twelve character Paths:
type PathName =
| 'seer'
| 'sage'
| 'oracle' // Clarity Paths
| 'weaver'
| 'herald' // Flow Paths
| 'champion'
| 'exemplar' // Presence Paths
| 'guardian'
| 'warden' // Root Paths
| 'shadow'
| 'mystic'
| 'harbinger'; // Void Paths
Character Interface#
interface Character {
id: string;
name: string;
path: PathName;
awakening: string;
level: number;
experience: number;
resonances: Record<ResonanceType, number>;
derivedStats: DerivedStats;
abilities: Ability[];
inventory: Item[];
background: Background;
notes: string;
createdAt: string;
updatedAt: string;
}
Derived Stats#
interface DerivedStats {
health: { current: number; max: number };
veilPoints: { current: number; max: number };
defense: number;
initiative: number;
movement: number;
resonancePool: number;
}
Character Creation API#
createCharacterFromTemplate()#
Creates a new character using the template-based system.
function createCharacterFromTemplate(template: CharacterTemplate): Character;
Parameters:
template: Configuration object for the new character
Returns: Complete Character object
Example:
const character = createCharacterFromTemplate({
name: 'Kelis the Wanderer',
path: 'weaver',
awakening: 'thread_dancer',
resonanceAllocation: {
clarity: 5,
flow: 7,
presence: 4,
root: 3,
void: 6,
},
backgroundChoice: 'wanderer',
startingAbilities: ['probability_shift', 'thread_sight'],
});
validateCharacter()#
Validates a character against game rules.
function validateCharacter(character: Character): ValidationResult;
interface ValidationResult {
valid: boolean;
errors: string[];
warnings: string[];
}
levelUpCharacter()#
Advances a character by one level.
function levelUpCharacter(
character: Character,
choices: LevelUpChoices
): Character;
Point-Buy System#
Characters have 25 points to distribute among Resonances:
| Resonance Value | Cost |
|---|---|
| 1-3 | 1 point each |
| 4-5 | 2 points each |
| 6-7 | 3 points each |
| 8+ | 4 points each |
Constraints:
- Minimum: 1 in each Resonance
- Maximum: 8 (before Path bonuses)
- Primary Resonance: +2 bonus from Path
- Secondary Resonance: +1 bonus from Path
Combat System API#
Hex Coordinates#
The combat system uses a hex grid with axial coordinates:
interface HexCoord {
q: number; // Column
r: number; // Row
}
Hex Utility Functions#
// Calculate distance between two hexes
function hexDistance(a: HexCoord, b: HexCoord): number;
// Get six neighboring hexes
function hexNeighbors(hex: HexCoord): HexCoord[];
// Get all hexes within radius (spiral)
function hexSpiral(center: HexCoord, radius: number): HexCoord[];
// Get hexes at exact distance (ring)
function hexRing(center: HexCoord, radius: number): HexCoord[];
// Get hexes in a line between two points
function hexLine(start: HexCoord, end: HexCoord): HexCoord[];
// Convert hex to unique string key
function hexKey(hex: HexCoord): string;
CombatManager Class#
Main class for managing combat encounters.
class CombatManager {
constructor(config?: CombatConfig);
// Combatant Management
addCombatant(combatant: Combatant): void;
removeCombatant(id: string): void;
getCombatant(id: string): Combatant | undefined;
// Initiative and Turns
startCombat(): void;
endCombat(): void;
getCurrentTurn(): string | null;
advanceTurn(): void;
// Movement
moveCombatant(id: string, path: HexCoord[]): MoveResult;
getValidMoves(id: string): HexCoord[];
// Actions
performAction(action: CombatAction): ActionResult;
getAvailableActions(id: string): CombatAction[];
}
Combatant Interface#
interface Combatant {
id: string;
name: string;
team: 'player' | 'enemy' | 'neutral';
position: HexCoord;
stats: CombatStats;
conditions: StatusEffectInstance[];
actionsRemaining: number;
movementRemaining: number;
}
interface CombatStats {
health: number;
maxHealth: number;
defense: number;
attack: number;
movement: number;
initiative: number;
}
Tide Initiative System#
Initiative is determined by Tide levels:
type TideLevel = 'rising' | 'high' | 'falling' | 'low' | 'slack';
interface TideState {
level: TideLevel;
round: number;
momentum: number;
}
Tide Cycle:
- Rising - Flow-dominant characters act first
- High - Clarity and Presence excel
- Falling - Root-dominant characters shine
- Low - Void abilities are strongest
- Slack - Normal initiative order
Terrain System#
type TerrainType =
| 'open' // Normal movement
| 'difficult' // Costs 2 movement
| 'water' // May require swimming
| 'elevation' // Height advantage
| 'void_touched' // Veil effects
| 'blocked'; // Impassable
interface TerrainHex {
coord: HexCoord;
terrain: TerrainType;
elevation: number;
cover: number; // 0-100
effects: string[];
}
Abilities API#
Targeting System#
type TargetingType =
| 'self'
| 'single_ally'
| 'single_enemy'
| 'single_any'
| 'area_burst'
| 'area_cone'
| 'area_line'
| 'area_ring'
| 'terrain'
| 'direction'
| 'none';
interface TargetingParams {
type: TargetingType;
range: number;
areaSize?: number;
areaShape?: AreaShape;
filter: TargetFilter;
coneAngle?: number;
}
Area-of-Effect Functions#
// Circular burst area
function getBurstArea(center: HexCoord, radius: number): HexCoord[];
// Line from start to end
function getLineArea(
start: HexCoord,
end: HexCoord,
width?: number
): HexCoord[];
// Cone in direction
function getConeArea(
origin: HexCoord,
direction: HexCoord,
range: number,
angle?: number
): HexCoord[];
// Ring at specific radius
function getRingArea(center: HexCoord, radius: number): HexCoord[];
// Cross pattern
function getCrossArea(center: HexCoord, length: number): HexCoord[];
// Wave pattern
function getWaveArea(
origin: HexCoord,
direction: HexCoord,
range: number,
width: number
): HexCoord[];
Status Effects#
type EffectCategory =
| 'buff'
| 'debuff'
| 'damage_over_time'
| 'heal_over_time'
| 'control'
| 'movement'
| 'special';
interface StatusEffectDef {
id: string;
name: string;
description: string;
category: EffectCategory;
duration: number; // -1 for permanent
stackingBehavior: StackingBehavior;
maxStacks: number;
ticksPerRound: number;
statModifiers: StatModifier[];
damagePerTick?: number;
healingPerTick?: number;
preventsMovement?: boolean;
preventsActions?: boolean;
isInvisible?: boolean;
}
Standard Effects#
| Effect | Category | Duration | Description |
|---|---|---|---|
blessed |
buff | 3 rounds | +2 to all rolls |
haste |
buff | 3 rounds | +2 movement, +5 initiative |
weakened |
debuff | 3 rounds | -2 attack per stack |
stunned |
control | 1 round | Cannot act or react |
burning |
DoT | 3 rounds | 2 damage per tick |
poisoned |
DoT | 5 rounds | 1 damage per tick |
invisible |
special | 3 rounds | Cannot be seen |
Status Effect Functions#
// Apply effect to target
function applyStatusEffect(
effects: StatusEffectInstance[],
def: StatusEffectDef,
sourceId: string,
targetId: string,
currentRound: number
): StatusEffectInstance[];
// Remove effect
function removeStatusEffect(
effects: StatusEffectInstance[],
effectId: string,
targetId: string
): StatusEffectInstance[];
// Process end-of-round ticks
function tickEffects(
effects: StatusEffectInstance[],
currentRound: number,
definitions: Map<string, StatusEffectDef>
): { effects: StatusEffectInstance[]; ticks: TickResult[] };
// Check if target has effect
function hasEffect(
effects: StatusEffectInstance[],
effectId: string,
targetId: string
): boolean;
Ability Definitions#
interface AbilityDef {
id: string;
name: string;
description: string;
targeting: TargetingParams;
cost: AbilityCost;
tideCost: number;
cooldownType: CooldownType;
cooldownDuration: number;
maxCharges: number;
damage?: DamageSpec;
healing?: HealingSpec;
statusEffects: StatusEffectApplication[];
isChanneled: boolean;
canBeInterrupted: boolean;
requiredPath?: string;
}
Environmental Effects#
interface EnvironmentalEffect {
id: string;
name: string;
hexes: HexCoord[];
hazardType?: HazardType;
onEnter?: TriggerEffect;
onExit?: TriggerEffect;
onStartTurn?: TriggerEffect;
onEndTurn?: TriggerEffect;
duration: number;
spreads?: boolean;
spreadChance?: number;
blocksLOS?: boolean;
providesConcealment?: number;
}
Game State API#
GameStateManager Class#
Central manager for game session state.
class GameStateManager {
constructor(initialSession: GameSession);
// State Access
getSession(): GameSession;
getVersion(): number;
// State Updates
update(
updater: (session: GameSession) => GameSession,
changeType: StateChangeType,
changeData?: Record<string, unknown>
): ValidationResult;
// Actions
applyAction(
action: GameAction,
result?: Record<string, unknown>
): ValidationResult;
// Undo/Redo
undo(): boolean;
redo(): boolean;
canUndo(): boolean;
canRedo(): boolean;
// Subscriptions
subscribe(listener: StateChangeListener): () => void;
}
Session Management#
// Create new session
function createGameSession(
name: string,
mode: GameMode,
gmUserId: string
): GameSession;
// Validate session
function validateSession(session: GameSession): ValidationResult;
// Serialize/Deserialize
function serializeSession(session: GameSession): string;
function deserializeSession(json: string): GameSession;
Player Management#
// Add player to session
function addPlayer(
session: GameSession,
userId: string,
role?: PlayerRole
): { session: GameSession; player: Player } | { error: string };
// Remove player
function removePlayer(session: GameSession, playerId: string): GameSession;
// Update player status
function updatePlayer(
session: GameSession,
playerId: string,
updates: Partial<Player>
): GameSession;
// Assign character to player
function assignCharacter(
session: GameSession,
playerId: string,
character: Character
): GameSession;
Phase Management#
// Start the game
function startGame(session: GameSession): GameSession | { error: string };
// Change phase
function changePhase(session: GameSession, newPhase: GamePhase): GameSession;
// Advance turn
function advanceTurn(session: GameSession): GameSession;
// End game
function endGame(session: GameSession): GameSession;
Snapshots#
// Create snapshot
function createStateSnapshot(
session: GameSession,
description?: string
): StateSnapshot;
// Restore from snapshot
function restoreFromSnapshot(snapshot: StateSnapshot): GameSession;
Multiplayer API#
MultiplayerService Class#
Main service for real-time multiplayer functionality.
class MultiplayerService {
constructor(config?: MultiplayerConfig);
// Room Management
createRoom(
hostId: string,
hostName: string,
roomName: string,
config?: Partial<RoomConfig>
): Room;
joinRoom(
roomCode: string,
playerId: string,
playerName: string,
asSpectator?: boolean,
password?: string
): { success: boolean; room?: Room; error?: string };
leaveRoom(roomId: string, playerId: string): boolean;
// Game Control
startGame(roomId: string, initialState?: Partial<GameState>): boolean;
submitAction(
roomId: string,
playerId: string,
type: string,
data: unknown
): GameAction | null;
endTurn(roomId: string, playerId: string): boolean;
// Communication
sendChat(
roomId: string,
senderId: string,
senderName: string,
content: string,
channel?: ChatChannel,
targetId?: string
): ChatMessage | { error: string };
rollDice(
roomId: string,
playerId: string,
playerName: string,
notation: string,
reason?: string,
isPrivate?: boolean
): DiceRoll | { error: string };
sendEmote(
roomId: string,
playerId: string,
playerName: string,
emoteType: string
): Emote | { error: string };
// Statistics
getStats(): MultiplayerStats;
}
Room Configuration#
interface RoomConfig {
maxPlayers: number; // Default: 6
allowSpectators: boolean; // Default: true
isPrivate: boolean; // Default: false
password?: string;
turnTimeLimit?: number; // In milliseconds
autoSave: boolean; // Default: true
replayEnabled: boolean; // Default: true
}
Connection Management#
class ConnectionManager {
addConnection(playerId: string, socket: WebSocket): void;
removeConnection(playerId: string): void;
getConnection(playerId: string): WebSocket | undefined;
getConnectedPlayers(): string[];
sendToPlayer(playerId: string, message: Message): boolean;
broadcast(message: Message, excludeIds?: string[]): number;
getAverageLatency(playerId: string): number;
}
State Synchronization#
class StateSyncManager {
initializeState(roomId: string, initialState: GameState): void;
getCurrentState(roomId: string): GameState | null;
applyAction(roomId: string, action: GameAction): GameState | null;
calculateDelta(
roomId: string,
fromVersion: number,
toVersion: number
): StateDelta | null;
applyDelta(state: GameState, delta: StateDelta): GameState;
}
Turn Management#
class TurnManager {
initializeTurnOrder(roomId: string, playerIds: string[]): void;
getCurrentPlayer(roomId: string): string | null;
advanceTurn(roomId: string): string | null;
startTurnTimer(roomId: string, timeLimit: number): void;
clearTurnTimer(roomId: string): void;
getRemainingTime(roomId: string, timeLimit: number): number;
isPlayerTurn(roomId: string, playerId: string): boolean;
}
Chat System#
class ChatManager {
sendMessage(
roomId: string,
senderId: string,
senderName: string,
content: string,
channel?: 'global' | 'party' | 'whisper',
targetId?: string
): ChatMessage | { error: string };
getChatHistory(roomId: string, limit?: number): ChatMessage[];
getMessagesForPlayer(roomId: string, playerId: string): ChatMessage[];
clearHistory(roomId: string): void;
}
Dice Rolling#
class DiceRollManager {
roll(
roomId: string,
playerId: string,
playerName: string,
diceNotation: string, // e.g., "2d6+3", "1d20-1"
reason?: string,
isPrivate?: boolean
): DiceRoll | { error: string };
getRollHistory(
roomId: string,
includePrivate?: boolean,
playerId?: string
): DiceRoll[];
parseDiceNotation(
notation: string
): { count: number; sides: number; modifier: number } | null;
}
Replay System#
class ReplayManager {
startRecording(roomId: string): void;
stopRecording(roomId: string): ReplayEvent[];
isRoomRecording(roomId: string): boolean;
recordEvent(roomId: string, type: ReplayEventType, data: unknown): void;
getRecording(roomId: string): ReplayEvent[];
getEventsInRange(
roomId: string,
startSeq: number,
endSeq: number
): ReplayEvent[];
}
Spectator Mode#
class SpectatorManager {
addSpectator(roomId: string, spectatorId: string): void;
removeSpectator(roomId: string, spectatorId: string): void;
getSpectators(roomId: string): string[];
getSpectatorCount(roomId: string): number;
isSpectator(roomId: string, playerId: string): boolean;
setSpectatorDelay(roomId: string, delayMs: number): void;
getSpectatorDelay(roomId: string): number;
}
Error Handling#
All API functions follow consistent error handling patterns:
Validation Results#
interface ValidationResult {
valid: boolean;
errors: string[]; // Critical issues that prevent operation
warnings: string[]; // Non-critical issues that may cause problems
}
Error Responses#
Functions that can fail return union types:
// Success or error
type Result<T> = T | { error: string };
// Example usage
const result = addPlayer(session, userId);
if ('error' in result) {
console.error(result.error);
} else {
console.log('Player added:', result.player);
}
Constants#
Game Limits#
const MAX_PLAYERS = 12;
const MAX_HISTORY_SIZE = 1000;
const MAX_UNDO_DEPTH = 50;
const MAX_ROOMS = 1000;
const DEFAULT_TURN_TIME_LIMIT = 120000; // 2 minutes
const DEFAULT_SPECTATOR_DELAY = 5000; // 5 seconds
Game Phases#
const GAME_PHASES: GamePhase[] = ['setup', 'playing', 'paused', 'completed'];
const PLAYER_ROLES: PlayerRole[] = ['player', 'gm', 'observer'];
const GAME_MODES: GameMode[] = ['rpg', 'wargame', 'hybrid'];
For integration guides and code examples, see Integration Guide For OpenAPI specifications, see OpenAPI Spec