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

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

@@ -0,0 +1,435 @@
+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 { INpcLifecycleServer } from '../../../adapters/contracts/server/npc-lifecycle/INpcLifecycleServer';
+import { IPedServer } from '../../../adapters/contracts/server/IPedServer';
+import { coreLogger } from '../../../kernel/logger';
+import { WorldContext } from '../../core/world';
+import { NPC } from '../entities/npc';
+/**
+ * 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;
+    npcLifecycle;
+    pedServer;
+    hasher;
+    events;
+    npcById = new Map();
+    idByHandle = new Map();
+    idByNetId = new Map();
+    adapters;
+    constructor(world, entityServer, npcLifecycle, pedServer, hasher, events) {
+        this.world = world;
+        this.entityServer = entityServer;
+        this.npcLifecycle = npcLifecycle;
+        this.pedServer = pedServer;
+        this.hasher = hasher;
+        this.events = events;
+        this.adapters = {
+            entityServer: this.entityServer,
+            pedServer: this.pedServer,
+            npcLifecycle: this.npcLifecycle,
+        };
+    }
+    /**
+     * 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, 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;
+        let lifecycleResult;
+        try {
+            lifecycleResult = await Promise.resolve(this.npcLifecycle.create({
+                model: typeof model === 'string' ? model : String(model),
+                modelHash,
+                position,
+                heading,
+                networked,
+                routingBucket,
+                persistent,
+            }));
+        }
+        catch (error) {
+            return {
+                result: {
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Failed to create NPC ped entity',
+                },
+            };
+        }
+        const handle = lifecycleResult.handle;
+        const resolvedModel = typeof model === 'string' ? model : modelHash.toString();
+        const netId = lifecycleResult.netId;
+        const session = {
+            id: npcId,
+            handle,
+            netId,
+            model: resolvedModel,
+            modelHash,
+            persistent,
+            routingBucket,
+            createdAt: Date.now(),
+        };
+        const npc = new NPC(session, this.adapters);
+        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());
+    }
+    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);
+    }
+};
+Npcs = __decorate([
+    injectable(),
+    __param(0, inject(WorldContext)),
+    __param(1, inject(IEntityServer)),
+    __param(2, inject(INpcLifecycleServer)),
+    __param(3, inject(IPedServer)),
+    __param(4, inject(IHasher)),
+    __param(5, inject(EventsAPI)),
+    __metadata("design:paramtypes", [WorldContext,
+        IEntityServer,
+        INpcLifecycleServer,
+        IPedServer,
+        IHasher,
+        EventsAPI])
+], Npcs);
+export { Npcs };

package/dist/runtime/server/apis/parallel-compute.api.d.ts

@@ -0,0 +1,118 @@
+import { Vector3 } from '../../../kernel';
+import { ParallelComputeMetrics, ParallelTask, ParallelTaskOptions, TaskResult, WorkerPoolConfig } from '../types/parallel.types';
+/**
+ * Service for managing parallel computation
+ */
+export declare class ParallelCompute {
+    private pool;
+    private metrics;
+    private totalExecutionTime;
+    private isInitialized;
+    private poolConfig;
+    /**
+     * Initialize the worker pool
+     * Must be called before using parallel execution
+     */
+    initialize(config?: Partial<WorkerPoolConfig>): void;
+    /**
+     * Check if initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Check if using native workers
+     */
+    get isNative(): boolean;
+    /**
+     * Shutdown the service and worker pool
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current metrics
+     */
+    getMetrics(): ParallelComputeMetrics;
+    /**
+     * Get worker pool statistics
+     */
+    getPoolStats(): {
+        totalWorkers: number;
+        idleWorkers: number;
+        busyWorkers: number;
+        queuedTasks: number;
+        isNative: boolean;
+    } | null;
+    /**
+     * Reset metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Execute a compute function with automatic mode selection
+     */
+    run<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput): Promise<TaskResult<TOutput>>;
+    /**
+     * Execute synchronously on main thread
+     */
+    sync<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput): TaskResult<TOutput>;
+    /**
+     * Execute on worker (async with yielding in FiveM)
+     */
+    parallel<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput): Promise<TaskResult<TOutput>>;
+    /**
+     * Execute distributed across multiple workers
+     */
+    distributed<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>, input: TInput, workerCount?: number): Promise<TaskResult<TOutput>>;
+    /**
+     * Update internal metrics
+     */
+    private updateMetrics;
+}
+/**
+ * Get or create the global ParallelCompute service instance
+ */
+export declare function getParallelComputeService(): ParallelCompute;
+/**
+ * Initialize the global ParallelCompute service
+ */
+export declare function initParallelCompute(config?: Partial<WorkerPoolConfig>): void;
+/**
+ * Shutdown the global ParallelCompute service
+ */
+export declare function shutdownParallelCompute(): Promise<void>;
+/**
+ * Define a parallel task with the given options
+ * Returns a task object with run, sync, parallel, and distributed methods
+ */
+export declare function defineTask<TInput, TOutput>(options: ParallelTaskOptions<TInput, TOutput>): ParallelTask<TInput, TOutput>;
+/**
+ * Built-in task: Filter entities by distance from a position
+ */
+export declare const filterByDistance: ParallelTask<{
+    entities: Vector3[];
+    position: Vector3;
+    radius: number;
+}, Vector3[]>;
+/**
+ * Built-in task: Sort entities by distance from a position
+ */
+export declare const sortByDistance: ParallelTask<{
+    entities: Vector3[];
+    position: Vector3;
+}, Vector3[]>;
+/**
+ * Built-in task: Find closest entity to a position
+ */
+export declare const findClosest: ParallelTask<{
+    entities: Vector3[];
+    position: Vector3;
+}, Vector3 | null>;
+/**
+ * Built-in task: Batch transform items
+ */
+export declare function defineBatchTransform<T, R>(name: string, transform: (item: T) => R, threshold?: number): ParallelTask<T[], R[]>;
+/**
+ * Built-in task: Batch filter items
+ */
+export declare function defineBatchFilter<T>(name: string, predicate: (item: T) => boolean, threshold?: number): ParallelTask<T[], T[]>;
+/**
+ * Built-in task: Batch reduce items
+ */
+export declare function defineBatchReduce<T, R>(name: string, reducer: (acc: R, item: T) => R, initial: R, merger: (results: R[]) => R, threshold?: number): ParallelTask<T[], R>;