larissa_progressionSystem.js

import { Component } from "../components/component.js";

/**
 * Validates that a value is a finite number greater than or equal to a minimum.
 * @param {number} value
 * @param {string} name
 * @param {number} [min=0]
 * @returns {number}
 */
function finiteNumber(value, name, min = 0) {
    if (typeof value !== "number" || !Number.isFinite(value) || value < min) {
        throw new TypeError(`${name} must be a finite number >= ${min}`);
    }
    return value;
}

/**
 * Validates that a value is a non-empty string.
 * @param {string} value
 * @param {string} name
 * @returns {string}
 */
function nonEmptyString(value, name) {
    if (typeof value !== "string" || !value.trim()) {
        throw new TypeError(`${name} must be a non-empty string`);
    }
    return value.trim();
}

/**
 * Manages experience curves, multi-level increments, and stat scaling per level.
 */
export class LevelProgression extends Component {
    /**
     * @param {Object} [config]
     * @param {number} [config.level=1]
     * @param {number} [config.experience=0]
     * @param {number} [config.baseExperience=100]
     * @param {number} [config.growthRate=1.5]
     * @param {number} [config.maxLevel=100]
     * @param {Object} [config.statGains] Stat increases per level
     * @param {Object} [config.baseStats] Initial stats at level 1
     */
    constructor({
        level = 1,
        experience = 0,
        baseExperience = 100,
        growthRate = 1.5,
        maxLevel = 100,
        statGains = {},
        baseStats = {}
    } = {}) {
        super();
        if (!Number.isInteger(level) || level < 1) throw new RangeError("Level must be a positive integer");
        finiteNumber(experience, "experience", 0);
        finiteNumber(baseExperience, "baseExperience", 1);
        finiteNumber(growthRate, "growthRate", 1);
        if (!Number.isInteger(maxLevel) || maxLevel < 1) throw new RangeError("maxLevel must be a positive integer");

        this.level = Math.min(level, maxLevel);
        this.experience = experience;
        this.baseExperience = baseExperience;
        this.growthRate = growthRate;
        this.maxLevel = maxLevel;
        this.statGains = { ...statGains };
        this.baseStats = { ...baseStats };
        this.statPoints = 0;
        this.unspentStatPoints = 0;
        this.statPointsPerLevel = 3;
        this.listeners = new Set();
    }

    /**
     * Calculate experience needed to advance from given level to next.
     * @param {number} [level=this.level]
     * @returns {number}
     */
    experienceToNextLevel(level = this.level) {
        if (level >= this.maxLevel) return Infinity;
        return Math.floor(this.baseExperience * (this.growthRate ** (level - 1)));
    }

    /**
     * Add a listener for progression events (level-up, exp-gained).
     * @param {Function} listener
     * @returns {Function} Unsubscribe function
     */
    onProgression(listener) {
        if (typeof listener !== "function") throw new TypeError("Listener must be a function");
        this.listeners.add(listener);
        return () => this.listeners.delete(listener);
    }

    _emit(event) {
        for (const listener of this.listeners) {
            listener(event);
        }
    }

    /**
     * Grant experience, potentially climbing multiple levels in one call.
     * @param {number} amount
     * @returns {Array} Array of level numbers reached
     */
    grantExperience(amount) {
        finiteNumber(amount, "amount", 0);
        if (amount === 0 || this.level >= this.maxLevel) return [];

        this.experience += amount;
        this._emit({ type: "experience-gained", amount, totalExperience: this.experience });

        const levelsGained = [];
        while (this.level < this.maxLevel && this.experience >= this.experienceToNextLevel()) {
            this.experience -= this.experienceToNextLevel();
            this.level += 1;
            this.statPoints += this.statPointsPerLevel;
            this.unspentStatPoints += this.statPointsPerLevel;
            levelsGained.push(this.level);

            this._emit({
                type: "level-up",
                level: this.level,
                remainingExperience: this.experience,
                statPointsAwarded: this.statPointsPerLevel,
                stats: this.getCalculatedStats()
            });
        }

        if (this.level >= this.maxLevel) {
            this.experience = 0;
        }

        return levelsGained;
    }

    /**
     * Get computed total stats for the current level.
     * @returns {Object}
     */
    getCalculatedStats() {
        const result = { ...this.baseStats };
        const levelOffset = this.level - 1;
        for (const [stat, gain] of Object.entries(this.statGains)) {
            const current = result[stat] ?? 0;
            result[stat] = current + (gain * levelOffset);
        }
        return result;
    }

    /**
     * Apply calculated stats to a Combatant or Stats component.
     * @param {Object} target
     */
    applyToTarget(target) {
        if (!target || typeof target !== "object") return;
        const stats = this.getCalculatedStats();
        if (typeof target.maxHealth === "number" && stats.maxHealth) {
            target.maxHealth = stats.maxHealth;
            if (target.health > target.maxHealth) target.health = target.maxHealth;
        }
        if (target.stats && typeof target.stats === "object") {
            Object.assign(target.stats, stats);
        }
    }

    /**
     * Create snapshot for serialization.
     * @returns {Object}
     */
    toJSON() {
        return {
            level: this.level,
            experience: this.experience,
            baseExperience: this.baseExperience,
            growthRate: this.growthRate,
            maxLevel: this.maxLevel,
            statGains: { ...this.statGains },
            baseStats: { ...this.baseStats },
            statPoints: this.statPoints,
            unspentStatPoints: this.unspentStatPoints,
            statPointsPerLevel: this.statPointsPerLevel
        };
    }

    /**
     * Restore from serialized state.
     * @param {Object} data
     * @returns {LevelProgression}
     */
    static fromJSON(data) {
        if (!data || typeof data !== "object") throw new TypeError("data must be an object");
        const progression = new LevelProgression(data);
        if (Number.isInteger(data.statPoints)) progression.statPoints = data.statPoints;
        if (Number.isInteger(data.unspentStatPoints)) progression.unspentStatPoints = data.unspentStatPoints;
        if (Number.isInteger(data.statPointsPerLevel)) progression.statPointsPerLevel = data.statPointsPerLevel;
        return progression;
    }
}

/**
 * Manages timed and periodic status effects with stacking rules (replace, duration_stack, intensity_stack, independent).
 */
export class StatusEffectManager extends Component {
    /**
     * @param {Object} [config]
     * @param {Object} [config.target] Target combatant or entity
     */
    constructor({ target = null } = {}) {
        super();
        this.target = target;
        this.effects = [];
        this.listeners = new Set();
        this._isPaused = false;
    }

    /**
     * Set paused state. When paused, effect durations and tick intervals do not advance.
     * @param {boolean} paused
     */
    setPaused(paused) {
        this._isPaused = Boolean(paused);
    }

    get isPaused() {
        return this._isPaused;
    }

    /**
     * Listen for status events: applied, refreshed, ticked, expired, cleansed.
     * @param {Function} listener
     * @returns {Function} Unsubscribe
     */
    onStatusEvent(listener) {
        if (typeof listener !== "function") throw new TypeError("Listener must be a function");
        this.listeners.add(listener);
        return () => this.listeners.delete(listener);
    }

    _emit(event) {
        for (const listener of this.listeners) {
            listener(event);
        }
    }

    /**
     * Apply or stack a status effect.
     * @param {Object} effectConfig
     * @param {string} effectConfig.name Unique effect identifier
     * @param {number} effectConfig.duration Duration in seconds
     * @param {string} [effectConfig.stackMode="replace"] 'replace'|'duration_stack'|'intensity_stack'|'independent'
     * @param {number} [effectConfig.maxStacks=5] Max stacks allowed for intensity_stack
     * @param {number} [effectConfig.maxDuration=60] Max duration for duration_stack
     * @param {number} [effectConfig.intensity=1] Initial intensity/multiplier
     * @param {Object} [effectConfig.modifiers={}] Stat multipliers or deltas
     * @param {number} [effectConfig.tickInterval=0] Periodic interval in seconds (0 = no periodic tick)
     * @param {Function} [effectConfig.onTick] Callback on periodic tick: (effect, target) => void
     * @param {string} [effectConfig.category="neutral"] 'buff'|'debuff'|'neutral'
     * @param {Array<string>} [effectConfig.tags=[]] Categorical tags (e.g. ['poison', 'curse'])
     * @returns {Object} The active effect record
     */
    applyEffect(effectConfig) {
        if (!effectConfig || typeof effectConfig !== "object") throw new TypeError("effectConfig must be an object");
        const name = nonEmptyString(effectConfig.name, "effectConfig.name");
        const duration = finiteNumber(effectConfig.duration, "effectConfig.duration", 0.001);
        const stackMode = effectConfig.stackMode ?? "replace";
        const maxStacks = effectConfig.maxStacks ?? 5;
        const maxDuration = effectConfig.maxDuration ?? 60;
        const intensity = effectConfig.intensity ?? 1;
        const modifiers = { ...(effectConfig.modifiers ?? {}) };
        const tickInterval = effectConfig.tickInterval ?? 0;
        const onTick = typeof effectConfig.onTick === "function" ? effectConfig.onTick : null;
        const category = effectConfig.category ?? "neutral";
        const tags = Array.isArray(effectConfig.tags) ? [...effectConfig.tags] : [];

        let record;
        const existing = this.effects.find(e => e.name === name);

        if (existing && stackMode !== "independent") {
            if (stackMode === "replace") {
                existing.duration = duration;
                existing.maxDuration = Math.max(existing.maxDuration, duration);
                existing.intensity = intensity;
                existing.modifiers = modifiers;
                existing.tickTimer = 0;
                record = existing;
                this._emit({ type: "refreshed", effect: record, stackMode });
            } else if (stackMode === "duration_stack") {
                existing.duration = Math.min(maxDuration, existing.duration + duration);
                existing.modifiers = modifiers;
                record = existing;
                this._emit({ type: "refreshed", effect: record, stackMode });
            } else if (stackMode === "intensity_stack") {
                existing.stacks = Math.min(maxStacks, (existing.stacks ?? 1) + 1);
                existing.duration = duration; // Refresh duration on new stack
                existing.modifiers = modifiers;
                record = existing;
                this._emit({ type: "stacked", effect: record, stacks: existing.stacks });
            }
        } else {
            record = {
                id: `${name}_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`,
                name,
                duration,
                maxDuration: Math.max(duration, maxDuration),
                stackMode,
                stacks: 1,
                maxStacks,
                intensity,
                modifiers,
                tickInterval,
                tickTimer: 0,
                onTick,
                category,
                tags
            };
            this.effects.push(record);
            this._emit({ type: "applied", effect: record });
        }

        return record;
    }

    /**
     * Advance elapsed time for active effects.
     * When paused, timers do not decrement and no periodic ticks fire.
     * @param {number} deltaTime
     * @param {Object} [options]
     * @param {boolean} [options.paused=false]
     */
    update(deltaTime, { paused = false } = {}) {
        finiteNumber(deltaTime, "deltaTime", 0);
        if (this._isPaused || paused || deltaTime === 0) return;

        const remaining = [];
        for (const effect of this.effects) {
            effect.duration -= deltaTime;

            // Handle periodic ticks
            if (effect.tickInterval > 0) {
                effect.tickTimer += deltaTime;
                while (effect.tickTimer >= effect.tickInterval) {
                    effect.tickTimer -= effect.tickInterval;
                    if (effect.onTick) {
                        effect.onTick(effect, this.target);
                    }
                    this._emit({ type: "ticked", effect, target: this.target });
                }
            }

            if (effect.duration > 0) {
                remaining.push(effect);
            } else {
                this._emit({ type: "expired", effect });
            }
        }

        this.effects = remaining;
    }

    /**
     * Remove all effects matching a tag or category.
     * @param {string} tagOrCategory E.g. 'poison', 'debuff', 'buff'
     * @returns {number} Count of removed effects
     */
    cleanse(tagOrCategory) {
        nonEmptyString(tagOrCategory, "tagOrCategory");
        const before = this.effects.length;
        const retained = [];
        for (const effect of this.effects) {
            const matches = effect.category === tagOrCategory || effect.tags.includes(tagOrCategory) || effect.name === tagOrCategory;
            if (matches) {
                this._emit({ type: "cleansed", effect });
            } else {
                retained.push(effect);
            }
        }
        this.effects = retained;
        return before - retained.length;
    }

    /**
     * Clear all active status effects unconditionally.
     */
    clearAll() {
        for (const effect of this.effects) {
            this._emit({ type: "cleansed", effect });
        }
        this.effects = [];
    }

    /**
     * Calculate compound stat multiplier across all active status effects.
     * For intensity_stack effects, multiplier applies per stack: 1 + (mod - 1) * stacks.
     * @param {string} stat Name of stat
     * @param {number} [baseValue=1]
     * @returns {number}
     */
    getModifiedStat(stat, baseValue = 1) {
        let value = baseValue;
        for (const effect of this.effects) {
            if (Object.hasOwn(effect.modifiers, stat)) {
                const multiplier = effect.modifiers[stat];
                if (effect.stackMode === "intensity_stack" && effect.stacks > 1) {
                    const delta = multiplier - 1;
                    value *= (1 + (delta * effect.stacks));
                } else {
                    value *= multiplier;
                }
            }
        }
        return value;
    }

    /**
     * Check if a status effect is active by name.
     * @param {string} name
     * @returns {boolean}
     */
    hasEffect(name) {
        return this.effects.some(e => e.name === name);
    }

    /**
     * Get effect record by name.
     * @param {string} name
     * @returns {Object|null}
     */
    getEffect(name) {
        return this.effects.find(e => e.name === name) ?? null;
    }

    toJSON() {
        return {
            effects: this.effects.map(e => ({
                name: e.name,
                duration: e.duration,
                maxDuration: e.maxDuration,
                stackMode: e.stackMode,
                stacks: e.stacks,
                maxStacks: e.maxStacks,
                intensity: e.intensity,
                modifiers: { ...e.modifiers },
                tickInterval: e.tickInterval,
                category: e.category,
                tags: [...e.tags]
            })),
            isPaused: this._isPaused
        };
    }

    static fromJSON(data) {
        const manager = new StatusEffectManager();
        if (data && Array.isArray(data.effects)) {
            for (const item of data.effects) {
                manager.applyEffect(item);
            }
        }
        if (data && typeof data.isPaused === "boolean") {
            manager.setPaused(data.isPaused);
        }
        return manager;
    }
}

/**
 * Handles death, retry cycles, checkpoint restoration, and progression penalties.
 */
export class DeathRetryManager extends Component {
    /**
     * @param {Object} [config]
     * @param {Object} [config.target] Player combatant/entity
     * @param {LevelProgression} [config.progression] Progression system
     * @param {StatusEffectManager} [config.statusManager] Status effect manager
     * @param {number} [config.experienceLossRatio=0.1] Ratio of unspent experience lost on death (0.0 to 1.0)
     */
    constructor({
        target = null,
        progression = null,
        statusManager = null,
        experienceLossRatio = 0.1
    } = {}) {
        super();
        this.target = target;
        this.progression = progression;
        this.statusManager = statusManager;
        this.experienceLossRatio = Math.max(0, Math.min(1, experienceLossRatio));
        this.checkpoint = null;
        this.deathCount = 0;
        this.retryCount = 0;
        this.isDead = false;
        this.listeners = new Set();
    }

    onDeathRetryEvent(listener) {
        if (typeof listener !== "function") throw new TypeError("Listener must be a function");
        this.listeners.add(listener);
        return () => this.listeners.delete(listener);
    }

    _emit(event) {
        for (const listener of this.listeners) {
            listener(event);
        }
    }

    /**
     * Save current game state as the active checkpoint.
     * @param {Object} [metadata={}] Optional scene, position, or flag data
     * @returns {Object} Checkpoint snapshot
     */
    recordCheckpoint(metadata = {}) {
        this.checkpoint = {
            timestamp: Date.now(),
            progression: this.progression ? this.progression.toJSON() : null,
            targetHealth: this.target?.health ?? null,
            targetMaxHealth: this.target?.maxHealth ?? null,
            metadata: { ...metadata }
        };
        this._emit({ type: "checkpoint-saved", checkpoint: this.checkpoint });
        return this.checkpoint;
    }

    /**
     * Process actor death: cleanses temporary buffs/debuffs, applies experience penalty.
     * @returns {Object} Death summary
     */
    handleDeath() {
        this.isDead = true;
        this.deathCount += 1;

        let expLost = 0;
        if (this.progression && this.experienceLossRatio > 0) {
            expLost = Math.floor(this.progression.experience * this.experienceLossRatio);
            this.progression.experience = Math.max(0, this.progression.experience - expLost);
        }

        // Cleanse temporary effects on death so dead actor doesn't keep ticking buffs
        if (this.statusManager) {
            this.statusManager.clearAll();
        }

        const summary = {
            deathCount: this.deathCount,
            experienceLost: expLost,
            remainingExperience: this.progression?.experience ?? 0,
            hasCheckpoint: this.checkpoint !== null
        };

        this._emit({ type: "death", ...summary });
        return summary;
    }

    /**
     * Retry from last checkpoint. Restores health, resets dead status, and applies checkpoint progression.
     * Can be invoked repeatedly across multiple death cycles without state corruption.
     * @returns {Object} Retry result
     */
    retry() {
        if (!this.checkpoint) {
            // Fallback retry without checkpoint: restore target health to max
            this.isDead = false;
            this.retryCount += 1;
            if (this.target) {
                if (typeof this.target.maxHealth === "number") {
                    this.target.health = this.target.maxHealth;
                }
                if (typeof this.target.isAlive === "boolean") {
                    this.target.isAlive = true;
                }
            }
            if (this.statusManager) {
                this.statusManager.clearAll();
            }
            const fallbackResult = {
                retryCount: this.retryCount,
                restoredFromCheckpoint: false,
                currentHealth: this.target?.health ?? 0
            };
            this._emit({ type: "retry", ...fallbackResult });
            return fallbackResult;
        }

        this.isDead = false;
        this.retryCount += 1;

        // Restore target health
        if (this.target) {
            const maxHp = this.checkpoint.targetMaxHealth ?? this.target.maxHealth ?? 100;
            this.target.maxHealth = maxHp;
            this.target.health = maxHp;
            if (typeof this.target.isAlive === "boolean") {
                this.target.isAlive = true;
            }
        }

        // Clear any leftover status effects
        if (this.statusManager) {
            this.statusManager.clearAll();
        }

        const result = {
            retryCount: this.retryCount,
            restoredFromCheckpoint: true,
            checkpoint: this.checkpoint,
            currentHealth: this.target?.health ?? 0
        };

        this._emit({ type: "retry", ...result });
        return result;
    }

    toJSON() {
        return {
            deathCount: this.deathCount,
            retryCount: this.retryCount,
            isDead: this.isDead,
            experienceLossRatio: this.experienceLossRatio,
            checkpoint: this.checkpoint ? structuredClone(this.checkpoint) : null
        };
    }

    static fromJSON(data, { target = null, progression = null, statusManager = null } = {}) {
        const manager = new DeathRetryManager({
            target,
            progression,
            statusManager,
            experienceLossRatio: data.experienceLossRatio ?? 0.1
        });
        manager.deathCount = data.deathCount ?? 0;
        manager.retryCount = data.retryCount ?? 0;
        manager.isDead = Boolean(data.isDead);
        manager.checkpoint = data.checkpoint ? structuredClone(data.checkpoint) : null;
        return manager;
    }
}