larissa_npcSchedules.js

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

/**
 * Standard routine activity types supported by NPC schedules.
 */
export const ROUTINE_ACTIVITIES = Object.freeze({
    WORK: "work",
    REST: "rest",
    PATROL: "patrol",
    SLEEP: "sleep",
    WANDER: "wander",
    IDLE: "idle",
    ALERT: "alert",
    FLEE: "flee",
    COMBAT: "combat"
});

/**
 * Standard faction dispositions.
 */
export const FACTION_DISPOSITION = Object.freeze({
    FRIENDLY: "friendly",
    NEUTRAL: "neutral",
    HOSTILE: "hostile"
});

/**
 * Normalizes and parses a game hour into a 24-hour float [0, 24).
 * Supports numbers, strings like "14:30" or "06:00", or GameClock instances.
 * @param {number|string|Object} time - The time value to parse.
 * @returns {number} Normalized hour from 0 up to (exclusive) 24.
 */
export function parseHour(time) {
    if (typeof time === "number") {
        if (!Number.isFinite(time)) {
            throw new TypeError("Time number must be finite");
        }
        return ((time % 24) + 24) % 24;
    }
    if (typeof time === "string") {
        const str = time.trim();
        if (str.includes(":")) {
            const parts = str.split(":");
            const hours = parseFloat(parts[0]);
            const minutes = parseFloat(parts[1] || "0");
            const seconds = parseFloat(parts[2] || "0");
            if (Number.isFinite(hours) && Number.isFinite(minutes)) {
                const totalHours = hours + (minutes / 60) + (seconds / 3600);
                return ((totalHours % 24) + 24) % 24;
            }
        }
        const parsed = parseFloat(str);
        if (Number.isFinite(parsed)) {
            return ((parsed % 24) + 24) % 24;
        }
    }
    if (time && typeof time === "object") {
        if (Number.isFinite(time.hour)) {
            const extra = Number.isFinite(time.minute) ? time.minute / 60 : 0;
            return (((time.hour + extra) % 24) + 24) % 24;
        }
        if (time.calendar && Number.isFinite(time.calendar.minuteOfDay)) {
            return (time.calendar.minuteOfDay / 60) % 24;
        }
        if (Number.isFinite(time.minute) && Number.isFinite(time.minutesPerDay) && time.minutesPerDay > 0) {
            const minuteOfDay = time.minute % time.minutesPerDay;
            return ((minuteOfDay / (time.minutesPerDay / 24)) % 24 + 24) % 24;
        }
    }
    throw new TypeError(`Unable to parse time: ${time}`);
}

/**
 * Checks whether a given hour falls inside a slot with optional midnight wraparound.
 * @param {number} hour - Hour to test [0, 24).
 * @param {number} start - Slot start hour [0, 24).
 * @param {number} end - Slot end hour [0, 24).
 * @returns {boolean} True if the hour falls within the slot interval.
 */
export function isHourInSlot(hour, start, end) {
    const h = ((hour % 24) + 24) % 24;
    const s = ((start % 24) + 24) % 24;
    const e = ((end % 24) + 24) % 24;

    if (s === e) {
        return true;
    }
    if (s < e) {
        return h >= s && h < e;
    }
    return h >= s || h < e;
}

/**
 * Derives a string identifier for a destination point or object.
 * @param {Object|string|number} point - Destination point.
 * @returns {string|null} String key or null if invalid.
 */
export function getPointKey(point) {
    if (point === null || point === undefined) return null;
    if (typeof point === "string" || typeof point === "number") return String(point);
    if (typeof point === "object") {
        if (point.id !== undefined && point.id !== null) return String(point.id);
        if (point.name !== undefined && point.name !== null) return String(point.name);
        if (Number.isFinite(point.x) && Number.isFinite(point.y)) {
            return `pt_${point.x}_${point.y}`;
        }
    }
    return String(point);
}

/**
 * An individual time slot inside an NPC's daily routine.
 */
export class ScheduleSlot {
    static _nextId = 1;

    /**
     * @param {Object} config - Configuration object.
     * @param {number|string} config.start - Start time (hour 0-24 or "HH:MM").
     * @param {number|string} config.end - End time (hour 0-24 or "HH:MM").
     * @param {string} [config.activity="idle"] - Scheduled activity.
     * @param {Object|string} [config.destination=null] - Primary destination point.
     * @param {Array} [config.fallbacks=[]] - Alternate destination points if primary is occupied.
     * @param {Object|string} [config.fallbackDestination=null] - Single fallback point shorthand.
     * @param {string} [config.fallbackActivity="idle"] - Activity if all destinations are occupied.
     * @param {string} [config.id] - Optional identifier for the slot.
     * @param {number} [config.priority=0] - Priority for overlapping slots (higher wins).
     * @param {boolean} [config.isAppointment=false] - Whether this slot represents an appointment.
     * @param {Function} [config.onEnter=null] - Lifecycle callback when slot becomes active.
     * @param {Function} [config.onExit=null] - Lifecycle callback when slot ends.
     * @param {Object} [config.data={}] - Additional custom metadata.
     */
    constructor(config = {}) {
        if (!config || typeof config !== "object") {
            throw new TypeError("ScheduleSlot configuration must be an object");
        }
        if (config.start === undefined || config.end === undefined) {
            throw new TypeError("ScheduleSlot requires start and end times");
        }

        this.id = config.id || `slot-${ScheduleSlot._nextId++}`;
        this.start = parseHour(config.start);
        this.end = parseHour(config.end);
        this.activity = config.activity || ROUTINE_ACTIVITIES.IDLE;
        this.destination = config.destination || null;

        const fallbacks = [];
        if (Array.isArray(config.fallbacks)) {
            fallbacks.push(...config.fallbacks);
        }
        if (config.fallbackDestination && !fallbacks.includes(config.fallbackDestination)) {
            fallbacks.push(config.fallbackDestination);
        }
        this.fallbacks = fallbacks;
        this.fallbackActivity = config.fallbackActivity || ROUTINE_ACTIVITIES.IDLE;
        this.priority = Number.isFinite(config.priority) ? config.priority : 0;
        this.isAppointment = Boolean(config.isAppointment);
        this.onEnter = typeof config.onEnter === "function" ? config.onEnter : null;
        this.onExit = typeof config.onExit === "function" ? config.onExit : null;
        this.data = config.data ? { ...config.data } : {};
    }

    /**
     * Whether this slot wraps around midnight (e.g. 22:00 to 06:00).
     * @returns {boolean}
     */
    get wrapsMidnight() {
        return this.start > this.end;
    }

    /**
     * Duration in hours of this slot.
     * @returns {number}
     */
    get duration() {
        if (this.start === this.end) return 24;
        if (this.start < this.end) return this.end - this.start;
        return (24 - this.start) + this.end;
    }

    /**
     * Checks if this slot is active at the given game hour.
     * @param {number|string} hour - Hour to test.
     * @returns {boolean}
     */
    isActive(hour) {
        const h = parseHour(hour);
        return isHourInSlot(h, this.start, this.end);
    }
}

/**
 * Manages an individual NPC's daily routine, danger state, and appointment history.
 */
export class NPCSchedule extends Component {
    static _nextId = 1;

    /**
     * @param {Object} [config={}] - Configuration options.
     * @param {string} [config.id] - Unique NPC identifier.
     * @param {Array} [config.slots=[]] - Initial schedule slots.
     * @param {string} [config.defaultActivity="idle"] - Fallback activity when no slot matches.
     * @param {number|string} [config.initialHour=0] - Initial game hour.
     * @param {string} [config.faction="neutral"] - NPC faction affiliation.
     * @param {ScheduleSystem} [config.system=null] - Reference to parent ScheduleSystem.
     * @param {Entity} [config.entity=null] - Neptune Entity this component attaches to.
     */
    constructor(config = {}) {
        super(config.entity || null);
        this.id = config.id || `npc-${NPCSchedule._nextId++}`;
        this.slots = [];
        this.defaultActivity = config.defaultActivity || ROUTINE_ACTIVITIES.IDLE;
        this.currentHour = config.initialHour !== undefined ? parseHour(config.initialHour) : 0;
        this.currentSlot = null;
        this.currentActivity = this.defaultActivity;
        this.currentDestination = null;
        this.destinationStatus = "none";
        this.claimedPoint = null;
        this.inDanger = false;
        this.dangerData = null;
        this.suspendedState = null;
        this.missedAppointments = [];
        this.faction = config.faction || "neutral";
        this.system = config.system || null;

        if (Array.isArray(config.slots)) {
            for (const slot of config.slots) {
                this.addSlot(slot);
            }
        }
    }

    /**
     * Whether schedule execution is currently suspended due to danger.
     * @returns {boolean}
     */
    get isSuspended() {
        return this.inDanger;
    }

    /**
     * Whether NPC is currently in danger.
     * @returns {boolean}
     */
    get isInDanger() {
        return this.inDanger;
    }

    /**
     * Adds a schedule slot to this NPC's routine.
     * @param {ScheduleSlot|Object} slot - Slot instance or config object.
     * @returns {ScheduleSlot} The added slot.
     */
    addSlot(slot) {
        const instance = slot instanceof ScheduleSlot ? slot : new ScheduleSlot(slot);
        this.slots.push(instance);
        this.slots.sort((a, b) => b.priority - a.priority);
        return instance;
    }

    /**
     * Removes a slot by its identifier.
     * @param {string} slotId - Identifier of slot to remove.
     * @returns {boolean} True if removed.
     */
    removeSlot(slotId) {
        const index = this.slots.findIndex(s => s.id === slotId);
        if (index >= 0) {
            this.slots.splice(index, 1);
            return true;
        }
        return false;
    }

    /**
     * Finds the matching slot for a given hour based on priority and time interval.
     * @param {number|string} hour - Game hour.
     * @returns {ScheduleSlot|null} Matching slot or null.
     */
    getSlotForHour(hour) {
        const h = parseHour(hour);
        for (const slot of this.slots) {
            if (slot.isActive(h)) {
                return slot;
            }
        }
        return null;
    }

    /**
     * Updates the NPC schedule to the given hour.
     * Handles slot transitions, danger suspension, and destination fallback.
     * @param {number|string|Object} time - Current game hour or clock.
     * @returns {string} Current activity.
     */
    update(time) {
        const previousHour = this.currentHour;
        const h = parseHour(time);
        this.currentHour = h;

        // If suspended by danger, remain in danger response and check for missed appointments
        if (this.inDanger) {
            this._checkMissedAppointments(previousHour, h);
            return this.currentActivity;
        }

        const nextSlot = this.getSlotForHour(h);
        const slotChanged = nextSlot !== this.currentSlot;

        if (slotChanged) {
            if (this.currentSlot && typeof this.currentSlot.onExit === "function") {
                this.currentSlot.onExit(this, this.currentSlot);
            }
            this._releaseClaimedPoint();

            const previousSlot = this.currentSlot;
            this.currentSlot = nextSlot;

            if (nextSlot) {
                this.currentActivity = nextSlot.activity;
                this._resolveAndClaimDestination(nextSlot);
                if (typeof nextSlot.onEnter === "function") {
                    nextSlot.onEnter(this, nextSlot);
                }
            } else {
                this.currentActivity = this.defaultActivity;
                this.currentDestination = null;
                this.destinationStatus = "none";
            }

            if (this.system && typeof this.system.emit === "function") {
                this.system.emit("transition", {
                    npcId: this.id,
                    previousSlot,
                    currentSlot: nextSlot,
                    hour: h
                });
            }
        } else if (this.currentSlot && (this.destinationStatus === "none" || this.destinationStatus === "all_occupied")) {
            // Re-attempt destination claiming if previously failed or all were occupied
            this._resolveAndClaimDestination(this.currentSlot);
        }

        return this.currentActivity;
    }

    /**
     * Suspends normal schedule execution in reaction to perceived danger.
     * @param {Object} [dangerData={}] - Details of the perceived threat.
     * @returns {NPCSchedule} This instance.
     */
    triggerDanger(dangerData = {}) {
        if (this.inDanger) {
            this.dangerData = { ...this.dangerData, ...dangerData };
            return this;
        }

        this.inDanger = true;
        this.dangerData = { ...dangerData };
        this.suspendedState = {
            slot: this.currentSlot,
            activity: this.currentActivity,
            destination: this.currentDestination,
            claimedPoint: this.claimedPoint,
            hour: this.currentHour
        };

        // Release claimed destination point so other actors can use it if needed
        if (dangerData.vacatePoint !== false) {
            this._releaseClaimedPoint();
        }

        this.currentActivity = dangerData.activity || ROUTINE_ACTIVITIES.FLEE;
        this.currentDestination = dangerData.destination || null;
        this.destinationStatus = "danger";

        if (this.system && typeof this.system.emit === "function") {
            this.system.emit("danger_interrupted", {
                npcId: this.id,
                dangerData,
                hour: this.currentHour
            });
        }
        return this;
    }

    /**
     * Resolves the danger condition and resumes scheduled activity.
     * Evaluates current hour and seamlessly picks up the appropriate schedule slot.
     * @param {Object} [options={}] - Resumption options.
     * @returns {string} Resumed activity.
     */
    resolveDanger(options = {}) {
        if (!this.inDanger) {
            return this.currentActivity;
        }

        this.inDanger = false;
        const dangerData = this.dangerData;
        this.dangerData = null;

        const effectiveHour = options.hour !== undefined ? parseHour(options.hour) : this.currentHour;
        this.currentHour = effectiveHour;

        const activeSlot = this.getSlotForHour(effectiveHour);
        this.currentSlot = activeSlot;

        if (activeSlot) {
            this.currentActivity = activeSlot.activity;
            this._resolveAndClaimDestination(activeSlot);
        } else {
            this.currentActivity = this.defaultActivity;
            this.currentDestination = null;
            this.destinationStatus = "none";
        }

        if (this.system && typeof this.system.emit === "function") {
            this.system.emit("danger_resolved", {
                npcId: this.id,
                resumedSlot: activeSlot,
                activity: this.currentActivity,
                hour: effectiveHour,
                dangerData
            });
        }
        return this.currentActivity;
    }

    /**
     * Resolves destination for a slot, falling back gracefully if points are occupied.
     * @private
     * @param {ScheduleSlot} slot - Active slot.
     */
    _resolveAndClaimDestination(slot) {
        if (!slot) return;

        const candidates = [];
        if (slot.destination) {
            candidates.push({ point: slot.destination, isPrimary: true });
        }
        if (Array.isArray(slot.fallbacks)) {
            for (const fb of slot.fallbacks) {
                if (fb) candidates.push({ point: fb, isPrimary: false });
            }
        }

        if (candidates.length === 0) {
            this.currentDestination = null;
            this.destinationStatus = "none";
            return;
        }

        for (const candidate of candidates) {
            const isOccupied = this._isPointOccupied(candidate.point);
            if (!isOccupied) {
                const claimed = this._claimPoint(candidate.point);
                if (claimed) {
                    this.currentDestination = candidate.point;
                    this.claimedPoint = candidate.point;
                    this.destinationStatus = candidate.isPrimary ? "primary" : "fallback";
                    this.currentActivity = slot.activity;
                    return;
                }
            }
        }

        // Graceful fallback when all candidate destination points are occupied
        this.currentDestination = null;
        this.claimedPoint = null;
        this.destinationStatus = "all_occupied";
        if (slot.fallbackActivity) {
            this.currentActivity = slot.fallbackActivity;
        }

        if (this.system && typeof this.system.emit === "function") {
            this.system.emit("occupied_fallback", {
                npcId: this.id,
                slot,
                status: "all_occupied",
                fallbackActivity: this.currentActivity
            });
        }
    }

    /**
     * Checks if a point is occupied, delegating to parent ScheduleSystem if present.
     * @private
     * @param {Object|string} point
     * @returns {boolean}
     */
    _isPointOccupied(point) {
        if (!point) return false;
        if (this.system && typeof this.system.isPointOccupied === "function") {
            return this.system.isPointOccupied(point, this.id);
        }
        if (typeof point === "object" && point.occupied === true) {
            return true;
        }
        return false;
    }

    /**
     * Claims a destination point, delegating to parent ScheduleSystem if present.
     * @private
     * @param {Object|string} point
     * @returns {boolean} True if successfully claimed.
     */
    _claimPoint(point) {
        if (!point) return false;
        if (this.system && typeof this.system.occupyPoint === "function") {
            return this.system.occupyPoint(point, this.id);
        }
        if (typeof point === "object") {
            point.occupied = true;
        }
        return true;
    }

    /**
     * Releases currently claimed destination point.
     * @private
     */
    _releaseClaimedPoint() {
        if (!this.claimedPoint) return;
        if (this.system && typeof this.system.vacatePoint === "function") {
            this.system.vacatePoint(this.claimedPoint, this.id);
        } else if (typeof this.claimedPoint === "object") {
            this.claimedPoint.occupied = false;
        }
        this.claimedPoint = null;
    }

    /**
     * Checks for any scheduled appointments that were missed between previous and current hour.
     * @private
     * @param {number} fromHour
     * @param {number} toHour
     */
    _checkMissedAppointments(fromHour, toHour) {
        for (const slot of this.slots) {
            if (slot.isAppointment) {
                // Check if appointment start time fell between fromHour and toHour
                if (isHourInSlot(slot.start, fromHour, toHour)) {
                    const alreadyRecorded = this.missedAppointments.some(m => m.slot.id === slot.id && m.hour === slot.start);
                    if (!alreadyRecorded) {
                        const record = {
                            slot,
                            hour: slot.start,
                            reason: this.inDanger ? "danger" : "interrupted",
                            timestamp: Date.now()
                        };
                        this.missedAppointments.push(record);
                        if (this.system && typeof this.system.emit === "function") {
                            this.system.emit("missed_appointment", {
                                npcId: this.id,
                                ...record
                            });
                        }
                    }
                }
            }
        }
    }
}

/**
 * Manages 24-hour schedules, activity points, occupancy reservations,
 * danger interruptions, and multi-NPC routines.
 */
export class ScheduleSystem {
    /**
     * @param {Object} [config={}] - System configuration.
     * @param {Object} [config.clock=null] - Optional GameClock instance.
     * @param {Array} [config.slots=null] - Initial slots for default single-NPC routine.
     * @param {string} [config.defaultActivity="idle"] - Default fallback activity.
     * @param {number|string} [config.initialHour=0] - Initial game hour.
     */
    constructor(config = {}) {
        this.clock = config.clock || null;
        this.defaultActivity = config.defaultActivity || ROUTINE_ACTIVITIES.IDLE;
        this.currentHour = config.initialHour !== undefined ? parseHour(config.initialHour) : 0;
        this.schedules = new Map();
        this._occupiedPoints = new Map();
        this._listeners = new Map();

        if (Array.isArray(config.slots) && config.slots.length > 0) {
            this.registerNPC("default", {
                slots: config.slots,
                defaultActivity: this.defaultActivity,
                initialHour: this.currentHour
            });
        }
    }

    /**
     * Subscribes a listener to a system event.
     * @param {string} event - Event name.
     * @param {Function} callback - Callback function.
     * @returns {ScheduleSystem} This instance.
     */
    on(event, callback) {
        if (typeof callback !== "function") return this;
        if (!this._listeners.has(event)) {
            this._listeners.set(event, new Set());
        }
        this._listeners.get(event).add(callback);
        return this;
    }

    /**
     * Unsubscribes a listener from a system event.
     * @param {string} event - Event name.
     * @param {Function} callback - Callback function.
     * @returns {ScheduleSystem} This instance.
     */
    off(event, callback) {
        const listeners = this._listeners.get(event);
        if (listeners) {
            listeners.delete(callback);
        }
        return this;
    }

    /**
     * Emits a system event to registered listeners.
     * @param {string} event - Event name.
     * @param {Object} data - Payload data.
     */
    emit(event, data) {
        const listeners = this._listeners.get(event);
        if (listeners) {
            for (const cb of listeners) {
                try {
                    cb(data);
                } catch (err) {
                    console.error(`Error in ScheduleSystem event listener (${event}):`, err);
                }
            }
        }
    }

    /**
     * Registers an NPC routine with the schedule system.
     * @param {string} npcId - Unique identifier for the NPC.
     * @param {Object|Array|NPCSchedule} config - Schedule configuration or slots array.
     * @returns {NPCSchedule} Registered schedule.
     */
    registerNPC(npcId, config = {}) {
        if (!npcId || typeof npcId !== "string") {
            throw new TypeError("registerNPC requires a non-empty string npcId");
        }

        let schedule;
        if (config instanceof NPCSchedule) {
            schedule = config;
            schedule.id = npcId;
            schedule.system = this;
        } else if (Array.isArray(config)) {
            schedule = new NPCSchedule({
                id: npcId,
                slots: config,
                defaultActivity: this.defaultActivity,
                initialHour: this.currentHour,
                system: this
            });
        } else {
            const initialHour = config.initialHour !== undefined ? parseHour(config.initialHour) : this.currentHour;
            schedule = new NPCSchedule({
                id: npcId,
                defaultActivity: this.defaultActivity,
                system: this,
                ...config,
                initialHour
            });
        }

        this.schedules.set(npcId, schedule);
        schedule.update(schedule.currentHour);
        return schedule;
    }

    /**
     * Unregisters an NPC routine and frees its claimed points.
     * @param {string} npcId - NPC identifier.
     * @returns {boolean} True if removed.
     */
    unregisterNPC(npcId) {
        this.vacateAllForNPC(npcId);
        return this.schedules.delete(npcId);
    }

    /**
     * Gets the schedule instance for an NPC.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {NPCSchedule|null}
     */
    getSchedule(npcId = "default") {
        return this.schedules.get(npcId) || null;
    }

    /**
     * Adds a schedule slot to the default or specified NPC routine.
     * @param {Object|ScheduleSlot} slot - Slot configuration.
     * @param {string} [npcId="default"] - Target NPC identifier.
     * @returns {ScheduleSlot}
     */
    addSlot(slot, npcId = "default") {
        let schedule = this.getSchedule(npcId);
        if (!schedule) {
            schedule = this.registerNPC(npcId);
        }
        return schedule.addSlot(slot);
    }

    /**
     * Updates time across all registered NPC schedules.
     * Accepts a game hour float, time string, or GameClock instance.
     * @param {number|string|Object} [timeOrClock] - New time value or clock.
     * @returns {number} Current hour after update.
     */
    update(timeOrClock) {
        let hour = this.currentHour;
        if (timeOrClock !== undefined && timeOrClock !== null) {
            hour = parseHour(timeOrClock);
        } else if (this.clock) {
            hour = parseHour(this.clock);
        }

        this.currentHour = hour;
        for (const schedule of this.schedules.values()) {
            schedule.update(hour);
        }
        return this.currentHour;
    }

    /**
     * Advances time by the given amount and updates all schedules.
     * @param {number} delta - Amount of time to advance.
     * @param {string} [unit="hours"] - "hours" or "minutes".
     * @returns {number} New current hour.
     */
    advance(delta, unit = "hours") {
        if (!Number.isFinite(delta)) {
            throw new TypeError("Advance delta must be a finite number");
        }
        const deltaHours = unit === "minutes" ? delta / 60 : delta;
        return this.update(this.currentHour + deltaHours);
    }

    /**
     * Gets the current activity of an NPC.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {string}
     */
    getActivity(npcId = "default") {
        const schedule = this.getSchedule(npcId);
        return schedule ? schedule.currentActivity : this.defaultActivity;
    }

    /**
     * Gets the active schedule slot for an NPC.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {ScheduleSlot|null}
     */
    getCurrentSlot(npcId = "default") {
        const schedule = this.getSchedule(npcId);
        return schedule ? schedule.currentSlot : null;
    }

    /**
     * Gets the current destination point for an NPC.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {Object|string|null}
     */
    getCurrentDestination(npcId = "default") {
        const schedule = this.getSchedule(npcId);
        return schedule ? schedule.currentDestination : null;
    }

    /**
     * Checks whether an NPC schedule is currently suspended by danger.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {boolean}
     */
    isSuspended(npcId = "default") {
        const schedule = this.getSchedule(npcId);
        return schedule ? schedule.isSuspended : false;
    }

    /**
     * Alias for isSuspended.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {boolean}
     */
    isInDanger(npcId = "default") {
        return this.isSuspended(npcId);
    }

    /**
     * Suspends an NPC's schedule with a danger reaction.
     * @param {string|Object} npcIdOrDanger - NPC identifier or danger data for default NPC.
     * @param {Object} [maybeDanger={}] - Danger configuration if npcId was provided.
     * @returns {boolean} True if danger was triggered.
     */
    triggerDanger(npcIdOrDanger, maybeDanger = {}) {
        let npcId = "default";
        let dangerData = maybeDanger;

        if (typeof npcIdOrDanger === "string") {
            npcId = npcIdOrDanger;
        } else if (npcIdOrDanger && typeof npcIdOrDanger === "object") {
            dangerData = npcIdOrDanger;
        }

        const schedule = this.getSchedule(npcId);
        if (schedule) {
            schedule.triggerDanger(dangerData);
            return true;
        }
        return false;
    }

    /**
     * Resolves danger reaction for an NPC, resuming normal schedule routine.
     * @param {string} [npcId="default"] - NPC identifier.
     * @param {Object} [options={}] - Options passed to resolveDanger.
     * @returns {string} Resumed activity.
     */
    resolveDanger(npcId = "default", options = {}) {
        const schedule = this.getSchedule(npcId);
        if (schedule) {
            return schedule.resolveDanger(options);
        }
        return this.defaultActivity;
    }

    /**
     * Evaluates a perceived target against a FactionRegistry and interrupts schedule if hostile.
     * @param {string} npcId - Observing NPC identifier.
     * @param {Object} target - Perceived target entity.
     * @param {FactionRegistry} factionRegistry - Faction registry to query.
     * @param {Object} [dangerOverrides={}] - Optional danger settings.
     * @returns {boolean} True if hostile danger reaction was triggered.
     */
    perceiveDanger(npcId, target, factionRegistry, dangerOverrides = {}) {
        const schedule = this.getSchedule(npcId);
        if (!schedule || !target || !factionRegistry) return false;

        const observerFaction = schedule.faction;
        const targetFaction = FactionRegistry.resolveFaction(target);

        if (factionRegistry.isHostile(observerFaction, targetFaction)) {
            schedule.triggerDanger({
                threat: target,
                activity: ROUTINE_ACTIVITIES.COMBAT,
                ...dangerOverrides
            });
            return true;
        }
        return false;
    }

    /**
     * Gets missed appointments recorded for an NPC.
     * @param {string} [npcId="default"] - NPC identifier.
     * @returns {Array} List of missed appointment records.
     */
    getMissedAppointments(npcId = "default") {
        const schedule = this.getSchedule(npcId);
        return schedule ? [...schedule.missedAppointments] : [];
    }

    /**
     * Clears missed appointment history for an NPC.
     * @param {string} [npcId="default"] - NPC identifier.
     */
    clearMissedAppointments(npcId = "default") {
        const schedule = this.getSchedule(npcId);
        if (schedule) {
            schedule.missedAppointments.length = 0;
        }
    }

    /**
     * Checks if an activity point is currently occupied.
     * @param {Object|string} point - Activity point to check.
     * @param {string} [excludingNpcId] - Optional NPC identifier to ignore (e.g. self).
     * @returns {boolean} True if occupied.
     */
    isPointOccupied(point, excludingNpcId) {
        if (!point) return false;
        if (typeof point === "object" && point.occupied === true && !this._occupiedPoints.has(getPointKey(point))) {
            return true;
        }
        const key = getPointKey(point);
        if (!key) return false;
        const record = this._occupiedPoints.get(key);
        if (!record) return false;
        if (excludingNpcId && record.npcId === excludingNpcId) {
            return false;
        }
        return true;
    }

    /**
     * Claims an activity point for an NPC.
     * @param {Object|string} point - Activity point to claim.
     * @param {string} npcId - Claiming NPC identifier.
     * @returns {boolean} True if successfully claimed.
     */
    occupyPoint(point, npcId) {
        if (!point) return false;
        const key = getPointKey(point);
        if (!key) return false;

        const existing = this._occupiedPoints.get(key);
        if (existing && existing.npcId !== npcId) {
            return false;
        }

        this._occupiedPoints.set(key, { npcId, point });
        if (typeof point === "object") {
            point.occupied = true;
        }
        return true;
    }

    /**
     * Vacates a claimed activity point.
     * @param {Object|string} point - Point to vacate.
     * @param {string} [npcId] - Optional NPC identifier to ensure ownership.
     * @returns {boolean} True if vacated.
     */
    vacatePoint(point, npcId) {
        if (!point) return false;
        const key = getPointKey(point);
        if (!key) return false;

        const existing = this._occupiedPoints.get(key);
        if (!existing) return false;
        if (npcId && existing.npcId !== npcId) {
            return false;
        }

        this._occupiedPoints.delete(key);
        if (typeof existing.point === "object") {
            existing.point.occupied = false;
        }
        if (typeof point === "object") {
            point.occupied = false;
        }
        return true;
    }

    /**
     * Vacates all activity points claimed by an NPC.
     * @param {string} npcId - NPC identifier.
     */
    vacateAllForNPC(npcId) {
        for (const [key, record] of Array.from(this._occupiedPoints.entries())) {
            if (record.npcId === npcId) {
                this._occupiedPoints.delete(key);
                if (typeof record.point === "object") {
                    record.point.occupied = false;
                }
            }
        }
    }

    /**
     * Gets the identifier of the NPC occupying a point.
     * @param {Object|string} point - Activity point.
     * @returns {string|null} Occupant NPC identifier or null.
     */
    getOccupant(point) {
        const key = getPointKey(point);
        if (!key) return null;
        const record = this._occupiedPoints.get(key);
        return record ? record.npcId : null;
    }
}

/**
 * Faction registry managing bidirectional and asymmetric faction standings,
 * numerical reputations, and disposition queries (friendly, neutral, hostile).
 */
export class FactionRegistry {
    /**
     * @param {Object} [config={}] - Registry configuration.
     * @param {string} [config.defaultDisposition="neutral"] - Disposition when no relation exists.
     * @param {number} [config.defaultReputation=0] - Default numerical reputation.
     * @param {number} [config.hostileThreshold=-25] - Reputation at or below which disposition is hostile.
     * @param {number} [config.friendlyThreshold=25] - Reputation at or above which disposition is friendly.
     * @param {Array} [config.factions=[]] - Initial faction names to register.
     */
    constructor(config = {}) {
        this.defaultDisposition = config.defaultDisposition || FACTION_DISPOSITION.NEUTRAL;
        this.defaultReputation = Number.isFinite(config.defaultReputation) ? config.defaultReputation : 0;
        this.hostileThreshold = Number.isFinite(config.hostileThreshold) ? config.hostileThreshold : -25;
        this.friendlyThreshold = Number.isFinite(config.friendlyThreshold) ? config.friendlyThreshold : 25;
        this._reputations = new Map();
        this._dispositions = new Map();
        this._factions = new Set();

        if (Array.isArray(config.factions)) {
            for (const f of config.factions) {
                this.registerFaction(f);
            }
        }
    }

    /**
     * Resolves a faction name from a string, entity, or combatant.
     * @param {Object|string} target - Entity, combatant, or faction string.
     * @returns {string} Faction name.
     */
    static resolveFaction(target) {
        if (!target) return "neutral";
        if (typeof target === "string") return target.trim();
        if (typeof target.faction === "string" && target.faction.trim()) {
            return target.faction.trim();
        }
        if (typeof target.GetComponent === "function") {
            const combatant = target.GetComponent("Combatant");
            if (combatant && typeof combatant.faction === "string" && combatant.faction.trim()) {
                return combatant.faction.trim();
            }
        }
        return "neutral";
    }

    /**
     * Registers a faction name into the registry.
     * @param {string} name - Faction name.
     * @returns {FactionRegistry} This instance.
     */
    registerFaction(name) {
        const faction = FactionRegistry.resolveFaction(name);
        if (faction) {
            this._factions.add(faction);
        }
        return this;
    }

    /**
     * Checks if a faction is registered.
     * @param {string} name - Faction name.
     * @returns {boolean}
     */
    hasFaction(name) {
        const faction = FactionRegistry.resolveFaction(name);
        return this._factions.has(faction);
    }

    /**
     * Returns all registered faction names.
     * @returns {Array} List of faction names.
     */
    getFactions() {
        return Array.from(this._factions);
    }

    /**
     * Sets numerical reputation from source towards target.
     * Supports asymmetric (default) or bidirectional updates.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @param {number} value - Numerical reputation value.
     * @param {Object} [options={}] - Options object.
     * @param {boolean} [options.bidirectional=false] - Whether to set target->source as well.
     * @param {boolean} [options.keepOverride=false] - Whether to keep explicit disposition overrides.
     * @returns {FactionRegistry} This instance.
     */
    setReputation(source, target, value, options = {}) {
        if (!Number.isFinite(value)) {
            throw new TypeError("Reputation value must be a finite number");
        }
        const src = FactionRegistry.resolveFaction(source);
        const tgt = FactionRegistry.resolveFaction(target);
        this.registerFaction(src);
        this.registerFaction(tgt);

        const key = `${src}->${tgt}`;
        this._reputations.set(key, value);
        if (!options.keepOverride) {
            this._dispositions.delete(key);
        }

        if (options.bidirectional || options.symmetric) {
            const revKey = `${tgt}->${src}`;
            this._reputations.set(revKey, value);
            if (!options.keepOverride) {
                this._dispositions.delete(revKey);
            }
        }
        return this;
    }

    /**
     * Modifies numerical reputation between source and target by delta.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @param {number} delta - Amount to adjust reputation by.
     * @param {Object} [options={}] - Options object.
     * @param {boolean} [options.bidirectional=false] - Whether to adjust target->source as well.
     * @returns {number} New reputation score.
     */
    modifyReputation(source, target, delta, options = {}) {
        if (!Number.isFinite(delta)) {
            throw new TypeError("Reputation delta must be a finite number");
        }
        const current = this.getReputation(source, target);
        const next = current + delta;
        this.setReputation(source, target, next, options);
        return next;
    }

    /**
     * Gets the numerical reputation of source faction towards target.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @returns {number} Numerical reputation.
     */
    getReputation(source, target) {
        const src = FactionRegistry.resolveFaction(source);
        const tgt = FactionRegistry.resolveFaction(target);
        const key = `${src}->${tgt}`;

        if (this._reputations.has(key)) {
            return this._reputations.get(key);
        }
        if (src === tgt) {
            return 100;
        }
        return this.defaultReputation;
    }

    /**
     * Sets an explicit disposition override from source towards target.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @param {string} disposition - "friendly", "neutral", or "hostile".
     * @param {Object} [options={}] - Options object.
     * @param {boolean} [options.bidirectional=false] - Whether to set target->source as well.
     * @param {boolean} [options.setReputation=true] - Whether to synchronize numerical reputation baseline.
     * @returns {FactionRegistry} This instance.
     */
    setDisposition(source, target, disposition, options = {}) {
        const valid = Object.values(FACTION_DISPOSITION);
        if (!valid.includes(disposition)) {
            throw new TypeError(`Disposition must be one of: ${valid.join(", ")}`);
        }
        const src = FactionRegistry.resolveFaction(source);
        const tgt = FactionRegistry.resolveFaction(target);
        this.registerFaction(src);
        this.registerFaction(tgt);

        const key = `${src}->${tgt}`;
        this._dispositions.set(key, disposition);

        if (options.setReputation !== false) {
            let repVal = 0;
            if (disposition === FACTION_DISPOSITION.HOSTILE) repVal = this.hostileThreshold;
            else if (disposition === FACTION_DISPOSITION.FRIENDLY) repVal = this.friendlyThreshold;
            this._reputations.set(key, repVal);
        }

        if (options.bidirectional || options.symmetric) {
            const revKey = `${tgt}->${src}`;
            this._dispositions.set(revKey, disposition);
            if (options.setReputation !== false) {
                let repVal = 0;
                if (disposition === FACTION_DISPOSITION.HOSTILE) repVal = this.hostileThreshold;
                else if (disposition === FACTION_DISPOSITION.FRIENDLY) repVal = this.friendlyThreshold;
                this._reputations.set(revKey, repVal);
            }
        }
        return this;
    }

    /**
     * Gets the disposition of source towards target ("friendly", "neutral", or "hostile").
     * Respects explicit disposition overrides and derives from reputation thresholds.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @returns {string} Disposition string.
     */
    getDisposition(source, target) {
        const src = FactionRegistry.resolveFaction(source);
        const tgt = FactionRegistry.resolveFaction(target);
        const key = `${src}->${tgt}`;

        if (this._dispositions.has(key)) {
            return this._dispositions.get(key);
        }
        if (src === tgt) {
            return FACTION_DISPOSITION.FRIENDLY;
        }

        const rep = this.getReputation(src, tgt);
        if (rep <= this.hostileThreshold) {
            return FACTION_DISPOSITION.HOSTILE;
        }
        if (rep >= this.friendlyThreshold) {
            return FACTION_DISPOSITION.FRIENDLY;
        }
        return this.defaultDisposition;
    }

    /**
     * Checks if source faction considers target hostile.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @returns {boolean} True if hostile.
     */
    isHostile(source, target) {
        return this.getDisposition(source, target) === FACTION_DISPOSITION.HOSTILE;
    }

    /**
     * Checks if source faction considers target friendly.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @returns {boolean} True if friendly.
     */
    isFriendly(source, target) {
        return this.getDisposition(source, target) === FACTION_DISPOSITION.FRIENDLY;
    }

    /**
     * Checks if source faction considers target neutral.
     * @param {Object|string} source - Source faction or entity.
     * @param {Object|string} target - Target faction or entity.
     * @returns {boolean} True if neutral.
     */
    isNeutral(source, target) {
        return this.getDisposition(source, target) === FACTION_DISPOSITION.NEUTRAL;
    }

    /**
     * Clears all recorded standings and registrations.
     */
    clear() {
        this._reputations.clear();
        this._dispositions.clear();
        this._factions.clear();
    }

    /**
     * Serializes faction standings into a plain JSON-compatible object.
     * @returns {Object}
     */
    serialize() {
        return {
            defaultDisposition: this.defaultDisposition,
            defaultReputation: this.defaultReputation,
            hostileThreshold: this.hostileThreshold,
            friendlyThreshold: this.friendlyThreshold,
            factions: Array.from(this._factions),
            reputations: Object.fromEntries(this._reputations),
            dispositions: Object.fromEntries(this._dispositions)
        };
    }

    /**
     * Restores faction standings from serialized data.
     * @param {Object} data - Serialized state object.
     * @returns {FactionRegistry} This instance.
     */
    restore(data) {
        if (!data || typeof data !== "object") return this;
        if (data.defaultDisposition) this.defaultDisposition = data.defaultDisposition;
        if (Number.isFinite(data.defaultReputation)) this.defaultReputation = data.defaultReputation;
        if (Number.isFinite(data.hostileThreshold)) this.hostileThreshold = data.hostileThreshold;
        if (Number.isFinite(data.friendlyThreshold)) this.friendlyThreshold = data.friendlyThreshold;
        if (Array.isArray(data.factions)) {
            for (const f of data.factions) this.registerFaction(f);
        }
        if (data.reputations && typeof data.reputations === "object") {
            for (const [k, v] of Object.entries(data.reputations)) {
                this._reputations.set(k, v);
            }
        }
        if (data.dispositions && typeof data.dispositions === "object") {
            for (const [k, v] of Object.entries(data.dispositions)) {
                this._dispositions.set(k, v);
            }
        }
        return this;
    }

    /**
     * Creates and deserializes a new FactionRegistry instance.
     * @param {Object} data - Serialized data.
     * @returns {FactionRegistry}
     */
    static deserialize(data) {
        const reg = new FactionRegistry(data);
        reg.restore(data);
        return reg;
    }
}