playlist-data-engine 1.1.0

package/dist/core/combat/Simulation/CombatSimulator.d.ts

@@ -0,0 +1,366 @@
+/**
+ * CombatSimulator — Monte Carlo combat simulation engine
+ *
+ * Runs N combat simulations with seeded RNG, aggregates statistical results,
+ * and returns structured data for balance analysis. Each simulation run gets
+ * a unique seed derived from the base seed, ensuring full determinism:
+ * same base seed + same config = identical results every time.
+ *
+ * Uses AICombatRunner internally for each run, so the AI makes all combat
+ * decisions. The simulator orchestrates running many fights and aggregating
+ * the outcomes into statistically meaningful summaries.
+ *
+ * Usage:
+ * ```ts
+ * const simulator = new CombatSimulator();
+ * const results = simulator.run(
+ *   party, enemies,
+ *   { runCount: 1000, baseSeed: 'my-sim', aiConfig: { playerStyle: 'normal', enemyStyle: 'aggressive' } },
+ *   (completed, total) => console.log(`${completed}/${total}`)
+ * );
+ * console.log(results.summary.playerWinRate); // e.g., 0.73
+ * ```
+ */
+import type { CharacterSheet } from '../../types/Character.js';
+import type { CombatConfig, CombatInstance, CombatResult } from '../../types/Combat.js';
+import type { AIConfig, CombatantMetrics } from '../../types/CombatAI.js';
+import type { EncounterGenerationOptions } from '../../types/Enemy.js';
+/**
+ * Configuration for a Monte Carlo combat simulation.
+ *
+ * Controls how many fights to run, what AI strategies to use, and
+ * whether to collect detailed per-run logs (memory-intensive).
+ */
+export interface SimulationConfig {
+    /** Number of simulations to run (100–10000 recommended) */
+    runCount: number;
+    /** Base seed for determinism — each run gets baseSeed + index */
+    baseSeed: string;
+    /** AI play styles per side */
+    aiConfig: AIConfig;
+    /** Optional combat engine configuration (max turns, flee, etc.) */
+    combatConfig?: CombatConfig;
+    /** If true, save full combat log per run (memory-intensive for large runCount) */
+    collectDetailedLogs?: boolean;
+    /**
+     * If provided, regenerate enemies per run using these options instead of
+     * reusing the same pre-generated enemies for all runs.
+     *
+     * Each run gets a unique seed derived from `baseSeed + runIndex`, producing
+     * different enemy templates/stats per run while keeping determinism.
+     * This captures the variance in enemy generation (different templates, etc.)
+     * across Monte Carlo iterations.
+     *
+     * The `enemies` array passed to `run()` is still used for:
+     * - Aggregator initialization (combatant IDs, encounter config)
+     * - Per-combatant metric slot naming
+     */
+    enemyRegeneration?: EncounterGenerationOptions;
+    /** Progress callback — called after each run completes */
+    onProgress?: (completed: number, total: number) => void;
+    /** AbortSignal for cancelling long-running simulations. When aborted, returns partial results. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Summary statistics aggregated across all simulation runs.
+ *
+ * Answers the core question: "Given this party and these enemies,
+ * how often does each side win, and how long do fights last?"
+ */
+export interface SimulationSummary {
+    /** Total simulation runs completed */
+    totalRuns: number;
+    /** Number of runs where all enemies were defeated */
+    playerWins: number;
+    /** Number of runs where all players were defeated */
+    enemyWins: number;
+    /** Number of runs that ended in a draw (max turns, mutual kill, etc.) */
+    draws: number;
+    /** Player win rate (0.0–1.0) */
+    playerWinRate: number;
+    /** Average number of rounds across all runs */
+    averageRounds: number;
+    /** Median number of rounds across all runs */
+    medianRounds: number;
+    /** Average rounds in runs where the player won */
+    averageRoundsOnWin: number;
+    /** Average rounds in runs where the player lost */
+    averageRoundsOnLoss: number;
+    /** Average remaining HP percent for player characters across winning runs */
+    averagePlayerHPPercentRemaining: number;
+    /** Total number of player character deaths across all runs */
+    totalPlayerDeaths: number;
+    /** Average rounds at which each player death occurred */
+    averageRoundsPerPlayerDeath: number;
+    /** Total number of enemy deaths across all runs */
+    totalEnemyDeaths: number;
+    /** Average rounds at which each enemy death occurred */
+    averageRoundsPerEnemyDeath: number;
+}
+/**
+ * Histogram bucket for distribution visualization.
+ *
+ * Used to build damage and HP distribution charts in the frontend.
+ */
+export interface HistogramBucket {
+    /** Start of the range (inclusive) */
+    rangeStart: number;
+    /** End of the range (exclusive, except the last bucket) */
+    rangeEnd: number;
+    /** Number of data points in this bucket */
+    count: number;
+    /** Percentage of total data points (0–100) */
+    percent: number;
+}
+/**
+ * Per-combatant aggregate statistics across all simulation runs.
+ *
+ * Computed by accumulating CombatantMetrics from each run, then
+ * calculating averages, rates, and distributions.
+ */
+export interface CombatantSimulationMetrics {
+    /** Combatant ID (from CharacterSheet) */
+    combatantId: string;
+    /** Combatant display name */
+    name: string;
+    /** Which side this combatant was on */
+    side: 'player' | 'enemy';
+    /** Average damage dealt per round across all runs */
+    averageDamagePerRound: number;
+    /** Median damage dealt per round across all runs */
+    medianDamagePerRound: number;
+    /** Average total damage dealt across all runs */
+    averageTotalDamageDealt: number;
+    /** Average total damage taken across all runs */
+    averageTotalDamageTaken: number;
+    /** Average healing done across all runs */
+    averageHealingDone: number;
+    /** Average number of rounds survived across all runs */
+    averageRoundsSurvived: number;
+    /** How often this combatant survived to combat end (0.0–1.0) */
+    survivalRate: number;
+    /** How often this combatant got the final blow on any enemy (0.0–1.0) */
+    killRate: number;
+    /** Rate of critical hits across all attack actions (0.0–1.0) */
+    criticalHitRate: number;
+    /** Average hit rate across all runs (0.0–1.0) */
+    averageHitRate: number;
+    /** Average number of hits per run */
+    averageHitsPerRun: number;
+    /** Average number of misses per run */
+    averageMissesPerRun: number;
+    /** Average number of spell slots consumed per run */
+    averageSpellSlotsUsed: number;
+    /** Most frequently used action type ('attack', 'castSpell', etc.) */
+    mostUsedAction: string;
+    /** Damage dealt per round histogram for visualization */
+    damageDistribution: HistogramBucket[];
+    /** HP remaining at combat end histogram for visualization */
+    hpRemainingDistribution: HistogramBucket[];
+}
+/**
+ * Detail record for a single simulation run.
+ * Only populated when `collectDetailedLogs` is true.
+ */
+export interface SimulationRunDetail {
+    /** Run index (0-based) */
+    runIndex: number;
+    /** Seed used for this run */
+    seed: string;
+    /** Full combat instance with complete action history */
+    combat: CombatInstance;
+    /** Final combat result */
+    result: CombatResult;
+    /** Per-combatant metrics for this run */
+    metrics: Map<string, CombatantMetrics>;
+}
+/**
+ * Party and encounter configuration — stored alongside results for context.
+ */
+export interface PartyConfig {
+    /** Number of party members */
+    memberCount: number;
+    /** Average party level */
+    averageLevel: number;
+    /** Party member names */
+    memberNames: string[];
+}
+export interface EncounterConfig {
+    /** Number of enemies */
+    enemyCount: number;
+    /** Average enemy CR */
+    averageCR: number;
+    /** Enemy names */
+    enemyNames: string[];
+}
+/**
+ * Complete results from a Monte Carlo combat simulation.
+ *
+ * Contains the aggregate summary, per-combatant metrics, and optionally
+ * the detailed per-run logs.
+ */
+export interface SimulationResults {
+    /** The configuration used for this simulation */
+    config: SimulationConfig;
+    /** Aggregate statistics across all runs */
+    summary: SimulationSummary;
+    /** Party configuration snapshot */
+    party: PartyConfig;
+    /** Encounter configuration snapshot */
+    encounter: EncounterConfig;
+    /** Per-combatant aggregate metrics keyed by combatant ID */
+    perCombatantMetrics: Map<string, CombatantSimulationMetrics>;
+    /**
+     * When enemyRegeneration is enabled, tracks per-enemy-type statistics
+     * aggregated across all runs. Each entry represents a unique enemy name
+     * that appeared during the simulation, with occurrence count and stat ranges.
+     */
+    enemyGenerationStats?: EnemyGenerationRecord[];
+    /** Detailed per-run data (only if collectDetailedLogs was true) */
+    runDetails?: SimulationRunDetail[];
+    /** Whether the simulation was cancelled before completing all requested runs */
+    wasCancelled: boolean;
+}
+/**
+ * Aggregated statistics for a unique enemy type across all simulation runs
+ * where enemyRegeneration was enabled.
+ */
+export interface EnemyGenerationRecord {
+    /** Enemy name (e.g., "Goblin Scout", "Orc Brute") */
+    name: string;
+    /** Number of runs this enemy appeared in */
+    count: number;
+    /** HP values observed across runs */
+    hpRange: {
+        min: number;
+        max: number;
+        avg: number;
+    };
+    /** AC values observed across runs */
+    acRange: {
+        min: number;
+        max: number;
+        avg: number;
+    };
+    /** CR values observed across runs */
+    crRange: {
+        min: number;
+        max: number;
+        avg: number;
+    };
+}
+/**
+ * CombatSimulator — Orchestrates Monte Carlo combat simulations.
+ *
+ * Runs N independent combat encounters using AI-controlled combatants,
+ * each with a unique seeded RNG for full determinism. Aggregates results
+ * into statistical summaries and per-combatant metrics.
+ *
+ * The simulator is stateless between `run()` calls — each call produces
+ * a fresh set of results.
+ */
+export declare class CombatSimulator {
+    /**
+     * Run a Monte Carlo combat simulation.
+     *
+     * Executes `config.runCount` independent combat simulations, each with
+     * a unique seed (`config.baseSeed + runIndex`). Results are aggregated
+     * into statistical summaries and per-combatant metrics.
+     *
+     * @param players - Player character sheets
+     * @param enemies - Enemy character sheets
+     * @param config - Simulation configuration (run count, seed, AI styles, etc.)
+     * @returns Complete simulation results with summary and per-combatant metrics
+     *
+     * @example
+     * ```ts
+     * const simulator = new CombatSimulator();
+     * const results = simulator.run(
+     *   myParty, myEnemies,
+     *   {
+     *     runCount: 1000,
+     *     baseSeed: 'balance-test-1',
+     *     aiConfig: { playerStyle: 'normal', enemyStyle: 'aggressive' },
+     *     onProgress: (done, total) => updateProgressBar(done / total),
+     *   }
+     * );
+     * console.log(`Player win rate: ${(results.summary.playerWinRate * 100).toFixed(1)}%`);
+     * ```
+     */
+    run(players: CharacterSheet[], enemies: CharacterSheet[], config: SimulationConfig): SimulationResults;
+}
+/**
+ * Accumulates per-run results and computes final aggregated statistics.
+ *
+ * Internal to CombatSimulator — not exported. Processes each run's
+ * CombatResult and CombatantMetrics, building up running totals that
+ * are finalized into SimulationResults when `getResults()` is called.
+ */
+export declare class SimulationAggregator {
+    private readonly config;
+    private readonly party;
+    private readonly encounter;
+    private playerWins;
+    private enemyWins;
+    private draws;
+    private roundsList;
+    private roundsOnWin;
+    private roundsOnLoss;
+    private playerHPPercentRemainingOnWin;
+    private playerDeathRounds;
+    private enemyDeathRounds;
+    private combatantAccumulators;
+    private runDetails;
+    private enemyGenTracker;
+    private readonly combatantIds;
+    constructor(config: SimulationConfig, players: CharacterSheet[], enemies: CharacterSheet[]);
+    /**
+     * Accumulate results from a single simulation run.
+     */
+    aggregateRun(runResult: {
+        combat: import('../../types/Combat.js').CombatInstance;
+        result: CombatResult;
+        metrics: Map<string, CombatantMetrics>;
+    }, runIndex: number, seed: string): void;
+    /**
+     * Compute final aggregated results from all accumulated runs.
+     */
+    getResults(wasCancelled?: boolean): SimulationResults;
+    private average;
+    private median;
+}
+/**
+ * Accumulates metrics for a single combatant across many simulation runs.
+ * Produces CombatantSimulationMetrics when finalized.
+ */
+export declare class CombatantAccumulator {
+    readonly id: string;
+    readonly name: string;
+    readonly side: 'player' | 'enemy';
+    private totalDamageDealtSum;
+    private totalDamageTakenSum;
+    private totalHealingDoneSum;
+    private roundsSurvivedSum;
+    private survivalCount;
+    private killCount;
+    private criticalHitSum;
+    private hitsSum;
+    private missesSum;
+    private totalAttackActions;
+    private spellsCastSum;
+    private actionTypeCounts;
+    private damagePerRoundList;
+    private hpRemainingList;
+    constructor(id: string, name: string, side: 'player' | 'enemy');
+    /**
+     * Accumulate metrics from a single run.
+     */
+    accumulate(m: CombatantMetrics, totalRounds: number): void;
+    /**
+     * Produce final aggregated metrics for this combatant.
+     */
+    toSimulationMetrics(totalRuns: number): CombatantSimulationMetrics;
+    private average;
+    private median;
+}
+//# sourceMappingURL=CombatSimulator.d.ts.map

package/dist/core/combat/Simulation/CombatSimulator.d.ts.map

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

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

@@ -0,0 +1,113 @@
+/**
+ * SpellCaster - Handles spell casting mechanics
+ * Manages spell slots, saving throws, and spell damage
+ */
+import type { Combatant, SpellCastResult, StatusEffectMechanics, DiceRollerAPI } from '../types/Combat';
+import type { Spell } from '../types/Character';
+/**
+ * SpellCaster - D&D 5e spell casting system
+ */
+export declare class SpellCaster {
+    private diceRoller?;
+    constructor(diceRoller?: DiceRollerAPI);
+    /**
+     * Cast a spell at one or more targets
+     * Handles:
+     * - Spell slot consumption
+     * - Spell attack rolls (if applicable)
+     * - Saving throws (if applicable)
+     * - Damage calculation
+     */
+    castSpell(caster: Combatant, spell: Spell, targets: Combatant[]): SpellCastResult;
+    /**
+     * Check if caster has a spell slot of the given level
+     */
+    hasSpellSlot(caster: Combatant, spellLevel: number): boolean;
+    /**
+     * Consume a spell slot
+     */
+    consumeSpellSlot(caster: Combatant, spellLevel: number): void;
+    /**
+     * Restore spell slots (e.g., after long rest)
+     * For simplicity, restores ALL spell slots to maximum
+     */
+    restoreSpellSlots(caster: Combatant): void;
+    /**
+     * Calculate spell save DC
+     * DC = 8 + spellcasting ability modifier + proficiency bonus
+     */
+    calculateSaveDC(caster: Combatant, ability: string): number;
+    /**
+     * Make a saving throw against a spell
+     * Returns true if save succeeds, false if fails
+     *
+     * @param target - The combatant making the save
+     * @param saveAbility - The ability score used for the save (e.g., 'dexterity')
+     * @param saveDC - The difficulty class to meet or exceed
+     * @param disadvantage - If true, roll with disadvantage (roll twice, take lower)
+     */
+    makeSavingThrow(target: Combatant, saveAbility: string, saveDC: number, disadvantage?: boolean): boolean;
+    /**
+     * Get spell slot information for a caster
+     */
+    getSpellSlotInfo(caster: Combatant): string;
+    /**
+     * Check if a spell can be upcast
+     * Upcasting is when a spell is cast using a higher-level spell slot
+     */
+    canUpcast(caster: Combatant, spell: Spell, targetSlotLevel: number): boolean;
+    /**
+     * Upcast a spell (cast it using a higher spell slot)
+     */
+    upcastSpell(caster: Combatant, spell: Spell, targets: Combatant[], slotLevelUsed: number): SpellCastResult;
+    /**
+     * Check if a spell has a specific tag.
+     * Tags are set on enemy InnateSpell objects and used by the AI
+     * for spell classification and decision-making.
+     */
+    static hasSpellTag(spell: Spell, tag: string): boolean;
+    /**
+     * Get all tags for a spell.
+     * Returns an empty array if the spell has no tags.
+     */
+    static getSpellTags(spell: Spell): string[];
+    /**
+     * Check if a spell deals damage.
+     * Uses tags (preferred) or falls back to checking damage dice fields.
+     */
+    static isDamageSpell(spell: Spell): boolean;
+    /**
+     * Check if a spell requires concentration.
+     */
+    static requiresConcentration(spell: Spell): boolean;
+    /**
+     * Check if a spell has an area-of-effect component.
+     */
+    static isAOESpell(spell: Spell): boolean;
+    /**
+     * Check if a spell targets multiple creatures.
+     */
+    static isMultiTargetSpell(spell: Spell): boolean;
+    /**
+     * Check if a spell can be used as a bonus action.
+     */
+    static isBonusActionSpell(spell: Spell): boolean;
+    /**
+     * Check if a spell can only target allies (healing, buffs).
+     */
+    static isAllySpell(spell: Spell): boolean;
+    /**
+     * Check if a spell only targets the caster.
+     */
+    static isSelfSpell(spell: Spell): boolean;
+    /**
+     * Get the tag-to-status-effect mapping.
+     * Used by tests and the AI to understand which tags produce which effects.
+     */
+    static getStatusEffectTags(): Readonly<Record<string, {
+        name: string;
+        requiresConcentration: boolean;
+        mechanicalEffects?: StatusEffectMechanics;
+    }>>;
+}
+//# sourceMappingURL=SpellCaster.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SpellCaster.d.ts","sourceRoot":"","sources":["../../../src/core/combat/SpellCaster.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAgB,qBAAqB,EAAc,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClI,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAoFhD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,UAAU,CAAC,CAAgB;gBAEvB,UAAU,CAAC,EAAE,aAAa;IAGtC;;;;;;;OAOG;IACH,SAAS,CACP,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,SAAS,EAAE,GACnB,eAAe;IAuIlB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAY5D;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAgB7D;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAI1C;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAQ3D;;;;;;;;OAQG;IACH,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAE,OAAe,GAAG,OAAO;IA2B/G;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM;IAgB3C;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO;IAS5E;;OAEG;IACH,WAAW,CACT,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,SAAS,EAAE,EACpB,aAAa,EAAE,MAAM,GACpB,eAAe;IA4BlB;;;;OAIG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAItD;;;OAGG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE;IAI3C;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAK3C;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAInD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIxC;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIhD;;OAEG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIhD;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIzC;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAIzC;;;OAGG;IACH,MAAM,CAAC,mBAAmB,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QACpD,IAAI,EAAE,MAAM,CAAC;QACb,qBAAqB,EAAE,OAAO,CAAC;QAC/B,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;KAC3C,CAAC,CAAC;CAGJ"}

package/dist/core/config/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sensor Configuration Module
+ *
+ * Centralized configuration for all sensor modules including:
+ * - Environmental sensors (geolocation, weather, motion)
+ * - Gaming platform sensors (Steam)
+ * - XP modifier calculation
+ * - Caching and retry behavior
+ *
+ * @example
+ * import { SensorConfig, mergeConfig, DEFAULT_SENSOR_CONFIG } from './core/config';
+ *
+ * // Use defaults
+ * const config = mergeConfig();
+ *
+ * // Override specific values
+ * const customConfig = mergeConfig({
+ *   weather: { cacheTTL: 15 * 60 * 1000 }, // 15 minutes
+ *   xpModifier: { maxModifier: 2.5 }
+ * });
+ */
+export type { SensorConfig, CacheConfig, GeolocationSensorConfig, WeatherSensorConfig, GamingSensorConfig, XPModifierConfig, RetryConfig, } from './sensorConfig.js';
+export { DEFAULT_SENSOR_CONFIG, loadConfigFromEnv, mergeConfig, } from './sensorConfig.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACR,YAAY,EACZ,WAAW,EACX,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,GACd,MAAM,mBAAmB,CAAC"}

package/dist/core/config/progressionConfig.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Progression System Configuration
+ *
+ * Centralized configuration for the progression system including:
+ * - XP calculation settings
+ * - Stat increase settings
+ * - Level up settings
+ * - Rhythm game XP settings
+ *
+ * Follows the pattern of sensorConfig.ts for consistency
+ */
+import type { StatIncreaseConfig } from '../types/Progression.js';
+import type { RhythmXPConfig } from '../types/RhythmXP.js';
+/**
+ * Complete progression system configuration
+ */
+export interface ProgressionConfig {
+    /** XP calculation configuration */
+    xp: {
+        level_thresholds: number[];
+        xp_per_second: number;
+        xp_per_track_completion: number;
+        activity_bonuses: {
+            stationary: number;
+            walking: number;
+            running: number;
+            driving: number;
+            night_time: number;
+            extreme_weather: number;
+            high_altitude: number;
+            rhythm_game_base: number;
+            rhythm_game_combo: number;
+            rhythm_game_groove: number;
+        };
+        track_mastery_threshold: number;
+        mastery_bonus_xp: number;
+        /** Rhythm game XP configuration (optional) */
+        rhythmXP?: Partial<RhythmXPConfig>;
+    };
+    /** Stat increase configuration */
+    statIncrease: Partial<StatIncreaseConfig>;
+    /** Level up configuration */
+    levelUp: {
+        /** Use average HP instead of rolling (default: false) */
+        useAverageHP: boolean;
+        /** Allow manual selection of stats during level up (default: true) */
+        allowManualStatSelection: boolean;
+        /** Show level up notifications (default: true) */
+        showNotifications: boolean;
+    };
+}
+/**
+ * Default progression configuration
+ */
+export declare const DEFAULT_PROGRESSION_CONFIG: Required<ProgressionConfig>;
+/**
+ * Merge user config with defaults
+ *
+ * @param userConfig - Partial configuration to override defaults
+ * @returns Merged configuration
+ *
+ * @example
+ * ```typescript
+ * const config = mergeProgressionConfig({
+ *   statIncrease: {
+ *     strategy: 'dnD5e_smart',
+ *     autoApply: true
+ *   }
+ * });
+ * ```
+ */
+export declare function mergeProgressionConfig(userConfig?: Partial<ProgressionConfig>): Required<ProgressionConfig>;
+//# sourceMappingURL=progressionConfig.d.ts.map

package/dist/core/config/progressionConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progressionConfig.d.ts","sourceRoot":"","sources":["../../../src/core/config/progressionConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,mCAAmC;IACnC,EAAE,EAAE;QACA,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;QACtB,uBAAuB,EAAE,MAAM,CAAC;QAChC,gBAAgB,EAAE;YACd,UAAU,EAAE,MAAM,CAAC;YACnB,OAAO,EAAE,MAAM,CAAC;YAChB,OAAO,EAAE,MAAM,CAAC;YAChB,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;YACnB,eAAe,EAAE,MAAM,CAAC;YACxB,aAAa,EAAE,MAAM,CAAC;YAEtB,gBAAgB,EAAE,MAAM,CAAC;YACzB,iBAAiB,EAAE,MAAM,CAAC;YAC1B,kBAAkB,EAAE,MAAM,CAAC;SAC9B,CAAC;QACF,uBAAuB,EAAE,MAAM,CAAC;QAChC,gBAAgB,EAAE,MAAM,CAAC;QACzB,8CAA8C;QAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;KACtC,CAAC;IAEF,kCAAkC;IAClC,YAAY,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE1C,6BAA6B;IAC7B,OAAO,EAAE;QACL,yDAAyD;QACzD,YAAY,EAAE,OAAO,CAAC;QAEtB,sEAAsE;QACtE,wBAAwB,EAAE,OAAO,CAAC;QAElC,kDAAkD;QAClD,iBAAiB,EAAE,OAAO,CAAC;KAC9B,CAAC;CACL;AAUD;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,iBAAiB,CAiClE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAClC,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACxC,QAAQ,CAAC,iBAAiB,CAAC,CAuB7B"}