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

package/dist/runtime/core/library/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Unique name used to identify a library.
+ */
+export type LibraryName = string;
+/**
+ * Namespace used to build external event names.
+ *
+ * @example
+ * `opencore:characters`
+ */
+export type LibraryNamespace = string;
+/**
+ * Internal or external event name segment.
+ *
+ * @example
+ * `created`
+ */
+export type LibraryEventName = string;
+/**
+ * Canonical library event identifier.
+ *
+ * @example
+ * `characters:session:created`
+ */
+export type LibraryEventId = string;
+/**
+ * Generic handler used by the internal library bus.
+ */
+export type LibraryEventHandler<TPayload = unknown> = (payload?: TPayload) => void;
+/**
+ * Metadata attached to runtime library event notifications.
+ */
+export interface LibraryEventMetadata {
+    libraryName: LibraryName;
+    eventName: LibraryEventName;
+    eventId: LibraryEventId;
+    namespace: LibraryNamespace;
+    side: 'server' | 'client';
+}
+/**
+ * Runtime notification envelope emitted by library wrappers.
+ */
+export interface LibraryEventEnvelope<TPayload = unknown> {
+    payload?: TPayload;
+    meta: LibraryEventMetadata;
+}
+/**
+ * Lightweight internal event bus for library-local communication.
+ *
+ * @remarks
+ * This bus is pure TypeScript and does not use FiveM or network events.
+ */
+export interface LibraryBus {
+    /**
+     * Subscribe to an internal event.
+     */
+    on<TPayload = unknown>(event: LibraryEventName, handler: LibraryEventHandler<TPayload>): void;
+    /**
+     * Subscribe to an internal event only once.
+     */
+    once<TPayload = unknown>(event: LibraryEventName, handler: LibraryEventHandler<TPayload>): void;
+    /**
+     * Remove an internal event handler.
+     */
+    off<TPayload = unknown>(event: LibraryEventName, handler: LibraryEventHandler<TPayload>): void;
+    /**
+     * Emit an internal event to handlers in this library.
+     */
+    emit<TPayload = unknown>(event: LibraryEventName, payload?: TPayload): void;
+}
+/**
+ * Shared base contract for OpenCore libraries.
+ *
+ * @remarks
+ * Includes only library-local event operations and event name composition.
+ * External bridge behavior is added by server/client wrappers.
+ */
+export interface OpenCoreLibraryBase extends LibraryBus {
+    /**
+     * Library identifier.
+     */
+    name: LibraryName;
+    /**
+     * Event namespace used by the external bridge.
+     */
+    namespace: LibraryNamespace;
+    /**
+     * Builds a namespaced external event name.
+     *
+     * @example
+     * `opencore:characters:created`
+     */
+    buildEventName(eventName: LibraryEventName): string;
+}
+/**
+ * Minimal config accessor used by library wrappers.
+ */
+export interface OpenCoreLibraryConfigAccessor<TConfig = Record<string, unknown>> {
+    /**
+     * Namespace of the library config segment.
+     */
+    namespace: LibraryNamespace;
+    /**
+     * Gets a value by key from the namespaced config source.
+     */
+    get<TKey extends keyof TConfig>(key: TKey): TConfig[TKey] | undefined;
+}
+/**
+ * Server library API.
+ *
+ * @remarks
+ * Adds a FiveM-based external bridge on top of the internal library bus.
+ */
+export interface OpenCoreServerLibrary extends OpenCoreLibraryBase {
+    side: 'server';
+    emitExternal<TPayload = unknown>(eventName: LibraryEventName, payload?: TPayload): void;
+    emitNetExternal<TPayload = unknown>(eventName: LibraryEventName, target: number, payload?: TPayload): void;
+    getLogger(): {
+        trace(message: string, context?: Record<string, unknown>): void;
+        debug(message: string, context?: Record<string, unknown>): void;
+        info(message: string, context?: Record<string, unknown>): void;
+        warn(message: string, context?: Record<string, unknown>): void;
+        error(message: string, context?: Record<string, unknown>, error?: Error): void;
+        fatal(message: string, context?: Record<string, unknown>, error?: Error): void;
+    };
+    getConfig<TConfig = Record<string, unknown>>(): OpenCoreLibraryConfigAccessor<TConfig>;
+}
+/**
+ * Client library API.
+ *
+ * @remarks
+ * Adds a client-to-server external bridge on top of the internal library bus.
+ */
+export interface OpenCoreClientLibrary extends OpenCoreLibraryBase {
+    side: 'client';
+    emitServer<TPayload = unknown>(eventName: LibraryEventName, payload?: TPayload): void;
+    getLogger(): {
+        trace(message: string, context?: Record<string, unknown>): void;
+        debug(message: string, context?: Record<string, unknown>): void;
+        info(message: string, context?: Record<string, unknown>): void;
+        warn(message: string, context?: Record<string, unknown>): void;
+        error(message: string, context?: Record<string, unknown>, error?: Error): void;
+        fatal(message: string, context?: Record<string, unknown>, error?: Error): void;
+    };
+    getConfig<TConfig = Record<string, unknown>>(): OpenCoreLibraryConfigAccessor<TConfig>;
+}

package/dist/runtime/core/nativehandle.d.ts

@@ -0,0 +1,3 @@
+export interface NativeHandle {
+    getHandle(): number;
+}

package/dist/runtime/core/spatial.d.ts

@@ -0,0 +1,7 @@
+import { Vector3 } from '../../kernel/utils/vector3';
+export interface Spatial {
+    getPosition(): Vector3;
+    setPosition(v: Vector3): void;
+    getHeading(): number;
+    setHeading(heading: number): void;
+}

package/dist/runtime/core/world.d.ts

@@ -0,0 +1,13 @@
+import { BaseEntity, EntityId } from './entity';
+export declare class WorldContext {
+    private entities;
+    private readonly kindIndex;
+    add(entity: BaseEntity): void;
+    remove(id: EntityId): void;
+    get<T extends BaseEntity = BaseEntity>(id: EntityId): T | undefined;
+    find<T extends BaseEntity>(predicate: (e: BaseEntity) => e is T): T[];
+    find(predicate: (e: BaseEntity) => boolean): BaseEntity[];
+    all(): BaseEntity[];
+    size(): number;
+    sizeBy(kind: string): number;
+}

package/dist/runtime/core/world.js

@@ -0,0 +1,57 @@
+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;
+};
+import { injectable } from 'tsyringe';
+function getKind(id) {
+    const i = id.indexOf(':');
+    return i === -1 ? id : id.slice(0, i);
+}
+let WorldContext = class WorldContext {
+    entities = new Map();
+    kindIndex = new Map();
+    add(entity) {
+        // If replacing, remove first to keep index consistent
+        const prev = this.entities.get(entity.id);
+        if (prev)
+            this.remove(entity.id);
+        this.entities.set(entity.id, entity);
+        const kind = getKind(entity.id);
+        this.kindIndex.set(kind, (this.kindIndex.get(kind) ?? 0) + 1);
+    }
+    remove(id) {
+        const entity = this.entities.get(id);
+        if (!entity)
+            return;
+        const kind = getKind(id);
+        const n = this.kindIndex.get(kind);
+        if (n !== undefined) {
+            if (n <= 1)
+                this.kindIndex.delete(kind);
+            else
+                this.kindIndex.set(kind, n - 1);
+        }
+        this.entities.delete(id);
+    }
+    get(id) {
+        return this.entities.get(id);
+    }
+    find(predicate) {
+        return [...this.entities.values()].filter(predicate);
+    }
+    all() {
+        return [...this.entities.values()];
+    }
+    size() {
+        return this.entities.size;
+    }
+    sizeBy(kind) {
+        return this.kindIndex.get(kind) ?? 0;
+    }
+};
+WorldContext = __decorate([
+    injectable()
+], WorldContext);
+export { WorldContext };

package/dist/runtime/server/.opencore/autoload.server.controllers.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+export { onFrameworkEvent } from './bus/internal-event.bus';
+export { init } from './core';
+export * from './apis';
+export * from './decorators';
+export * from './library';
+export * from './contracts';
+export * from './ports/players.api-port';
+export * from './ports/authorization.api-port';
+export * from './ports/channel.api-port';
+export * from './devmode';
+export * from './entities';
+export * from './concepts/channel';
+export * from './runtime';
+export * from './setup';
+export * from './types';

package/dist/runtime/server/api.js

@@ -0,0 +1,21 @@
+// Framework functions
+export { onFrameworkEvent } from './bus/internal-event.bus';
+export { init } from './core';
+// API
+export * from './apis';
+export * from './decorators';
+export * from './library';
+export * from './contracts';
+export * from './ports/players.api-port';
+export * from './ports/authorization.api-port';
+export * from './ports/channel.api-port';
+// DevMode (development tools)
+export * from './devmode';
+// Entities + Concepts
+export * from './entities';
+export * from './concepts/channel';
+// Configurations
+export * from './runtime';
+export * from './setup';
+// Types
+export * from './types';

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

@@ -0,0 +1,41 @@
+import { AppearanceService } from '../services';
+import { AppearanceValidationResult, PlayerAppearance } from '../../..';
+import { Player } from '../entities/player';
+type PlayerRef = Player | number | string;
+type Clothes = Pick<PlayerAppearance, 'components' | 'props'>;
+export declare class Appearance {
+    private readonly appearance;
+    constructor(appearance: AppearanceService);
+    /**
+     * Apply full appearance to a player.
+     *
+     * This method:
+     * - Resolves the player source automatically
+     * - Validates appearance server-side
+     * - Applies appearance securely
+     * - Returns validated appearance for persistence
+     */
+    apply(player: PlayerRef, appearance: PlayerAppearance): Promise<{
+        success: boolean;
+        appearance?: PlayerAppearance;
+        errors?: string[];
+    }>;
+    /**
+     * Apply only clothing (components + props).
+     *
+     * Useful for quick outfit swaps without touching face / tattoos.
+     */
+    applyClothing(player: PlayerRef, appearance: Clothes): boolean;
+    /**
+     * Reset player appearance to default.
+     */
+    reset(player: PlayerRef): boolean;
+    /**
+     * Validate appearance data without applying it.
+     *
+     * Useful before persistence or preview flows.
+     */
+    validate(appearance: Partial<PlayerAppearance>): AppearanceValidationResult;
+    private resolveSource;
+}
+export {};

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

@@ -0,0 +1,66 @@
+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);
+};
+import { injectable } from 'tsyringe';
+import { AppearanceService } from '../services';
+let Appearance = class Appearance {
+    appearance;
+    constructor(appearance) {
+        this.appearance = appearance;
+    }
+    /**
+     * Apply full appearance to a player.
+     *
+     * This method:
+     * - Resolves the player source automatically
+     * - Validates appearance server-side
+     * - Applies appearance securely
+     * - Returns validated appearance for persistence
+     */
+    async apply(player, appearance) {
+        const src = this.resolveSource(player);
+        return this.appearance.applyAppearance(src, appearance);
+    }
+    /**
+     * Apply only clothing (components + props).
+     *
+     * Useful for quick outfit swaps without touching face / tattoos.
+     */
+    applyClothing(player, appearance) {
+        const src = this.resolveSource(player);
+        return this.appearance.applyClothing(src, appearance);
+    }
+    /**
+     * Reset player appearance to default.
+     */
+    reset(player) {
+        const src = this.resolveSource(player);
+        return this.appearance.resetAppearance(src);
+    }
+    /**
+     * Validate appearance data without applying it.
+     *
+     * Useful before persistence or preview flows.
+     */
+    validate(appearance) {
+        return this.appearance.validateAppearance(appearance);
+    }
+    resolveSource(player) {
+        if (typeof player === 'string')
+            return player;
+        if (typeof player === 'number')
+            return String(player);
+        return player.clientID.toString();
+    }
+};
+Appearance = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [AppearanceService])
+], Appearance);
+export { Appearance };

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

@@ -0,0 +1,69 @@
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { RGB } from '../../../kernel/utils/rgb';
+import { Player } from '../entities/player';
+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.
+ */
+export declare class Chat {
+    private readonly events;
+    private readonly players;
+    constructor(events: EventsAPI<'server'>, 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: string, author?: string, color?: RGB): void;
+    /**
+     * 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: Player, message: string, author?: string, color?: RGB): void;
+    /**
+     * Clear chat for a single player.
+     *
+     * @param player - Target player.
+     */
+    clearChat(player: Player): void;
+    /**
+     * 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: (Player | number)[], message: string, author?: string, color?: RGB): void;
+    /**
+     * 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: Player, message: string, radius: number, author?: string, color?: RGB): void;
+    /**
+     * Broadcast a system message to all players.
+     *
+     * @param message - Message body.
+     * @param color - Message color (RGB). Defaults to a light blue/cyan.
+     */
+    broadcastSystem(message: string, color: RGB): void;
+    /**
+     * Clear chat for all connected players.
+     */
+    clearChatAll(): void;
+}

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';