@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.1

package/dist/runtime/server/apis/npcs.api.d.ts

@@ -0,0 +1,213 @@
+import { IHasher } from '../../../adapters/contracts/IHasher';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
+import { IPedServer } from '../../../adapters/contracts/server/IPedServer';
+import { Vector3 } from '../../../kernel/utils/vector3';
+import { WorldContext } from '../../core/world';
+import { NPC } from '../entities/npc';
+import { NpcSpawnOptions, NpcSpawnResult, SerializedNpcData } from '../types/npc.types';
+/**
+ * Server-side API responsible for the full NPC (ped) lifecycle:
+ * spawn, registry, queries, spatial search, serialization and deletion.
+ *
+ * @remarks
+ * Prefer consuming this API from gameplay / AI systems instead of calling natives directly.
+ * This class keeps a stable in-memory registry keyed by `npcId` and maintains secondary
+ * indexes by `handle` and (when networked) by `netId`.
+ *
+ * The registry is authoritative for lookups, while `NPC.exists` reflects runtime existence.
+ */
+export declare class Npcs {
+    private readonly world;
+    private readonly entityServer;
+    private readonly pedServer;
+    private readonly hasher;
+    private readonly events;
+    private readonly npcById;
+    private readonly idByHandle;
+    private readonly idByNetId;
+    private readonly adapters;
+    constructor(world: WorldContext, entityServer: IEntityServer, pedServer: IPedServer, hasher: IHasher, events: EventsAPI<'server'>);
+    /**
+     * Spawn (create) a single NPC and register it into the runtime.
+     *
+     * @remarks
+     * - Generates a UUID if `options.id` is not provided.
+     * - Prevents duplicate `npcId` collisions within this runtime.
+     * - Waits until the underlying entity exists (polling) and fails fast on timeout.
+     * - Applies routing bucket, orphan mode (persistent), and metadata after spawn.
+     * - Registers the NPC in `WorldContext` and internal indexes.
+     *
+     * @param options - Spawn options (model, position, routingBucket, persistence, metadata, etc.).
+     * @returns An object containing a `result` (success/error) and the created `npc` on success.
+     */
+    create(options: NpcSpawnOptions): Promise<{
+        result: NpcSpawnResult;
+        npc?: NPC;
+    }>;
+    /**
+     * Spawn multiple NPCs sequentially using {@link create}.
+     *
+     * @remarks
+     * This method is intentionally sequential to keep spawn load predictable and to preserve
+     * deterministic side-effects (logging, indexing, world registration).
+     *
+     * If you want parallel spawning, you can build it externally, but be mindful of server load
+     * and potential native limits.
+     *
+     * @param options - List of spawn requests.
+     * @returns A list of per-item results, each containing a `result` and optionally an `npc`.
+     */
+    createMany(options: NpcSpawnOptions[]): Promise<Array<{
+        result: NpcSpawnResult;
+        npc?: NPC;
+    }>>;
+    /**
+     * Get an NPC instance by its logical id (`npcId`).
+     *
+     * @param id - NPC logical identifier.
+     * @returns The NPC instance if present in the registry, otherwise `undefined`.
+     */
+    getById(id: string): NPC | undefined;
+    /**
+     * Get an NPC instance by its ped handle.
+     *
+     * @remarks
+     * Handles are runtime-specific and can become invalid if the entity is removed.
+     * This lookup uses the internal `handle -> npcId` index.
+     *
+     * @param handle - Ped handle.
+     * @returns The NPC instance if present, otherwise `undefined`.
+     */
+    getByHandle(handle: number): NPC | undefined;
+    /**
+     * Get an NPC instance by its network id (netId).
+     *
+     * @remarks
+     * Only NPCs created with `networked=true` will have a netId and be indexed here.
+     *
+     * @param netId - Network id of the entity.
+     * @returns The NPC instance if present, otherwise `undefined`.
+     */
+    getByNetId(netId: number): NPC | undefined;
+    /**
+     * Return a snapshot array of all NPCs currently registered.
+     *
+     * @remarks
+     * This includes NPCs that may no longer exist at runtime (e.g. removed externally),
+     * until {@link cleanupOrphans} is called.
+     *
+     * @returns An array of NPC instances.
+     */
+    getAll(): NPC[];
+    /**
+     * Return all NPCs whose current routing bucket (dimension) matches the given bucket.
+     *
+     * @remarks
+     * The check is performed using `npc.dimension` (which resolves via entity server).
+     *
+     * @param bucket - Routing bucket / dimension.
+     * @returns An array of NPC instances in the given bucket.
+     */
+    getInRoutingBucket(bucket: number): NPC[];
+    /**
+     * Find NPCs within `radius` of a position (Euclidean distance in 3D).
+     *
+     * @remarks
+     * - This method performs a linear scan over registered NPCs.
+     * - Uses squared distance (avoids `Math.sqrt`) for performance.
+     * - Skips NPCs that no longer exist (`npc.exists === false`).
+     * - Optionally filters by routing bucket (dimension).
+     *
+     * @param position - Center position.
+     * @param radius - Search radius (negative values are clamped to 0).
+     * @param bucket - Optional routing bucket filter.
+     * @returns Matching NPCs (order is insertion/iteration order).
+     */
+    findNear(position: Vector3, radius: number, bucket?: number): NPC[];
+    /**
+     * Return the current number of NPCs tracked in the registry.
+     *
+     * @remarks
+     * This is the registry size, not necessarily the number of NPCs that still exist in the world.
+     * Use {@link cleanupOrphans} to remove non-existing NPCs from the registry.
+     *
+     * @returns Registry count.
+     */
+    count(): number;
+    /**
+     * Check if a given `npcId` is registered and the underlying entity currently exists.
+     *
+     * @param id - NPC logical identifier.
+     * @returns `true` if registered and exists in the runtime, otherwise `false`.
+     */
+    exists(id: string): boolean;
+    /**
+     * Delete an NPC by its logical id and remove it from internal registries.
+     *
+     * @remarks
+     * - Calls {@link NPC.delete} (ped deletion) if the entity exists.
+     * - Removes the NPC from internal indexes and {@link WorldContext}.
+     * - Emits the `opencore:npc:deleted` server event to `'all'` with the `npcId`.
+     *
+     * @param id - NPC logical identifier.
+     * @returns `true` if an NPC was found and deleted, otherwise `false`.
+     */
+    deleteById(id: string): boolean;
+    /**
+     * Delete an NPC by its handle.
+     *
+     * @remarks
+     * Resolves `handle -> npcId` and delegates to {@link deleteById}.
+     *
+     * @param handle - Ped handle.
+     * @returns `true` if an NPC was found and deleted, otherwise `false`.
+     */
+    deleteByHandle(handle: number): boolean;
+    /**
+     * Delete an NPC by its network id (netId).
+     *
+     * @remarks
+     * Resolves `netId -> npcId` and delegates to {@link deleteById}.
+     * Only applies to NPCs created with `networked=true`.
+     *
+     * @param netId - Network id.
+     * @returns `true` if an NPC was found and deleted, otherwise `false`.
+     */
+    deleteByNetId(netId: number): boolean;
+    /**
+     * Delete all currently registered NPCs.
+     *
+     * @remarks
+     * Iterates over a snapshot of ids to avoid mutation issues during deletion.
+     *
+     * @returns The number of NPCs successfully deleted.
+     */
+    deleteAll(): number;
+    /**
+     * Remove registry entries for NPCs whose underlying entities no longer exist.
+     *
+     * @remarks
+     * This is useful when entities were deleted externally (by natives, scripts, cleanup, etc.).
+     * It removes them from internal indexes and {@link WorldContext}, without attempting to delete
+     * the already-nonexistent entity.
+     *
+     * @returns The number of orphan registry entries removed.
+     */
+    cleanupOrphans(): number;
+    /**
+     * Serialize all registered NPCs to plain data objects.
+     *
+     * @remarks
+     * Each NPC serialization includes position, heading, routing bucket, metadata and state bag snapshot.
+     * NPCs that no longer exist may still serialize, but values depending on natives could be stale or fail
+     * depending on adapter behavior; prefer calling {@link cleanupOrphans} first when needed.
+     *
+     * @returns An array of serialized NPC data.
+     */
+    serializeAll(): SerializedNpcData[];
+    private resolveNetId;
+    private removeFromRegistry;
+    private safeDeleteHandle;
+    private waitForSpawn;
+}

package/dist/runtime/server/apis/npcs.api.js

@@ -0,0 +1,465 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'tsyringe';
+import { v4 as uuid } from 'uuid';
+import { IHasher } from '../../../adapters/contracts/IHasher';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { IEntityServer } from '../../../adapters/contracts/server/IEntityServer';
+import { IPedServer } from '../../../adapters/contracts/server/IPedServer';
+import { coreLogger } from '../../../kernel/logger';
+import { WorldContext } from '../../core/world';
+import { NPC } from '../entities/npc';
+const DEFAULT_PED_TYPE = 4;
+const DEFAULT_SPAWN_TIMEOUT_MS = 2000;
+/**
+ * Server-side API responsible for the full NPC (ped) lifecycle:
+ * spawn, registry, queries, spatial search, serialization and deletion.
+ *
+ * @remarks
+ * Prefer consuming this API from gameplay / AI systems instead of calling natives directly.
+ * This class keeps a stable in-memory registry keyed by `npcId` and maintains secondary
+ * indexes by `handle` and (when networked) by `netId`.
+ *
+ * The registry is authoritative for lookups, while `NPC.exists` reflects runtime existence.
+ */
+let Npcs = class Npcs {
+    world;
+    entityServer;
+    pedServer;
+    hasher;
+    events;
+    npcById = new Map();
+    idByHandle = new Map();
+    idByNetId = new Map();
+    adapters;
+    constructor(world, entityServer, pedServer, hasher, events) {
+        this.world = world;
+        this.entityServer = entityServer;
+        this.pedServer = pedServer;
+        this.hasher = hasher;
+        this.events = events;
+        this.adapters = {
+            entityServer: this.entityServer,
+            pedServer: this.pedServer,
+        };
+    }
+    /**
+     * Spawn (create) a single NPC and register it into the runtime.
+     *
+     * @remarks
+     * - Generates a UUID if `options.id` is not provided.
+     * - Prevents duplicate `npcId` collisions within this runtime.
+     * - Waits until the underlying entity exists (polling) and fails fast on timeout.
+     * - Applies routing bucket, orphan mode (persistent), and metadata after spawn.
+     * - Registers the NPC in `WorldContext` and internal indexes.
+     *
+     * @param options - Spawn options (model, position, routingBucket, persistence, metadata, etc.).
+     * @returns An object containing a `result` (success/error) and the created `npc` on success.
+     */
+    async create(options) {
+        const { id, model, position, heading = 0, networked = true, pedType = DEFAULT_PED_TYPE, routingBucket = 0, persistent = false, metadata, } = options;
+        const npcId = id ?? uuid();
+        if (this.npcById.has(npcId)) {
+            return {
+                result: {
+                    success: false,
+                    error: `NPC '${npcId}' already exists`,
+                },
+            };
+        }
+        const modelHash = typeof model === 'string' ? this.hasher.getHashKey(model) : model;
+        const handle = this.pedServer.create(pedType, modelHash, position.x, position.y, position.z, heading, networked);
+        if (!handle || handle <= 0) {
+            return {
+                result: {
+                    success: false,
+                    error: 'Failed to create NPC ped entity',
+                },
+            };
+        }
+        const spawnOk = await this.waitForSpawn(handle);
+        if (!spawnOk) {
+            this.safeDeleteHandle(handle);
+            return {
+                result: {
+                    success: false,
+                    error: `NPC spawn timed out after ${DEFAULT_SPAWN_TIMEOUT_MS}ms`,
+                },
+            };
+        }
+        const resolvedModel = typeof model === 'string' ? model : modelHash.toString();
+        const netId = networked ? this.resolveNetId(handle) : undefined;
+        const session = {
+            id: npcId,
+            handle,
+            netId,
+            model: resolvedModel,
+            modelHash,
+            persistent,
+            routingBucket,
+            createdAt: Date.now(),
+        };
+        const npc = new NPC(session, this.adapters);
+        if (routingBucket !== 0) {
+            npc.setRoutingBucket(routingBucket);
+        }
+        if (persistent) {
+            this.entityServer.setOrphanMode(handle, 2);
+        }
+        if (metadata) {
+            for (const [key, value] of Object.entries(metadata)) {
+                npc.setMeta(key, value);
+            }
+        }
+        this.npcById.set(npcId, npc);
+        this.idByHandle.set(handle, npcId);
+        if (netId !== undefined) {
+            this.idByNetId.set(netId, npcId);
+        }
+        this.world.add(npc);
+        coreLogger.info('NPC created', {
+            npcId,
+            handle,
+            netId,
+            model: resolvedModel,
+            persistent,
+            routingBucket,
+            totalNpcs: this.npcById.size,
+        });
+        // this.events.emit('opencore:npc:created', 'all', npc.serialize())
+        return {
+            result: {
+                success: true,
+                id: npcId,
+                handle,
+                netId,
+            },
+            npc,
+        };
+    }
+    /**
+     * Spawn multiple NPCs sequentially using {@link create}.
+     *
+     * @remarks
+     * This method is intentionally sequential to keep spawn load predictable and to preserve
+     * deterministic side-effects (logging, indexing, world registration).
+     *
+     * If you want parallel spawning, you can build it externally, but be mindful of server load
+     * and potential native limits.
+     *
+     * @param options - List of spawn requests.
+     * @returns A list of per-item results, each containing a `result` and optionally an `npc`.
+     */
+    async createMany(options) {
+        const result = [];
+        for (const item of options) {
+            result.push(await this.create(item));
+        }
+        return result;
+    }
+    /**
+     * Get an NPC instance by its logical id (`npcId`).
+     *
+     * @param id - NPC logical identifier.
+     * @returns The NPC instance if present in the registry, otherwise `undefined`.
+     */
+    getById(id) {
+        return this.npcById.get(id);
+    }
+    /**
+     * Get an NPC instance by its ped handle.
+     *
+     * @remarks
+     * Handles are runtime-specific and can become invalid if the entity is removed.
+     * This lookup uses the internal `handle -> npcId` index.
+     *
+     * @param handle - Ped handle.
+     * @returns The NPC instance if present, otherwise `undefined`.
+     */
+    getByHandle(handle) {
+        const id = this.idByHandle.get(handle);
+        return id ? this.npcById.get(id) : undefined;
+    }
+    /**
+     * Get an NPC instance by its network id (netId).
+     *
+     * @remarks
+     * Only NPCs created with `networked=true` will have a netId and be indexed here.
+     *
+     * @param netId - Network id of the entity.
+     * @returns The NPC instance if present, otherwise `undefined`.
+     */
+    getByNetId(netId) {
+        const id = this.idByNetId.get(netId);
+        return id ? this.npcById.get(id) : undefined;
+    }
+    /**
+     * Return a snapshot array of all NPCs currently registered.
+     *
+     * @remarks
+     * This includes NPCs that may no longer exist at runtime (e.g. removed externally),
+     * until {@link cleanupOrphans} is called.
+     *
+     * @returns An array of NPC instances.
+     */
+    getAll() {
+        return Array.from(this.npcById.values());
+    }
+    /**
+     * Return all NPCs whose current routing bucket (dimension) matches the given bucket.
+     *
+     * @remarks
+     * The check is performed using `npc.dimension` (which resolves via entity server).
+     *
+     * @param bucket - Routing bucket / dimension.
+     * @returns An array of NPC instances in the given bucket.
+     */
+    getInRoutingBucket(bucket) {
+        const npcs = [];
+        for (const npc of this.npcById.values()) {
+            if (npc.dimension === bucket) {
+                npcs.push(npc);
+            }
+        }
+        return npcs;
+    }
+    /**
+     * Find NPCs within `radius` of a position (Euclidean distance in 3D).
+     *
+     * @remarks
+     * - This method performs a linear scan over registered NPCs.
+     * - Uses squared distance (avoids `Math.sqrt`) for performance.
+     * - Skips NPCs that no longer exist (`npc.exists === false`).
+     * - Optionally filters by routing bucket (dimension).
+     *
+     * @param position - Center position.
+     * @param radius - Search radius (negative values are clamped to 0).
+     * @param bucket - Optional routing bucket filter.
+     * @returns Matching NPCs (order is insertion/iteration order).
+     */
+    findNear(position, radius, bucket) {
+        const maxDistance = Math.max(0, radius);
+        const maxDistanceSq = maxDistance * maxDistance;
+        const npcs = [];
+        for (const npc of this.npcById.values()) {
+            if (!npc.exists)
+                continue;
+            if (bucket !== undefined && npc.dimension !== bucket)
+                continue;
+            const npcPos = npc.getPosition();
+            const dx = npcPos.x - position.x;
+            const dy = npcPos.y - position.y;
+            const dz = npcPos.z - position.z;
+            const distSq = dx * dx + dy * dy + dz * dz;
+            if (distSq <= maxDistanceSq) {
+                npcs.push(npc);
+            }
+        }
+        return npcs;
+    }
+    /**
+     * Return the current number of NPCs tracked in the registry.
+     *
+     * @remarks
+     * This is the registry size, not necessarily the number of NPCs that still exist in the world.
+     * Use {@link cleanupOrphans} to remove non-existing NPCs from the registry.
+     *
+     * @returns Registry count.
+     */
+    count() {
+        return this.npcById.size;
+    }
+    /**
+     * Check if a given `npcId` is registered and the underlying entity currently exists.
+     *
+     * @param id - NPC logical identifier.
+     * @returns `true` if registered and exists in the runtime, otherwise `false`.
+     */
+    exists(id) {
+        const npc = this.npcById.get(id);
+        return npc ? npc.exists : false;
+    }
+    /**
+     * Delete an NPC by its logical id and remove it from internal registries.
+     *
+     * @remarks
+     * - Calls {@link NPC.delete} (ped deletion) if the entity exists.
+     * - Removes the NPC from internal indexes and {@link WorldContext}.
+     * - Emits the `opencore:npc:deleted` server event to `'all'` with the `npcId`.
+     *
+     * @param id - NPC logical identifier.
+     * @returns `true` if an NPC was found and deleted, otherwise `false`.
+     */
+    deleteById(id) {
+        const npc = this.npcById.get(id);
+        if (!npc) {
+            return false;
+        }
+        npc.delete();
+        this.removeFromRegistry(npc);
+        coreLogger.info('NPC deleted', {
+            npcId: npc.npcId,
+            handle: npc.getHandle(),
+            netId: npc.netId,
+            remainingNpcs: this.npcById.size,
+        });
+        this.events.emit('opencore:npc:deleted', 'all', npc.npcId);
+        return true;
+    }
+    /**
+     * Delete an NPC by its handle.
+     *
+     * @remarks
+     * Resolves `handle -> npcId` and delegates to {@link deleteById}.
+     *
+     * @param handle - Ped handle.
+     * @returns `true` if an NPC was found and deleted, otherwise `false`.
+     */
+    deleteByHandle(handle) {
+        const id = this.idByHandle.get(handle);
+        if (!id)
+            return false;
+        return this.deleteById(id);
+    }
+    /**
+     * Delete an NPC by its network id (netId).
+     *
+     * @remarks
+     * Resolves `netId -> npcId` and delegates to {@link deleteById}.
+     * Only applies to NPCs created with `networked=true`.
+     *
+     * @param netId - Network id.
+     * @returns `true` if an NPC was found and deleted, otherwise `false`.
+     */
+    deleteByNetId(netId) {
+        const id = this.idByNetId.get(netId);
+        if (!id)
+            return false;
+        return this.deleteById(id);
+    }
+    /**
+     * Delete all currently registered NPCs.
+     *
+     * @remarks
+     * Iterates over a snapshot of ids to avoid mutation issues during deletion.
+     *
+     * @returns The number of NPCs successfully deleted.
+     */
+    deleteAll() {
+        const ids = Array.from(this.npcById.keys());
+        let deleted = 0;
+        for (const id of ids) {
+            if (this.deleteById(id)) {
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Remove registry entries for NPCs whose underlying entities no longer exist.
+     *
+     * @remarks
+     * This is useful when entities were deleted externally (by natives, scripts, cleanup, etc.).
+     * It removes them from internal indexes and {@link WorldContext}, without attempting to delete
+     * the already-nonexistent entity.
+     *
+     * @returns The number of orphan registry entries removed.
+     */
+    cleanupOrphans() {
+        const toDelete = [];
+        for (const npc of this.npcById.values()) {
+            if (!npc.exists) {
+                toDelete.push(npc.npcId);
+            }
+        }
+        for (const id of toDelete) {
+            const npc = this.npcById.get(id);
+            if (!npc)
+                continue;
+            this.removeFromRegistry(npc);
+            coreLogger.debug('Cleaned up orphaned NPC', { npcId: id });
+        }
+        if (toDelete.length > 0) {
+            coreLogger.info('NPC cleanup completed', {
+                cleaned: toDelete.length,
+                remaining: this.npcById.size,
+            });
+        }
+        return toDelete.length;
+    }
+    /**
+     * Serialize all registered NPCs to plain data objects.
+     *
+     * @remarks
+     * Each NPC serialization includes position, heading, routing bucket, metadata and state bag snapshot.
+     * NPCs that no longer exist may still serialize, but values depending on natives could be stale or fail
+     * depending on adapter behavior; prefer calling {@link cleanupOrphans} first when needed.
+     *
+     * @returns An array of serialized NPC data.
+     */
+    serializeAll() {
+        return Array.from(this.npcById.values()).map((npc) => npc.serialize());
+    }
+    resolveNetId(handle) {
+        const netId = this.pedServer.getNetworkIdFromEntity(handle);
+        return netId > 0 ? netId : undefined;
+    }
+    removeFromRegistry(npc) {
+        this.npcById.delete(npc.npcId);
+        this.idByHandle.delete(npc.getHandle());
+        if (npc.netId !== undefined) {
+            this.idByNetId.delete(npc.netId);
+        }
+        this.world.remove(npc.id);
+    }
+    safeDeleteHandle(handle) {
+        try {
+            if (this.entityServer.doesExist(handle)) {
+                this.pedServer.delete(handle);
+            }
+        }
+        catch (error) {
+            coreLogger.warn('Failed to cleanup NPC handle after spawn failure', {
+                handle,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async waitForSpawn(handle, timeoutMs = DEFAULT_SPAWN_TIMEOUT_MS) {
+        const startedAt = Date.now();
+        while (!this.entityServer.doesExist(handle)) {
+            if (Date.now() - startedAt > timeoutMs) {
+                return false;
+            }
+            await sleep(0);
+        }
+        return true;
+    }
+};
+Npcs = __decorate([
+    injectable(),
+    __param(0, inject(WorldContext)),
+    __param(1, inject(IEntityServer)),
+    __param(2, inject(IPedServer)),
+    __param(3, inject(IHasher)),
+    __param(4, inject(EventsAPI)),
+    __metadata("design:paramtypes", [WorldContext,
+        IEntityServer,
+        IPedServer,
+        IHasher,
+        EventsAPI])
+], Npcs);
+export { Npcs };
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}