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

package/dist/runtime/server/types/vehicle.types.d.ts

@@ -0,0 +1,152 @@
+import { Vector3 } from '../../../';
+/**
+ * Vehicle ownership information
+ */
+export interface VehicleOwnership {
+    /** Client ID of the owner (if player-owned) */
+    clientID?: number;
+    /** Account ID of the owner (if persistent) */
+    accountID?: string;
+    /** Type of ownership */
+    type: 'player' | 'server' | 'temporary' | 'shared';
+}
+/**
+ * Vehicle modification data structure
+ */
+export interface VehicleMods {
+    spoiler?: number;
+    frontBumper?: number;
+    rearBumper?: number;
+    sideSkirt?: number;
+    exhaust?: number;
+    frame?: number;
+    grille?: number;
+    hood?: number;
+    fender?: number;
+    rightFender?: number;
+    roof?: number;
+    engine?: number;
+    brakes?: number;
+    transmission?: number;
+    horns?: number;
+    suspension?: number;
+    armor?: number;
+    turbo?: boolean;
+    xenon?: boolean;
+    xenonColor?: number;
+    wheelType?: number;
+    wheels?: number;
+    windowTint?: number;
+    livery?: number;
+    plateStyle?: number;
+    primaryColor?: number;
+    secondaryColor?: number;
+    pearlescentColor?: number;
+    wheelColor?: number;
+    neonEnabled?: [boolean, boolean, boolean, boolean];
+    neonColor?: [number, number, number];
+    extras?: Record<number, boolean>;
+}
+/**
+ * Options for creating a new vehicle
+ */
+export interface VehicleCreateOptions {
+    /** Vehicle model name or hash */
+    model: string;
+    /** Spawn position */
+    position: Vector3;
+    /** Heading/rotation in degrees */
+    heading?: number;
+    /** License plate text */
+    plate?: string;
+    /** Primary color */
+    primaryColor?: number;
+    /** Secondary color */
+    secondaryColor?: number;
+    /** Initial modifications */
+    mods?: Partial<VehicleMods>;
+    /** Whether vehicle should be persistent (survives server restart if saved) */
+    persistent?: boolean;
+    /** Ownership information */
+    ownership?: Partial<VehicleOwnership>;
+    /** Custom metadata */
+    metadata?: Record<string, any>;
+    /** Routing bucket (default: 0) */
+    routingBucket?: number;
+    /** Whether to lock the vehicle */
+    locked?: boolean;
+    /** Fuel level (0.0-1.0) */
+    fuel?: number;
+}
+/**
+ * Options for modifying an existing vehicle
+ */
+export interface VehicleModificationOptions {
+    /** Network ID of the vehicle to modify */
+    networkId: number;
+    /** Modifications to apply */
+    mods: Partial<VehicleMods>;
+    /** Client ID requesting the modification (for validation) */
+    requestedBy?: number;
+}
+/**
+ * Vehicle metadata stored in state bags
+ */
+export interface VehicleMetadata {
+    /** Custom key-value pairs */
+    [key: string]: any;
+    /** Fuel level */
+    fuel?: number;
+    /** Engine health */
+    engineHealth?: number;
+    /** Body health */
+    bodyHealth?: number;
+    /** Last driver client ID */
+    lastDriver?: number;
+    /** Creation timestamp */
+    createdAt?: number;
+    /** Last modification timestamp */
+    modifiedAt?: number;
+}
+/**
+ * Serialized vehicle data for network transfer
+ */
+export interface SerializedVehicleData {
+    /** Network ID */
+    networkId: number;
+    /** Entity handle (server-side) */
+    handle: number;
+    /** Vehicle model hash */
+    modelHash: number;
+    /** Vehicle model */
+    model: string;
+    /** Current position */
+    position: Vector3;
+    /** Current heading */
+    heading: number;
+    /** License plate */
+    plate: string;
+    /** Ownership information */
+    ownership: VehicleOwnership;
+    /** Applied modifications */
+    mods: VehicleMods;
+    /** Custom metadata */
+    metadata: VehicleMetadata;
+    /** Routing bucket */
+    routingBucket: number;
+    /** Whether vehicle is persistent */
+    persistent: boolean;
+}
+/**
+ * Vehicle spawn result
+ */
+export interface VehicleSpawnResult {
+    /** Network ID of the spawned vehicle */
+    networkId: number;
+    /** Entity handle */
+    handle: number;
+    /** Success status */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@open-core/framework",
-  "version": "1.0.2-beta.1",
-  "description": "Secure, Event-Driven, OOP Engine for FiveM. Stop scripting, start engineering.",
+  "version": "1.0.5-beta.1",
+  "description": "Secure, event-driven TypeScript Framework & Runtime engine for CitizenFX (Cfx).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
   "repository": {
     "type": "git",
-    "url": "https://github.com/newcore-network/opencore.git"
+    "url": "git+https://github.com/newcore-network/opencore.git"
   },
-  "homepage": "https://github.com/newcore-network/opencore",
+  "homepage": "https://opencorejs.dev",
   "bugs": {
     "url": "https://github.com/newcore-network/opencore/issues"
   },
@@ -25,64 +25,71 @@
       "require": "./dist/index.js"
     },
     "./server": {
-      "types": "./dist/server/index.d.ts",
-      "import": "./dist/server/index.js",
-      "require": "./dist/server/index.js"
+      "types": "./dist/runtime/server/index.d.ts",
+      "import": "./dist/runtime/server/index.js",
+      "require": "./dist/runtime/server/index.js"
     },
     "./client": {
-      "types": "./dist/client/index.d.ts",
-      "import": "./dist/client/index.js",
-      "require": "./dist/client/index.js"
+      "types": "./dist/runtime/client/index.d.ts",
+      "import": "./dist/runtime/client/index.js",
+      "require": "./dist/runtime/client/index.js"
     },
     "./package.json": "./package.json"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "watch": "tsc -p tsconfig.build.json --watch",
-    "lint": "eslint . --ext .ts",
-    "lint:fix": "eslint . --ext .ts --fix",
-    "format": "prettier --write .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:coverage": "vitest run --coverage",
-    "bench": "tsx benchmark/index.ts",
-    "bench:core": "tsx benchmark/index.ts --core",
-    "bench:load": "vitest run --project benchmark",
-    "bench:all": "tsx benchmark/index.ts --all"
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "check:fix:unsafe": "biome check --write --unsafe",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "npx vitest run --project unit --project integration",
+    "test:ci": "npx vitest run --project unit --project integration",
+    "test:watch": "npx vitest --project unit --project integration",
+    "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:all": "npx tsx benchmark/index.ts --all"
   },
   "keywords": [
     "framework",
     "opencore",
-    "fivem",
+    "cfx",
+    "citizenfx",
+    "redm",
     "typescript",
     "roleplay"
   ],
   "author": "OpenCore Team",
   "license": "MPL-2.0",
   "packageManager": "pnpm@10.13.1",
-  "dependencies": {
+  "peerDependencies": {
     "reflect-metadata": "^0.2.2",
     "tsyringe": "^4.10.0",
-    "uuid": "^13.0.0",
-    "zod": "^4.1.13"
+    "zod": "^4.3.5"
+  },
+  "dependencies": {
+    "uuid": "^13.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
     "@citizenfx/client": "2.0.22443-1",
     "@citizenfx/server": "2.0.22443-1",
-    "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
-    "@vitest/coverage-v8": "^4.0.15",
-    "eslint": "^9.39.1",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "dependency-cruiser": "^17.3.6",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "prettier": "3.7.1",
-    "tinybench": "^2.7.0",
-    "tsx": "^4.19.2",
+    "graphviz": "^0.0.9",
+    "tinybench": "^2.9.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.16"
   }
 }

package/dist/client/client-bootstrap.d.ts

@@ -1 +0,0 @@
-export declare function initClientCore(): Promise<void>;

package/dist/client/client-bootstrap.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.initClientCore = initClientCore;
-const metadata_scanner_1 = require("../system/metadata.scanner");
-const client_container_1 = require("./client-container");
-const decorators_1 = require("./decorators");
-const player_loader_1 = require("./player/player.loader");
-const processors_register_1 = require("./system/processors.register");
-const ui_bridge_1 = require("./ui-bridge");
-// Services
-const core_1 = require("./services/core");
-const ui_1 = require("./services/ui");
-const world_1 = require("./services/world");
-const streaming_1 = require("./services/streaming");
-const bootServices = [core_1.Spawner];
-/**
- * Basic setup for client, for configs, decorators, containers... etc
- */
-function setSingletons() {
-    // Core services
-    client_container_1.di.registerSingleton(core_1.Spawner, core_1.Spawner);
-    // NUI
-    client_container_1.di.registerSingleton(ui_bridge_1.NuiBridge, ui_bridge_1.NuiBridge);
-    // UI services
-    client_container_1.di.registerSingleton(ui_1.NotificationService, ui_1.NotificationService);
-    client_container_1.di.registerSingleton(ui_1.TextUIService, ui_1.TextUIService);
-    client_container_1.di.registerSingleton(ui_1.ProgressService, ui_1.ProgressService);
-    // World services
-    client_container_1.di.registerSingleton(world_1.MarkerService, world_1.MarkerService);
-    client_container_1.di.registerSingleton(world_1.BlipService, world_1.BlipService);
-    client_container_1.di.registerSingleton(world_1.VehicleService, world_1.VehicleService);
-    client_container_1.di.registerSingleton(world_1.PedService, world_1.PedService);
-    // Streaming services
-    client_container_1.di.registerSingleton(streaming_1.StreamingService, streaming_1.StreamingService);
-}
-async function bootstraper() {
-    for (const Service of bootServices) {
-        const instance = client_container_1.di.resolve(Service);
-        if (typeof instance.init === 'function') {
-            await instance.init();
-        }
-    }
-}
-async function initClientCore() {
-    setSingletons();
-    // Register system processors
-    (0, processors_register_1.registerSystemClient)();
-    await bootstraper();
-    // Loaders
-    (0, player_loader_1.playerClientLoader)();
-    const scanner = client_container_1.di.resolve(metadata_scanner_1.MetadataScanner);
-    scanner.scan(decorators_1.clientControllerRegistry);
-}

package/dist/client/client-container.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.di = void 0;
-require("reflect-metadata");
-const tsyringe_1 = require("tsyringe");
-exports.di = tsyringe_1.container;

package/dist/client/client-core.d.ts

@@ -1,18 +0,0 @@
-import { NuiBridge } from './ui-bridge';
-import { Spawner } from './services/core';
-import { NotificationService, TextUIService, ProgressService } from './services/ui';
-import { MarkerService, BlipService, VehicleService, PedService } from './services/world';
-import { StreamingService } from './services/streaming';
-export declare function init(): Promise<void>;
-export declare const services: {
-    readonly spawner: Spawner;
-    readonly nui: NuiBridge<Record<string, any>, Record<string, any>>;
-    readonly notifications: NotificationService;
-    readonly textUI: TextUIService;
-    readonly progress: ProgressService;
-    readonly markers: MarkerService;
-    readonly blips: BlipService;
-    readonly vehicles: VehicleService;
-    readonly peds: PedService;
-    readonly streaming: StreamingService;
-};

package/dist/client/client-core.js

@@ -1,52 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.services = void 0;
-exports.init = init;
-const client_bootstrap_1 = require("./client-bootstrap");
-const client_container_1 = require("./client-container");
-const ui_bridge_1 = require("./ui-bridge");
-// Services
-const core_1 = require("./services/core");
-const ui_1 = require("./services/ui");
-const world_1 = require("./services/world");
-const streaming_1 = require("./services/streaming");
-async function init() {
-    await (0, client_bootstrap_1.initClientCore)();
-}
-exports.services = {
-    // Core
-    get spawner() {
-        return client_container_1.di.resolve(core_1.Spawner);
-    },
-    // NUI
-    get nui() {
-        return client_container_1.di.resolve(ui_bridge_1.NuiBridge);
-    },
-    // UI
-    get notifications() {
-        return client_container_1.di.resolve(ui_1.NotificationService);
-    },
-    get textUI() {
-        return client_container_1.di.resolve(ui_1.TextUIService);
-    },
-    get progress() {
-        return client_container_1.di.resolve(ui_1.ProgressService);
-    },
-    // World
-    get markers() {
-        return client_container_1.di.resolve(world_1.MarkerService);
-    },
-    get blips() {
-        return client_container_1.di.resolve(world_1.BlipService);
-    },
-    get vehicles() {
-        return client_container_1.di.resolve(world_1.VehicleService);
-    },
-    get peds() {
-        return client_container_1.di.resolve(world_1.PedService);
-    },
-    // Streaming
-    get streaming() {
-        return client_container_1.di.resolve(streaming_1.StreamingService);
-    },
-};

package/dist/client/decorators/controller.d.ts

@@ -1,3 +0,0 @@
-import type { ClassConstructor } from '../../system/class-constructor';
-export declare const clientControllerRegistry: ClassConstructor[];
-export declare function Controller(): (target: ClassConstructor) => void;

package/dist/client/decorators/controller.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.clientControllerRegistry = void 0;
-exports.Controller = Controller;
-const tsyringe_1 = require("tsyringe");
-const metadata_client_keys_1 = require("../system/metadata-client.keys");
-exports.clientControllerRegistry = [];
-function Controller() {
-    return function (target) {
-        (0, tsyringe_1.injectable)()(target);
-        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.CONTROLLER, { type: 'client' }, target);
-        exports.clientControllerRegistry.push(target);
-    };
-}

package/dist/client/decorators/export.d.ts

@@ -1,7 +0,0 @@
-/**
- * Decorator to expose a method as a client export.
- * Other resources can call this via exports['resourceName']['exportName']()
- *
- * @param name - Optional custom export name. Defaults to method name.
- */
-export declare function Export(name?: string): (target: any, propertyKey: string) => void;

package/dist/client/decorators/export.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Export = Export;
-const metadata_client_keys_1 = require("../system/metadata-client.keys");
-/**
- * Decorator to expose a method as a client export.
- * Other resources can call this via exports['resourceName']['exportName']()
- *
- * @param name - Optional custom export name. Defaults to method name.
- */
-function Export(name) {
-    return (target, propertyKey) => {
-        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.EXPORT, { exportName: name || propertyKey }, target, propertyKey);
-    };
-}

package/dist/client/decorators/gameEvent.d.ts

@@ -1,47 +0,0 @@
-import type { GameEventName, GameEventMap } from '../types/game-events';
-/**
- * Decorator for handling native game events from the RAGE engine.
- *
- * These are low-level events triggered internally by GTA V.
- * FiveM captures them via the 'gameEventTriggered' event.
- *
- * **Documentation:** https://docs.fivem.net/docs/game-references/game-events/
- *
- * ## Common Events:
- *
- * | Event | Description |
- * |-------|-------------|
- * | `CEventNetworkEntityDamage` | Entity receives damage |
- * | `CEventNetworkPlayerEnteredVehicle` | Player enters vehicle |
- * | `CEventNetworkPlayerLeftVehicle` | Player exits vehicle |
- * | `CEventNetworkVehicleUndrivable` | Vehicle destroyed |
- * | `CEventShockingSeenPedKilled` | Ped witnesses death |
- * | `CEventGunShot` | Weapon fired |
- *
- * ## Usage:
- *
- * ```typescript
- * @Controller()
- * class CombatController {
- *   // Raw args (array)
- *   @OnGameEvent('CEventNetworkEntityDamage')
- *   onDamage(args: number[]) {
- *     const [victim, attacker] = args
- *   }
- *
- *   // Or with auto-parsing (set autoParse: true)
- *   @OnGameEvent('CEventNetworkEntityDamage', { autoParse: true })
- *   onDamageParsed(data: EntityDamageEvent) {
- *     console.log(data.victim, data.attacker, data.victimDied)
- *   }
- * }
- * ```
- *
- * @param eventName - The native game event name (CEvent*)
- * @param options - Optional configuration
- */
-export declare function OnGameEvent<K extends GameEventName>(eventName: K, options?: {
-    autoParse?: boolean;
-}): (target: any, propertyKey: string) => void;
-export type { GameEventName, GameEventMap };
-export type { EntityDamageEvent, PlayerEnteredVehicleEvent, PlayerLeftVehicleEvent, SeenPedKilledEvent, VehicleUndrivableEvent, GunShotEvent, } from '../types/game-events';

package/dist/client/decorators/gameEvent.js

@@ -1,54 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OnGameEvent = OnGameEvent;
-const metadata_client_keys_1 = require("../system/metadata-client.keys");
-/**
- * Decorator for handling native game events from the RAGE engine.
- *
- * These are low-level events triggered internally by GTA V.
- * FiveM captures them via the 'gameEventTriggered' event.
- *
- * **Documentation:** https://docs.fivem.net/docs/game-references/game-events/
- *
- * ## Common Events:
- *
- * | Event | Description |
- * |-------|-------------|
- * | `CEventNetworkEntityDamage` | Entity receives damage |
- * | `CEventNetworkPlayerEnteredVehicle` | Player enters vehicle |
- * | `CEventNetworkPlayerLeftVehicle` | Player exits vehicle |
- * | `CEventNetworkVehicleUndrivable` | Vehicle destroyed |
- * | `CEventShockingSeenPedKilled` | Ped witnesses death |
- * | `CEventGunShot` | Weapon fired |
- *
- * ## Usage:
- *
- * ```typescript
- * @Controller()
- * class CombatController {
- *   // Raw args (array)
- *   @OnGameEvent('CEventNetworkEntityDamage')
- *   onDamage(args: number[]) {
- *     const [victim, attacker] = args
- *   }
- *
- *   // Or with auto-parsing (set autoParse: true)
- *   @OnGameEvent('CEventNetworkEntityDamage', { autoParse: true })
- *   onDamageParsed(data: EntityDamageEvent) {
- *     console.log(data.victim, data.attacker, data.victimDied)
- *   }
- * }
- * ```
- *
- * @param eventName - The native game event name (CEvent*)
- * @param options - Optional configuration
- */
-function OnGameEvent(eventName, options) {
-    return (target, propertyKey) => {
-        var _a;
-        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.GAME_EVENT, {
-            eventName,
-            autoParse: (_a = options === null || options === void 0 ? void 0 : options.autoParse) !== null && _a !== void 0 ? _a : false,
-        }, target, propertyKey);
-    };
-}

package/dist/client/decorators/index.d.ts

@@ -1,10 +0,0 @@
-export * from './controller';
-export * from './key';
-export * from './nui';
-export * from './onNet';
-export * from './tick';
-export * from './localEvent';
-export * from './interval';
-export * from './export';
-export * from './resourceLifecycle';
-export * from './gameEvent';

package/dist/client/decorators/index.js

@@ -1,26 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./controller"), exports);
-__exportStar(require("./key"), exports);
-__exportStar(require("./nui"), exports);
-__exportStar(require("./onNet"), exports);
-__exportStar(require("./tick"), exports);
-__exportStar(require("./localEvent"), exports);
-__exportStar(require("./interval"), exports);
-__exportStar(require("./export"), exports);
-__exportStar(require("./resourceLifecycle"), exports);
-__exportStar(require("./gameEvent"), exports);

package/dist/client/decorators/interval.d.ts

@@ -1,7 +0,0 @@
-/**
- * Decorator for creating interval-based ticks.
- * Unlike @Tick which runs every frame, @Interval runs at specified intervals.
- *
- * @param ms - Interval in milliseconds between executions
- */
-export declare function Interval(ms: number): (target: any, propertyKey: string) => void;

package/dist/client/decorators/interval.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Interval = Interval;
-const metadata_client_keys_1 = require("../system/metadata-client.keys");
-/**
- * Decorator for creating interval-based ticks.
- * Unlike @Tick which runs every frame, @Interval runs at specified intervals.
- *
- * @param ms - Interval in milliseconds between executions
- */
-function Interval(ms) {
-    return (target, propertyKey) => {
-        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.INTERVAL, { interval: ms }, target, propertyKey);
-    };
-}

package/dist/client/decorators/key.d.ts

@@ -1,2 +0,0 @@
-import 'reflect-metadata';
-export declare function KeyMapping(key: string, description: string): (target: any, propertyKey: string) => void;

package/dist/client/decorators/key.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyMapping = KeyMapping;
-require("reflect-metadata");
-const metadata_client_keys_1 = require("../system/metadata-client.keys");
-function KeyMapping(key, description) {
-    return (target, propertyKey) => {
-        Reflect.defineMetadata(metadata_client_keys_1.METADATA_KEYS.KEY, { key, description }, target, propertyKey);
-    };
-}

package/dist/client/decorators/localEvent.d.ts

@@ -1,7 +0,0 @@
-/**
- * Decorator for handling local events (non-networked).
- * Use this for client-side only events.
- *
- * @param eventName - The name of the local event to listen for
- */
-export declare function OnLocalEvent(eventName: string): (target: any, propertyKey: string) => void;