@open-core/framework 1.0.7 → 1.0.8

package/dist/runtime/server/bootstrap.js

@@ -5,9 +5,11 @@ import { GLOBAL_CONTAINER, MetadataScanner } from '../../kernel/di/index';
 import { getLogLevel, LogLevelLabels, loggers } from '../../kernel/logger';
 import { createNodeServerAdapter } from './adapter/node-server-adapter';
 import { installServerAdapter } from './adapter/registry';
+import { configureFrameworkEventBridge } from './bus/internal-event.bus';
 import { PrincipalProviderContract } from './contracts/index';
 import { getServerBinaryServiceRegistry } from './decorators/binaryService';
 import { getServerControllerRegistry } from './decorators/controller';
+import { Players } from './ports/players.api-port';
 import { getFrameworkModeScope, setRuntimeContext, validateRuntimeOptions, } from './runtime';
 import { BinaryProcessManager } from './system/managers/binary-process.manager';
 import { PlayerPersistenceService } from './services/persistence.service';
@@ -116,6 +118,13 @@ export async function initServer(options, plugins) {
     // 1. Register Core Services (WorldContext, PlayerService, etc.)
     registerServicesServer(ctx);
     loggers.bootstrap.debug('Core services registered');
+    configureFrameworkEventBridge({
+        mode: ctx.mode,
+        engineEvents: GLOBAL_CONTAINER.resolve(IEngineEvents),
+        players: GLOBAL_CONTAINER.isRegistered(Players)
+            ? GLOBAL_CONTAINER.resolve(Players)
+            : undefined,
+    });
     // 2. Load Controllers (Framework & User controllers)
     // This is where user services get registered if they are decorated with @injectable()
     // and imported before init() or discovered here.

package/dist/runtime/server/bus/internal-event.bus.d.ts

@@ -1,6 +1,15 @@
-import { FrameworkEventsMap } from '../types/framework-events.types';
+import { IEngineEvents } from '../../../adapters/contracts/IEngineEvents';
+import { type FrameworkMode } from '../runtime';
+import { Players } from '../ports/players.api-port';
+import { type FrameworkEventsMap } from '../types/framework-events.types';
 type InternalEventName = keyof FrameworkEventsMap;
 type InternalEventHandler<E extends InternalEventName> = (payload: FrameworkEventsMap[E]) => void;
+interface FrameworkEventBridgeConfig {
+    mode: FrameworkMode;
+    engineEvents?: IEngineEvents;
+    players?: Players;
+}
 export declare function onFrameworkEvent<E extends InternalEventName>(event: E, handler: InternalEventHandler<E>): () => void;
+export declare function configureFrameworkEventBridge(config: FrameworkEventBridgeConfig): void;
 export declare function emitFrameworkEvent<E extends InternalEventName>(event: E, payload: FrameworkEventsMap[E]): void;
 export {};

package/dist/runtime/server/bus/internal-event.bus.js

@@ -1,5 +1,10 @@
 import { loggers } from '../../../kernel/logger';
+import { SYSTEM_EVENTS } from '../../shared/types/system-types';
 const handlers = {};
+const bridgeListenerRegistrations = new WeakSet();
+let bridgeConfig = {
+    mode: 'STANDALONE',
+};
 export function onFrameworkEvent(event, handler) {
     let list = handlers[event];
     if (!list) {
@@ -13,7 +18,32 @@ export function onFrameworkEvent(event, handler) {
             list.splice(index, 1);
     };
 }
+export function configureFrameworkEventBridge(config) {
+    bridgeConfig = config;
+    if (config.mode !== 'RESOURCE' || !config.engineEvents)
+        return;
+    if (bridgeListenerRegistrations.has(config.engineEvents))
+        return;
+    config.engineEvents.on(SYSTEM_EVENTS.framework.dispatch, (envelope) => {
+        if (bridgeConfig.mode !== 'RESOURCE')
+            return;
+        dispatchTransportFrameworkEvent(envelope.event, envelope.payload);
+    });
+    bridgeListenerRegistrations.add(config.engineEvents);
+}
 export function emitFrameworkEvent(event, payload) {
+    dispatchLocalFrameworkEvent(event, payload);
+    if (bridgeConfig.mode !== 'CORE' || !bridgeConfig.engineEvents)
+        return;
+    const transportPayload = serializeFrameworkEvent(event, payload);
+    if (!transportPayload)
+        return;
+    bridgeConfig.engineEvents.emit(SYSTEM_EVENTS.framework.dispatch, {
+        event,
+        payload: transportPayload,
+    });
+}
+function dispatchLocalFrameworkEvent(event, payload) {
     const list = handlers[event];
     if (!list)
         return;
@@ -28,3 +58,68 @@ export function emitFrameworkEvent(event, payload) {
         }
     }
 }
+function dispatchTransportFrameworkEvent(event, payload) {
+    const hydrated = hydrateFrameworkEvent(event, payload);
+    if (!hydrated)
+        return;
+    dispatchLocalFrameworkEvent(event, hydrated);
+}
+function serializeFrameworkEvent(event, payload) {
+    switch (event) {
+        case 'internal:playerSessionCreated':
+        case 'internal:playerSessionDestroyed':
+            return payload;
+        case 'internal:playerFullyConnected': {
+            const fullyConnectedPayload = payload;
+            return {
+                clientId: fullyConnectedPayload.player.clientID,
+            };
+        }
+        case 'internal:playerSessionRecovered': {
+            const recoveredPayload = payload;
+            return {
+                clientId: recoveredPayload.clientId,
+                license: recoveredPayload.license,
+            };
+        }
+        default:
+            return null;
+    }
+}
+function hydrateFrameworkEvent(event, payload) {
+    switch (event) {
+        case 'internal:playerSessionCreated':
+        case 'internal:playerSessionDestroyed':
+            return payload;
+        case 'internal:playerFullyConnected': {
+            const fullyConnectedPayload = payload;
+            const player = bridgeConfig.players?.getByClient(fullyConnectedPayload.clientId);
+            if (!player) {
+                loggers.eventBus.warn('Skipping framework event: player not found during hydration', {
+                    event,
+                    clientId: fullyConnectedPayload.clientId,
+                });
+                return null;
+            }
+            return { player };
+        }
+        case 'internal:playerSessionRecovered': {
+            const recoveredPayload = payload;
+            const player = bridgeConfig.players?.getByClient(recoveredPayload.clientId);
+            if (!player) {
+                loggers.eventBus.warn('Skipping framework event: player not found during hydration', {
+                    event,
+                    clientId: recoveredPayload.clientId,
+                });
+                return null;
+            }
+            return {
+                clientId: recoveredPayload.clientId,
+                license: recoveredPayload.license,
+                player,
+            };
+        }
+        default:
+            return null;
+    }
+}

package/dist/runtime/server/decorators/onFrameworkEvent.d.ts

@@ -6,7 +6,23 @@ import { FrameworkEventsMap } from '../types/framework-events.types';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ * The handler receives the framework payload associated with the selected event from
+ * {@link FrameworkEventsMap}. Unlike {@link OnRuntimeEvent}, this payload is framework-defined
+ * and may include hydrated entities such as {@link Player}.
+ *
+ * Framework events are delivered:
+ * - locally in `STANDALONE`
+ * - locally inside `CORE`
+ * - from `CORE` to `RESOURCE` through the internal framework bridge
+ *
+ * For bridged events, the transport payload is serialized in `CORE` and then rehydrated in the
+ * receiving `RESOURCE`. That means handlers can keep using the same payload shape in every mode.
+ *
+ * Current built-in payloads:
+ * - `internal:playerSessionCreated`: `{ clientId, license }`
+ * - `internal:playerSessionDestroyed`: `{ clientId }`
+ * - `internal:playerFullyConnected`: `{ player }`
+ * - `internal:playerSessionRecovered`: `{ clientId, license, player }`
  *
  * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
  *
@@ -16,7 +32,7 @@ import { FrameworkEventsMap } from '../types/framework-events.types';
  * export class SystemController {
  *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
  *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
- *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *     console.log(`Player ${payload.player.clientID} connected`)
  *   }
  * }
  * ```

package/dist/runtime/server/decorators/onFrameworkEvent.js

@@ -6,7 +6,23 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * This decorator only stores metadata. The framework binds listeners during bootstrap by scanning
  * controller methods.
  *
- * The handler should accept the payload type corresponding to the event from {@link FrameworkEventsMap}.
+ * The handler receives the framework payload associated with the selected event from
+ * {@link FrameworkEventsMap}. Unlike {@link OnRuntimeEvent}, this payload is framework-defined
+ * and may include hydrated entities such as {@link Player}.
+ *
+ * Framework events are delivered:
+ * - locally in `STANDALONE`
+ * - locally inside `CORE`
+ * - from `CORE` to `RESOURCE` through the internal framework bridge
+ *
+ * For bridged events, the transport payload is serialized in `CORE` and then rehydrated in the
+ * receiving `RESOURCE`. That means handlers can keep using the same payload shape in every mode.
+ *
+ * Current built-in payloads:
+ * - `internal:playerSessionCreated`: `{ clientId, license }`
+ * - `internal:playerSessionDestroyed`: `{ clientId }`
+ * - `internal:playerFullyConnected`: `{ player }`
+ * - `internal:playerSessionRecovered`: `{ clientId, license, player }`
  *
  * @param event - Internal event name, strongly typed to {@link FrameworkEventsMap}.
  *
@@ -16,7 +32,7 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * export class SystemController {
  *   @Server.OnFrameworkEvent('internal:playerFullyConnected')
  *   onPlayerConnected(payload: PlayerFullyConnectedPayload) {
- *     console.log(`Player ${payload.player.session.clientId} connected`)
+ *     console.log(`Player ${payload.player.clientID} connected`)
  *   }
  * }
  * ```

package/dist/runtime/server/decorators/onRuntimeEvent.d.ts

@@ -7,6 +7,19 @@ import type { RuntimeEventName } from '../../../adapters/contracts/runtime';
  * This decorator only stores metadata. During bootstrap, the framework scans controller
  * methods and binds handlers to runtime events.
  *
+ * The decorated method receives the raw runtime arguments emitted by the adapter for
+ * the selected event. OpenCore does not wrap these arguments into an object payload and
+ * does not automatically resolve a {@link Player} entity for you.
+ *
+ * Common server event signatures in the current runtime map:
+ * - `playerJoining`: `(clientId: number, identifiers?: Record<string, string>)`
+ * - `playerDropped`: `(clientId: number)`
+ * - `onServerResourceStop`: `(resourceName: string)`
+ * - `playerCommand`: runtime-specific raw arguments from the adapter
+ *
+ * If you need a framework-managed payload such as `{ player }`, use
+ * {@link OnFrameworkEvent} instead.
+ *
  * CitizenFX server event reference:
  * https://docs.fivem.net/docs/scripting-reference/events/server-events/
  *
@@ -17,8 +30,8 @@ import type { RuntimeEventName } from '../../../adapters/contracts/runtime';
  * @Server.Controller()
  * export class SessionController {
  *   @Server.OnRuntimeEvent('playerJoining')
- *   onPlayerJoining() {
- *     // ...
+ *   onPlayerJoining(clientId: number, identifiers?: Record<string, string>) {
+ *     // Raw runtime arguments
  *   }
  * }
  * ```

package/dist/runtime/server/decorators/onRuntimeEvent.js

@@ -7,6 +7,19 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * This decorator only stores metadata. During bootstrap, the framework scans controller
  * methods and binds handlers to runtime events.
  *
+ * The decorated method receives the raw runtime arguments emitted by the adapter for
+ * the selected event. OpenCore does not wrap these arguments into an object payload and
+ * does not automatically resolve a {@link Player} entity for you.
+ *
+ * Common server event signatures in the current runtime map:
+ * - `playerJoining`: `(clientId: number, identifiers?: Record<string, string>)`
+ * - `playerDropped`: `(clientId: number)`
+ * - `onServerResourceStop`: `(resourceName: string)`
+ * - `playerCommand`: runtime-specific raw arguments from the adapter
+ *
+ * If you need a framework-managed payload such as `{ player }`, use
+ * {@link OnFrameworkEvent} instead.
+ *
  * CitizenFX server event reference:
  * https://docs.fivem.net/docs/scripting-reference/events/server-events/
  *
@@ -17,8 +30,8 @@ import { METADATA_KEYS } from '../system/metadata-server.keys';
  * @Server.Controller()
  * export class SessionController {
  *   @Server.OnRuntimeEvent('playerJoining')
- *   onPlayerJoining() {
- *     // ...
+ *   onPlayerJoining(clientId: number, identifiers?: Record<string, string>) {
+ *     // Raw runtime arguments
  *   }
  * }
  * ```

package/dist/runtime/server/types/framework-events.types.d.ts

@@ -1,19 +1,65 @@
 import { Player } from '../entities';
+/**
+ * Emitted when a player session is created in the framework session lifecycle.
+ */
 export interface PlayerSessionCreatedPayload {
     clientId: number;
     license: string | undefined;
 }
+/**
+ * Emitted when a player session is destroyed in the framework session lifecycle.
+ */
 export interface PlayerSessionDestroyedPayload {
     clientId: number;
 }
+/**
+ * Emitted when the framework considers the player fully connected and the runtime-specific
+ * {@link Player} entity can be consumed safely by application code.
+ */
 export interface PlayerFullyConnectedPayload {
     player: Player;
 }
+/**
+ * Emitted when the framework recreates a player session after resource restart recovery.
+ */
 export interface PlayerSessionRecoveredPayload {
     clientId: number;
     player: Player;
     license: string | undefined;
 }
+/**
+ * Serialized transport payload for `internal:playerFullyConnected` used across `CORE -> RESOURCE`.
+ */
+export interface PlayerFullyConnectedTransportPayload {
+    clientId: number;
+}
+/**
+ * Serialized transport payload for `internal:playerSessionRecovered` used across `CORE -> RESOURCE`.
+ */
+export interface PlayerSessionRecoveredTransportPayload {
+    clientId: number;
+    license: string | undefined;
+}
+/**
+ * Internal transport contract used by the framework bridge when delivering framework events
+ * between different server runtimes.
+ */
+export type FrameworkTransportEventsMap = {
+    'internal:playerSessionCreated': PlayerSessionCreatedPayload;
+    'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;
+    'internal:playerFullyConnected': PlayerFullyConnectedTransportPayload;
+    'internal:playerSessionRecovered': PlayerSessionRecoveredTransportPayload;
+};
+/**
+ * Envelope emitted through the internal framework bridge.
+ */
+export interface FrameworkEventEnvelope<E extends keyof FrameworkTransportEventsMap> {
+    event: E;
+    payload: FrameworkTransportEventsMap[E];
+}
+/**
+ * Public payload map consumed by {@link OnFrameworkEvent} and `onFrameworkEvent(...)`.
+ */
 export type FrameworkEventsMap = {
     'internal:playerSessionCreated': PlayerSessionCreatedPayload;
     'internal:playerSessionDestroyed': PlayerSessionDestroyedPayload;

package/dist/runtime/shared/types/system-types.d.ts

@@ -16,6 +16,9 @@ export declare const SYSTEM_EVENTS: {
     readonly command: {
         readonly execute: `opencore:${string}:${string}`;
     };
+    readonly framework: {
+        readonly dispatch: `opencore:${string}:${string}`;
+    };
     readonly spawner: {
         readonly spawn: `opencore:${string}:${string}`;
         readonly teleport: `opencore:${string}:${string}`;

package/dist/runtime/shared/types/system-types.js

@@ -17,6 +17,9 @@ export const SYSTEM_EVENTS = {
     command: {
         execute: systemEvent('command', 'execute'),
     },
+    framework: {
+        dispatch: systemEvent('framework', 'dispatch'),
+    },
     spawner: {
         spawn: systemEvent('spawner', 'spawn'),
         teleport: systemEvent('spawner', 'teleport'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Secure, event-driven TypeScript Framework & Runtime engine for CitizenFX (Cfx).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",