larissa_itemSystem.js

/**
 * Larissa RPG System - Item, Inventory, Equipment, and Loot Systems
 * RPG-01: Validated item registry, slot-based inventory with capacity and stacking,
 * designated equipment slots with stat modifier binding and slot protection,
 * weighted loot table generator with min/max quantities, and persistence snapshots.
 */

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

/**
 * Designated equipment slots supported by the equipment system.
 * @type {Array.<string>}
 */
export const EQUIPMENT_SLOTS = Object.freeze(["mainHand", "offHand", "armor", "accessory"]);

/**
 * Validate that an equipment slot name is one of the designated slots.
 * @param {string} slot
 * @returns {boolean}
 */
export function isValidEquipmentSlot(slot) {
    return typeof slot === "string" && EQUIPMENT_SLOTS.includes(slot);
}

/**
 * Deep-freeze a plain object or array to ensure immutability.
 * @param {Object} value
 * @returns {Object}
 */
function deepFreeze(value) {
    if (value && typeof value === "object" && !Object.isFrozen(value)) {
        for (const child of Object.values(value)) {
            deepFreeze(child);
        }
        Object.freeze(value);
    }
    return value;
}

/**
 * Registry for item definitions.
 */
export class ItemRegistry {
    /**
     * @param {Array.<Object>|Object} [items] - Initial item definitions.
     */
    constructor(items = []) {
        /** @type {Map.<string, Object>} */
        this._items = new Map();

        if (Array.isArray(items)) {
            for (const item of items) {
                this.register(item);
            }
        } else if (items && typeof items === "object") {
            for (const item of Object.values(items)) {
                this.register(item);
            }
        }
    }

    /**
     * Register an item definition.
     * @param {Object} itemDef - Item definition object.
     * @returns {Object} Registered immutable item definition.
     */
    register(itemDef) {
        if (!itemDef || typeof itemDef !== "object" || Array.isArray(itemDef)) {
            throw new TypeError("Item definition must be an object");
        }
        if (typeof itemDef.id !== "string" || !itemDef.id.trim()) {
            throw new TypeError("Item id must be a non-empty string");
        }

        const id = itemDef.id.trim();
        const type = typeof itemDef.type === "string" ? itemDef.type : "misc";
        const name = typeof itemDef.name === "string" ? itemDef.name : id;
        const description = typeof itemDef.description === "string" ? itemDef.description : "";

        // Resolve maxStack / stackable
        let maxStack = 1;
        if (Number.isInteger(itemDef.maxStack) && itemDef.maxStack >= 1) {
            maxStack = itemDef.maxStack;
        } else if (Number.isInteger(itemDef.stackable) && itemDef.stackable >= 1) {
            maxStack = itemDef.stackable;
        } else if (type === "consumable") {
            maxStack = 99;
        }

        const value = Number.isFinite(itemDef.value) ? Math.max(0, itemDef.value) : 0;

        // Resolve designated equipment slot
        let slot = itemDef.slot ?? null;
        let allowedSlots = [];
        if (Array.isArray(itemDef.allowedSlots)) {
            allowedSlots = itemDef.allowedSlots.filter(s => isValidEquipmentSlot(s));
        }
        if (!slot) {
            if (type === "weapon") slot = "mainHand";
            else if (type === "armor") slot = "armor";
            else if (type === "accessory") slot = "accessory";
        }
        if (typeof slot === "string" && !allowedSlots.includes(slot)) {
            allowedSlots.push(slot);
        }

        // Normalize stat modifiers
        const stats = {};
        const sourceStats = itemDef.stats ?? itemDef.statModifiers ?? {};
        if (sourceStats && typeof sourceStats === "object") {
            for (const [statKey, statVal] of Object.entries(sourceStats)) {
                if (Number.isFinite(statVal)) {
                    stats[statKey] = statVal;
                }
            }
        }

        // Normalize effects
        const effects = {};
        const sourceEffects = itemDef.effects ?? {};
        if (sourceEffects && typeof sourceEffects === "object") {
            if (Number.isFinite(sourceEffects.health)) effects.health = sourceEffects.health;
            if (Number.isFinite(sourceEffects.stamina)) effects.stamina = sourceEffects.stamina;
            if (sourceEffects.stats && typeof sourceEffects.stats === "object") {
                effects.stats = { ...sourceEffects.stats };
            }
            if (sourceEffects.statModifiers && typeof sourceEffects.statModifiers === "object") {
                effects.stats = { ...sourceEffects.statModifiers };
            }
            if (sourceEffects.statusEffect && typeof sourceEffects.statusEffect === "object") {
                effects.statusEffect = structuredClone(sourceEffects.statusEffect);
            }
        }

        const registered = {
            ...itemDef,
            id,
            name,
            type,
            slot,
            allowedSlots: Object.freeze(allowedSlots),
            maxStack,
            stackable: maxStack,
            value,
            stats: Object.freeze(stats),
            statModifiers: Object.freeze(stats),
            effects: deepFreeze(effects),
            description
        };

        deepFreeze(registered);
        this._items.set(id, registered);
        return registered;
    }

    /**
     * Alias for register.
     * @param {Object} itemDef
     * @returns {Object}
     */
    registerItem(itemDef) {
        return this.register(itemDef);
    }

    /**
     * Retrieve an item definition by id.
     * @param {string} id
     * @returns {Object|null}
     */
    get(id) {
        if (typeof id !== "string") return null;
        return this._items.get(id) ?? null;
    }

    /**
     * Alias for get.
     * @param {string} id
     * @returns {Object|null}
     */
    getItem(id) {
        return this.get(id);
    }

    /**
     * Check if an item id exists.
     * @param {string} id
     * @returns {boolean}
     */
    has(id) {
        if (typeof id !== "string") return false;
        return this._items.has(id);
    }

    /**
     * Alias for has.
     * @param {string} id
     * @returns {boolean}
     */
    hasItem(id) {
        return this.has(id);
    }

    /**
     * Unregister an item by id.
     * @param {string} id
     * @returns {boolean}
     */
    unregister(id) {
        if (typeof id !== "string") return false;
        return this._items.delete(id);
    }

    /**
     * Get all registered items.
     * @returns {Array.<Object>}
     */
    getAll() {
        return Array.from(this._items.values());
    }

    /**
     * Clear all registered items.
     */
    clear() {
        this._items.clear();
    }
}

/**
 * Equipment system managing designated slots (mainHand, offHand, armor, accessory),
 * stat modifier binding to Combatant/Stats, and incompatible slot rejection.
 */
export class EquipmentSystem extends Component {
    /**
     * @param {Object} [config]
     */
    constructor(config = {}) {
        super();
        const target = config.target ?? null;
        this.target = target;
        this.inventory = config.inventory ?? null;

        // Designated slots: mainHand, offHand, armor, accessory
        this.slots = {
            mainHand: null,
            offHand: null,
            armor: null,
            accessory: null
        };

        // Aliases for legacy compatibility
        Object.defineProperties(this.slots, {
            hand: {
                get: () => this.slots.mainHand,
                set: (val) => { this.slots.mainHand = val; },
                enumerable: false,
                configurable: true
            },
            weapon: {
                get: () => this.slots.mainHand,
                set: (val) => { this.slots.mainHand = val; },
                enumerable: false,
                configurable: true
            }
        });

        this.onEquip = null;
        this.onUnequip = null;
    }

    /**
     * Bind a Combatant, Stats, or composite target to receive equipment stat modifiers.
     * @param {Object} target
     * @returns {EquipmentSystem}
     */
    bindTarget(target) {
        if (this.target && this.target !== target) {
            this.unbindTarget();
        }
        this.target = target;
        // Apply existing equipped items' stats to newly bound target
        if (this.target) {
            for (const item of Object.values(this.slots)) {
                if (item) {
                    this._applyStats(item, this.target);
                }
            }
        }
        return this;
    }

    /**
     * Unbind current target, reverting any applied stat modifiers.
     * @returns {boolean}
     */
    unbindTarget() {
        if (!this.target) return false;
        for (const item of Object.values(this.slots)) {
            if (item) {
                this._revertStats(item, this.target);
            }
        }
        this.target = null;
        return true;
    }

    /**
     * Normalize slot name, mapping aliases like 'hand' or 'weapon' to 'mainHand'.
     * @param {string} slot
     * @returns {string|null}
     */
    normalizeSlot(slot) {
        if (typeof slot !== "string") return null;
        const normalized = slot.trim();
        if (normalized === "hand" || normalized === "weapon") return "mainHand";
        if (EQUIPMENT_SLOTS.includes(normalized)) return normalized;
        return null;
    }

    /**
     * Check if an item can be equipped into a designated slot.
     * Rejects incompatible items, consumables, or unknown slots.
     * @param {string} slot
     * @param {Object} item
     * @returns {boolean}
     */
    canEquip(slot, item) {
        const designatedSlot = this.normalizeSlot(slot);
        if (!designatedSlot) return false;
        if (!item || typeof item !== "object") return false;

        // Consumables cannot be equipped
        if (item.type === "consumable") return false;

        // Gather allowed slots for this item
        const allowed = new Set();
        if (Array.isArray(item.allowedSlots)) {
            for (const s of item.allowedSlots) {
                const norm = this.normalizeSlot(s);
                if (norm) allowed.add(norm);
            }
        }
        if (typeof item.slot === "string") {
            const norm = this.normalizeSlot(item.slot);
            if (norm) allowed.add(norm);
        }

        // Inferred fallback from item.type
        if (allowed.size === 0) {
            if (item.type === "weapon") allowed.add("mainHand");
            else if (item.type === "armor") allowed.add("armor");
            else if (item.type === "accessory") allowed.add("accessory");
        }

        return allowed.has(designatedSlot);
    }

    /**
     * Equip an item into a designated slot.
     * Modifies bound Combatant/Stats and reverts previous item stats if replacing.
     * Rejects incompatible slots.
     * @param {string|Object} slotOrItem
     * @param {Object} [maybeItem]
     * @param {Object} [options]
     * @returns {Object|boolean} Returns previous item or equipped item on success, false on rejection.
     */
    equip(slotOrItem, maybeItem, options = {}) {
        let slot;
        let item;
        let opt = options;

        if (typeof slotOrItem === "string") {
            slot = slotOrItem;
            item = maybeItem;
        } else if (slotOrItem && typeof slotOrItem === "object") {
            item = slotOrItem;
            slot = item.slot ?? null;
            if (maybeItem && typeof maybeItem === "object") {
                opt = maybeItem;
            }
        }

        const designatedSlot = this.normalizeSlot(slot);
        if (!designatedSlot || !this.canEquip(designatedSlot, item)) {
            if (opt.throwOnError) {
                throw new Error(`Incompatible equipment slot '${slot}' for item '${item?.id ?? "unknown"}'`);
            }
            return false;
        }

        const target = opt.target ?? this.target;
        const previousItem = this.slots[designatedSlot];

        // If slot currently has an item, unequip it first
        if (previousItem) {
            if (target) {
                this._revertStats(previousItem, target);
            }
            this.slots[designatedSlot] = null;
            if (this.onUnequip) {
                this.onUnequip(designatedSlot, previousItem);
            }
        }

        // Equip new item
        this.slots[designatedSlot] = item;
        if (target) {
            this._applyStats(item, target);
        }
        if (this.onEquip) {
            this.onEquip(designatedSlot, item);
        }

        return previousItem ?? item;
    }

    /**
     * Unequip item from a designated slot, reverting stats on bound Combatant/Stats.
     * @param {string} slot
     * @param {Object} [options]
     * @returns {Object|null} Unequipped item or null if slot was empty.
     */
    unequip(slot, options = {}) {
        const designatedSlot = this.normalizeSlot(slot);
        if (!designatedSlot) return null;

        const item = this.slots[designatedSlot];
        if (!item) return null;

        const target = options.target ?? this.target;
        if (target) {
            this._revertStats(item, target);
        }

        this.slots[designatedSlot] = null;
        if (this.onUnequip) {
            this.onUnequip(designatedSlot, item);
        }

        return item;
    }

    /**
     * Get item in a designated slot.
     * @param {string} slot
     * @returns {Object|null}
     */
    getSlot(slot) {
        const designatedSlot = this.normalizeSlot(slot);
        if (!designatedSlot) return null;
        return this.slots[designatedSlot] ?? null;
    }

    /**
     * Alias for getSlot.
     * @param {string} slot
     * @returns {Object|null}
     */
    getEquippedItem(slot) {
        return this.getSlot(slot);
    }

    /**
     * Compute total stat modifier for a specific stat across all equipped items.
     * @param {string} statName
     * @returns {number}
     */
    getStatModifier(statName) {
        if (typeof statName !== "string" || !statName) return 0;
        let total = 0;
        for (const slotName of EQUIPMENT_SLOTS) {
            const item = this.slots[slotName];
            if (item) {
                const statMods = item.stats ?? item.statModifiers ?? {};
                if (Number.isFinite(statMods[statName])) {
                    total += statMods[statName];
                }
            }
        }
        return total;
    }

    /**
     * Compute aggregate stat modifiers across all equipped items.
     * @returns {Object}
     */
    getAllStatModifiers() {
        const totals = {};
        for (const slotName of EQUIPMENT_SLOTS) {
            const item = this.slots[slotName];
            if (item) {
                const statMods = item.stats ?? item.statModifiers ?? {};
                for (const [name, val] of Object.entries(statMods)) {
                    if (Number.isFinite(val)) {
                        totals[name] = (totals[name] ?? 0) + val;
                    }
                }
            }
        }
        return totals;
    }

    /**
     * Apply an item's stat modifiers to a target (Combatant, Stats, or both).
     * @private
     * @param {Object} item
     * @param {Object} target
     */
    _applyStats(item, target) {
        if (!item || !target) return;
        const stats = item.stats ?? item.statModifiers ?? {};

        // Target can be a composite { combatant, stats } or direct instance
        const targets = [];
        if (target.combatant) targets.push(target.combatant);
        if (target.stats) targets.push(target.stats);
        if (!targets.includes(target)) targets.push(target);

        for (const [statName, amount] of Object.entries(stats)) {
            if (!Number.isFinite(amount)) continue;

            for (const t of targets) {
                if (statName === "maxHealth") {
                    if (Number.isFinite(t.maxHealth)) {
                        t.maxHealth += amount;
                    }
                } else if (t.resistances && Object.hasOwn(t.resistances, statName)) {
                    t.resistances[statName] = Math.max(0, Math.min(1, (t.resistances[statName] ?? 0) + amount));
                } else if (typeof t[statName] === "number") {
                    t[statName] += amount;
                }
            }
        }
    }

    /**
     * Revert an item's stat modifiers from a target (Combatant, Stats, or both).
     * @private
     * @param {Object} item
     * @param {Object} target
     */
    _revertStats(item, target) {
        if (!item || !target) return;
        const stats = item.stats ?? item.statModifiers ?? {};

        const targets = [];
        if (target.combatant) targets.push(target.combatant);
        if (target.stats) targets.push(target.stats);
        if (!targets.includes(target)) targets.push(target);

        for (const [statName, amount] of Object.entries(stats)) {
            if (!Number.isFinite(amount)) continue;

            for (const t of targets) {
                if (statName === "maxHealth") {
                    if (Number.isFinite(t.maxHealth)) {
                        t.maxHealth = Math.max(1, t.maxHealth - amount);
                        if (t.health > t.maxHealth) {
                            if (typeof t.setHealth === "function") {
                                t.setHealth(t.maxHealth);
                            } else {
                                t.health = t.maxHealth;
                            }
                        }
                    }
                } else if (t.resistances && Object.hasOwn(t.resistances, statName)) {
                    t.resistances[statName] = Math.max(0, Math.min(1, (t.resistances[statName] ?? 0) - amount));
                } else if (typeof t[statName] === "number") {
                    t[statName] -= amount;
                }
            }
        }
    }

    /**
     * Create persistence snapshot of equipped items.
     * @returns {Object}
     */
    createSnapshot() {
        const slotsData = {};
        for (const slotName of EQUIPMENT_SLOTS) {
            slotsData[slotName] = this.slots[slotName] ? structuredClone(this.slots[slotName]) : null;
        }
        return {
            slots: slotsData
        };
    }

    /**
     * Restore equipped items from snapshot, maintaining stat modifier binding.
     * @param {Object} snapshot
     * @param {Object} [options]
     * @returns {boolean}
     */
    restoreSnapshot(snapshot, options = {}) {
        if (!snapshot || typeof snapshot !== "object") {
            throw new TypeError("Invalid equipment snapshot data");
        }
        const slotsData = snapshot.slots ?? snapshot;
        const registry = options.registry ?? null;
        const target = options.target ?? this.target;

        // Unequip all current slots first to revert old stats
        for (const slotName of EQUIPMENT_SLOTS) {
            if (this.slots[slotName]) {
                this.unequip(slotName, { target });
            }
        }

        // Restore each slot
        for (const slotName of EQUIPMENT_SLOTS) {
            let item = slotsData[slotName] ?? null;
            if (typeof item === "string" && registry) {
                item = registry.get(item);
            }
            if (item) {
                this.equip(slotName, item, { target });
            }
        }

        return true;
    }

    /**
     * Export to plain JSON representation.
     * @returns {Object}
     */
    toJSON() {
        return this.createSnapshot().slots;
    }

    /**
     * Load from JSON representation.
     * @param {Object} data
     */
    loadJSON(data) {
        this.restoreSnapshot(data);
    }
}

/**
 * Slot-based inventory with stacking (maxStack), capacity limits (maxSlots),
 * item add/remove/consume methods, and integrated equipment handling.
 */
export class Inventory extends Component {
    /**
     * @param {number|Object} [maxSlotsOrConfig] - Max slots number or configuration object.
     * @param {Object} [config] - Optional configuration when first param is number.
     */
    constructor(maxSlotsOrConfig = 20, config = {}) {
        super();

        let maxSlots = 20;
        let maxStack = 99;
        let gold = 0;
        let registry = null;

        if (typeof maxSlotsOrConfig === "number") {
            maxSlots = maxSlotsOrConfig;
            if (config && typeof config === "object") {
                if (Number.isInteger(config.maxStack) && config.maxStack >= 1) maxStack = config.maxStack;
                if (Number.isFinite(config.gold)) gold = Math.max(0, config.gold);
                if (Number.isFinite(config.currency)) gold = Math.max(0, config.currency);
                if (config.registry) registry = config.registry;
            }
        } else if (maxSlotsOrConfig && typeof maxSlotsOrConfig === "object") {
            if (Number.isInteger(maxSlotsOrConfig.maxSlots)) maxSlots = maxSlotsOrConfig.maxSlots;
            if (Number.isInteger(maxSlotsOrConfig.maxStack) && maxSlotsOrConfig.maxStack >= 1) maxStack = maxSlotsOrConfig.maxStack;
            if (Number.isFinite(maxSlotsOrConfig.gold)) gold = Math.max(0, maxSlotsOrConfig.gold);
            if (Number.isFinite(maxSlotsOrConfig.currency)) gold = Math.max(0, maxSlotsOrConfig.currency);
            if (maxSlotsOrConfig.registry) registry = maxSlotsOrConfig.registry;
        }

        this.maxSlots = maxSlots;
        this.maxStack = maxStack;
        this.slots = []; // Array of { item: Object, quantity: number }
        this.gold = gold;
        this.registry = registry;

        this.equipmentSystem = new EquipmentSystem({ inventory: this });

        this.onItemAdded = null;
        this.onItemRemoved = null;
    }

    /**
     * Currency alias for gold.
     * @type {number}
     */
    get currency() {
        return this.gold;
    }

    set currency(value) {
        if (!Number.isFinite(value) || value < 0) {
            throw new TypeError("Currency must be a non-negative finite number");
        }
        this.gold = value;
    }

    /**
     * Equipment mapping getter mirroring the equipment system slots.
     * Non-null slots are enumerable so Object.entries(equipment) reflects only equipped items,
     * while direct slot property access (e.g. equipment.mainHand or equipment.weapon) returns the item or null.
     * @type {Object}
     */
    get equipment() {
        const slots = this.equipmentSystem.slots;
        return new Proxy(slots, {
            get(target, prop) {
                if (prop === "weapon" || prop === "hand") {
                    return target.mainHand ?? null;
                }
                if (typeof prop === "string" && prop in target) {
                    return target[prop] ?? null;
                }
                return target[prop];
            },
            has(target, prop) {
                if (prop === "weapon" || prop === "hand") {
                    return target.mainHand !== null;
                }
                return prop in target && target[prop] !== null;
            },
            ownKeys(target) {
                const keys = [];
                for (const k of Object.keys(target)) {
                    if (target[k] !== null) {
                        const item = target[k];
                        if (k === "mainHand" && item?.slot === "weapon") {
                            keys.push("weapon");
                        } else {
                            keys.push(k);
                        }
                    }
                }
                return keys;
            },
            getOwnPropertyDescriptor(target, prop) {
                if ((prop === "weapon" || prop === "hand") && target.mainHand) {
                    return {
                        value: target.mainHand,
                        writable: true,
                        enumerable: true,
                        configurable: true
                    };
                }
                if (target[prop] !== null && target[prop] !== undefined) {
                    return {
                        value: target[prop],
                        writable: true,
                        enumerable: true,
                        configurable: true
                    };
                }
                return undefined;
            }
        });
    }

    set equipment(value) {
        if (value && typeof value === "object") {
            this.equipmentSystem.restoreSnapshot(value);
        }
    }

    /**
     * Check if inventory is full.
     * @type {boolean}
     */
    get isFull() {
        return this.slots.length >= this.maxSlots;
    }

    /**
     * Resolve an item object from item or item id.
     * @private
     * @param {Object|string} itemOrId
     * @returns {Object|null}
     */
    _resolveItem(itemOrId) {
        if (!itemOrId) return null;
        if (typeof itemOrId === "object" && itemOrId.id) return itemOrId;
        if (typeof itemOrId === "string" && this.registry) return this.registry.get(itemOrId);
        return null;
    }

    /**
     * Resolve the maxStack limit for an item.
     * @param {Object} item
     * @returns {number}
     */
    getItemMaxStack(item) {
        if (!item) return 1;
        if (Number.isInteger(item.maxStack) && item.maxStack >= 1) return item.maxStack;
        if (Number.isInteger(item.stackable) && item.stackable >= 1) return item.stackable;
        if (item.type === "consumable") return this.maxStack;
        return 1;
    }

    /**
     * Check whether an item quantity can be added without exceeding capacity limits.
     * @param {Object|string} itemOrId
     * @param {number} [quantity]
     * @returns {boolean}
     */
    canAddItem(itemOrId, quantity = 1) {
        const item = this._resolveItem(itemOrId);
        if (!item || !Number.isInteger(quantity) || quantity < 1) return false;

        const maxStack = this.getItemMaxStack(item);
        let remaining = quantity;

        if (maxStack > 1) {
            for (const slot of this.slots) {
                if (slot.item.id === item.id && slot.quantity < maxStack) {
                    remaining -= Math.max(0, maxStack - slot.quantity);
                }
            }
        }

        const needed = maxStack > 1 ? Math.ceil(Math.max(0, remaining) / maxStack) : remaining;
        return this.slots.length + needed <= this.maxSlots;
    }

    /**
     * Add an item to the inventory.
     * Stacks with existing matching slots up to maxStack, then allocates new slots.
     * Enforces maxSlots capacity limits to prevent overflow.
     * @param {Object|string} itemOrId
     * @param {number} [quantity]
     * @param {Object} [options]
     * @returns {boolean} True if added successfully, false if rejected due to capacity.
     */
    addItem(itemOrId, quantity = 1, options = {}) {
        const item = this._resolveItem(itemOrId);
        if (!item || !Number.isInteger(quantity) || quantity < 1) return false;

        const allowPartial = options.allowPartial ?? false;

        // Atomic check: prevent overflow if total quantity cannot fit
        if (!allowPartial && !this.canAddItem(item, quantity)) {
            return false;
        }

        const maxStack = this.getItemMaxStack(item);
        let remaining = quantity;

        // 1. Stack into existing slots
        if (maxStack > 1) {
            for (const slot of this.slots) {
                if (slot.item.id === item.id && slot.quantity < maxStack) {
                    const addAmount = Math.min(remaining, maxStack - slot.quantity);
                    slot.quantity += addAmount;
                    remaining -= addAmount;
                    if (this.onItemAdded) this.onItemAdded(item, addAmount);
                    if (remaining === 0) return true;
                }
            }
        }

        // 2. Add to new slots up to maxSlots
        while (remaining > 0 && this.slots.length < this.maxSlots) {
            const addAmount = maxStack > 1 ? Math.min(remaining, maxStack) : 1;
            this.slots.push({ item, quantity: addAmount });
            remaining -= addAmount;
            if (this.onItemAdded) this.onItemAdded(item, addAmount);
        }

        return remaining === 0;
    }

    /**
     * Remove an item quantity from the inventory.
     * @param {string} itemId
     * @param {number} [quantity]
     * @returns {boolean} True if removed successfully, false if insufficient items.
     */
    removeItem(itemId, quantity = 1) {
        if (typeof itemId !== "string" || !Number.isInteger(quantity) || quantity < 1) return false;
        if (this.getItemCount(itemId) < quantity) return false;

        let remaining = quantity;
        for (let i = this.slots.length - 1; i >= 0 && remaining > 0; i--) {
            if (this.slots[i].item.id === itemId) {
                const removeAmount = Math.min(remaining, this.slots[i].quantity);
                this.slots[i].quantity -= removeAmount;
                remaining -= removeAmount;

                if (this.onItemRemoved) this.onItemRemoved(this.slots[i].item, removeAmount);

                if (this.slots[i].quantity === 0) {
                    this.slots.splice(i, 1);
                }
            }
        }
        return remaining === 0;
    }

    /**
     * Check if inventory contains at least quantity of an item.
     * @param {string} itemId
     * @param {number} [quantity]
     * @returns {boolean}
     */
    hasItem(itemId, quantity = 1) {
        if (typeof itemId !== "string" || !Number.isInteger(quantity) || quantity < 1) return false;
        return this.getItemCount(itemId) >= quantity;
    }

    /**
     * Get total quantity of an item across all slots.
     * @param {string} itemId
     * @returns {number}
     */
    getItemCount(itemId) {
        if (typeof itemId !== "string") return 0;
        let count = 0;
        for (const slot of this.slots) {
            if (slot.item.id === itemId) {
                count += slot.quantity;
            }
        }
        return count;
    }

    /**
     * Consume a consumable item, applying its effects to the target and decrementing count.
     * Supports targets that are Combatant, Stats, or custom entities.
     * @param {string} itemId
     * @param {Object} target - Target Combatant or Stats.
     * @returns {boolean} True if consumed successfully, false otherwise.
     */
    consume(itemId, target) {
        if (typeof itemId !== "string") return false;
        const slot = this.slots.find(entry => entry.item.id === itemId);
        if (!slot || slot.item.type !== "consumable") return false;

        const item = slot.item;
        const effects = item.effects ?? {};

        // 1. Health restoration
        if (Number.isFinite(effects.health)) {
            if (typeof target?.heal === "function") {
                target.heal(effects.health);
            } else if (Number.isFinite(target?.health)) {
                const max = target.maxHealth ?? Infinity;
                target.health = Math.min(max, target.health + effects.health);
            }
        }

        // 2. Stamina restoration
        if (Number.isFinite(effects.stamina) && Number.isFinite(target?.stamina)) {
            const maxStamina = target.maxStamina ?? Infinity;
            target.stamina = Math.min(maxStamina, target.stamina + effects.stamina);
        }

        // 3. Stat modifications
        const statMods = effects.stats ?? effects.statModifiers ?? {};
        for (const [statName, amount] of Object.entries(statMods)) {
            if (Number.isFinite(amount)) {
                if (Number.isFinite(target?.[statName])) {
                    target[statName] += amount;
                } else if (target?.stats && Number.isFinite(target.stats[statName])) {
                    target.stats[statName] += amount;
                }
            }
        }

        // 4. Status effects
        if (effects.statusEffect && typeof target?.applyEffect === "function") {
            target.applyEffect(effects.statusEffect);
        }

        // 5. Custom onUse hook
        if (typeof item.onUse === "function") {
            item.onUse(target, item);
        }

        // Decrement item count
        this.removeItem(itemId, 1);
        return true;
    }

    /**
     * Alias for consume.
     * @param {string} itemId
     * @param {Object} target
     * @returns {boolean}
     */
    useItem(itemId, target) {
        return this.consume(itemId, target);
    }

    /**
     * Alias for consume.
     * @param {string} itemId
     * @param {Object} target
     * @returns {boolean}
     */
    consumeItem(itemId, target) {
        return this.consume(itemId, target);
    }

    /**
     * Equip an item from inventory into designated equipment slot.
     * @param {string} slotOrItemId
     * @param {string} [maybeItemId]
     * @returns {Object|boolean}
     */
    equip(slotOrItemId, maybeItemId) {
        let slotName = null;
        let itemId = null;

        if (maybeItemId !== undefined) {
            slotName = slotOrItemId;
            itemId = maybeItemId;
        } else {
            itemId = slotOrItemId;
        }

        const slotIndex = this.slots.findIndex(entry => entry.item.id === itemId);
        if (slotIndex === -1) return false;
        const item = this.slots[slotIndex].item;

        if (!slotName) {
            slotName = item.slot ?? (item.type === "weapon" ? "mainHand" : item.type === "armor" ? "armor" : item.type === "accessory" ? "accessory" : null);
        }
        const designatedSlot = this.equipmentSystem.normalizeSlot(slotName);
        if (!designatedSlot || !this.equipmentSystem.canEquip(designatedSlot, item)) {
            return false;
        }

        const prior = this.equipmentSystem.slots[designatedSlot];

        // Remove 1 quantity of the item from inventory
        this.removeItem(itemId, 1);

        // Equip into equipment system
        this.equipmentSystem.equip(designatedSlot, item);

        // Put prior item back into inventory if present
        if (prior) {
            this.addItem(prior, 1);
        }

        return prior ?? item;
    }

    /**
     * Unequip an item from equipment slot back into inventory.
     * Rejects if inventory has no capacity to store the unequipped item.
     * @param {string} slot
     * @returns {Object|boolean} Unequipped item or false if failed.
     */
    unequip(slot) {
        const designatedSlot = this.equipmentSystem.normalizeSlot(slot);
        if (!designatedSlot) return false;

        const item = this.equipmentSystem.slots[designatedSlot];
        if (!item) return false;

        // Check if inventory has room
        if (!this.canAddItem(item, 1)) {
            return false;
        }

        this.equipmentSystem.unequip(designatedSlot);
        this.addItem(item, 1);
        return item;
    }

    /**
     * Add currency (gold).
     * @param {number} amount
     * @returns {number} Total currency.
     */
    addCurrency(amount) {
        if (!Number.isFinite(amount) || amount < 0) {
            throw new RangeError("Currency amount must be a non-negative finite number");
        }
        this.gold += amount;
        return this.gold;
    }

    /**
     * Deduct currency (gold) if sufficient.
     * @param {number} amount
     * @returns {boolean} True if deducted, false if insufficient.
     */
    removeCurrency(amount) {
        if (!Number.isFinite(amount) || amount < 0) {
            throw new RangeError("Currency amount must be a non-negative finite number");
        }
        if (this.gold < amount) return false;
        this.gold -= amount;
        return true;
    }

    /**
     * Check if inventory has at least currency amount.
     * @param {number} amount
     * @returns {boolean}
     */
    hasCurrency(amount) {
        if (!Number.isFinite(amount) || amount < 0) return false;
        return this.gold >= amount;
    }

    /**
     * Create persistence snapshot of inventory, equipment, and currency.
     * @returns {Object}
     */
    createSnapshot() {
        return {
            version: 1,
            maxSlots: this.maxSlots,
            maxStack: this.maxStack,
            currency: this.gold,
            gold: this.gold,
            slots: this.slots.map(s => ({
                itemId: s.item.id,
                quantity: s.quantity,
                item: structuredClone(s.item)
            })),
            equipment: this.equipmentSystem.createSnapshot()
        };
    }

    /**
     * Restore inventory, equipment, and currency from persistence snapshot.
     * @param {Object} snapshot
     * @param {Object} [options]
     * @returns {boolean}
     */
    restoreSnapshot(snapshot, options = {}) {
        if (!snapshot || typeof snapshot !== "object") {
            throw new TypeError("Invalid inventory snapshot data");
        }
        if (Number.isInteger(snapshot.maxSlots) && snapshot.maxSlots >= 0) {
            this.maxSlots = snapshot.maxSlots;
        }
        if (Number.isInteger(snapshot.maxStack) && snapshot.maxStack >= 1) {
            this.maxStack = snapshot.maxStack;
        }

        this.gold = Number.isFinite(snapshot.currency) ? Math.max(0, snapshot.currency)
            : Number.isFinite(snapshot.gold) ? Math.max(0, snapshot.gold) : 0;

        const registry = options.registry ?? this.registry;
        const target = options.target ?? null;

        this.slots = [];
        if (Array.isArray(snapshot.slots)) {
            for (const slotData of snapshot.slots) {
                let item = slotData.item;
                if (!item && registry && slotData.itemId) {
                    item = registry.get(slotData.itemId);
                }
                if (item && Number.isInteger(slotData.quantity) && slotData.quantity > 0) {
                    this.slots.push({
                        item: structuredClone(item),
                        quantity: slotData.quantity
                    });
                }
            }
        }

        if (snapshot.equipment) {
            this.equipmentSystem.restoreSnapshot(snapshot.equipment, { registry, target });
        }

        return true;
    }

    /**
     * Export to plain JSON representation.
     * @returns {Object}
     */
    toJSON() {
        return {
            maxSlots: this.maxSlots,
            gold: this.gold,
            currency: this.gold,
            slots: this.slots.map(slot => ({
                item: structuredClone(slot.item),
                quantity: slot.quantity
            })),
            equipment: structuredClone(this.equipmentSystem.toJSON())
        };
    }

    /**
     * Load state from plain JSON representation.
     * @param {Object} data
     */
    loadJSON(data) {
        if (!data || !Number.isInteger(data.maxSlots) || data.maxSlots < 0 || !Array.isArray(data.slots) || !Number.isFinite(data.gold) || data.gold < 0) {
            throw new TypeError("Invalid inventory data");
        }
        if (data.slots.length > data.maxSlots || data.slots.some(slot => !slot.item || !Number.isInteger(slot.quantity) || slot.quantity < 1 || slot.quantity > (slot.item.maxStack ?? slot.item.stackable ?? 1))) {
            throw new TypeError("Invalid inventory slots");
        }
        this.maxSlots = data.maxSlots;
        this.gold = data.gold;
        this.slots = data.slots.map(slot => ({ item: structuredClone(slot.item), quantity: slot.quantity }));

        // Clear equipment
        for (const slot of EQUIPMENT_SLOTS) {
            this.equipmentSystem.slots[slot] = null;
        }

        if (data.equipment) {
            const eqData = data.equipment.slots ?? data.equipment;
            for (const [k, v] of Object.entries(eqData)) {
                const designatedSlot = this.equipmentSystem.normalizeSlot(k);
                if (designatedSlot && v) {
                    this.equipmentSystem.slots[designatedSlot] = structuredClone(v);
                }
            }
        }
    }
}

/**
 * Loot table managing weighted drop rolls with min/max quantities.
 */
export class LootTable {
    /**
     * @param {Array.<Object>} [entries] - Initial loot entries.
     * @param {Object} [config] - Optional configuration { id, name }.
     */
    constructor(entries = [], config = {}) {
        this.id = config.id ?? null;
        this.name = config.name ?? null;
        this.entries = [];

        if (Array.isArray(entries)) {
            for (const entry of entries) {
                this.addEntry(entry);
            }
        }
    }

    /**
     * Add a drop entry to the loot table.
     * @param {Object} entry - { itemId, weight, minQuantity, maxQuantity, chance, item }
     * @returns {LootTable}
     */
    addEntry(entry) {
        if (!entry || typeof entry !== "object") {
            throw new TypeError("LootTable entry must be an object");
        }
        const itemId = entry.itemId ?? entry.id;
        if (typeof itemId !== "string" || !itemId.trim()) {
            throw new TypeError("LootTable entry itemId must be a non-empty string");
        }

        const weight = Number.isFinite(entry.weight) ? Math.max(0, entry.weight) : 1;
        const chance = Number.isFinite(entry.chance) ? Math.min(1, Math.max(0, entry.chance)) : 1;

        let minQuantity = 1;
        if (Number.isInteger(entry.minQuantity) && entry.minQuantity >= 1) minQuantity = entry.minQuantity;
        else if (Number.isInteger(entry.min) && entry.min >= 1) minQuantity = entry.min;
        else if (Number.isInteger(entry.quantity) && entry.quantity >= 1) minQuantity = entry.quantity;

        let maxQuantity = minQuantity;
        if (Number.isInteger(entry.maxQuantity) && entry.maxQuantity >= minQuantity) maxQuantity = entry.maxQuantity;
        else if (Number.isInteger(entry.max) && entry.max >= minQuantity) maxQuantity = entry.max;

        this.entries.push({
            itemId: itemId.trim(),
            weight,
            chance,
            minQuantity,
            maxQuantity,
            item: entry.item ?? null
        });

        return this;
    }

    /**
     * Convenience method to add an item drop.
     * @param {string} itemId
     * @param {number} [weight]
     * @param {number} [minQuantity]
     * @param {number} [maxQuantity]
     * @param {number} [chance]
     * @returns {LootTable}
     */
    addItem(itemId, weight = 1, minQuantity = 1, maxQuantity = 1, chance = 1) {
        return this.addEntry({ itemId, weight, minQuantity, maxQuantity, chance });
    }

    /**
     * Remove a drop entry by item id.
     * @param {string} itemId
     * @returns {boolean}
     */
    removeEntry(itemId) {
        if (typeof itemId !== "string") return false;
        const initialLen = this.entries.length;
        this.entries = this.entries.filter(e => e.itemId !== itemId);
        return this.entries.length < initialLen;
    }

    /**
     * Roll drops from this loot table.
     * Supports weighted roll mode (default) and independent chance mode.
     * Produces random quantities between minQuantity and maxQuantity inclusive.
     * @param {Object|Function} [optionsOrRandom] - Options object or custom random function.
     * @returns {Array.<Object>} Array of generated drops { itemId, quantity, [item] }
     */
    roll(optionsOrRandom = {}) {
        let random = Math.random;
        let rolls = 1;
        let mode = "weighted";

        if (typeof optionsOrRandom === "function") {
            random = optionsOrRandom;
        } else if (optionsOrRandom && typeof optionsOrRandom === "object") {
            if (typeof optionsOrRandom.random === "function") random = optionsOrRandom.random;
            if (Number.isInteger(optionsOrRandom.rolls) && optionsOrRandom.rolls >= 1) rolls = optionsOrRandom.rolls;
            if (typeof optionsOrRandom.mode === "string") mode = optionsOrRandom.mode;
        }

        if (this.entries.length === 0) return [];

        if (mode === "independent") {
            const results = [];
            for (const entry of this.entries) {
                const rollVal = random();
                if (rollVal <= entry.chance) {
                    const quantity = this._rollQuantity(entry, random);
                    if (quantity > 0) {
                        results.push({
                            itemId: entry.itemId,
                            quantity,
                            item: entry.item
                        });
                    }
                }
            }
            return results;
        }

        // Weighted drop generation mode
        const totalWeight = this.entries.reduce((sum, e) => sum + e.weight, 0);
        if (totalWeight <= 0) return [];

        const results = [];
        for (let r = 0; r < rolls; r++) {
            let rollPick = random() * totalWeight;
            let selected = this.entries[this.entries.length - 1];

            for (const entry of this.entries) {
                if (rollPick < entry.weight) {
                    selected = entry;
                    break;
                }
                rollPick -= entry.weight;
            }

            // Independent chance gate on chosen entry
            if (selected.chance < 1 && random() > selected.chance) {
                continue;
            }

            const quantity = this._rollQuantity(selected, random);
            if (quantity > 0) {
                const existing = results.find(d => d.itemId === selected.itemId);
                if (existing) {
                    existing.quantity += quantity;
                } else {
                    results.push({
                        itemId: selected.itemId,
                        quantity,
                        item: selected.item
                    });
                }
            }
        }

        return results;
    }

    /**
     * Compute quantity between minQuantity and maxQuantity inclusive.
     * @private
     * @param {Object} entry
     * @param {Function} random
     * @returns {number}
     */
    _rollQuantity(entry, random) {
        if (entry.minQuantity === entry.maxQuantity) {
            return entry.minQuantity;
        }
        const delta = entry.maxQuantity - entry.minQuantity;
        const randVal = Math.min(0.999999, Math.max(0, random()));
        return entry.minQuantity + Math.floor(randVal * (delta + 1));
    }

    /**
     * Export to plain JSON representation.
     * @returns {Object}
     */
    toJSON() {
        return {
            id: this.id,
            name: this.name,
            entries: this.entries.map(e => ({ ...e }))
        };
    }

    /**
     * Reconstruct a LootTable from JSON data.
     * @param {Object} data
     * @returns {LootTable}
     */
    static fromJSON(data) {
        if (!data || !Array.isArray(data.entries)) {
            throw new TypeError("Invalid LootTable data");
        }
        return new LootTable(data.entries, { id: data.id, name: data.name });
    }
}

/**
 * Helper to create a unified snapshot for inventory, equipment, and currency.
 * @param {Object} context
 * @returns {Object}
 */
export function createRPGSnapshot({ inventory = null, equipment = null, currency = 0 } = {}) {
    return {
        version: 1,
        timestamp: Date.now(),
        currency: Number.isFinite(currency) ? currency : (inventory?.gold ?? 0),
        inventory: inventory ? inventory.createSnapshot() : null,
        equipment: equipment ? equipment.createSnapshot() : (inventory?.equipmentSystem ? inventory.equipmentSystem.createSnapshot() : null)
    };
}

/**
 * Helper to restore a unified snapshot for inventory, equipment, and currency.
 * @param {Object} snapshot
 * @param {Object} context
 * @returns {boolean}
 */
export function restoreRPGSnapshot(snapshot, { inventory = null, equipment = null, target = null, registry = null } = {}) {
    if (!snapshot || typeof snapshot !== "object") {
        throw new TypeError("Invalid RPG snapshot");
    }

    if (inventory && snapshot.inventory) {
        inventory.restoreSnapshot(snapshot.inventory, { registry, target });
    } else if (inventory && Number.isFinite(snapshot.currency)) {
        inventory.gold = snapshot.currency;
    }

    if (equipment && snapshot.equipment) {
        equipment.restoreSnapshot(snapshot.equipment, { registry, target });
    }

    return true;
}