playlist-data-engine 1.1.0

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

@@ -0,0 +1,215 @@
+/**
+ * PartyAnalyzer - Analyzes party strength for encounter generation
+ *
+ * Provides methods to calculate party level, XP budget, and combat stats
+ * for generating balanced encounters based on D&D 5e encounter building rules.
+ *
+ * All methods are static for convenient access without instantiation.
+ */
+import type { CharacterSheet } from '../types/Character.js';
+import type { EncounterDifficulty } from '../types/Enemy.js';
+/**
+ * Analysis result for a party's combat capabilities
+ *
+ * Provides comprehensive view of party strength for encounter generation.
+ * Used internally by encounter generation system to balance enemies.
+ */
+export interface PartyAnalysis {
+    /** Average party level (rounded down) */
+    averageLevel: number;
+    /** Number of party members */
+    partySize: number;
+    /** Average armor class across all party members */
+    averageAC: number;
+    /** Average hit points across all party members */
+    averageHP: number;
+    /** Average damage output (estimated) */
+    averageDamage: number;
+    /** Total party strength score (abstract value) */
+    totalStrength: number;
+    /** XP budget for easy difficulty */
+    easyXP: number;
+    /** XP budget for medium difficulty */
+    mediumXP: number;
+    /** XP budget for hard difficulty */
+    hardXP: number;
+    /** XP budget for deadly difficulty */
+    deadlyXP: number;
+}
+/**
+ * PartyAnalyzer - Static class for party strength analysis
+ *
+ * Analyzes CharacterSheet instances to determine combat capabilities
+ * and calculate appropriate encounter XP budgets using D&D 5e rules.
+ *
+ * All methods handle edge cases:
+ * - Empty party arrays return safe defaults
+ * - Invalid character sheets are skipped
+ * - Levels are clamped to valid D&D range (1-20)
+ *
+ * @example
+ * ```typescript
+ * const party = [character1, character2, character3];
+ * const budget = PartyAnalyzer.getXPBudget(party, 'medium');
+ * const avgLevel = PartyAnalyzer.calculatePartyLevel(party);
+ * ```
+ */
+export declare class PartyAnalyzer {
+    /**
+     * Calculate average party level
+     *
+     * Returns the average level of all party members, rounded down.
+     * Empty party returns level 1 as safe default.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Average level (1-20), or 1 for empty party
+     *
+     * @example
+     * ```typescript
+     * const party = [level3Char, level5Char, level4Char];
+     * PartyAnalyzer.calculatePartyLevel(party); // 4 (12 / 3 = 4)
+     * ```
+     */
+    static calculatePartyLevel(party: CharacterSheet[]): number;
+    /**
+     * Calculate overall party strength score
+     *
+     * Combines multiple factors into a single strength value:
+     * - HP pool (total hit points)
+     * - Average AC (defense)
+     * - Average damage output (offense)
+     * - Party size (action economy)
+     *
+     * This is an abstract score useful for comparing parties
+     * and tuning encounter difficulty.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Strength score (higher = stronger party)
+     *
+     * @example
+     * ```typescript
+     * const strength = PartyAnalyzer.calculatePartyStrength(party);
+     * // Returns ~500-2000 for typical level 1-10 parties
+     * ```
+     */
+    static calculatePartyStrength(party: CharacterSheet[]): number;
+    /**
+     * Get XP budget for desired encounter difficulty
+     *
+     * Calculates total XP budget for the entire party based on
+     * D&D 5e encounter building tables. Sum of individual budgets.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @param difficulty - Desired encounter difficulty
+     * @returns Total XP budget for encounter
+     *
+     * @example
+     * ```typescript
+     * // Level 5 party of 4, medium difficulty
+     * const budget = PartyAnalyzer.getXPBudget(party, 'medium');
+     * // Returns: 2000 (500 × 4)
+     * ```
+     */
+    static getXPBudget(party: CharacterSheet[], difficulty: EncounterDifficulty): number;
+    /**
+     * Get average armor class across party
+     *
+     * Calculates mean AC for all party members.
+     * Used for tuning enemy attack bonuses to match party defense.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Average AC (typically 10-20), or 10 for empty party
+     *
+     * @example
+     * ```typescript
+     * const avgAC = PartyAnalyzer.getAverageAC(party);
+     * // Returns ~15 for typical level 5 party
+     * ```
+     */
+    static getAverageAC(party: CharacterSheet[]): number;
+    /**
+     * Get average hit points across party
+     *
+     * Calculates mean maximum HP for all party members.
+     * Used for tuning enemy damage output to match party durability.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Average HP, or 10 for empty party
+     *
+     * @example
+     * ```typescript
+     * const avgHP = PartyAnalyzer.getAverageHP(party);
+     * // Returns ~35-45 for level 5 party
+     * ```
+     */
+    static getAverageHP(party: CharacterSheet[]): number;
+    /**
+     * Get party size (number of members)
+     *
+     * Utility method for encounter scaling calculations.
+     * Returns count of valid CharacterSheet objects.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Number of party members
+     *
+     * @example
+     * ```typescript
+     * PartyAnalyzer.getPartySize([pc1, pc2, pc3]); // 3
+     * ```
+     */
+    static getPartySize(party: CharacterSheet[]): number;
+    /**
+     * Get estimated average damage per party member
+     *
+     * Estimates damage output based on:
+     * - Primary attack stat (STR or DEX)
+     * - Proficiency bonus (scales with level)
+     * - Assumed weapon damage (d8 for martial, d6 for casters)
+     *
+     * This is a rough estimate used for encounter balancing.
+     * Actual damage varies greatly based on equipment and class features.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Average damage per round per character
+     *
+     * @example
+     * ```typescript
+     * const avgDamage = PartyAnalyzer.getAverageDamage(party);
+     * // Returns ~10-15 for level 5 party
+     * ```
+     */
+    static getAverageDamage(party: CharacterSheet[]): number;
+    /**
+     * Estimate damage output for a single character
+     *
+     * Reads the character's actually equipped weapon to compute average damage
+     * per hit. Falls back to unarmed strike (1 + STR mod) if no weapon equipped.
+     *
+     * Private helper used by getAverageDamage().
+     *
+     * @param character - CharacterSheet to estimate
+     * @returns Estimated average damage per hit
+     */
+    private static estimateCharacterDamage;
+    /**
+     * Get comprehensive party analysis
+     *
+     * Returns complete analysis of party capabilities including
+     * level, size, defensive stats, offensive stats, and
+     * XP budgets for all difficulty levels.
+     *
+     * Useful for encounter generation UI and debugging.
+     *
+     * @param party - Array of CharacterSheet objects
+     * @returns Complete PartyAnalysis object
+     *
+     * @example
+     * ```typescript
+     * const analysis = PartyAnalyzer.analyzeParty(party);
+     * console.log(`Party level: ${analysis.averageLevel}`);
+     * console.log(`Medium budget: ${analysis.mediumXP} XP`);
+     * ```
+     */
+    static analyzeParty(party: CharacterSheet[]): PartyAnalysis;
+}
+//# sourceMappingURL=PartyAnalyzer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PartyAnalyzer.d.ts","sourceRoot":"","sources":["../../../src/core/combat/PartyAnalyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAQ7D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAElB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IAEtB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IAEtB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IAEf,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IAEjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IAEf,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IACtB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IAS3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,sBAAsB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IAmB9D;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,WAAW,CACd,KAAK,EAAE,cAAc,EAAE,EACvB,UAAU,EAAE,mBAAmB,GAChC,MAAM;IAST;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IASpD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IASpD;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IAIpD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IAYxD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAkCtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,aAAa;CA2B9D"}

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

@@ -0,0 +1,120 @@
+/**
+ * SeededDiceRoller - Deterministic D&D-style dice rolling for reproducible combat simulations
+ *
+ * Implements the same API as DiceRoller but uses SeededRNG internally,
+ * producing deterministic results given the same seed and call sequence.
+ *
+ * Instance-based (not static) so each simulation run gets its own roller
+ * with its own RNG state.
+ */
+import { SeededRNG } from '../../utils/random.js';
+/**
+ * Factory: create a SeededDiceRoller from a seed string.
+ * Each call produces a fresh roller with its own RNG state —
+ * this is what CombatSimulator will call per simulation run.
+ */
+export declare function createSeededRoller(seed: string): SeededDiceRoller;
+export declare class SeededDiceRoller {
+    private rng;
+    constructor(seedOrRng: string | SeededRNG);
+    /**
+     * 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)
+     */
+    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
+     */
+    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
+     */
+    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)
+     */
+    rollD20(): number;
+    /**
+     * Roll with advantage (roll twice, take higher)
+     * @returns Object with both rolls and final result
+     */
+    rollWithAdvantage(): {
+        roll1: number;
+        roll2: number;
+        result: number;
+    };
+    /**
+     * Roll with disadvantage (roll twice, take lower)
+     * @returns Object with both rolls and final result
+     */
+    rollWithDisadvantage(): {
+        roll1: number;
+        roll2: number;
+        result: number;
+    };
+    /**
+     * Roll initiative (d20 + DEX modifier)
+     * @param dexModifier Character's dexterity modifier
+     * @returns Initiative value
+     */
+    rollInitiative(dexModifier: number): number;
+    /**
+     * Check if a roll is a critical hit (natural 20)
+     */
+    isCriticalHit(d20Roll: number): boolean;
+    /**
+     * Check if a roll is a critical miss (natural 1)
+     */
+    isCriticalMiss(d20Roll: number): boolean;
+    /**
+     * Double the damage from a critical hit
+     */
+    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
+     */
+    calculateDamage(formula: string, modifier: number, isCritical?: boolean): {
+        diceFormula: string;
+        rolls: number[];
+        modifier: number;
+        total: number;
+        isCritical: boolean;
+    };
+    /**
+     * Roll a saving throw (d20 + ability modifier + proficiency bonus)
+     * @param abilityModifier Modifier from the ability being saved
+     * @param proficiencyBonus Optional proficiency bonus if character is proficient
+     * @returns Save result
+     */
+    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
+     */
+    rollAbilityCheck(abilityModifier: number, proficiencyBonus?: number): number;
+    /**
+     * Roll percentiles (d100)
+     * @returns Roll result (1-100)
+     */
+    rollPercentile(): number;
+}
+//# sourceMappingURL=SeededDiceRoller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SeededDiceRoller.d.ts","sourceRoot":"","sources":["../../../src/core/combat/SeededDiceRoller.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAEjE;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,GAAG,CAAY;gBAEX,SAAS,EAAE,MAAM,GAAG,SAAS;IAIzC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK9B;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAQxD;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;QACjC,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;IAgBD;;;OAGG;IACH,OAAO,IAAI,MAAM;IAIjB;;;OAGG;IACH,iBAAiB,IAAI;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB;IAMD;;;OAGG;IACH,oBAAoB,IAAI;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB;IAMD;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAI3C;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIvC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIxC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAIvC;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG;QAC/E,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;IAaD;;;;;OAKG;IACH,eAAe,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAE,MAAU,GAAG,MAAM;IAI9E;;;;;OAKG;IACH,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,gBAAgB,GAAE,MAAU,GAAG,MAAM;IAI/E;;;OAGG;IACH,cAAc,IAAI,MAAM;CAGzB"}