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

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

@@ -0,0 +1,129 @@
+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 { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { Players } from '../ports/players.api-port';
+/**
+ * Service for sending chat messages to players.
+ *
+ * @remarks
+ * This service emits framework chat events over the network.
+ * Internally uses ChannelService for advanced channel-based communication.
+ */
+let Chat = class Chat {
+    events;
+    players;
+    constructor(events, players) {
+        this.events = events;
+        this.players = players;
+    }
+    /**
+     * Broadcast a chat message to all connected players.
+     *
+     * @param message - Message body.
+     * @param author - Author label shown in chat. Defaults to `SYSTEM`.
+     * @param color - Message color (RGB). Defaults to white.
+     */
+    broadcast(message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
+        this.events.emit('core:chat:message', 'all', {
+            args: [author, message],
+            color: color,
+        });
+    }
+    /**
+     * Send a private chat message to a single player.
+     *
+     * @param player - Target player.
+     * @param message - Message body.
+     * @param author - Author label shown in chat. Defaults to `Private`.
+     * @param color - Message color (RGB).
+     */
+    sendPrivate(player, message, author = 'Private', color = { r: 200, g: 200, b: 200 }) {
+        this.events.emit('core:chat:addMessage', player.clientID, {
+            args: [author, message],
+            color: color,
+        });
+    }
+    /**
+     * Clear chat for a single player.
+     *
+     * @param player - Target player.
+     */
+    clearChat(player) {
+        this.events.emit('core:chat:clear', player.clientID);
+    }
+    /**
+     * Send a chat message to multiple players.
+     *
+     * @param players - Array of target players or their client IDs.
+     * @param message - Message body.
+     * @param author - Author label.
+     * @param color - Message color (RGB).
+     */
+    sendMany(players, message, author = 'SYSTEM', color = { r: 255, g: 255, b: 255 }) {
+        const targetIds = players.map((p) => (typeof p === 'number' ? p : p.clientID));
+        this.events.emit('core:chat:addMessage', targetIds, {
+            args: [author, message],
+            color: color,
+        });
+    }
+    /**
+     * Send a chat message to players within a certain radius of a specific player.
+     *
+     * @param playerFrom - Origin player.
+     * @param message - Message body.
+     * @param radius - Distance radius in game units.
+     * @param author - Author label.
+     * @param color - Message color (RGB).
+     */
+    sendNearby(playerFrom, message, radius, author = playerFrom.name, color = { r: 255, g: 255, b: 255 }) {
+        const originPos = playerFrom.getPosition();
+        if (!originPos)
+            return;
+        const allPlayers = this.players.getAll();
+        const nearbyPlayers = allPlayers.filter((p) => {
+            const pos = p.getPosition();
+            if (!pos)
+                return false;
+            const dx = originPos.x - pos.x;
+            const dy = originPos.y - pos.y;
+            const dz = originPos.z - pos.z;
+            const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            return distance <= radius;
+        });
+        this.sendMany(nearbyPlayers, message, author, color);
+    }
+    /**
+     * Broadcast a system message to all players.
+     *
+     * @param message - Message body.
+     * @param color - Message color (RGB). Defaults to a light blue/cyan.
+     */
+    broadcastSystem(message, color) {
+        this.broadcast(message, 'SYSTEM', color);
+    }
+    /**
+     * Clear chat for all connected players.
+     */
+    clearChatAll() {
+        this.events.emit('core:chat:clear', 'all');
+    }
+};
+Chat = __decorate([
+    injectable(),
+    __param(0, inject(EventsAPI)),
+    __param(1, inject(Players)),
+    __metadata("design:paramtypes", [EventsAPI,
+        Players])
+], Chat);
+export { Chat };

package/dist/runtime/server/apis/index.d.ts

@@ -0,0 +1,6 @@
+export * from './appearance.api';
+export * from './chat.api';
+export * from './npcs.api';
+export * from './parallel-compute.api';
+export * from './vehicle-modification.api';
+export * from './vehicles.api';

package/dist/runtime/server/apis/index.js

@@ -0,0 +1,6 @@
+export * from './appearance.api';
+export * from './chat.api';
+export * from './npcs.api';
+export * from './parallel-compute.api';
+export * from './vehicle-modification.api';
+export * from './vehicles.api';

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

@@ -0,0 +1,212 @@
+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 { 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 npcLifecycle;
+    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, npcLifecycle: INpcLifecycleServer, 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 removeFromRegistry;
+}