larissa_perceptionMemory.js

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

/**
 * Built-in archetype profiles with configured perception and memory budgets.
 */
export const ARCHETYPES = Object.freeze({
    sentinel: Object.freeze({
        visionRange: 350,
        fov: Math.PI * 0.5,
        hearingRadius: 120,
        alertRadius: 120,
        maxEntries: 8,
        decayRate: 0.05,
        forgetThreshold: 0
    }),
    patrol: Object.freeze({
        visionRange: 250,
        fov: Math.PI * 0.65,
        hearingRadius: 100,
        alertRadius: 100,
        maxEntries: 12,
        decayRate: 0.1,
        forgetThreshold: 0
    }),
    civilian: Object.freeze({
        visionRange: 150,
        fov: Math.PI * 0.75,
        hearingRadius: 80,
        alertRadius: 80,
        maxEntries: 4,
        decayRate: 0.25,
        forgetThreshold: 0
    }),
    boss: Object.freeze({
        visionRange: 500,
        fov: Math.PI * 0.9,
        hearingRadius: 250,
        alertRadius: 250,
        maxEntries: 25,
        decayRate: 0.02,
        forgetThreshold: 0
    })
});

/**
 * Normalize an angle into [-PI, PI].
 * @param {number} rad
 * @returns {number}
 */
export function normalizeAngle(rad) {
    let a = rad % (2 * Math.PI);
    if (a > Math.PI) a -= 2 * Math.PI;
    if (a < -Math.PI) a += 2 * Math.PI;
    return a;
}

/**
 * Safely extracts a 2D coordinate from an object, component, or entity.
 * @param {Object} obj
 * @returns {Object|null}
 */
export function extractPosition(obj) {
    if (!obj || typeof obj !== "object") return null;

    if (typeof obj.GetComponent === "function") {
        const tr = obj.GetComponent(Transform);
        if (tr && tr.position && Number.isFinite(tr.position.x) && Number.isFinite(tr.position.y)) {
            return { x: tr.position.x, y: tr.position.y };
        }
    }

    if (obj.transform) {
        const tPos = obj.transform.position ?? obj.transform;
        if (Number.isFinite(tPos.x) && Number.isFinite(tPos.y)) {
            return { x: tPos.x, y: tPos.y };
        }
    }

    if (obj.position && Number.isFinite(obj.position.x) && Number.isFinite(obj.position.y)) {
        return { x: obj.position.x, y: obj.position.y };
    }

    if (Number.isFinite(obj.x) && Number.isFinite(obj.y)) {
        return { x: obj.x, y: obj.y };
    }

    if (Array.isArray(obj) && Number.isFinite(obj[0]) && Number.isFinite(obj[1])) {
        return { x: obj[0], y: obj[1] };
    }

    return null;
}

/**
 * Safely extracts facing angle in radians from an observer.
 * @param {Object} obj
 * @returns {number}
 */
export function extractFacing(obj) {
    if (!obj || typeof obj !== "object") return 0;

    let val = obj.facing ?? obj.direction ?? obj.rotation ?? obj.angle;
    if (val === undefined && obj.transform) {
        val = obj.transform.rotation ?? obj.transform.facing ?? obj.transform.direction;
    }

    if (typeof val === "number") {
        if (Math.abs(val) > 2 * Math.PI) {
            return (val * Math.PI) / 180;
        }
        return val;
    }

    if (typeof val === "string") {
        const s = val.toLowerCase().trim();
        switch (s) {
            case "right":
            case "east":
                return 0;
            case "down-right":
            case "southeast":
                return Math.PI / 4;
            case "down":
            case "south":
                return Math.PI / 2;
            case "down-left":
            case "southwest":
                return (Math.PI * 3) / 4;
            case "left":
            case "west":
                return Math.PI;
            case "up-left":
            case "northwest":
                return (-Math.PI * 3) / 4;
            case "up":
            case "north":
                return -Math.PI / 2;
            case "up-right":
            case "northeast":
                return -Math.PI / 4;
            default: {
                const parsed = Number(s);
                if (Number.isFinite(parsed)) {
                    return Math.abs(parsed) > 2 * Math.PI ? (parsed * Math.PI) / 180 : parsed;
                }
                return 0;
            }
        }
    }

    if (val && typeof val === "object" && Number.isFinite(val.x) && Number.isFinite(val.y)) {
        if (val.x !== 0 || val.y !== 0) {
            return Math.atan2(val.y, val.x);
        }
    }

    return 0;
}

/**
 * Determines whether an entity has been destroyed or flagged as dead.
 * @param {Object} entity
 * @returns {boolean}
 */
export function isDestroyed(entity) {
    if (!entity || typeof entity !== "object") return false;
    return entity._destroyed === true || entity.destroyed === true;
}

/**
 * Tests 2D line segment intersection.
 * @param {Object} p1
 * @param {Object} p2
 * @param {Object} p3
 * @param {Object} p4
 * @returns {boolean}
 */
export function segmentIntersectsSegment(p1, p2, p3, p4) {
    const d = (p4.y - p3.y) * (p2.x - p1.x) - (p4.x - p3.x) * (p2.y - p1.y);
    if (Math.abs(d) < 1e-9) return false;

    const ua = ((p4.x - p3.x) * (p1.y - p3.y) - (p4.y - p3.y) * (p1.x - p3.x)) / d;
    const ub = ((p2.x - p1.x) * (p1.y - p3.y) - (p2.y - p1.y) * (p1.x - p3.x)) / d;

    const eps = 1e-6;
    return (ua > eps && ua < 1 - eps && ub >= 0 && ub <= 1);
}

/**
 * Tests ray segment intersection against an axis-aligned bounding box.
 * @param {Object} p1
 * @param {Object} p2
 * @param {number} left
 * @param {number} top
 * @param {number} right
 * @param {number} bottom
 * @returns {boolean}
 */
export function segmentIntersectsAABB(p1, p2, left, top, right, bottom) {
    const minX = Math.min(left, right);
    const maxX = Math.max(left, right);
    const minY = Math.min(top, bottom);
    const maxY = Math.max(top, bottom);

    if ((p1.x < minX && p2.x < minX) || (p1.x > maxX && p2.x > maxX) ||
        (p1.y < minY && p2.y < minY) || (p1.y > maxY && p2.y > maxY)) {
        return false;
    }

    const dx = p2.x - p1.x;
    const dy = p2.y - p1.y;
    let t0 = 0.0;
    let t1 = 1.0;

    if (Math.abs(dx) < 1e-9) {
        if (p1.x < minX || p1.x > maxX) return false;
    } else {
        let tx1 = (minX - p1.x) / dx;
        let tx2 = (maxX - p1.x) / dx;
        if (tx1 > tx2) { const tmp = tx1; tx1 = tx2; tx2 = tmp; }
        t0 = Math.max(t0, tx1);
        t1 = Math.min(t1, tx2);
        if (t0 > t1) return false;
    }

    if (Math.abs(dy) < 1e-9) {
        if (p1.y < minY || p1.y > maxY) return false;
    } else {
        let ty1 = (minY - p1.y) / dy;
        let ty2 = (maxY - p1.y) / dy;
        if (ty1 > ty2) { const tmp = ty1; ty1 = ty2; ty2 = tmp; }
        t0 = Math.max(t0, ty1);
        t1 = Math.min(t1, ty2);
        if (t0 > t1) return false;
    }

    const eps = 1e-5;
    return t1 > eps && t0 < 1.0 - eps;
}

/**
 * Tests ray segment intersection against a circle obstacle.
 * @param {Object} p1
 * @param {Object} p2
 * @param {number} cx
 * @param {number} cy
 * @param {number} radius
 * @returns {boolean}
 */
export function segmentIntersectsCircle(p1, p2, cx, cy, radius) {
    const dx = p2.x - p1.x;
    const dy = p2.y - p1.y;
    const lenSq = dx * dx + dy * dy;
    if (lenSq < 1e-9) {
        const distSq = (p1.x - cx) ** 2 + (p1.y - cy) ** 2;
        return distSq <= radius * radius;
    }
    let t = ((cx - p1.x) * dx + (cy - p1.y) * dy) / lenSq;
    t = Math.max(0, Math.min(1, t));
    const closeX = p1.x + t * dx;
    const closeY = p1.y + t * dy;
    const distSq = (closeX - cx) ** 2 + (closeY - cy) ** 2;
    const eps = 1e-5;
    return distSq <= radius * radius && t > eps && t < 1.0 - eps;
}

/**
 * Checks whether a line segment from p1 to p2 intersects an obstacle.
 * @param {Object} p1
 * @param {Object} p2
 * @param {Object} obstacle
 * @returns {boolean}
 */
export function rayIntersectsObstacle(p1, p2, obstacle) {
    if (!obstacle || typeof obstacle !== "object") return false;
    if (isDestroyed(obstacle)) return false;
    if (obstacle.blocksVision === false) return false;

    if (typeof obstacle.blocksLineOfSight === "function") {
        return obstacle.blocksLineOfSight(p1, p2);
    }
    if (typeof obstacle.intersectsRay === "function") {
        return obstacle.intersectsRay(p1, p2);
    }

    if (obstacle.start && obstacle.end) {
        return segmentIntersectsSegment(p1, p2, obstacle.start, obstacle.end);
    }
    if (Number.isFinite(obstacle.x1) && Number.isFinite(obstacle.y1) &&
        Number.isFinite(obstacle.x2) && Number.isFinite(obstacle.y2)) {
        return segmentIntersectsSegment(p1, p2,
            { x: obstacle.x1, y: obstacle.y1 },
            { x: obstacle.x2, y: obstacle.y2 }
        );
    }

    if (Number.isFinite(obstacle.radius) && obstacle.radius > 0) {
        const center = obstacle.center ? extractPosition(obstacle.center) : extractPosition(obstacle);
        if (center) {
            return segmentIntersectsCircle(p1, p2, center.x, center.y, obstacle.radius);
        }
    }

    let bounds = null;
    if (typeof obstacle.getBounds === "function") {
        const pos = extractPosition(obstacle) || { x: 0, y: 0 };
        bounds = obstacle.getBounds(pos.x, pos.y);
    } else if (obstacle.bounds) {
        bounds = obstacle.bounds;
    } else if (obstacle.box) {
        bounds = obstacle.box;
    } else if (Number.isFinite(obstacle.left) && Number.isFinite(obstacle.right) &&
               Number.isFinite(obstacle.top) && Number.isFinite(obstacle.bottom)) {
        bounds = obstacle;
    } else if (Number.isFinite(obstacle.width) && Number.isFinite(obstacle.height)) {
        const pos = extractPosition(obstacle) || { x: 0, y: 0 };
        bounds = {
            left: pos.x,
            top: pos.y,
            right: pos.x + obstacle.width,
            bottom: pos.y + obstacle.height
        };
    }

    if (bounds) {
        const left = bounds.left ?? bounds.x;
        const top = bounds.top ?? bounds.y;
        const right = bounds.right ?? (bounds.left !== undefined ? bounds.right : (left + (bounds.width ?? 0)));
        const bottom = bounds.bottom ?? (bounds.top !== undefined ? bounds.bottom : (top + (bounds.height ?? 0)));
        if (Number.isFinite(left) && Number.isFinite(top) && Number.isFinite(right) && Number.isFinite(bottom)) {
            return segmentIntersectsAABB(p1, p2, left, top, right, bottom);
        }
    }

    return false;
}

/**
 * PerceptionSystem calculates vision, FOV cone, line-of-sight raycasting, and hearing alert detection.
 */
export class PerceptionSystem {
    /**
     * @param {Object} [config]
     */
    constructor(config = {}) {
        this.visionRange = config.visionRange ?? 200;
        this.fov = config.fov !== undefined
            ? (config.fov > 2 * Math.PI ? (config.fov * Math.PI) / 180 : config.fov)
            : Math.PI * 0.5;
        this.hearingRadius = config.hearingRadius ?? config.alertRadius ?? 80;
        this.alertRadius = config.alertRadius ?? this.hearingRadius;
    }

    /**
     * Checks if line-of-sight from source to target is unobstructed by obstacles.
     * @param {Object} from
     * @param {Object} to
     * @param {Array} [obstacles]
     * @returns {boolean}
     */
    hasLineOfSight(from, to, obstacles = []) {
        const p1 = extractPosition(from);
        const p2 = extractPosition(to);
        if (!p1 || !p2) return false;

        const dx = p2.x - p1.x;
        const dy = p2.y - p1.y;
        if (dx === 0 && dy === 0) return true;

        if (!Array.isArray(obstacles) || obstacles.length === 0) return true;

        for (const obstacle of obstacles) {
            if (!obstacle || obstacle === from || obstacle === to) continue;
            if (rayIntersectsObstacle(p1, p2, obstacle)) {
                return false;
            }
        }

        return true;
    }

    /**
     * Checks if target is within observer's vision range.
     * @param {Object} observer
     * @param {Object} target
     * @returns {boolean}
     */
    isInVisionRange(observer, target) {
        const p1 = extractPosition(observer);
        const p2 = extractPosition(target);
        if (!p1 || !p2) return false;

        const maxRange = observer?.visionRange ?? observer?.sightRange ?? observer?.perceptionRadius ?? this.visionRange;
        const distSq = (p2.x - p1.x) ** 2 + (p2.y - p1.y) ** 2;
        return distSq <= maxRange * maxRange;
    }

    /**
     * Checks if target is within observer's field of view (FOV) cone.
     * @param {Object} observer
     * @param {Object} target
     * @returns {boolean}
     */
    isInFov(observer, target) {
        const p1 = extractPosition(observer);
        const p2 = extractPosition(target);
        if (!p1 || !p2) return false;

        const dx = p2.x - p1.x;
        const dy = p2.y - p1.y;
        if (dx === 0 && dy === 0) return true;

        let fov = observer?.fov ?? this.fov;
        if (fov > 2 * Math.PI) fov = (fov * Math.PI) / 180;
        if (fov >= 2 * Math.PI) return true;

        const facing = extractFacing(observer);
        const angle = Math.atan2(dy, dx);
        const diff = Math.abs(normalizeAngle(angle - facing));

        return diff <= fov / 2 + 1e-6;
    }

    /**
     * Determines whether a candidate emits sound or alert signals.
     * @param {Object} candidate
     * @returns {boolean}
     */
    isAudibleCandidate(candidate) {
        if (!candidate || typeof candidate !== "object") return false;
        if (candidate.type === "sound" || candidate.type === "noise" || candidate.type === "audio") return true;
        if (candidate.isSound === true || candidate.isAudible === true || candidate.audible === true) return true;
        if (candidate.sound === true || (typeof candidate.noise === "number" && candidate.noise > 0)) return true;
        if (typeof candidate.soundRadius === "number" && candidate.soundRadius > 0) return true;
        if (candidate.type === "alert" || candidate.isAlert === true || candidate.alert === true) return true;
        if (candidate.audibleDanger === true || candidate.dangerSound === true) return true;
        return false;
    }

    /**
     * Checks if observer can see target (in range, in cone, and LOS unobstructed).
     * @param {Object} observer
     * @param {Object} target
     * @param {Array} [obstacles]
     * @returns {boolean}
     */
    canSee(observer, target, obstacles = []) {
        if (!observer || !target) return false;
        if (isDestroyed(target)) return false;
        if (!this.isInVisionRange(observer, target)) return false;
        if (!this.isInFov(observer, target)) return false;
        return this.hasLineOfSight(observer, target, obstacles);
    }

    /**
     * Checks if observer can hear target (within hearing/alert radius and emitting sound/alert).
     * @param {Object} observer
     * @param {Object} target
     * @returns {boolean}
     */
    canHear(observer, target) {
        if (!observer || !target) return false;
        if (isDestroyed(target)) return false;

        const p1 = extractPosition(observer);
        const p2 = extractPosition(target);
        if (!p1 || !p2) return false;

        const hearingRadius = observer?.hearingRadius ?? observer?.alertRadius ?? this.hearingRadius;
        const targetRadius = target?.soundRadius ?? target?.alertRadius ?? target?.radius ?? 0;
        const maxDist = hearingRadius + targetRadius;
        const distSq = (p2.x - p1.x) ** 2 + (p2.y - p1.y) ** 2;

        if (distSq > maxDist * maxDist) return false;
        return this.isAudibleCandidate(target);
    }

    /**
     * Filters candidate entities, returning visible and audible candidates.
     * @param {Object} observer
     * @param {Array} candidates
     * @param {Array} [obstacles]
     * @param {Object} [options]
     * @returns {Array}
     */
    observe(observer, candidates = [], obstacles = [], options = {}) {
        if (!observer || !Array.isArray(candidates) || candidates.length === 0) {
            return [];
        }

        const visibleAudible = [];
        const observations = [];

        for (const candidate of candidates) {
            if (!candidate || isDestroyed(candidate)) continue;

            const visible = this.canSee(observer, candidate, obstacles);
            const audible = this.canHear(observer, candidate);

            if (visible || audible) {
                visibleAudible.push(candidate);

                const p1 = extractPosition(observer) || { x: 0, y: 0 };
                const p2 = extractPosition(candidate) || { x: 0, y: 0 };
                const dx = p2.x - p1.x;
                const dy = p2.y - p1.y;
                const dist = Math.sqrt(dx * dx + dy * dy);
                const angle = Math.atan2(dy, dx);

                observations.push({
                    target: candidate,
                    candidate,
                    visible,
                    audible,
                    sense: visible && audible ? "both" : (visible ? "vision" : "hearing"),
                    distance: dist,
                    angle,
                    confidence: 1.0,
                    timestamp: Date.now()
                });
            }
        }

        if (options.detailed === true) {
            return observations;
        }

        Object.defineProperty(visibleAudible, "observations", {
            value: observations,
            enumerable: false,
            configurable: true
        });

        return visibleAudible;
    }
}

/**
 * Capacity-capped memory with confidence decay, expiration, and safe handling of missing entities.
 */
export class BoundedMemory {
    /**
     * @param {Object} [config]
     */
    constructor(config = {}) {
        this.maxEntries = config.maxEntries ?? 10;
        this.decayRate = config.decayRate ?? 0.1;
        this.forgetThreshold = config.forgetThreshold ?? 0;
        this.defaultConfidence = config.defaultConfidence ?? 1.0;
        this._entries = new Map();
        this._idCounter = 1;
    }

    get size() {
        return this._entries.size;
    }

    /**
     * Resolves a key for a target entity or id.
     * @param {Object|string|number} target
     * @returns {string|null}
     * @private
     */
    _getKey(target) {
        if (target === null || target === undefined) return null;
        if (typeof target === "string") return target;
        if (typeof target === "number") return String(target);
        if (typeof target === "object") {
            if (target.id !== undefined && target.id !== null) return String(target.id);
            if (target.name !== undefined && target.name !== null) return String(target.name);
            if (target.key !== undefined && target.key !== null) return String(target.key);
            if (!target.__memoryId) {
                target.__memoryId = `mem_ent_${this._idCounter++}`;
            }
            return target.__memoryId;
        }
        return null;
    }

    /**
     * Evicts one entry from memory according to eviction rules:
     * 1. Destroyed/missing targets first.
     * 2. Lowest confidence entry.
     * 3. Oldest entry when confidence ties.
     * @private
     */
    _evictOne() {
        if (this._entries.size === 0) return;

        let candidateKey = null;
        let lowestConfidence = Infinity;
        let oldestTime = Infinity;

        for (const [key, entry] of this._entries) {
            if (isDestroyed(entry.target)) {
                candidateKey = key;
                break;
            }

            const conf = entry.confidence;
            const time = entry.lastSeen ?? entry.timestamp ?? 0;

            if (conf < lowestConfidence - 1e-4) {
                lowestConfidence = conf;
                oldestTime = time;
                candidateKey = key;
            } else if (Math.abs(conf - lowestConfidence) <= 1e-4) {
                if (time < oldestTime) {
                    oldestTime = time;
                    candidateKey = key;
                }
            }
        }

        if (candidateKey !== null) {
            this._entries.delete(candidateKey);
        } else {
            const firstKey = this._entries.keys().next().value;
            if (firstKey !== undefined) this._entries.delete(firstKey);
        }
    }

    /**
     * Removes all destroyed entities currently held in memory.
     * @returns {number}
     */
    pruneDestroyed() {
        const toDelete = [];
        for (const [key, entry] of this._entries) {
            if (isDestroyed(entry.target)) {
                toDelete.push(key);
            }
        }
        for (const key of toDelete) {
            this._entries.delete(key);
        }
        return toDelete.length;
    }

    /**
     * Records or refreshes an observation record in memory.
     * @param {Object|string} target
     * @param {Object} [options]
     * @returns {Object|null}
     */
    record(target, options = {}) {
        if (!target || isDestroyed(target)) return null;
        const key = this._getKey(target);
        if (!key) return null;

        const pos = extractPosition(options.position ?? target);
        const timestamp = options.timestamp ?? Date.now();
        const confidence = options.confidence ?? this.defaultConfidence;

        if (this._entries.has(key)) {
            const entry = this._entries.get(key);
            entry.confidence = confidence;
            entry.lastSeen = timestamp;
            entry.timestamp = timestamp;
            if (pos) entry.position = pos;
            entry.target = target;
            entry.entity = target;
            if (options.sense) entry.sense = options.sense;
            if (options.data) entry.data = { ...entry.data, ...options.data };

            this._entries.delete(key);
            this._entries.set(key, entry);
            return entry;
        }

        this.pruneDestroyed();
        while (this._entries.size >= this.maxEntries) {
            this._evictOne();
        }

        const entry = {
            id: key,
            target,
            entity: target,
            position: pos ? { x: pos.x, y: pos.y } : null,
            confidence,
            lastSeen: timestamp,
            timestamp,
            sense: options.sense ?? "vision",
            decayRate: options.decayRate ?? this.decayRate,
            data: options.data ? { ...options.data } : {}
        };

        this._entries.set(key, entry);
        return entry;
    }

    /**
     * Alias for record.
     * @param {Object|string} target
     * @param {Object} [options]
     * @returns {Object|null}
     */
    remember(target, options = {}) {
        return this.record(target, options);
    }

    /**
     * Decays confidence over time and forgets expired entries.
     * @param {number} [deltaTime=1]
     */
    decay(deltaTime = 1) {
        if (!Number.isFinite(deltaTime) || deltaTime <= 0) return;
        const toDelete = [];

        for (const [key, entry] of this._entries) {
            if (isDestroyed(entry.target)) {
                toDelete.push(key);
                continue;
            }

            const rate = entry.decayRate ?? this.decayRate;
            entry.confidence -= rate * deltaTime;

            if (entry.confidence <= this.forgetThreshold) {
                toDelete.push(key);
            }
        }

        for (const key of toDelete) {
            this._entries.delete(key);
        }
    }

    /**
     * Alias for decay.
     * @param {number} [deltaTime=1]
     */
    update(deltaTime = 1) {
        this.decay(deltaTime);
    }

    /**
     * Retrieves an entry for a target, handling destroyed and expired entities.
     * @param {Object|string} target
     * @returns {Object|null}
     */
    get(target) {
        if (!target) return null;
        const key = this._getKey(target);
        if (!key || !this._entries.has(key)) return null;

        const entry = this._entries.get(key);
        if (isDestroyed(entry.target) || entry.confidence <= this.forgetThreshold) {
            this._entries.delete(key);
            return null;
        }
        return entry;
    }

    /**
     * Returns true if target is remembered with valid confidence.
     * @param {Object|string} target
     * @returns {boolean}
     */
    has(target) {
        return this.get(target) !== null;
    }

    /**
     * Forgets a target immediately.
     * @param {Object|string} target
     * @returns {boolean}
     */
    forget(target) {
        if (!target) return false;
        const key = this._getKey(target);
        if (!key) return false;
        return this._entries.delete(key);
    }

    /**
     * Clears all memory records.
     */
    clear() {
        this._entries.clear();
    }

    /**
     * Returns all active, non-expired memory records.
     * @returns {Array}
     */
    values() {
        this.pruneDestroyed();
        const active = [];
        for (const entry of this._entries.values()) {
            if (!isDestroyed(entry.target) && entry.confidence > this.forgetThreshold) {
                active.push(entry);
            }
        }
        return active;
    }

    /**
     * Returns all active remembered entities.
     * @returns {Array}
     */
    getKnownTargets() {
        return this.values().map(e => e.target).filter(Boolean);
    }

    /**
     * Serializes memory state for save game snapshot.
     * @returns {Object}
     */
    serialize() {
        this.pruneDestroyed();
        const entries = [];
        for (const entry of this._entries.values()) {
            entries.push({
                id: entry.id,
                targetId: entry.target?.id ?? entry.id,
                position: entry.position ? { x: entry.position.x, y: entry.position.y } : null,
                confidence: entry.confidence,
                lastSeen: entry.lastSeen,
                timestamp: entry.timestamp,
                sense: entry.sense,
                decayRate: entry.decayRate,
                data: entry.data ? structuredClone(entry.data) : {}
            });
        }
        return {
            maxEntries: this.maxEntries,
            decayRate: this.decayRate,
            forgetThreshold: this.forgetThreshold,
            defaultConfidence: this.defaultConfidence,
            entries
        };
    }

    /**
     * Restores memory state from a snapshot.
     * @param {Object} snapshot
     * @param {Function} [entityResolver]
     * @returns {BoundedMemory}
     */
    restore(snapshot, entityResolver = null) {
        if (!snapshot || typeof snapshot !== "object") {
            throw new TypeError("Snapshot must be an object");
        }
        this.clear();
        if (Number.isFinite(snapshot.maxEntries)) this.maxEntries = snapshot.maxEntries;
        if (Number.isFinite(snapshot.decayRate)) this.decayRate = snapshot.decayRate;
        if (Number.isFinite(snapshot.forgetThreshold)) this.forgetThreshold = snapshot.forgetThreshold;
        if (Number.isFinite(snapshot.defaultConfidence)) this.defaultConfidence = snapshot.defaultConfidence;

        if (Array.isArray(snapshot.entries)) {
            for (const rec of snapshot.entries) {
                let target = null;
                if (typeof entityResolver === "function") {
                    target = entityResolver(rec.targetId ?? rec.id);
                }
                if (!target) {
                    target = { id: rec.targetId ?? rec.id, position: rec.position };
                }
                this._entries.set(rec.id, {
                    id: rec.id,
                    target,
                    entity: target,
                    position: rec.position ? { ...rec.position } : null,
                    confidence: rec.confidence ?? this.defaultConfidence,
                    lastSeen: rec.lastSeen ?? rec.timestamp ?? Date.now(),
                    timestamp: rec.timestamp ?? rec.lastSeen ?? Date.now(),
                    sense: rec.sense ?? "vision",
                    decayRate: rec.decayRate ?? this.decayRate,
                    data: rec.data ? structuredClone(rec.data) : {}
                });
            }
        }
        return this;
    }

    /**
     * JSON serialization support.
     * @returns {Object}
     */
    toJSON() {
        return this.serialize();
    }
}

/**
 * NPCKnowledge ties together archetype perception settings, bounded memory, and snapshot state.
 */
export class NPCKnowledge extends Component {
    static ARCHETYPES = ARCHETYPES;

    /**
     * @param {string|Object} [archetypeOrConfig="patrol"]
     * @param {Object} [overrides={}]
     */
    constructor(archetypeOrConfig = "patrol", overrides = {}) {
        super();
        let archetype = "patrol";
        let config = {};

        if (typeof archetypeOrConfig === "string") {
            archetype = archetypeOrConfig;
            config = { ...overrides };
        } else if (archetypeOrConfig && typeof archetypeOrConfig === "object") {
            if (archetypeOrConfig instanceof Component || typeof archetypeOrConfig.AddComponent === "function") {
                this.entity = archetypeOrConfig;
                if (typeof overrides === "string") {
                    archetype = overrides;
                } else if (typeof overrides === "object") {
                    archetype = overrides.archetype ?? "patrol";
                    config = { ...overrides };
                }
            } else {
                archetype = archetypeOrConfig.archetype ?? "patrol";
                config = { ...archetypeOrConfig, ...overrides };
            }
        }

        const baseProfile = NPCKnowledge.ARCHETYPES[archetype] ?? NPCKnowledge.ARCHETYPES.patrol;
        this.archetype = archetype in NPCKnowledge.ARCHETYPES ? archetype : "custom";
        this.profile = { ...baseProfile, ...config };

        this.perception = new PerceptionSystem({
            visionRange: this.profile.visionRange,
            fov: this.profile.fov,
            hearingRadius: this.profile.hearingRadius,
            alertRadius: this.profile.alertRadius
        });

        this.memory = new BoundedMemory({
            maxEntries: this.profile.maxEntries,
            decayRate: this.profile.decayRate,
            forgetThreshold: this.profile.forgetThreshold ?? 0,
            defaultConfidence: this.profile.defaultConfidence ?? 1.0
        });

        this.facts = {};
        this.state = config.state ?? "idle";
    }

    /**
     * Performs observation on candidates and records visible/audible entities into memory.
     * @param {Array} [candidates=[]]
     * @param {Array} [obstacles=[]]
     * @param {Object} [observer=null]
     * @returns {Array}
     */
    observe(candidates = [], obstacles = [], observer = null) {
        const actor = observer ?? this.entity;
        const perceived = this.perception.observe(actor, candidates, obstacles);
        for (const cand of perceived) {
            this.memory.record(cand, {
                position: extractPosition(cand),
                timestamp: Date.now()
            });
        }
        return perceived;
    }

    /**
     * Updates NPC knowledge: decays memory confidence and optionally processes observations.
     * @param {number} [deltaTime=1]
     * @param {Array} [candidates=null]
     * @param {Array} [obstacles=null]
     * @param {Object} [observer=null]
     * @returns {Array}
     */
    update(deltaTime = 1, candidates = null, obstacles = null, observer = null) {
        this.memory.decay(deltaTime);
        if (candidates && Array.isArray(candidates)) {
            return this.observe(candidates, obstacles, observer);
        }
        return [];
    }

    /**
     * Records a target into memory.
     * @param {Object|string} target
     * @param {Object} [data={}]
     * @returns {Object|null}
     */
    remember(target, data = {}) {
        return this.memory.record(target, data);
    }

    /**
     * Forgets a target from memory.
     * @param {Object|string} target
     * @returns {boolean}
     */
    forget(target) {
        return this.memory.forget(target);
    }

    /**
     * Returns all remembered entities.
     * @returns {Array}
     */
    getKnownTargets() {
        return this.memory.getKnownTargets();
    }

    /**
     * Serializes NPCKnowledge for save game snapshots.
     * @returns {Object}
     */
    serialize() {
        return {
            archetype: this.archetype,
            state: this.state,
            facts: structuredClone(this.facts),
            profile: structuredClone(this.profile),
            perception: {
                visionRange: this.perception.visionRange,
                fov: this.perception.fov,
                hearingRadius: this.perception.hearingRadius,
                alertRadius: this.perception.alertRadius
            },
            memory: this.memory.serialize()
        };
    }

    /**
     * Restores NPCKnowledge from a serialized snapshot.
     * @param {Object} snapshot
     * @param {Function} [entityResolver]
     * @returns {NPCKnowledge}
     */
    restore(snapshot, entityResolver = null) {
        if (!snapshot || typeof snapshot !== "object") throw new TypeError("Snapshot must be an object");
        if (snapshot.archetype) {
            this.archetype = snapshot.archetype;
            const baseProfile = NPCKnowledge.ARCHETYPES[this.archetype] ?? NPCKnowledge.ARCHETYPES.patrol;
            this.profile = { ...baseProfile, ...(snapshot.profile ?? {}) };
        }
        if (snapshot.state !== undefined) this.state = snapshot.state;
        if (snapshot.facts) this.facts = structuredClone(snapshot.facts);

        if (snapshot.perception) {
            if (Number.isFinite(snapshot.perception.visionRange)) this.perception.visionRange = snapshot.perception.visionRange;
            if (Number.isFinite(snapshot.perception.fov)) this.perception.fov = snapshot.perception.fov;
            if (Number.isFinite(snapshot.perception.hearingRadius)) this.perception.hearingRadius = snapshot.perception.hearingRadius;
            if (Number.isFinite(snapshot.perception.alertRadius)) this.perception.alertRadius = snapshot.perception.alertRadius;
        }

        if (snapshot.memory) {
            this.memory.restore(snapshot.memory, entityResolver);
        }
        return this;
    }

    /**
     * Creates and restores an NPCKnowledge instance from a snapshot.
     * @param {Object} snapshot
     * @param {Function} [entityResolver]
     * @returns {NPCKnowledge}
     */
    static restore(snapshot, entityResolver = null) {
        const instance = new NPCKnowledge(snapshot?.archetype ?? "patrol");
        instance.restore(snapshot, entityResolver);
        return instance;
    }

    /**
     * Populates the component properties from a data object during scene deserialization.
     * @param {Object} props
     */
    deserialize(props) {
        super.deserialize(props);
        if (props) {
            this.restore(props);
        }
    }

    /**
     * JSON serialization support.
     * @returns {Object}
     */
    toJSON() {
        return this.serialize();
    }
}