@open-core/framework 1.0.5 → 1.0.7

package/README.md

@@ -6,9 +6,9 @@
 [![website](https://img.shields.io/badge/web-opencorejs.dev-black?style=flat-square)](https://opencorejs.dev)
 
 
-# OpenCore Framework - Open Stable beta
+# OpenCore Framework - Stable v1
 
-OpenCore is a TypeScript multiplayer runtime framework targeting CitizenFX runtimes (Cfx) via adapters.
+OpenCore is a TypeScript multiplayer runtime framework targeting CitizenFX runtimes (Cfx/RageMP) via adapters.
 
 It is not a gamemode or RP framework. It provides:
 
@@ -227,34 +227,37 @@ Note: `pnpm test` does not run benchmarks.
 
 ## Benchmarks
 
-There are two benchmark suites:
-
-- Core benchmarks (Tinybench)
-- Load benchmarks (Vitest project `benchmark`)
+Benchmarks are split by value, so the default run focuses on framework features that matter for real servers.
 
 ```bash
-pnpm bench:core
+pnpm bench
+pnpm bench:value
+pnpm bench:gold
+pnpm bench:startup
+pnpm bench:diagnostic
+pnpm bench:soak
 pnpm bench:load
 pnpm bench:all
 ```
 
+- `bench` / `bench:value`: value-focused suite. Commands, net events, RPC, lifecycle, ticks, binary path, bootstrap.
+- `bench:gold`: hot-path load scenarios only.
+- `bench:startup`: startup and registration cost.
+- `bench:diagnostic`: internal and low-level synthetic benchmarks.
+- `bench:soak`: long-running stress scenario.
+
 ### Snapshot (latest local run)
 
-These values are a small extract from the latest local run (`1.0.0-beta.1`, Feb 26, 2026). Results vary by machine.
-
-- **Core**
-  - BinaryService - classify response type: `~18.25M ops/sec` (mean `~0.055μs`, p95 `~0.076μs`)
-  - EventInterceptor - getStatistics (1000 events): `~17.78M ops/sec` (mean `~0.056μs`)
-  - RuntimeConfig - resolve CORE mode: `~10.49M ops/sec` (mean `~0.095μs`)
-  - Decorators - define metadata (Command): `~6.92M ops/sec` (mean `~0.145μs`)
-  - EventBus - multiple event types: `~2.57M ops/sec` (mean `~0.390μs`)
-  - DI - resolve simple service: `~1.78M ops/sec` (mean `~0.560μs`)
-- **Load**
-  - Commands - 500 players (validated): `~4.78M ops/sec` (p95 `~0.008ms`)
-  - Pipeline - validated (500 players): `~4.79M ops/sec` (p95 `~0.024ms`)
-  - Pipeline - full (500 players): `~2.34M ops/sec` (p95 `~0.011ms`)
-  - RPC - schema generation complex (500 methods): `~705K ops/sec` (p95 `~0.335ms`)
-  - Commands - 500 players (concurrent): `~6.31K ops/sec` (p95 `~76.00ms`)
+Use `benchmark/reports/` as the source of truth. Results vary by machine and should be compared relatively, not treated as product guarantees.
+
+- Primary benchmark targets:
+  - full command execution
+  - full net event handling
+  - RPC processing
+  - player lifecycle churn
+  - tick budget impact
+  - bootstrap cost
+  - binary transport cost
 
 Full reports and methodology are available in benchmark/README.md.
 
@@ -277,12 +280,6 @@ pnpm lint:fix
 pnpm format
 ```
 
-## Ecosystem
-
-OpenCore is designed to be extended via separate packages/resources.
-
-- `@open-core/identity`: identity and permission system
-
 ## License
 
 MPL-2.0. See `LICENSE`.

package/dist/adapters/contracts/transport/index.d.ts

@@ -1,4 +1,5 @@
 export * from './context';
 export * from './events.api';
 export * from './rpc.api';
+export * from './rpc-error';
 export * from './messaging.transport';

package/dist/adapters/contracts/transport/index.js

@@ -1,4 +1,5 @@
 export * from './context';
 export * from './events.api';
 export * from './rpc.api';
+export * from './rpc-error';
 export * from './messaging.transport';

package/dist/adapters/contracts/transport/rpc-error.d.ts

@@ -0,0 +1,17 @@
+export declare const PUBLIC_RPC_ERROR_MESSAGE = "An internal server error occurred";
+export type RpcErrorInfo = {
+    message: string;
+    name?: string;
+};
+type ExposedRpcError = {
+    message: string;
+    name?: string;
+    expose: true;
+};
+export declare class RpcPublicError extends Error {
+    readonly expose = true;
+    constructor(message: string, name?: string);
+}
+export declare function isExposedRpcError(error: unknown): error is ExposedRpcError;
+export declare function serializeRpcError(error: unknown): RpcErrorInfo;
+export {};

package/dist/adapters/contracts/transport/rpc-error.js

@@ -0,0 +1,28 @@
+export const PUBLIC_RPC_ERROR_MESSAGE = 'An internal server error occurred';
+export class RpcPublicError extends Error {
+    expose = true;
+    constructor(message, name) {
+        super(message);
+        if (name) {
+            this.name = name;
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export function isExposedRpcError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'message' in error &&
+        typeof error.message === 'string' &&
+        'expose' in error &&
+        error.expose === true);
+}
+export function serializeRpcError(error) {
+    if (isExposedRpcError(error)) {
+        return {
+            message: error.message,
+            name: 'name' in error && typeof error.name === 'string' ? error.name : undefined,
+        };
+    }
+    return { message: PUBLIC_RPC_ERROR_MESSAGE };
+}

package/dist/adapters/node/transport/node.events.d.ts

@@ -3,12 +3,14 @@ import { RuntimeContext } from '../../contracts/transport/context';
 type NodeTarget = number | number[] | 'all';
 export declare class NodeEvents extends EventsAPI<RuntimeContext> {
     private readonly emitter;
+    private readonly asyncHandlers;
     on<TArgs extends readonly unknown[]>(event: string, handler: (ctx: {
         clientId?: number;
         raw?: unknown;
     }, ...args: TArgs) => unknown): void;
     emit(event: string, targetOrArg?: NodeTarget | unknown, ...args: unknown[]): void;
     simulateClientEvent(event: string, clientId: number, ...args: unknown[]): void;
+    simulateClientEventAsync(event: string, clientId: number, ...args: unknown[]): Promise<void>;
     clearHandlers(): void;
 }
 export {};

package/dist/adapters/node/transport/node.events.js

@@ -3,7 +3,14 @@ import { EventsAPI } from '../../contracts/transport/events.api';
 import { loggers } from '../../../kernel/logger';
 export class NodeEvents extends EventsAPI {
     emitter = new EventEmitter();
+    asyncHandlers = new Map();
     on(event, handler) {
+        let handlers = this.asyncHandlers.get(event);
+        if (!handlers) {
+            handlers = new Set();
+            this.asyncHandlers.set(event, handlers);
+        }
+        handlers.add(handler);
         this.emitter.on(event, (ctx, ...args) => {
             void Promise.resolve(handler(ctx, ...args)).catch((err) => {
                 loggers.netEvent.error(`handler error for '${event}'`, {}, err);
@@ -32,7 +39,16 @@ export class NodeEvents extends EventsAPI {
     simulateClientEvent(event, clientId, ...args) {
         this.emitter.emit(event, { clientId, raw: clientId }, ...args);
     }
+    async simulateClientEventAsync(event, clientId, ...args) {
+        const handlers = this.asyncHandlers.get(event);
+        if (!handlers || handlers.size === 0) {
+            return;
+        }
+        const ctx = { clientId, raw: clientId };
+        await Promise.allSettled(Array.from(handlers, (handler) => Promise.resolve(handler(ctx, ...args))));
+    }
     clearHandlers() {
         this.emitter.removeAllListeners();
+        this.asyncHandlers.clear();
     }
 }

package/dist/runtime/server/bootstrap.js

@@ -10,6 +10,7 @@ import { getServerBinaryServiceRegistry } from './decorators/binaryService';
 import { getServerControllerRegistry } from './decorators/controller';
 import { getFrameworkModeScope, setRuntimeContext, validateRuntimeOptions, } from './runtime';
 import { BinaryProcessManager } from './system/managers/binary-process.manager';
+import { PlayerPersistenceService } from './services/persistence.service';
 import { SessionRecoveryService } from './services/session-recovery.local';
 import { registerServicesServer } from './services/services.register';
 import { SYSTEM_EVENTS } from '../shared/types/system-types';
@@ -131,6 +132,9 @@ export async function initServer(options, plugins) {
     registerSystemServer(ctx);
     loggers.bootstrap.debug('System processors registered');
     checkProviders(ctx);
+    if (ctx.features.sessionLifecycle.enabled && ctx.mode !== 'RESOURCE') {
+        GLOBAL_CONTAINER.resolve(PlayerPersistenceService).initialize();
+    }
     const scanner = GLOBAL_CONTAINER.resolve(MetadataScanner);
     scanner.scan(getServerControllerRegistry());
     const binaryServices = getServerBinaryServiceRegistry();

package/dist/runtime/server/implementations/local/player.local.d.ts

@@ -24,13 +24,13 @@ export declare class LocalPlayerImplementation implements Players, PlayerSession
     private readonly world;
     private readonly playerInfo;
     private readonly playerServer;
-    private readonly playerLifecycle;
-    private readonly playerStateSync;
-    private readonly entityServer;
-    private readonly events;
-    private readonly platformContext;
+    private readonly playerLifecycle?;
+    private readonly playerStateSync?;
+    private readonly entityServer?;
+    private readonly events?;
+    private readonly platformContext?;
     private readonly playerAdapters;
-    constructor(world: WorldContext, playerInfo: IPlayerInfo, playerServer: IPlayerServer, playerLifecycle: IPlayerLifecycleServer, playerStateSync: IPlayerStateSyncServer, entityServer: IEntityServer, events: EventsAPI<'server'>, platformContext: IPlatformContext);
+    constructor(world: WorldContext, playerInfo: IPlayerInfo, playerServer: IPlayerServer, playerLifecycle?: IPlayerLifecycleServer | undefined, playerStateSync?: IPlayerStateSyncServer | undefined, entityServer?: IEntityServer | undefined, events?: EventsAPI<"server"> | undefined, platformContext?: IPlatformContext | undefined);
     private isPlayer;
     /**
      * Initializes a new player session for a connecting client.

package/dist/runtime/server/implementations/local/player.local.js

@@ -21,6 +21,37 @@ import { IPlayerServer } from '../../../../adapters/contracts/server/IPlayerServ
 import { loggers } from '../../../../kernel/logger';
 import { WorldContext } from '../../../core/world';
 import { createLocalServerPlayer } from '../../adapter/registry';
+class NoopPlayerLifecycleServer extends IPlayerLifecycleServer {
+    spawn() { }
+    teleport() { }
+    respawn() { }
+}
+class NoopPlayerStateSyncServer extends IPlayerStateSyncServer {
+    getHealth() {
+        return 200;
+    }
+    setHealth() { }
+    getArmor() {
+        return 0;
+    }
+    setArmor() { }
+}
+const DEFAULT_PLATFORM_CONTEXT = {
+    platformName: 'node',
+    displayName: 'Node.js',
+    identifierTypes: ['license'],
+    maxPlayers: undefined,
+    gameProfile: 'common',
+    defaultSpawnModel: 'mp_m_freemode_01',
+    defaultVehicleType: 'automobile',
+    enableServerVehicleCreation: true,
+};
+function isEntityServer(value) {
+    return (!!value && typeof value === 'object' && typeof value.getCoords === 'function');
+}
+function isEventsAPI(value) {
+    return (!!value && typeof value === 'object' && typeof value.on === 'function');
+}
 /**
  * Service responsible for managing the lifecycle of player sessions.
  * It acts as the central registry for all connected players, mapping FiveM client IDs
@@ -49,14 +80,54 @@ let LocalPlayerImplementation = class LocalPlayerImplementation {
         this.entityServer = entityServer;
         this.events = events;
         this.platformContext = platformContext;
-        const defaultSpawnModel = this.platformContext.defaultSpawnModel;
+        let resolvedPlayerLifecycle = this.playerLifecycle;
+        let resolvedPlayerStateSync = this.playerStateSync;
+        let resolvedEntityServer = this.entityServer;
+        let resolvedEvents = this.events;
+        // Backward compatibility for tests/benchmarks still using the old 5-arg constructor.
+        if (!resolvedEntityServer &&
+            isEntityServer(resolvedPlayerLifecycle) &&
+            isEventsAPI(resolvedPlayerStateSync)) {
+            resolvedEntityServer = resolvedPlayerLifecycle;
+            resolvedEvents = resolvedPlayerStateSync;
+            resolvedPlayerLifecycle = new NoopPlayerLifecycleServer();
+            resolvedPlayerStateSync = new NoopPlayerStateSyncServer();
+        }
+        resolvedPlayerLifecycle ??= new NoopPlayerLifecycleServer();
+        resolvedPlayerStateSync ??= new NoopPlayerStateSyncServer();
+        resolvedEntityServer ??= {
+            doesExist: () => true,
+            getCoords: () => ({ x: 0, y: 0, z: 0 }),
+            setCoords: () => { },
+            setPosition: () => { },
+            getHeading: () => 0,
+            setHeading: () => { },
+            getModel: () => 0,
+            delete: () => { },
+            setOrphanMode: () => { },
+            setDimension: () => { },
+            getDimension: () => 0,
+            getStateBag: () => ({
+                set: () => undefined,
+                get: () => undefined,
+            }),
+            getHealth: () => 200,
+            setHealth: () => { },
+            getArmor: () => 0,
+            setArmor: () => { },
+        };
+        resolvedEvents ??= {
+            on: () => { },
+            emit: () => { },
+        };
+        const defaultSpawnModel = (this.platformContext ?? DEFAULT_PLATFORM_CONTEXT).defaultSpawnModel;
         this.playerAdapters = {
             playerInfo: this.playerInfo,
             playerServer: this.playerServer,
-            playerLifecycle: this.playerLifecycle,
-            playerStateSync: this.playerStateSync,
-            entityServer: this.entityServer,
-            events: this.events,
+            playerLifecycle: resolvedPlayerLifecycle,
+            playerStateSync: resolvedPlayerStateSync,
+            entityServer: resolvedEntityServer,
+            events: resolvedEvents,
             defaultSpawnModel,
         };
     }

package/dist/runtime/server/system/processors/onRpc.processor.js

@@ -124,10 +124,21 @@ let OnRpcProcessor = class OnRpcProcessor {
                 });
                 throw error;
             }
-            if (hasNoDeclaredParams) {
-                return handler();
+            try {
+                if (hasNoDeclaredParams) {
+                    return await handler();
+                }
+                return await handler(player, ...validatedArgs);
+            }
+            catch (error) {
+                loggers.netEvent.error(`Handler error in RPC`, {
+                    event: metadata.eventName,
+                    handler: handlerName,
+                    playerId: player.clientID,
+                    accountId: player.accountID,
+                }, error);
+                throw error;
             }
-            return handler(player, ...validatedArgs);
         });
         loggers.netEvent.debug(`Registered RPC: ${metadata.eventName} -> ${handlerName}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Secure, event-driven TypeScript Framework & Runtime engine for CitizenFX (Cfx).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,9 +72,14 @@
     "test:unit": "npx vitest run --project unit",
     "test:integration": "npx vitest run --project integration",
     "test:coverage": "npx vitest run --coverage",
-    "bench": "npx tsx benchmark/index.ts",
-    "bench:core": "npx tsx benchmark/index.ts --core",
-    "bench:load": "npx vitest run --project benchmark",
+    "bench": "npx tsx benchmark/index.ts --value",
+    "bench:value": "npx tsx benchmark/index.ts --value",
+    "bench:gold": "BENCHMARK_SUITE=gold npx vitest run --project benchmark-gold",
+    "bench:startup": "npx tsx benchmark/index.ts --startup",
+    "bench:diagnostic": "npx tsx benchmark/index.ts --diagnostic",
+    "bench:soak": "BENCHMARK_SUITE=soak npx vitest run --project benchmark-soak",
+    "bench:core": "npx tsx benchmark/index.ts --diagnostic",
+    "bench:load": "npx vitest run --project benchmark-gold --project benchmark-startup",
     "bench:all": "npx tsx benchmark/index.ts --all",
     "validate": "pnpm check && pnpm typecheck && pnpm test",
     "lint-staged": "lint-staged",