playlist-data-engine 1.1.0

package/dist/core/combat/CombatEngine.d.ts

@@ -0,0 +1,388 @@
+/**
+ * CombatEngine - Main orchestrator for D&D 5e turn-based combat
+ * Manages combat lifecycle, turn order, and action resolution
+ */
+import type { CharacterSheet, Attack, Spell } from '../types/Character';
+import type { CombatInstance, Combatant, CombatAction, CombatConfig, CombatResult, DiceRollerAPI, StatusEffect } from '../types/Combat';
+import type { EnvironmentalContext } from '../types/Progression';
+/**
+ * Describes a single validation issue found in spell slot data.
+ */
+export interface SpellSlotValidationIssue {
+    /** Human-readable description of the issue */
+    message: string;
+    /** Which spell level is affected (1-9), or undefined if structural */
+    level?: number;
+    /** Severity: 'error' means data is unusable, 'warn' means data is questionable but usable */
+    severity: 'error' | 'warn';
+}
+/**
+ * D&D 5e turn-based combat engine
+ *
+ * Fully implements D&D 5e combat rules:
+ * - Initiative rolls (d20 + DEX modifier)
+ * - Attack rolls (d20 + attack bonus vs AC)
+ * - Damage calculation with dice rolling
+ * - Critical hits (natural 20 = double damage dice)
+ * - Spell casting with spell slots and saving throws
+ * - Environmental modifiers and music bonuses
+ * - Deterministic treasure generation using seeded RNG
+ */
+export declare class CombatEngine {
+    private initiativeRoller;
+    private attackResolver;
+    private spellCaster;
+    private config;
+    private rng;
+    private diceRoller?;
+    /**
+     * Initialize the combat engine with configuration options
+     *
+     * @param {CombatConfig} [config] - Combat configuration
+     * @param {boolean} [config.useEnvironment=true] - Apply environmental bonuses
+     * @param {boolean} [config.useMusic=false] - Apply music bonuses to combat
+     * @param {boolean} [config.tacticalMode=false] - Enable advanced tactical rules
+     * @param {number} [config.maxTurnsBeforeDraw=100] - Max turns before combat draws
+     * @param {boolean} [config.allowFleeing=false] - Allow combatants to flee
+     * @param {string} [config.seed] - Seed for deterministic treasure generation
+     * @param {DiceRollerAPI} [diceRoller] - Optional dice roller for deterministic simulations
+     *
+     * @example
+     * const combat = new CombatEngine({ tacticalMode: true, seed: 'my-seed' });
+     * const seeded = new CombatEngine({}, createSeededRoller('sim-42'));
+     */
+    constructor(config?: CombatConfig, diceRoller?: DiceRollerAPI);
+    /**
+     * Initialize a combat encounter with players vs enemies
+     *
+     * Sets up the combat instance, creates combatant objects, rolls initiative,
+     * and establishes turn order based on DEX modifiers and initiative rolls.
+     *
+     * @param {CharacterSheet[]} playerCharacters - Playable characters
+     * @param {CharacterSheet[]} enemies - Non-player characters/enemies
+     * @param {EnvironmentalContext} [environment] - Environmental modifiers (optional)
+     * @returns {CombatInstance} Active combat instance with established turn order
+     *
+     * @example
+     * const combat = combatEngine.startCombat(
+     *   [playerCharacter],
+     *   [enemy1, enemy2],
+     *   environmentalContext
+     * );
+     * console.log(`Combat started! Turn order: ${combat.combatants.map(c => c.character.name).join(' → ')}`);
+     */
+    startCombat(playerCharacters: CharacterSheet[], enemies: CharacterSheet[], environment?: EnvironmentalContext): CombatInstance;
+    /**
+     * Get the current active combatant
+     */
+    getCurrentCombatant(combat: CombatInstance): Combatant;
+    /**
+     * Execute an attack action
+     *
+     * Checks attacker and target status effects for advantage/disadvantage
+     * (e.g., Charmed → disadvantage vs non-source, Frightened → disadvantage,
+     * Prone target → advantage on melee/ranged).
+     */
+    executeAttack(combat: CombatInstance, attacker: Combatant, target: Combatant, attack: Attack): CombatAction;
+    /**
+     * Execute an attack using equipped weapon(s) or unarmed strike
+     *
+     * Automatically builds Attack object from equipped weapons or unarmed combat.
+     * Uses the first equipped weapon by default, or a specific weapon if named.
+     * If no weapon equipped or weaponName is "unarmed", uses unarmed strike.
+     *
+     * @param combat - Combat instance
+     * @param attacker - Attacking combatant
+     * @param target - Target combatant
+     * @param weaponName - Optional specific weapon name (if multiple equipped), or "unarmed" for unarmed strike
+     * @returns Combat action with result
+     *
+     * @example
+     * // Attack with first equipped weapon (or unarmed if none)
+     * combat.executeWeaponAttack(combat, attacker, target);
+     *
+     * // Attack with specific weapon
+     * combat.executeWeaponAttack(combat, attacker, target, 'Longsword');
+     *
+     * // Unarmed strike explicitly
+     * combat.executeWeaponAttack(combat, attacker, target, 'unarmed');
+     */
+    executeWeaponAttack(combat: CombatInstance, attacker: Combatant, target: Combatant, weaponName?: string): CombatAction;
+    /**
+     * Build an Attack object from a weapon
+     * Prefers damage_dice set during enemy generation (on the weapon object),
+     * falling back to DEFAULT_EQUIPMENT for player characters using standard gear.
+     * Uses character's stats to calculate attack bonus.
+     */
+    private buildAttackFromWeapon;
+    /**
+     * Build an unarmed strike Attack object
+     * D&D 5e: 1 + STR modifier damage, proficiency bonus applies to attack
+     */
+    private buildUnarmedAttack;
+    /**
+     * Execute a spell casting action
+     */
+    executeCastSpell(combat: CombatInstance, caster: Combatant, spell: Spell, targets: Combatant[]): CombatAction;
+    /**
+     * Execute a legendary action for a boss combatant.
+     *
+     * Legendary actions are special abilities that boss enemies can use at the end
+     * of another creature's turn, spending legendary action points (3 per round).
+     *
+     * Validates that the action exists on the boss's `legendary_config`, checks
+     * that enough action points remain, resolves damage if applicable, and records
+     * the action in combat history.
+     *
+     * @param combat - Combat instance
+     * @param bossCombatant - The boss combatant executing the legendary action
+     * @param action - The legendary action to execute (from `legendary_config.actions`)
+     * @param target - Optional target combatant for damaging/controlling actions
+     * @returns Combat action with result
+     * @throws {Error} If the combatant has no legendary config, the action doesn't
+     *                  belong to this boss, or not enough action points remain
+     */
+    executeLegendaryAction(combat: CombatInstance, bossCombatant: Combatant, action: {
+        id: string;
+        name: string;
+        cost: number;
+        effect: string;
+        damage?: string;
+        damage_type?: string;
+        description?: string;
+        tags?: string[];
+    }, target?: Combatant): CombatAction;
+    /**
+     * Use a legendary resistance to automatically succeed a saving throw.
+     *
+     * Per D&D 5e: If the boss fails a saving throw, it can choose to use one
+     * legendary resistance to succeed instead. This is a per-day resource
+     * (tracked by `legendaryResistancesRemaining` on the Combatant).
+     *
+     * @param combat - Combat instance (for history logging)
+     * @param bossCombatant - The boss combatant using the resistance
+     * @returns true if the resistance was available and used, false if no resistances remain
+     */
+    useLegendaryResistance(combat: CombatInstance, bossCombatant: Combatant): boolean;
+    /**
+     * Execute a dodge action (increase AC by 2)
+     */
+    executeDodge(combat: CombatInstance, combatant: Combatant): CombatAction;
+    /**
+     * Execute a dash action (increase movement speed)
+     */
+    executeDash(combat: CombatInstance, combatant: Combatant): CombatAction;
+    /**
+     * Execute a disengage action (avoid opportunity attacks)
+     */
+    executeDisengage(combat: CombatInstance, combatant: Combatant): CombatAction;
+    /**
+     * Check if fleeing is allowed by configuration
+     */
+    canFlee(): boolean;
+    /**
+     * Execute a flee action (combatant flees from combat)
+     *
+     * Removes the combatant from the active combat instance and records
+     * the flee action in combat history. Only available when allowFleeing
+     * configuration is enabled.
+     *
+     * @param combat - Combat instance
+     * @param combatant - Combatant attempting to flee
+     * @returns Combat action with result
+     * @throws {Error} If fleeing is not allowed by configuration
+     *
+     * @example
+     * const combat = combatEngine.startCombat([player], [enemy]);
+     * const current = combatEngine.getCurrentCombatant(combat);
+     *
+     * if (combatEngine.canFlee()) {
+     *   combatEngine.executeFlee(combat, current);
+     *   // current is now removed from combat.combatants
+     * }
+     */
+    executeFlee(combat: CombatInstance, combatant: Combatant): CombatAction;
+    /**
+     * Advance to the next turn
+     * Resets action trackers and moves to next combatant.
+     *
+     * Handles skipTurn effects (Stunned, Unconscious): the combatant's
+     * actions are marked as used and the turn auto-advances. Damage
+     * effects (Burning, Poison) are processed before the skip.
+     *
+     * Uses a loop instead of recursion to avoid resetting stunned
+     * combatants' action flags when advancing past them.
+     */
+    nextTurn(combat: CombatInstance): CombatInstance;
+    /**
+     * Process start-of-turn damage effects (Burning, Poison, etc.).
+     *
+     * Deals damage equal to each effect's `damage` value and logs it
+     * in combat history. Called before the skip-turn check so that
+     * stunned combatants still take damage from burning/poison.
+     */
+    private processStartOfTurnDamage;
+    /**
+     * Process status effect tick-down at the start of a combatant's turn.
+     *
+     * Decrements duration by 1 for all active status effects, then removes
+     * any that have expired (duration <= 0). If effects expired, a
+     * 'statusEffectTick' entry is added to combat history for logging.
+     */
+    private tickStatusEffects;
+    /**
+     * Determine whether an attack should be rolled with advantage, disadvantage,
+     * or normally, based on the attacker's and target's active status effects.
+     *
+     * Advantage and disadvantage cancel each other out per D&D 5e rules.
+     *
+     * Sources of advantage:
+     * - Target has `advantageOnMeleeAttackAgainst` and attack is melee (Prone)
+     * - Target has `advantageOnRangedAttackAgainst` and attack is ranged (Prone)
+     *
+     * Sources of disadvantage:
+     * - Attacker has `disadvantageOnAttack` (Frightened, Prone attacker)
+     * - Attacker has `disadvantageOnAttackNonSource` and target is not the source (Charmed)
+     */
+    private getAttackAdvantageDisadvantage;
+    /**
+     * Check if a combatant has any status effect that causes them to skip
+     * their turn (e.g., Stunned, Unconscious).
+     */
+    private shouldSkipTurn;
+    /**
+     * Check if combat should end
+     * Ends when:
+     * - All enemies defeated
+     * - All players defeated
+     * - Max turns reached
+     * - Player surrender
+     */
+    private checkCombatStatus;
+    /**
+     * Get combat result when combat ends
+     */
+    getCombatResult(combat: CombatInstance): CombatResult | null;
+    /**
+     * Create a combatant from a character
+     */
+    private createCombatant;
+    /**
+     * Validate spell slot data on a character sheet.
+     *
+     * Checks for common issues:
+     * - Negative `total` or `used` values
+     * - `used` exceeding `total` (more slots consumed than exist)
+     * - Non-integer spell level keys
+     * - Spell levels outside the 1-9 range
+     * - `total` of 0 with non-zero `used`
+     *
+     * Returns an array of issues (empty = valid). Does not throw — callers
+     * decide how to handle issues (log, warn, fall back to table).
+     */
+    validateSpellSlots(character: CharacterSheet): SpellSlotValidationIssue[];
+    /**
+     * Validate that combatant spell slots are consistent with the source character.
+     *
+     * After `createCombatant()` runs, this checks that the combatant's remaining
+     * spell slots match what the character's `spells.spell_slots` would produce.
+     * Useful for catching regressions in the initialization pipeline.
+     *
+     * Returns an array of issues (empty = consistent).
+     */
+    validateCombatantSpellSlots(combatant: Combatant): SpellSlotValidationIssue[];
+    /**
+     * Initialize spell slots for a character.
+     *
+     * Priority:
+     * 1. If `character.spells.spell_slots` is populated (e.g. generated enemies),
+     *    convert `{ [level]: { total, used } }` → `{ [level]: total - used }`.
+     * 2. Fall back to the D&D 5e full-caster table for known spellcasting classes.
+     * 3. Return undefined for non-spellcasters with no spell slot data.
+     *
+     * If validation errors are found in source spell slot data, the problematic
+     * levels are skipped (treated as if they don't exist) and the method falls
+     * through to the fallback table for known classes.
+     */
+    private initializeSpellSlots;
+    /**
+     * Get combat status summary
+     */
+    getCombatSummary(combat: CombatInstance): string;
+    /**
+     * Apply damage to a combatant (accounting for armor class)
+     */
+    applyDamage(combatant: Combatant, damage: number): number;
+    /**
+     * Heal a combatant
+     */
+    healCombatant(combatant: Combatant, healing: number): number;
+    /**
+     * Apply temporary hit points
+     */
+    applyTemporaryHP(combatant: Combatant, tempHP: number): void;
+    /**
+     * Apply a status effect to a combatant.
+     *
+     * Handles stacking rules:
+     * - If an effect with the same name already exists on the combatant,
+     *   the duration is refreshed to the new effect's duration (take the higher).
+     * - If the new effect has `damage`, keep the higher damage value.
+     * - Otherwise, the new effect is pushed onto the combatant's statusEffects array.
+     *
+     * Returns the effect that is now active on the combatant (either the existing
+     * refreshed effect or the newly pushed one).
+     */
+    applyStatusEffect(combatant: Combatant, effect: StatusEffect): StatusEffect;
+    /**
+     * Drop a combatant's concentration, removing the concentrated effect.
+     *
+     * Per D&D 5e: a combatant can only maintain concentration on one effect
+     * at a time. When concentration ends (new concentration spell, failed save,
+     * incapacitated, or dead), the effect is removed immediately.
+     *
+     * @param combatant - The concentrating combatant
+     * @param reason - Why concentration was dropped (for logging)
+     * @returns The dropped StatusEffect, or undefined if not concentrating
+     */
+    dropConcentration(combatant: Combatant, reason?: string): StatusEffect | undefined;
+    /**
+     * Make a concentration saving throw when a concentrating combatant takes damage.
+     *
+     * Per D&D 5e: DC = 10 or half the damage taken (rounded down), whichever is higher.
+     * The save is a CON saving throw.
+     *
+     * @param combatant - The concentrating combatant
+     * @param damage - The total damage taken in the triggering event
+     * @returns true if concentration maintained, false if broken
+     */
+    private rollConcentrationSave;
+    /**
+     * Check and potentially break concentration when a combatant takes damage.
+     *
+     * Should be called whenever a concentrating combatant takes damage.
+     * If the concentration save fails, the concentrated effect is dropped.
+     *
+     * @param combat - Combat instance (for history logging)
+     * @param combatant - The combatant who took damage
+     * @param damage - The amount of damage taken
+     * @returns true if concentration was broken, false if maintained or not concentrating
+     */
+    checkConcentration(combat: CombatInstance, combatant: Combatant, damage: number): boolean;
+    /**
+     * Remove expired status effects from a combatant.
+     *
+     * Filters out all effects where `duration <= 0`.
+     * Returns the array of removed effects for logging purposes.
+     */
+    removeExpiredStatusEffects(combatant: Combatant): StatusEffect[];
+    /**
+     * Get all living combatants
+     */
+    getLivingCombatants(combat: CombatInstance): Combatant[];
+    /**
+     * Get all defeated combatants
+     */
+    getDefeatedCombatants(combat: CombatInstance): Combatant[];
+}
+//# sourceMappingURL=CombatEngine.d.ts.map

package/dist/core/combat/CombatEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatEngine.d.ts","sourceRoot":"","sources":["../../../src/core/combat/CombatEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAWjE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,UAAU,CAAC,CAAgB;IAEnC;;;;;;;;;;;;;;;OAeG;gBACS,MAAM,GAAE,YAAiB,EAAE,UAAU,CAAC,EAAE,aAAa;IAkBjE;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CACT,gBAAgB,EAAE,cAAc,EAAE,EAClC,OAAO,EAAE,cAAc,EAAE,EACzB,WAAW,CAAC,EAAE,oBAAoB,GACjC,cAAc;IAiCjB;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS;IAItD;;;;;;OAMG;IACH,aAAa,CACX,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,GACb,YAAY;IA8Cf;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,mBAAmB,CACjB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,SAAS,EACnB,MAAM,EAAE,SAAS,EACjB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY;IAyBf;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;OAEG;IACH,gBAAgB,CACd,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,SAAS,EAAE,GACnB,YAAY;IA8Cf;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAAsB,CACpB,MAAM,EAAE,cAAc,EACtB,aAAa,EAAE,SAAS,EACxB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAChJ,MAAM,CAAC,EAAE,SAAS,GACjB,YAAY;IA2Ff;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,GAAG,OAAO;IAqBjF;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,GAAG,YAAY;IAcxE;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,GAAG,YAAY;IAcvE;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,GAAG,YAAY;IAc5E;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,GAAG,YAAY;IA2CvE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc;IAyGhD;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA4BhC;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,8BAA8B;IA0CtC;;;OAGG;IACH,OAAO,CAAC,cAAc;IAMtB;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAyBzB;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,GAAG,IAAI;IA6D5D;;OAEG;IACH,OAAO,CAAC,eAAe;IAwBvB;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,SAAS,EAAE,cAAc,GAAG,wBAAwB,EAAE;IAgFzE;;;;;;;;OAQG;IACH,2BAA2B,CAAC,SAAS,EAAE,SAAS,GAAG,wBAAwB,EAAE;IAwF7E;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IAuC5B;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;IAMhD;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAsBzD;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAM5D;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5D;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY;IA8D3E;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,GAAE,MAA8B,GAAG,YAAY,GAAG,SAAS;IAmBzG;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAyBzF;;;;;OAKG;IACH,0BAA0B,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,EAAE;IAsBhE;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE;IAIxD;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE;CAG3D"}

package/dist/core/combat/DiceRoller.d.ts

@@ -0,0 +1,115 @@
+/**
+ * DiceRoller - Utility for D&D-style dice rolling
+ * Supports standard polyhedral dice and dice formulas
+ *
+ * All methods are static - call directly without instantiation:
+ * DiceRoller.rollD20(), DiceRoller.parseDiceFormula('2d6+3'), etc.
+ */
+export declare class DiceRoller {
+    /**
+     * Roll a single die
+     * @param sides Number of sides on the die (4, 6, 8, 10, 12, 20, 100)
+     * @returns Roll result (1 to sides)
+     */
+    static rollDie(sides: number): number;
+    /**
+     * Roll multiple dice and sum results
+     * @param count Number of dice to roll
+     * @param sides Sides per die
+     * @returns Array of individual rolls
+     */
+    static rollMultipleDice(count: number, sides: number): number[];
+    /**
+     * Parse and roll a dice formula like "2d6+3"
+     * @param formula Dice formula (e.g., "1d20", "2d6+3", "3d8-1")
+     * @returns Object with parsed formula and results
+     */
+    static parseDiceFormula(formula: string): {
+        diceCount: number;
+        diceSides: number;
+        modifier: number;
+        rolls: number[];
+        total: number;
+    };
+    /**
+     * Roll a d20 (common for attacks and ability checks)
+     * @returns Roll result (1-20)
+     */
+    static rollD20(): number;
+    /**
+     * Roll with advantage (roll twice, take higher)
+     * @returns Object with both rolls and final result
+     */
+    static rollWithAdvantage(): {
+        roll1: number;
+        roll2: number;
+        result: number;
+    };
+    /**
+     * Roll with disadvantage (roll twice, take lower)
+     * @returns Object with both rolls and final result
+     */
+    static rollWithDisadvantage(): {
+        roll1: number;
+        roll2: number;
+        result: number;
+    };
+    /**
+     * Roll initiative (d20 + DEX modifier)
+     * @param dexModifier Character's dexterity modifier
+     * @returns Initiative value
+     */
+    static rollInitiative(dexModifier: number): number;
+    /**
+     * Check if a roll is a critical hit (natural 20)
+     */
+    static isCriticalHit(d20Roll: number): boolean;
+    /**
+     * Check if a roll is a critical miss (natural 1)
+     */
+    static isCriticalMiss(d20Roll: number): boolean;
+    /**
+     * Double the damage from a critical hit
+     */
+    static doubleDamage(rolls: number[]): number[];
+    /**
+     * Calculate total damage from a damage formula with modifier
+     * @param formula Dice formula (e.g., "1d8")
+     * @param modifier Ability modifier to add
+     * @param isCritical Whether this is a critical hit
+     * @returns Total damage
+     */
+    static calculateDamage(formula: string, modifier: number, isCritical?: boolean): {
+        diceFormula: string;
+        rolls: number[];
+        modifier: number;
+        total: number;
+        isCritical: boolean;
+    };
+    /**
+     * Roll a saving throw (d20 + ability modifier)
+     * @param abilityModifier Modifier from the ability being saved
+     * @param proficiencyBonus Optional proficiency bonus if character is proficient
+     * @returns Save result
+     */
+    static rollSavingThrow(abilityModifier: number, proficiencyBonus?: number): number;
+    /**
+     * Roll an ability check (d20 + ability modifier + proficiency if applicable)
+     * @param abilityModifier The ability modifier
+     * @param proficiencyBonus Proficiency bonus if character is proficient (default 0)
+     * @returns Check result
+     */
+    static rollAbilityCheck(abilityModifier: number, proficiencyBonus?: number): number;
+    /**
+     * Generate a deterministic "seeded" roll for reproducibility
+     * @param seed Seed value for RNG
+     * @returns Roll result (1-20)
+     */
+    static seededRoll(seed: number): number;
+    /**
+     * Roll percentiles (d100)
+     * @returns Roll result (1-100)
+     */
+    static rollPercentile(): number;
+}
+//# sourceMappingURL=DiceRoller.d.ts.map

package/dist/core/combat/DiceRoller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiceRoller.d.ts","sourceRoot":"","sources":["../../../src/core/combat/DiceRoller.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,UAAU;IACrB;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAKrC;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAQ/D;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;QACxC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf;IAuBD;;;OAGG;IACH,MAAM,CAAC,OAAO,IAAI,MAAM;IAIxB;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB;IAUD;;;OAGG;IACH,MAAM,CAAC,oBAAoB,IAAI;QAC7B,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB;IAUD;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAIlD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI9C;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI/C;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAI9C;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG;QACtF,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,OAAO,CAAC;KACrB;IAoBD;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAE,MAAU,GAAG,MAAM;IAIrF;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAE,MAAU,GAAG,MAAM;IAItF;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMvC;;;OAGG;IACH,MAAM,CAAC,cAAc,IAAI,MAAM;CAGhC"}

package/dist/core/combat/InitiativeRoller.d.ts

@@ -0,0 +1,62 @@
+/**
+ * InitiativeRoller - Handles initiative rolling and turn order sorting
+ * D&D 5e: Initiative = d20 + DEX modifier
+ */
+import type { Combatant, DiceRollerAPI } from '../types/Combat';
+/**
+ * Result of initiative rolling
+ */
+export interface InitiativeResult {
+    combatant: Combatant;
+    d20Roll: number;
+    dexModifier: number;
+    initiativeTotal: number;
+}
+/**
+ * InitiativeRoller - Manages initiative system for D&D combat
+ */
+export declare class InitiativeRoller {
+    private diceRoller?;
+    constructor(diceRoller?: DiceRollerAPI);
+    /**
+     * Roll initiative for a single combatant
+     * Initiative = d20 + DEX modifier
+     */
+    rollInitiativeForCombatant(combatant: Combatant): InitiativeResult;
+    /**
+     * Roll initiative for all combatants and sort by descending initiative
+     * Higher initiative acts first
+     */
+    rollInitiativeForAll(combatants: Combatant[]): {
+        results: InitiativeResult[];
+        sortedCombatants: Combatant[];
+    };
+    /**
+     * Get the next combatant in turn order
+     * Wraps around to beginning when reaching end of list
+     */
+    getNextCombatant(combatants: Combatant[], currentIndex: number): {
+        combatant: Combatant;
+        index: number;
+        isNewRound: boolean;
+    };
+    /**
+     * Get initiative order as a formatted string for display
+     */
+    getInitiativeOrder(combatants: Combatant[]): string[];
+    /**
+     * Re-roll initiative for a specific combatant (e.g., if an effect changes DEX)
+     */
+    rerollInitiativeForCombatant(combatant: Combatant): number;
+    /**
+     * Delay a combatant's turn (move them later in initiative order)
+     * Used when a combatant takes the "Ready" action
+     */
+    delayTurn(combatants: Combatant[], combatantId: string): Combatant[];
+    /**
+     * Shuffle combatants back into position by exact initiative value
+     * Used if new combatants join mid-combat
+     */
+    resortByInitiative(combatants: Combatant[]): Combatant[];
+}
+//# sourceMappingURL=InitiativeRoller.d.ts.map

package/dist/core/combat/InitiativeRoller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InitiativeRoller.d.ts","sourceRoot":"","sources":["../../../src/core/combat/InitiativeRoller.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAC,CAAgB;gBAEvB,UAAU,CAAC,EAAE,aAAa;IAItC;;;OAGG;IACH,0BAA0B,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB;IAkBlE;;;OAGG;IACH,oBAAoB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG;QAC7C,OAAO,EAAE,gBAAgB,EAAE,CAAC;QAC5B,gBAAgB,EAAE,SAAS,EAAE,CAAC;KAC/B;IA0BD;;;OAGG;IACH,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG;QAC/D,SAAS,EAAE,SAAS,CAAC;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,OAAO,CAAC;KACrB;IAWD;;OAEG;IACH,kBAAkB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE;IAOrD;;OAEG;IACH,4BAA4B,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM;IAS1D;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE;IAcpE;;;OAGG;IACH,kBAAkB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE;CAWzD"}