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

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

@@ -0,0 +1,168 @@
+/**
+ * Entity identifier format: `kind:id`
+ * @example 'player:1', 'vehicle:42', 'npc:spawn-1'
+ */
+export type EntityId = `${string}:${string | number}`;
+/**
+ * Entity metadata storage type.
+ */
+export type EntityMeta = Record<string, unknown>;
+/**
+ * Base entity class for all game entities.
+ *
+ * @remarks
+ * Provides common functionality for all entities in the game world:
+ * - Unique identification
+ * - State flags (active states like 'dead', 'frozen', etc.)
+ * - Metadata storage
+ * - Dimension/world support
+ *
+ * This class is platform-agnostic and should be extended by
+ * platform-specific entity implementations.
+ */
+export declare abstract class BaseEntity {
+    /**
+     * Unique identifier for this entity.
+     * Format: `kind:id` (e.g., 'player:1', 'vehicle:42')
+     */
+    readonly id: EntityId;
+    /**
+     * Entity kind extracted from the ID.
+     * @example 'player', 'vehicle', 'npc'
+     */
+    readonly kind: string;
+    /**
+     * Active state flags.
+     */
+    private state;
+    /**
+     * Transient metadata storage.
+     */
+    private meta;
+    /**
+     * Current dimension/world ID.
+     * 0 is the default shared world.
+     */
+    protected _dimension: number;
+    /**
+     * Stream distance for this entity.
+     * Determines how far away players can see this entity.
+     */
+    protected _streamDistance: number;
+    /**
+     * Creates a new entity.
+     * @param id - Unique entity identifier in format 'kind:id'
+     */
+    constructor(id: EntityId);
+    /**
+     * Adds a state flag to the entity.
+     * @param state - State identifier (e.g., 'dead', 'frozen', 'invisible')
+     */
+    add(state: string): void;
+    /**
+     * Checks if the entity has a state flag.
+     * @param key - State identifier to check
+     */
+    has(key: string): boolean;
+    /**
+     * Gets all active state flags.
+     * @returns Array of state identifiers
+     */
+    all(): string[];
+    /**
+     * Removes a state flag from the entity.
+     * @param key - State identifier to remove
+     */
+    delete(key: string): void;
+    /**
+     * Clears all state flags.
+     */
+    clearStates(): void;
+    /**
+     * Toggles a state flag.
+     * @param state - State identifier
+     * @param force - Optional force value (true = add, false = remove)
+     * @returns The new state (true if added, false if removed)
+     */
+    toggle(state: string, force?: boolean): boolean;
+    /**
+     * Sets a metadata value.
+     * @param key - Metadata key
+     * @param value - Value to store
+     */
+    setMeta<T = unknown>(key: string, value: T): void;
+    /**
+     * Gets a metadata value.
+     * @param key - Metadata key
+     * @returns The stored value or undefined
+     */
+    getMeta<T = unknown>(key: string): T | undefined;
+    /**
+     * Checks if a metadata key exists.
+     * @param key - Metadata key
+     */
+    hasMeta(key: string): boolean;
+    /**
+     * Deletes a metadata value.
+     * @param key - Metadata key
+     */
+    deleteMeta(key: string): void;
+    /**
+     * Gets all metadata.
+     * @returns Copy of the metadata object
+     */
+    getAllMeta(): EntityMeta;
+    /**
+     * Clears all metadata.
+     */
+    clearMeta(): void;
+    /**
+     * Gets the current dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    get dimension(): number;
+    /**
+     * Sets the dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    set dimension(value: number);
+    /**
+     * Gets the stream distance for this entity.
+     *
+     * @remarks
+     * Stream distance determines how far away players can see this entity.
+     * Not all platforms support custom stream distances.
+     */
+    get streamDistance(): number;
+    /**
+     * Sets the stream distance for this entity.
+     */
+    set streamDistance(value: number);
+    /**
+     * Creates a snapshot of the entity state.
+     * @returns Plain object with entity data
+     */
+    snapshot(): EntitySnapshot;
+    /**
+     * Restores entity state from a snapshot.
+     * @param snapshot - Snapshot to restore from
+     */
+    restore(snapshot: Partial<EntitySnapshot>): void;
+}
+/**
+ * Entity snapshot for serialization.
+ */
+export interface EntitySnapshot {
+    id: EntityId;
+    kind: string;
+    states: string[];
+    meta: EntityMeta;
+    dimension: number;
+    streamDistance: number;
+}

package/dist/runtime/core/entity.js

@@ -0,0 +1,232 @@
+/**
+ * Base entity class for all game entities.
+ *
+ * @remarks
+ * Provides common functionality for all entities in the game world:
+ * - Unique identification
+ * - State flags (active states like 'dead', 'frozen', etc.)
+ * - Metadata storage
+ * - Dimension/world support
+ *
+ * This class is platform-agnostic and should be extended by
+ * platform-specific entity implementations.
+ */
+export class BaseEntity {
+    /**
+     * Unique identifier for this entity.
+     * Format: `kind:id` (e.g., 'player:1', 'vehicle:42')
+     */
+    id;
+    /**
+     * Entity kind extracted from the ID.
+     * @example 'player', 'vehicle', 'npc'
+     */
+    kind;
+    /**
+     * Active state flags.
+     */
+    state = new Set();
+    /**
+     * Transient metadata storage.
+     */
+    meta = {};
+    /**
+     * Current dimension/world ID.
+     * 0 is the default shared world.
+     */
+    _dimension = 0;
+    /**
+     * Stream distance for this entity.
+     * Determines how far away players can see this entity.
+     */
+    _streamDistance = 100;
+    /**
+     * Creates a new entity.
+     * @param id - Unique entity identifier in format 'kind:id'
+     */
+    constructor(id) {
+        this.id = id;
+        this.kind = id.split(':')[0];
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // State Management
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Adds a state flag to the entity.
+     * @param state - State identifier (e.g., 'dead', 'frozen', 'invisible')
+     */
+    add(state) {
+        this.state.add(state);
+    }
+    /**
+     * Checks if the entity has a state flag.
+     * @param key - State identifier to check
+     */
+    has(key) {
+        return this.state.has(key);
+    }
+    /**
+     * Gets all active state flags.
+     * @returns Array of state identifiers
+     */
+    all() {
+        return Array.from(this.state);
+    }
+    /**
+     * Removes a state flag from the entity.
+     * @param key - State identifier to remove
+     */
+    delete(key) {
+        this.state.delete(key);
+    }
+    /**
+     * Clears all state flags.
+     */
+    clearStates() {
+        this.state.clear();
+    }
+    /**
+     * Toggles a state flag.
+     * @param state - State identifier
+     * @param force - Optional force value (true = add, false = remove)
+     * @returns The new state (true if added, false if removed)
+     */
+    toggle(state, force) {
+        if (force !== undefined) {
+            force ? this.add(state) : this.delete(state);
+            return force;
+        }
+        if (this.has(state)) {
+            this.delete(state);
+            return false;
+        }
+        this.add(state);
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Metadata Management
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Sets a metadata value.
+     * @param key - Metadata key
+     * @param value - Value to store
+     */
+    setMeta(key, value) {
+        this.meta[key] = value;
+    }
+    /**
+     * Gets a metadata value.
+     * @param key - Metadata key
+     * @returns The stored value or undefined
+     */
+    getMeta(key) {
+        return this.meta[key];
+    }
+    /**
+     * Checks if a metadata key exists.
+     * @param key - Metadata key
+     */
+    hasMeta(key) {
+        return key in this.meta;
+    }
+    /**
+     * Deletes a metadata value.
+     * @param key - Metadata key
+     */
+    deleteMeta(key) {
+        delete this.meta[key];
+    }
+    /**
+     * Gets all metadata.
+     * @returns Copy of the metadata object
+     */
+    getAllMeta() {
+        return { ...this.meta };
+    }
+    /**
+     * Clears all metadata.
+     */
+    clearMeta() {
+        this.meta = {};
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Dimension/World Support
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Gets the current dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    get dimension() {
+        return this._dimension;
+    }
+    /**
+     * Sets the dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    set dimension(value) {
+        this._dimension = value;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Stream Distance
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Gets the stream distance for this entity.
+     *
+     * @remarks
+     * Stream distance determines how far away players can see this entity.
+     * Not all platforms support custom stream distances.
+     */
+    get streamDistance() {
+        return this._streamDistance;
+    }
+    /**
+     * Sets the stream distance for this entity.
+     */
+    set streamDistance(value) {
+        this._streamDistance = Math.max(0, value);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Serialization
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Creates a snapshot of the entity state.
+     * @returns Plain object with entity data
+     */
+    snapshot() {
+        return {
+            id: this.id,
+            kind: this.kind,
+            states: this.all(),
+            meta: this.getAllMeta(),
+            dimension: this._dimension,
+            streamDistance: this._streamDistance,
+        };
+    }
+    /**
+     * Restores entity state from a snapshot.
+     * @param snapshot - Snapshot to restore from
+     */
+    restore(snapshot) {
+        if (snapshot.states) {
+            this.clearStates();
+            for (const s of snapshot.states) {
+                this.add(s);
+            }
+        }
+        if (snapshot.meta) {
+            this.meta = { ...snapshot.meta };
+        }
+        if (snapshot.dimension !== undefined) {
+            this._dimension = snapshot.dimension;
+        }
+        if (snapshot.streamDistance !== undefined) {
+            this._streamDistance = snapshot.streamDistance;
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from './entity';
+export * from './library';
+export * from './spatial';
+export * from './world';
+export * from './nativehandle';

package/dist/runtime/core/index.js

@@ -0,0 +1,5 @@
+export * from './entity';
+export * from './library';
+export * from './spatial';
+export * from './world';
+export * from './nativehandle';

package/dist/runtime/core/library/create-library-base.d.ts

@@ -0,0 +1,15 @@
+import { OpenCoreLibraryBase } from './types';
+/**
+ * Creates the shared base API for an OpenCore library.
+ *
+ * @remarks
+ * The base contains only library-local events (internal bus) and namespaced
+ * event-name building. External bridge behavior is added by server/client wrappers.
+ */
+export declare function createLibraryBase(name: string, opts?: {
+    namespace?: string;
+}): OpenCoreLibraryBase;
+/**
+ * Backwards-compatible alias.
+ */
+export declare const createLibraryCore: typeof createLibraryBase;

package/dist/runtime/core/library/create-library-base.js

@@ -0,0 +1,27 @@
+import { createLibraryBus } from './library-bus';
+/**
+ * Creates the shared base API for an OpenCore library.
+ *
+ * @remarks
+ * The base contains only library-local events (internal bus) and namespaced
+ * event-name building. External bridge behavior is added by server/client wrappers.
+ */
+export function createLibraryBase(name, opts) {
+    const bus = createLibraryBus();
+    const namespace = opts?.namespace ?? `opencore:${name}`;
+    return {
+        name,
+        namespace,
+        on: bus.on,
+        once: bus.once,
+        off: bus.off,
+        emit: bus.emit,
+        buildEventName(eventName) {
+            return `${namespace}:${eventName}`;
+        },
+    };
+}
+/**
+ * Backwards-compatible alias.
+ */
+export const createLibraryCore = createLibraryBase;

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

@@ -0,0 +1,5 @@
+export { createLibraryBase, createLibraryCore } from './create-library-base';
+export { buildLibraryEventId } from './library-event-id';
+export { createLibraryBus } from './library-bus';
+export { createLibraryConfigAccessor } from './library-config';
+export type { LibraryEventEnvelope, LibraryEventId, LibraryBus, LibraryEventHandler, LibraryEventName, LibraryEventMetadata, LibraryName, LibraryNamespace, OpenCoreClientLibrary, OpenCoreLibraryBase, OpenCoreLibraryConfigAccessor, OpenCoreServerLibrary, } from './types';

package/dist/runtime/core/library/index.js

@@ -0,0 +1,4 @@
+export { createLibraryBase, createLibraryCore } from './create-library-base';
+export { buildLibraryEventId } from './library-event-id';
+export { createLibraryBus } from './library-bus';
+export { createLibraryConfigAccessor } from './library-config';

package/dist/runtime/core/library/library-bus.d.ts

@@ -0,0 +1,9 @@
+import { LibraryBus } from './types';
+/**
+ * Creates a lightweight library-local event bus.
+ *
+ * @remarks
+ * This is a pure TypeScript event bus intended for internal library events.
+ * It does not use FiveM, network events, or Node core modules.
+ */
+export declare function createLibraryBus(): LibraryBus;

package/dist/runtime/core/library/library-bus.js

@@ -0,0 +1,46 @@
+/**
+ * Creates a lightweight library-local event bus.
+ *
+ * @remarks
+ * This is a pure TypeScript event bus intended for internal library events.
+ * It does not use FiveM, network events, or Node core modules.
+ */
+export function createLibraryBus() {
+    const handlers = new Map();
+    const on = (event, handler) => {
+        const eventHandlers = handlers.get(event) ?? new Set();
+        eventHandlers.add(handler);
+        handlers.set(event, eventHandlers);
+    };
+    const off = (event, handler) => {
+        const eventHandlers = handlers.get(event);
+        if (!eventHandlers)
+            return;
+        eventHandlers.delete(handler);
+        if (eventHandlers.size === 0) {
+            handlers.delete(event);
+        }
+    };
+    const once = (event, handler) => {
+        const onceHandler = (payload) => {
+            off(event, onceHandler);
+            const typedHandler = handler;
+            typedHandler(payload);
+        };
+        on(event, onceHandler);
+    };
+    const emit = (event, payload) => {
+        const eventHandlers = handlers.get(event);
+        if (!eventHandlers || eventHandlers.size === 0)
+            return;
+        for (const handler of [...eventHandlers]) {
+            handler(payload);
+        }
+    };
+    return {
+        on,
+        once,
+        off,
+        emit,
+    };
+}

package/dist/runtime/core/library/library-config.d.ts

@@ -0,0 +1,10 @@
+import { OpenCoreLibraryConfigAccessor } from './types';
+type LibraryConfigStore = Record<string, Record<string, unknown>>;
+declare global {
+    var __OPENCORE_LIBRARY_CONFIG__: LibraryConfigStore | undefined;
+}
+/**
+ * Creates a namespaced config accessor for library wrappers.
+ */
+export declare function createLibraryConfigAccessor<TConfig = Record<string, unknown>>(namespace: string): OpenCoreLibraryConfigAccessor<TConfig>;
+export {};

package/dist/runtime/core/library/library-config.js

@@ -0,0 +1,12 @@
+/**
+ * Creates a namespaced config accessor for library wrappers.
+ */
+export function createLibraryConfigAccessor(namespace) {
+    return {
+        namespace,
+        get(key) {
+            const configSource = globalThis.__OPENCORE_LIBRARY_CONFIG__?.[namespace];
+            return configSource?.[key];
+        },
+    };
+}

package/dist/runtime/core/library/library-event-id.d.ts

@@ -0,0 +1,8 @@
+import { LibraryEventId, LibraryEventName, LibraryName } from './types';
+/**
+ * Builds a deterministic library event identifier.
+ *
+ * @example
+ * `characters:session:created`
+ */
+export declare function buildLibraryEventId(libraryName: LibraryName, eventName: LibraryEventName): LibraryEventId;

package/dist/runtime/core/library/library-event-id.js

@@ -0,0 +1,9 @@
+/**
+ * Builds a deterministic library event identifier.
+ *
+ * @example
+ * `characters:session:created`
+ */
+export function buildLibraryEventId(libraryName, eventName) {
+    return `${libraryName}:${eventName}`;
+}