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

package/dist/runtime/server/adapter/node-vehicle-lifecycle-server.d.ts

@@ -0,0 +1,13 @@
+import { IVehicleLifecycleServer } from '../../../adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer';
+import type { CreateVehicleServerRequest, CreateVehicleServerResult, WarpPlayerIntoVehicleRequest } from '../../../adapters/contracts/server/vehicle-lifecycle/types';
+import { IPlatformContext } from '../../../adapters/contracts/IPlatformContext';
+import { IVehicleServer } from '../../../adapters/contracts/server/IVehicleServer';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+export declare class NodeVehicleLifecycleServer extends IVehicleLifecycleServer {
+    private readonly vehicleServer;
+    private readonly platformContext;
+    private readonly events;
+    constructor(vehicleServer: IVehicleServer, platformContext: IPlatformContext, events: EventsAPI<'server'>);
+    create(request: CreateVehicleServerRequest): CreateVehicleServerResult;
+    warpPlayerIntoVehicle(request: WarpPlayerIntoVehicleRequest): void;
+}

package/dist/runtime/server/adapter/node-vehicle-lifecycle-server.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;
+};
+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 { IVehicleLifecycleServer } from '../../../adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer';
+import { IPlatformContext } from '../../../adapters/contracts/IPlatformContext';
+import { IVehicleServer } from '../../../adapters/contracts/server/IVehicleServer';
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+let NodeVehicleLifecycleServer = class NodeVehicleLifecycleServer extends IVehicleLifecycleServer {
+    vehicleServer;
+    platformContext;
+    events;
+    constructor(vehicleServer, platformContext, events) {
+        super();
+        this.vehicleServer = vehicleServer;
+        this.platformContext = platformContext;
+        this.events = events;
+    }
+    create(request) {
+        if (!this.platformContext.enableServerVehicleCreation) {
+            throw new Error(`Server vehicle creation is disabled for profile '${this.platformContext.gameProfile}'`);
+        }
+        const handle = this.vehicleServer.createServerSetter(request.modelHash, this.platformContext.defaultVehicleType, request.position.x, request.position.y, request.position.z, request.heading);
+        if (!handle || handle === 0) {
+            throw new Error('Failed to create vehicle entity');
+        }
+        return {
+            handle,
+            networkId: this.vehicleServer.getNetworkIdFromEntity(handle),
+        };
+    }
+    warpPlayerIntoVehicle(request) {
+        const clientId = Number(request.playerSrc);
+        if (Number.isNaN(clientId))
+            return;
+        this.events.emit('opencore:vehicle:warpInto', clientId, request.networkId, request.seatIndex);
+    }
+};
+NodeVehicleLifecycleServer = __decorate([
+    injectable(),
+    __param(0, inject(IVehicleServer)),
+    __param(1, inject(IPlatformContext)),
+    __param(2, inject(EventsAPI)),
+    __metadata("design:paramtypes", [IVehicleServer,
+        IPlatformContext,
+        EventsAPI])
+], NodeVehicleLifecycleServer);
+export { NodeVehicleLifecycleServer };

package/dist/runtime/server/adapter/player-adapter.d.ts

@@ -0,0 +1,28 @@
+import { PlayerAdapters, Player } from '../entities/player';
+import { PlayerSession } from '../types/player-session.types';
+import { SerializedPlayerData } from '../types/core-exports.types';
+/**
+ * Dependencies required to build server-side player instances.
+ */
+export type PlayerFactoryDeps = PlayerAdapters;
+/**
+ * Adapter hook for creating and hydrating Player instances.
+ */
+export interface ServerPlayerAdapter {
+    createLocal(session: PlayerSession, deps: PlayerFactoryDeps): Player;
+    createRemote(data: SerializedPlayerData, deps: PlayerFactoryDeps): Player;
+    serialize?(player: Player): Record<string, unknown> | undefined;
+    hydrate?(player: Player, payload: Record<string, unknown> | undefined): void;
+}
+/**
+ * Restores base state shared by all Player instances.
+ */
+export declare function hydrateBasePlayerState(player: Player, data: SerializedPlayerData): Player;
+/**
+ * Creates the framework default local Player instance.
+ */
+export declare function createDefaultLocalPlayer(session: PlayerSession, deps: PlayerFactoryDeps): Player;
+/**
+ * Creates the framework default remote Player instance.
+ */
+export declare function createDefaultRemotePlayer(data: SerializedPlayerData, deps: PlayerFactoryDeps): Player;

package/dist/runtime/server/adapter/player-adapter.js

@@ -0,0 +1,28 @@
+import { Player } from '../entities/player';
+/**
+ * Restores base state shared by all Player instances.
+ */
+export function hydrateBasePlayerState(player, data) {
+    for (const state of data.states) {
+        player.addState(state);
+    }
+    return player;
+}
+/**
+ * Creates the framework default local Player instance.
+ */
+export function createDefaultLocalPlayer(session, deps) {
+    return new Player(session, deps);
+}
+/**
+ * Creates the framework default remote Player instance.
+ */
+export function createDefaultRemotePlayer(data, deps) {
+    const player = new Player({
+        clientID: data.clientID,
+        accountID: data.accountID,
+        identifiers: data.identifiers,
+        meta: data.meta,
+    }, deps);
+    return hydrateBasePlayerState(player, data);
+}

package/dist/runtime/server/adapter/registry.d.ts

@@ -0,0 +1,26 @@
+import { Player } from '../entities/player';
+import { SerializedPlayerData } from '../types/core-exports.types';
+import { PlayerSession } from '../types/player-session.types';
+import { type PlayerFactoryDeps } from './player-adapter';
+import { type OpenCoreServerAdapter } from './server-adapter';
+/**
+ * Installs the active server adapter for the current bootstrap.
+ */
+export declare function installServerAdapter(adapter: OpenCoreServerAdapter): Promise<void>;
+/**
+ * Returns the currently active server adapter name.
+ */
+export declare function getActiveServerAdapterName(): string | undefined;
+/**
+ * Builds a local Player through the active adapter.
+ */
+export declare function createLocalServerPlayer(session: PlayerSession, deps: PlayerFactoryDeps): Player;
+/**
+ * Builds a remote Player through the active adapter.
+ */
+export declare function createRemoteServerPlayer(data: SerializedPlayerData, deps: PlayerFactoryDeps): Player;
+/**
+ * Serializes adapter-specific player payload.
+ */
+export declare function serializeServerPlayerAdapterPayload(player: Player): SerializedPlayerData['adapter'] | undefined;
+export declare function __resetServerAdapterRegistryForTests(): void;

package/dist/runtime/server/adapter/registry.js

@@ -0,0 +1,101 @@
+import { GLOBAL_CONTAINER } from '../../../kernel/di/container';
+import { createDefaultLocalPlayer, createDefaultRemotePlayer, } from './player-adapter';
+import { bindTransportInstances, } from './server-adapter';
+const DEFAULT_PLAYER_ADAPTER = {
+    createLocal: createDefaultLocalPlayer,
+    createRemote: createDefaultRemotePlayer,
+};
+let activeServerAdapter = null;
+function assertTokenAvailable(container, token, adapterName) {
+    if (container.isRegistered(token)) {
+        throw new Error(`[OpenCore] Adapter '${adapterName}' cannot bind an already registered token.`);
+    }
+}
+function createAdapterContext(adapterName) {
+    let playerAdapterConfigured = false;
+    return {
+        adapterName,
+        container: GLOBAL_CONTAINER,
+        isRegistered(token) {
+            return GLOBAL_CONTAINER.isRegistered(token);
+        },
+        bindSingleton(token, implementation) {
+            assertTokenAvailable(GLOBAL_CONTAINER, token, adapterName);
+            GLOBAL_CONTAINER.registerSingleton(token, implementation);
+        },
+        bindInstance(token, value) {
+            assertTokenAvailable(GLOBAL_CONTAINER, token, adapterName);
+            GLOBAL_CONTAINER.registerInstance(token, value);
+        },
+        bindFactory(token, factory) {
+            assertTokenAvailable(GLOBAL_CONTAINER, token, adapterName);
+            GLOBAL_CONTAINER.register(token, { useFactory: factory });
+        },
+        bindMessagingTransport(transport) {
+            bindTransportInstances(this, transport);
+        },
+        usePlayerAdapter(adapter) {
+            if (playerAdapterConfigured) {
+                throw new Error(`[OpenCore] Adapter '${adapterName}' already configured a Player adapter.`);
+            }
+            activeServerAdapter = {
+                name: adapterName,
+                playerAdapter: adapter,
+            };
+            playerAdapterConfigured = true;
+        },
+    };
+}
+/**
+ * Installs the active server adapter for the current bootstrap.
+ */
+export async function installServerAdapter(adapter) {
+    activeServerAdapter = {
+        name: adapter.name,
+        playerAdapter: DEFAULT_PLAYER_ADAPTER,
+    };
+    const context = createAdapterContext(adapter.name);
+    await adapter.register(context);
+}
+/**
+ * Returns the currently active server adapter name.
+ */
+export function getActiveServerAdapterName() {
+    return activeServerAdapter?.name;
+}
+/**
+ * Builds a local Player through the active adapter.
+ */
+export function createLocalServerPlayer(session, deps) {
+    return (activeServerAdapter?.playerAdapter ?? DEFAULT_PLAYER_ADAPTER).createLocal(session, deps);
+}
+/**
+ * Builds a remote Player through the active adapter.
+ */
+export function createRemoteServerPlayer(data, deps) {
+    if (data.adapter?.name &&
+        activeServerAdapter?.name &&
+        data.adapter.name !== activeServerAdapter.name) {
+        throw new Error(`[OpenCore] Cannot hydrate Player for adapter '${data.adapter.name}' with active adapter '${activeServerAdapter.name}'.`);
+    }
+    const playerAdapter = activeServerAdapter?.playerAdapter ?? DEFAULT_PLAYER_ADAPTER;
+    const player = playerAdapter.createRemote(data, deps);
+    playerAdapter.hydrate?.(player, data.adapter?.payload);
+    return player;
+}
+/**
+ * Serializes adapter-specific player payload.
+ */
+export function serializeServerPlayerAdapterPayload(player) {
+    const payload = activeServerAdapter?.playerAdapter.serialize?.(player);
+    if (!activeServerAdapter || payload === undefined) {
+        return undefined;
+    }
+    return {
+        name: activeServerAdapter.name,
+        payload,
+    };
+}
+export function __resetServerAdapterRegistryForTests() {
+    activeServerAdapter = null;
+}

package/dist/runtime/server/adapter/serialization.d.ts

@@ -0,0 +1,6 @@
+import type { Player } from '../entities/player';
+import type { SerializedPlayerData } from '../types/core-exports.types';
+/**
+ * Serializes a Player using the active server adapter payload hooks.
+ */
+export declare function serializeServerPlayerData(player: Player): SerializedPlayerData;

package/dist/runtime/server/adapter/serialization.js

@@ -0,0 +1,9 @@
+import { serializeServerPlayerAdapterPayload } from './registry';
+/**
+ * Serializes a Player using the active server adapter payload hooks.
+ */
+export function serializeServerPlayerData(player) {
+    const base = player.serialize();
+    const adapter = serializeServerPlayerAdapterPayload(player);
+    return adapter ? { ...base, adapter } : base;
+}

package/dist/runtime/server/adapter/server-adapter.d.ts

@@ -0,0 +1,28 @@
+import type { DependencyContainer, InjectionToken } from 'tsyringe';
+import { MessagingTransport } from '../../../adapters/contracts/transport/messaging.transport';
+import { ServerPlayerAdapter } from './player-adapter';
+/**
+ * Public contract implemented by external server adapters.
+ */
+export interface OpenCoreServerAdapter {
+    readonly name: string;
+    register(context: ServerAdapterContext): void | Promise<void>;
+}
+/**
+ * Registration helpers exposed to server adapters.
+ */
+export interface ServerAdapterContext {
+    readonly adapterName: string;
+    readonly container: DependencyContainer;
+    isRegistered<T>(token: InjectionToken<T>): boolean;
+    bindSingleton<T>(token: InjectionToken<T>, implementation: InjectionToken<T>): void;
+    bindInstance<T>(token: InjectionToken<T>, value: T): void;
+    bindFactory<T>(token: InjectionToken<T>, factory: () => T): void;
+    bindMessagingTransport(transport: MessagingTransport): void;
+    usePlayerAdapter(adapter: ServerPlayerAdapter): void;
+}
+/**
+ * Helper for strongly typed adapter declarations.
+ */
+export declare function defineServerAdapter(adapter: OpenCoreServerAdapter): OpenCoreServerAdapter;
+export declare function bindTransportInstances(context: Pick<ServerAdapterContext, 'bindInstance'>, transport: MessagingTransport): void;

package/dist/runtime/server/adapter/server-adapter.js

@@ -0,0 +1,14 @@
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { MessagingTransport } from '../../../adapters/contracts/transport/messaging.transport';
+import { RpcAPI } from '../../../adapters/contracts/transport/rpc.api';
+/**
+ * Helper for strongly typed adapter declarations.
+ */
+export function defineServerAdapter(adapter) {
+    return adapter;
+}
+export function bindTransportInstances(context, transport) {
+    context.bindInstance(MessagingTransport, transport);
+    context.bindInstance(EventsAPI, transport.events);
+    context.bindInstance(RpcAPI, transport.rpc);
+}

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

@@ -0,0 +1,16 @@
+export { onFrameworkEvent } from './bus/internal-event.bus';
+export { init, useAdapter } from './core';
+export * from './apis';
+export * from './decorators';
+export * from './library';
+export * from './adapter';
+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,22 @@
+// Framework functions
+export { onFrameworkEvent } from './bus/internal-event.bus';
+export { init, useAdapter } from './core';
+// API
+export * from './apis';
+export * from './decorators';
+export * from './library';
+export * from './adapter';
+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,43 @@
+import { AppearanceService } from '../services';
+import { IPlayerAppearanceLifecycleServer } from '../../../adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer';
+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;
+    private readonly lifecycle;
+    constructor(appearance: AppearanceService, lifecycle: IPlayerAppearanceLifecycleServer);
+    /**
+     * 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): Promise<boolean>;
+    /**
+     * Reset player appearance to default.
+     */
+    reset(player: PlayerRef): Promise<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,79 @@
+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 { injectable } from 'tsyringe';
+import { inject } from 'tsyringe';
+import { AppearanceService } from '../services';
+import { IPlayerAppearanceLifecycleServer } from '../../../adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer';
+let Appearance = class Appearance {
+    appearance;
+    lifecycle;
+    constructor(appearance, lifecycle) {
+        this.appearance = appearance;
+        this.lifecycle = lifecycle;
+    }
+    /**
+     * 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 validation = this.appearance.validateAppearance(appearance);
+        if (!validation.valid) {
+            return { success: false, errors: validation.errors };
+        }
+        const src = this.resolveSource(player);
+        return this.lifecycle.apply(src, appearance);
+    }
+    /**
+     * Apply only clothing (components + props).
+     *
+     * Useful for quick outfit swaps without touching face / tattoos.
+     */
+    async applyClothing(player, appearance) {
+        const src = this.resolveSource(player);
+        return await Promise.resolve(this.lifecycle.applyClothing(src, appearance));
+    }
+    /**
+     * Reset player appearance to default.
+     */
+    async reset(player) {
+        const src = this.resolveSource(player);
+        return await Promise.resolve(this.lifecycle.reset(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(),
+    __param(1, inject(IPlayerAppearanceLifecycleServer)),
+    __metadata("design:paramtypes", [AppearanceService,
+        IPlayerAppearanceLifecycleServer])
+], 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;
+}