playlist-data-engine 1.1.0

package/dist/core/types/Combat.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Combat System Types
+ * D&D 5e-inspired turn-based combat mechanics
+ */
+import type { CharacterSheet, Attack, Spell } from './Character';
+import type { EnvironmentalContext } from './Progression';
+import type { Equipment } from '../../utils/constants.ts';
+import type { LegendaryAction } from './Enemy';
+import type { CombatantMetrics } from './CombatAI';
+/**
+ * DiceRollerAPI - Common interface for dice rolling implementations.
+ * Both the static DiceRoller (via adapter) and instance-based SeededDiceRoller
+ * satisfy this interface, allowing CombatEngine to work in both live (random)
+ * and simulation (seeded) modes.
+ */
+export interface DiceRollerAPI {
+    rollDie(sides: number): number;
+    rollD20(): number;
+    rollWithAdvantage(): {
+        roll1: number;
+        roll2: number;
+        result: number;
+    };
+    rollWithDisadvantage(): {
+        roll1: number;
+        roll2: number;
+        result: number;
+    };
+    calculateDamage(formula: string, modifier: number, isCritical?: boolean): DamageRoll;
+    rollSavingThrow(abilityModifier: number, proficiencyBonus?: number): number;
+    rollAbilityCheck(abilityModifier: number, proficiencyBonus?: number): number;
+    isCriticalHit(d20Roll: number): boolean;
+    isCriticalMiss(d20Roll: number): boolean;
+    parseDiceFormula(formula: string): {
+        diceCount: number;
+        diceSides: number;
+        modifier: number;
+        rolls: number[];
+        total: number;
+    };
+}
+/**
+ * StatusEffectMechanics - Mechanical impact of a status effect on combat
+ *
+ * Used by CombatEngine to enforce combat rules for conditions like
+ * Charmed (disadvantage on attacks vs non-source), Frightened (disadvantage
+ * on attacks/checks while source visible), Stunned (skip turn), etc.
+ */
+export interface StatusEffectMechanics {
+    /** Combatant has disadvantage on attack rolls against targets other than source */
+    disadvantageOnAttackNonSource?: boolean;
+    /** Combatant has disadvantage on attack rolls (unconditional) */
+    disadvantageOnAttack?: boolean;
+    /** Combatant has disadvantage on ability checks */
+    disadvantageOnAbilityChecks?: boolean;
+    /** Melee attacks against this combatant have advantage */
+    advantageOnMeleeAttackAgainst?: boolean;
+    /** Ranged attacks against this combatant have advantage */
+    advantageOnRangedAttackAgainst?: boolean;
+    /** Combatant has disadvantage on DEX saving throws */
+    disadvantageOnDexSaves?: boolean;
+    /** Combatant's speed is set to 0 */
+    speedZero?: boolean;
+    /** Combatant skips their turn entirely */
+    skipTurn?: boolean;
+    /** Combatant is immune to a specific damage type while this effect is active */
+    damageImmunity?: DamageType;
+    /** Combatant has resistance to a specific damage type while this effect is active */
+    damageResistance?: DamageType;
+    /** Combatant has vulnerability to a specific damage type while this effect is active */
+    damageVulnerability?: DamageType;
+}
+/**
+ * StatusEffect - Temporary condition affecting a combatant
+ */
+export interface StatusEffect {
+    name: string;
+    description: string;
+    duration: number;
+    source?: string;
+    hasConcentration?: boolean;
+    /** Optional icon URL for small UI display */
+    icon?: string;
+    /** Optional image URL for larger display */
+    image?: string;
+    /** Damage dealt at the start of each of the affected combatant's turns (e.g., Burning) */
+    damage?: number;
+    /** Damage type for the effect's damage (e.g., 'fire' for Burning) */
+    damageType?: DamageType;
+    /** Mechanical effects that CombatEngine enforces during combat */
+    mechanicalEffects?: StatusEffectMechanics;
+}
+/**
+ * Combatant - A character participating in combat
+ */
+export interface Combatant {
+    id: string;
+    character: CharacterSheet;
+    initiative: number;
+    currentHP: number;
+    temporaryHP?: number;
+    statusEffects: StatusEffect[];
+    position?: {
+        x: number;
+        y: number;
+    };
+    isDefeated: boolean;
+    actionUsed: boolean;
+    bonusActionUsed: boolean;
+    reactionUsed: boolean;
+    spellSlots?: {
+        [level: number]: number;
+    };
+    /** Name of the status effect this combatant is concentrating on, if any */
+    concentratingOn?: string;
+    /** Legendary action points remaining this round (3 per round for bosses, 0 for non-bosses) */
+    legendaryActionsRemaining?: number;
+    /** Legendary resistances remaining (per-day resource for bosses) */
+    legendaryResistancesRemaining?: number;
+}
+/**
+ * CombatAction - An action taken during combat
+ */
+export interface CombatAction {
+    type: 'attack' | 'spell' | 'dodge' | 'dash' | 'disengage' | 'help' | 'hide' | 'ready' | 'flee' | 'useItem' | 'legendaryAction' | 'statusEffectTick';
+    actor: Combatant;
+    target?: Combatant;
+    targets?: Combatant[];
+    attack?: Attack;
+    spell?: Spell;
+    item?: Equipment;
+    legendaryAction?: LegendaryAction;
+    result?: CombatActionResult;
+}
+/**
+ * CombatActionResult - Outcome of a combat action
+ */
+export interface CombatActionResult {
+    success: boolean;
+    roll?: number;
+    isCritical?: boolean;
+    damage?: number;
+    damageType?: string;
+    targetHP?: number;
+    description: string;
+}
+/**
+ * HitMode - Determines how attack rolls resolve hits and misses
+ *
+ * - 'dnd': Classic D&D 5e — d20 + bonus vs target AC. Below AC = miss.
+ * - 'scaled': AC reduces damage instead of determining hit/miss.
+ *   Only natural 1 misses. Natural 20 is always a critical hit.
+ *   For each point the total roll falls below AC, damage is reduced by 10%,
+ *   down to a minimum of 1 damage.
+ */
+export type HitMode = 'dnd' | 'scaled';
+/**
+ * AttackRoll - Result of an attack roll
+ */
+export interface AttackRoll {
+    d20Roll: number;
+    attackBonus: number;
+    totalRoll: number;
+    targetAC: number;
+    hit: boolean;
+    isCritical: boolean;
+    isMiss: boolean;
+    damageScale?: number;
+}
+/**
+ * DamageRoll - Result of a damage roll
+ *
+ * Damage formula: totalDamage = max(1, baseDamage + weaponBonus)
+ * - baseDamage = max(0, attacker.STR - defender.AC)
+ * - weaponBonus = max(1, floor(rawDiceSum / 4))
+ */
+export interface DamageRoll {
+    diceFormula: string;
+    rolls: number[];
+    modifier?: number;
+    total: number;
+    isCritical: boolean;
+    baseDamage?: number;
+    weaponRoll?: number;
+}
+/**
+ * SpellCastResult - Outcome of casting a spell
+ */
+export interface SpellCastResult {
+    success: boolean;
+    spellName: string;
+    caster: Combatant;
+    targets: Combatant[];
+    saveDC?: number;
+    damage?: DamageRoll;
+    effectsApplied: StatusEffect[];
+    spellSlotUsed: number;
+    description: string;
+}
+/**
+ * CombatInstance - Represents an active combat encounter
+ */
+export interface CombatInstance {
+    id: string;
+    combatants: Combatant[];
+    currentTurnIndex: number;
+    roundNumber: number;
+    environment?: EnvironmentalContext;
+    history: CombatAction[];
+    isActive: boolean;
+    winner?: Combatant;
+    winnerSide?: 'player' | 'enemy' | 'draw';
+    startTime: number;
+    lastUpdated: number;
+    /** Per-combatant metrics computed from combat history (populated by CombatMetricsTracker) */
+    metrics?: Map<string, CombatantMetrics>;
+}
+/**
+ * CombatResult - Final outcome of a combat encounter
+ */
+export interface CombatResult {
+    winner?: Combatant;
+    winnerSide: 'player' | 'enemy' | 'draw';
+    defeated: Combatant[];
+    roundsElapsed: number;
+    totalTurns: number;
+    xpAwarded: number;
+    treasureAwarded?: {
+        gold: number;
+        items: Equipment[];
+    };
+    description: string;
+}
+/**
+ * D&D Damage Type Classification
+ */
+export type DamageType = 'slashing' | 'piercing' | 'bludgeoning' | 'fire' | 'cold' | 'lightning' | 'thunder' | 'poison' | 'acid' | 'necrotic' | 'radiant' | 'psychic' | 'force';
+/**
+ * D&D Ability Saving Throw
+ */
+export type SavingThrowAbility = 'strength' | 'dexterity' | 'constitution' | 'intelligence' | 'wisdom' | 'charisma';
+/**
+ * Treasure Configuration Options
+ * - Fixed amount: `{ gold: 500 }` - always rewards exactly 500 gold
+ * - Range: `{ gold: { min: 100, max: 200 } }` - random amount between 100-200 (uses seed if provided)
+ * - Items: Optional array of items to award (supports any Equipment type including boxes)
+ */
+export interface TreasureConfig {
+    gold?: number | {
+        min: number;
+        max: number;
+    };
+    items?: Equipment[];
+}
+/**
+ * Combat Configuration Options
+ */
+export interface CombatConfig {
+    useEnvironment?: boolean;
+    useMusic?: boolean;
+    tacticalMode?: boolean;
+    maxTurnsBeforeDraw?: number;
+    allowFleeing?: boolean;
+    seed?: string;
+    treasure?: TreasureConfig;
+    hitMode?: HitMode;
+}
+//# sourceMappingURL=Combat.d.ts.map

package/dist/core/types/Combat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Combat.d.ts","sourceRoot":"","sources":["../../../src/core/types/Combat.ts"],"names":[],"mappings":"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"}

package/dist/core/types/CombatAI.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Combat AI Type Definitions
+ *
+ * Defines types and interfaces for the combat AI system that controls
+ * both player characters and enemies during simulated combat.
+ */
+/**
+ * AIPlayStyle - How an AI-controlled combatant approaches combat
+ *
+ * Two fundamental strategies drive all AI decisions:
+ * - **Normal**: Measures baseline difficulty. Balanced resource use.
+ * - **Aggressive**: Measures difficulty ceiling. No resource conservation.
+ *
+ * Comparing Normal vs Aggressive results reveals the true difficulty
+ * range of an encounter.
+ */
+export type AIPlayStyle = 'normal' | 'aggressive';
+/**
+ * AIConfig - Configuration for AI-controlled combat
+ *
+ * Controls how both sides fight during simulation. Each side can have
+ * a different play style, and individual combatants can be overridden.
+ */
+export interface AIConfig {
+    /** How player characters play */
+    playerStyle: AIPlayStyle;
+    /** How enemies play */
+    enemyStyle: AIPlayStyle;
+    /** Optional per-combatant style overrides (combatant ID → style) */
+    overrides?: Map<string, AIPlayStyle>;
+    /**
+     * Enable class-specific features for player AI
+     * Default: false (basic attacks + spells + items only)
+     * When true: AI attempts to use class features like Sneak Attack, Divine Smite, Action Surge
+     */
+    enableClassFeatures?: boolean;
+}
+/**
+ * AIDecision - The output of the AI's decision for a single turn
+ *
+ * Returned by CombatAI.decide() and executed by AICombatRunner.
+ * Contains all information needed to execute one combatant's turn.
+ */
+export interface AIDecision {
+    /** The type of action to take */
+    action: 'attack' | 'castSpell' | 'dodge' | 'dash' | 'disengage' | 'flee' | 'useItem' | 'legendaryAction' | 'skip';
+    /** Target combatant ID (for single-target actions) */
+    target?: string;
+    /** Target combatant IDs (for multi-target spells) */
+    targetIds?: string[];
+    /** Which weapon to attack with */
+    weaponName?: string;
+    /** Which spell to cast */
+    spellName?: string;
+    /** Which consumable item to use */
+    itemName?: string;
+    /** Which legendary action to execute */
+    legendaryActionId?: string;
+    /** Human-readable explanation of why the AI chose this action */
+    reasoning?: string;
+}
+/**
+ * AIThreatAssessment - How the AI evaluates the current battlefield state
+ *
+ * Computed each turn to inform decision-making. Provides a snapshot
+ * of tactical conditions that drive style-dependent behavior.
+ */
+export interface AIThreatAssessment {
+    /** Current HP as a fraction of max HP (0.0 - 1.0) */
+    myHPPercent: number;
+    /** Current armor class */
+    myAC: number;
+    /** Lowest ally HP as a fraction of max HP (1.0 if no allies) */
+    lowestAllyHPPercent: number;
+    /** Absolute HP of the weakest living enemy (Infinity if no enemies) */
+    lowestEnemyHP: number;
+    /** Estimated DPR of the scariest enemy */
+    highestEnemyDamage: number;
+    /** Number of living allies (including self) */
+    partySize: number;
+    /** Number of living enemies */
+    enemyCount: number;
+    /** Current round number */
+    roundNumber: number;
+    /** Below 25% HP */
+    isLowHP: boolean;
+    /** Below 10% HP */
+    isCriticalHP: boolean;
+    /** Has healing items in inventory */
+    hasHealingItems: boolean;
+    /** Has remaining spell slots for leveled spells */
+    hasSpellSlots: boolean;
+    /** Has remaining limited-use abilities (not yet expended) */
+    hasRemainingLimitedAbilities: boolean;
+}
+/**
+ * CombatantMetrics - Per-combatant aggregate statistics from a single combat
+ *
+ * Computed from combat history by CombatMetricsTracker. Used by the
+ * Monte Carlo simulator to aggregate per-combatant performance across
+ * many simulation runs (DPR, survival rate, etc.).
+ */
+export interface CombatantMetrics {
+    /** Combatant ID */
+    combatantId: string;
+    /** Combatant display name */
+    name: string;
+    /** Which side this combatant was on */
+    side: 'player' | 'enemy';
+    /** Total damage dealt to enemies (via attacks, spells, legendary actions) */
+    totalDamageDealt: number;
+    /** Total damage taken from all sources */
+    totalDamageTaken: number;
+    /** Total HP restored via healing spells and items */
+    totalHealingDone: number;
+    /** Number of spells cast (successful and failed) */
+    spellsCast: number;
+    /** Number of consumable items used */
+    itemsUsed: number;
+    /** Number of critical hits scored */
+    criticalHits: number;
+    /** Number of successful attack/spell hits */
+    hits: number;
+    /** Number of missed attack/spell attempts */
+    misses: number;
+    /** Number of enemies/opponents this combatant defeated (killed) */
+    kills: number;
+    /** Number of rounds the combatant survived (0 if defeated in round 1) */
+    roundsSurvived: number;
+    /** Whether the combatant was still alive at combat end */
+    survived: boolean;
+    /** Breakdown of actions by type */
+    actionsByType: Record<string, number>;
+    /** Damage dealt per round (index = round number, value = damage that round) */
+    damagePerRound: number[];
+    /** HP remaining at combat end (as percentage of max HP, 0–100). 0 if defeated. */
+    hpRemainingPercent: number;
+}
+/**
+ * Type guard to check if a value is a valid AIPlayStyle
+ */
+export declare function isValidAIPlayStyle(value: unknown): value is AIPlayStyle;
+//# sourceMappingURL=CombatAI.d.ts.map

package/dist/core/types/CombatAI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CombatAI.d.ts","sourceRoot":"","sources":["../../../src/core/types/CombatAI.ts"],"names":[],"mappings":"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"}