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

package/dist/adapters/contracts/client/vehicle/IClientVehiclePort.d.ts

@@ -0,0 +1,166 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+/**
+ * High-level vehicle creation options understood by client adapters.
+ */
+export interface ClientVehicleSpawnOptions {
+    model: string;
+    position: Vector3;
+    heading?: number;
+    placeOnGround?: boolean;
+    warpIntoVehicle?: boolean;
+    seatIndex?: number;
+    primaryColor?: number;
+    secondaryColor?: number;
+    plate?: string;
+    networked?: boolean;
+}
+/**
+ * Common vehicle modification payload used by the framework.
+ */
+export interface ClientVehicleMods {
+    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;
+    wheelType?: number;
+    wheels?: number;
+    windowTint?: number;
+    livery?: number;
+    plateStyle?: number;
+    neonEnabled?: [boolean, boolean, boolean, boolean];
+    neonColor?: [number, number, number];
+    extras?: Record<string, boolean>;
+    pearlescentColor?: number;
+    wheelColor?: number;
+}
+/**
+ * Intent-oriented client vehicle port.
+ *
+ * The framework requests vehicle operations through this port and the adapter
+ * decides how to fulfill them for the active runtime.
+ */
+export declare abstract class IClientVehiclePort {
+    /**
+     * Spawns a vehicle and returns its runtime handle.
+     */
+    abstract spawn(options: ClientVehicleSpawnOptions): Promise<number>;
+    /**
+     * Deletes an existing vehicle handle.
+     */
+    abstract delete(vehicle: number): void;
+    /**
+     * Repairs a vehicle and restores it to a drivable state.
+     */
+    abstract repair(vehicle: number): void;
+    /**
+     * Sets normalized fuel in the 0..1 range unless the adapter documents otherwise.
+     */
+    abstract setFuel(vehicle: number, level: number): void;
+    /**
+     * Gets normalized fuel in the 0..1 range unless the adapter documents otherwise.
+     */
+    abstract getFuel(vehicle: number): number;
+    /**
+     * Returns the closest vehicle around the local player.
+     */
+    abstract getClosest(radius?: number): number | null;
+    /**
+     * Returns whether the local player is currently inside any vehicle.
+     */
+    abstract isLocalPlayerInVehicle(): boolean;
+    /**
+     * Returns the vehicle currently occupied by the local player.
+     */
+    abstract getCurrentForLocalPlayer(): number | null;
+    /**
+     * Returns the last vehicle used by the local player.
+     */
+    abstract getLastForLocalPlayer(): number | null;
+    /**
+     * Returns whether the local player is driving the provided vehicle.
+     */
+    abstract isLocalPlayerDriver(vehicle: number): boolean;
+    /**
+     * Warps the local player into a seat.
+     */
+    abstract warpLocalPlayerInto(vehicle: number, seatIndex?: number): void;
+    /**
+     * Makes the local player leave the provided vehicle.
+     */
+    abstract leaveLocalPlayerVehicle(vehicle: number, flags?: number): void;
+    /**
+     * Applies visual/performance modifications to a vehicle.
+     */
+    abstract applyMods(vehicle: number, mods: ClientVehicleMods): void;
+    /**
+     * Updates door lock state.
+     */
+    abstract setDoorsLocked(vehicle: number, locked: boolean): void;
+    /**
+     * Starts or stops the engine.
+     */
+    abstract setEngineRunning(vehicle: number, running: boolean, instant?: boolean): void;
+    /**
+     * Sets invincibility state for the vehicle entity.
+     */
+    abstract setInvincible(vehicle: number, invincible: boolean): void;
+    /**
+     * Returns speed in meters per second.
+     */
+    abstract getSpeed(vehicle: number): number;
+    /**
+     * Sets heading for a vehicle.
+     */
+    abstract setHeading(vehicle: number, heading: number): void;
+    /**
+     * Teleports a vehicle to a world position.
+     */
+    abstract teleport(vehicle: number, position: Vector3, heading?: number): void;
+    /**
+     * Returns whether a vehicle handle exists.
+     */
+    abstract exists(vehicle: number): boolean;
+    /**
+     * Resolves the runtime network identifier for a vehicle.
+     */
+    abstract getNetworkId(vehicle: number): number;
+    /**
+     * Resolves a vehicle handle from a runtime network identifier.
+     */
+    abstract getFromNetworkId(networkId: number): number;
+    /**
+     * Reads a runtime state bag/state entry from a vehicle.
+     */
+    abstract getState<T = unknown>(vehicle: number, key: string): T | undefined;
+    /**
+     * Returns the world position of a vehicle.
+     */
+    abstract getPosition(vehicle: number): Vector3 | null;
+    /**
+     * Returns the heading of a vehicle.
+     */
+    abstract getHeading(vehicle: number): number;
+    /**
+     * Returns the model hash of a vehicle.
+     */
+    abstract getModel(vehicle: number): number;
+    /**
+     * Returns the current number plate text.
+     */
+    abstract getPlate(vehicle: number): string;
+}

package/dist/adapters/contracts/client/vehicle/IClientVehiclePort.js

@@ -0,0 +1,8 @@
+/**
+ * Intent-oriented client vehicle port.
+ *
+ * The framework requests vehicle operations through this port and the adapter
+ * decides how to fulfill them for the active runtime.
+ */
+export class IClientVehiclePort {
+}

package/dist/adapters/contracts/client/vehicle/index.d.ts

@@ -0,0 +1 @@
+export * from './IClientVehiclePort';

package/dist/adapters/contracts/client/vehicle/index.js

@@ -0,0 +1 @@
+export * from './IClientVehiclePort';

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

@@ -1,2 +1,4 @@
-export * from './transport/events.api';
-export * from './transport/rpc.api';
+export * from './IHasher';
+export * from './types';
+export * from './transport';
+export * from './runtime';

package/dist/adapters/contracts/index.js

@@ -1,3 +1,4 @@
-// Transport API
-export * from './transport/events.api';
-export * from './transport/rpc.api';
+export * from './IHasher';
+export * from './types';
+export * from './transport';
+export * from './runtime';

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

@@ -0,0 +1 @@
+export * from './runtime-events';

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

@@ -0,0 +1 @@
+export * from './runtime-events';

package/dist/adapters/contracts/runtime/runtime-events.d.ts

@@ -0,0 +1,9 @@
+export declare const RUNTIME_EVENTS: {
+    readonly playerJoining: "playerJoining";
+    readonly playerDropped: "playerDropped";
+    readonly serverResourceStop: "onServerResourceStop";
+    readonly playerCommand: "playerCommand";
+};
+export type RuntimeEventName = (typeof RUNTIME_EVENTS)[keyof typeof RUNTIME_EVENTS];
+export type RuntimeEventMap = Record<RuntimeEventName, string>;
+export declare const DEFAULT_RUNTIME_EVENT_MAP: RuntimeEventMap;

package/dist/adapters/contracts/runtime/runtime-events.js

@@ -0,0 +1,7 @@
+export const RUNTIME_EVENTS = {
+    playerJoining: 'playerJoining',
+    playerDropped: 'playerDropped',
+    serverResourceStop: 'onServerResourceStop',
+    playerCommand: 'playerCommand',
+};
+export const DEFAULT_RUNTIME_EVENT_MAP = Object.fromEntries(Object.values(RUNTIME_EVENTS).map((e) => [e, e]));

package/dist/adapters/contracts/server/IEntityServer.d.ts

@@ -98,25 +98,23 @@ export declare abstract class IEntityServer {
      * Sets entity routing bucket (virtual world/dimension).
      *
      * @remarks
-     * Not all platforms support routing buckets.
-     * Use IPlatformCapabilities.supportsRoutingBuckets to check support.
+     * Platform-specific behavior may vary.
      *
      * @param handle - Entity handle
      * @param bucket - Routing bucket ID
      */
-    abstract setRoutingBucket(handle: number, bucket: number): void;
+    abstract setDimension(handle: number, bucket: number): void;
     /**
      * Gets entity routing bucket (virtual world/dimension).
      * @param handle - Entity handle
      * @returns Routing bucket ID (0 is default world)
      */
-    abstract getRoutingBucket(handle: number): number;
+    abstract getDimension(handle: number): number;
     /**
      * Gets the state bag interface for an entity.
      *
      * @remarks
-     * Not all platforms support state bags.
-     * Use IPlatformCapabilities.supportsStateBags to check support.
+     * Platform-specific behavior may vary.
      *
      * @param handle - Entity handle
      */
@@ -145,28 +143,6 @@ export declare abstract class IEntityServer {
      * @param armor - Armor value
      */
     abstract setArmor(handle: number, armor: number): void;
-    /**
-     * Gets entity dimension (alias for getRoutingBucket).
-     *
-     * @remarks
-     * This is a cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param handle - Entity handle
-     * @returns Dimension ID
-     */
-    getDimension(handle: number): number;
-    /**
-     * Sets entity dimension (alias for setRoutingBucket).
-     *
-     * @remarks
-     * This is a cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param handle - Entity handle
-     * @param dimension - Dimension ID
-     */
-    setDimension(handle: number, dimension: number): void;
 }
 /**
  * State bag interface for entity state synchronization.

package/dist/adapters/contracts/server/IEntityServer.js

@@ -6,30 +6,4 @@
  * Allows the runtime to work without direct platform dependencies.
  */
 export class IEntityServer {
-    /**
-     * Gets entity dimension (alias for getRoutingBucket).
-     *
-     * @remarks
-     * This is a cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param handle - Entity handle
-     * @returns Dimension ID
-     */
-    getDimension(handle) {
-        return this.getRoutingBucket(handle);
-    }
-    /**
-     * Sets entity dimension (alias for setRoutingBucket).
-     *
-     * @remarks
-     * This is a cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param handle - Entity handle
-     * @param dimension - Dimension ID
-     */
-    setDimension(handle, dimension) {
-        this.setRoutingBucket(handle, dimension);
-    }
 }

package/dist/adapters/contracts/server/IPlayerServer.d.ts

@@ -21,6 +21,10 @@ export declare abstract class IPlayerServer {
      * @param reason - Kick reason message
      */
     abstract drop(playerSrc: string, reason: string): void;
+    /**
+     * Sets the active player model when the runtime supports it.
+     */
+    abstract setModel(playerSrc: string, model: string): void;
     /**
      * Gets a player identifier by type.
      *
@@ -68,20 +72,19 @@ export declare abstract class IPlayerServer {
      * Sets player routing bucket (virtual world/dimension).
      *
      * @remarks
-     * Not all platforms support routing buckets.
-     * Use IPlatformCapabilities.supportsRoutingBuckets to check support.
+     * Platform-specific behavior may vary.
      *
      * @param playerSrc - Player source/client ID (as string)
      * @param bucket - Routing bucket ID
      */
-    abstract setRoutingBucket(playerSrc: string, bucket: number): void;
+    abstract setDimension(playerSrc: string, bucket: number): void;
     /**
      * Gets player routing bucket (virtual world/dimension).
      *
      * @param playerSrc - Player source/client ID (as string)
      * @returns Routing bucket ID (0 is default world)
      */
-    abstract getRoutingBucket(playerSrc: string): number;
+    abstract getDimension(playerSrc: string): number;
     /**
      * Gets all currently connected player sources.
      *
@@ -92,26 +95,4 @@ export declare abstract class IPlayerServer {
      * @returns Array of player source strings
      */
     abstract getConnectedPlayers(): string[];
-    /**
-     * Gets player dimension (alias for getRoutingBucket).
-     *
-     * @remarks
-     * Cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param playerSrc - Player source/client ID (as string)
-     * @returns Dimension ID
-     */
-    getDimension(playerSrc: string): number;
-    /**
-     * Sets player dimension (alias for setRoutingBucket).
-     *
-     * @remarks
-     * Cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param playerSrc - Player source/client ID (as string)
-     * @param dimension - Dimension ID
-     */
-    setDimension(playerSrc: string, dimension: number): void;
 }

package/dist/adapters/contracts/server/IPlayerServer.js

@@ -6,30 +6,4 @@
  * Allows the runtime to work without direct platform dependencies.
  */
 export class IPlayerServer {
-    /**
-     * Gets player dimension (alias for getRoutingBucket).
-     *
-     * @remarks
-     * Cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param playerSrc - Player source/client ID (as string)
-     * @returns Dimension ID
-     */
-    getDimension(playerSrc) {
-        return this.getRoutingBucket(playerSrc);
-    }
-    /**
-     * Sets player dimension (alias for setRoutingBucket).
-     *
-     * @remarks
-     * Cross-platform alias. Some platforms call it "dimension",
-     * others call it "routing bucket" or "virtual world".
-     *
-     * @param playerSrc - Player source/client ID (as string)
-     * @param dimension - Dimension ID
-     */
-    setDimension(playerSrc, dimension) {
-        this.setRoutingBucket(playerSrc, dimension);
-    }
 }

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

@@ -0,0 +1,10 @@
+export * from './IEntityServer';
+export * from './npc-lifecycle';
+export * from './IPedAppearanceServer';
+export * from './IPedServer';
+export * from './player-appearance';
+export * from './player-state';
+export * from './IPlayerServer';
+export * from './IVehicleServer';
+export * from './player-lifecycle';
+export * from './vehicle-lifecycle';

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

@@ -0,0 +1,10 @@
+export * from './IEntityServer';
+export * from './npc-lifecycle';
+export * from './IPedAppearanceServer';
+export * from './IPedServer';
+export * from './player-appearance';
+export * from './player-state';
+export * from './IPlayerServer';
+export * from './IVehicleServer';
+export * from './player-lifecycle';
+export * from './vehicle-lifecycle';

package/dist/adapters/contracts/server/npc-lifecycle/INpcLifecycleServer.d.ts

@@ -0,0 +1,5 @@
+import type { CreateNpcServerRequest, CreateNpcServerResult, DeleteNpcServerRequest } from './types';
+export declare abstract class INpcLifecycleServer {
+    abstract create(request: CreateNpcServerRequest): Promise<CreateNpcServerResult> | CreateNpcServerResult;
+    abstract delete(request: DeleteNpcServerRequest): Promise<void> | void;
+}

package/dist/adapters/contracts/server/npc-lifecycle/INpcLifecycleServer.js

@@ -0,0 +1,2 @@
+export class INpcLifecycleServer {
+}

package/dist/adapters/contracts/server/npc-lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export * from './INpcLifecycleServer';
+export * from './types';

package/dist/adapters/contracts/server/npc-lifecycle/index.js

@@ -0,0 +1,2 @@
+export * from './INpcLifecycleServer';
+export * from './types';

package/dist/adapters/contracts/server/npc-lifecycle/types.d.ts

@@ -0,0 +1,17 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export interface CreateNpcServerRequest {
+    model: string;
+    modelHash: number;
+    position: Vector3;
+    heading: number;
+    networked: boolean;
+    routingBucket?: number;
+    persistent?: boolean;
+}
+export interface CreateNpcServerResult {
+    handle: number;
+    netId?: number;
+}
+export interface DeleteNpcServerRequest {
+    handle: number;
+}

package/dist/adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer.d.ts

@@ -0,0 +1,11 @@
+import type { PlayerAppearance } from '../../../../kernel/shared';
+export interface ApplyPlayerAppearanceResult {
+    success: boolean;
+    appearance?: PlayerAppearance;
+    errors?: string[];
+}
+export declare abstract class IPlayerAppearanceLifecycleServer {
+    abstract apply(playerSrc: string, appearance: PlayerAppearance): Promise<ApplyPlayerAppearanceResult> | ApplyPlayerAppearanceResult;
+    abstract applyClothing(playerSrc: string, appearance: Pick<PlayerAppearance, 'components' | 'props'>): Promise<boolean> | boolean;
+    abstract reset(playerSrc: string): Promise<boolean> | boolean;
+}

package/dist/adapters/contracts/server/player-appearance/IPlayerAppearanceLifecycleServer.js

@@ -0,0 +1,2 @@
+export class IPlayerAppearanceLifecycleServer {
+}

package/dist/adapters/contracts/server/player-appearance/index.d.ts

@@ -0,0 +1 @@
+export * from './IPlayerAppearanceLifecycleServer';

package/dist/adapters/contracts/server/player-appearance/index.js

@@ -0,0 +1 @@
+export * from './IPlayerAppearanceLifecycleServer';

package/dist/adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer.d.ts

@@ -0,0 +1,6 @@
+import type { RespawnPlayerRequest, SpawnPlayerRequest, TeleportPlayerRequest } from './types';
+export declare abstract class IPlayerLifecycleServer {
+    abstract spawn(playerSrc: string, request: SpawnPlayerRequest): Promise<void> | void;
+    abstract teleport(playerSrc: string, request: TeleportPlayerRequest): Promise<void> | void;
+    abstract respawn(playerSrc: string, request: RespawnPlayerRequest): Promise<void> | void;
+}

package/dist/adapters/contracts/server/player-lifecycle/IPlayerLifecycleServer.js

@@ -0,0 +1,2 @@
+export class IPlayerLifecycleServer {
+}

package/dist/adapters/contracts/server/player-lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IPlayerLifecycleServer';
+export * from './types';

package/dist/adapters/contracts/server/player-lifecycle/index.js

@@ -0,0 +1,2 @@
+export * from './IPlayerLifecycleServer';
+export * from './types';

package/dist/adapters/contracts/server/player-lifecycle/types.d.ts

@@ -0,0 +1,17 @@
+import type { PlayerAppearance } from '../../../../kernel';
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export interface SpawnPlayerRequest {
+    position: Vector3;
+    model?: string;
+    heading?: number;
+    appearance?: PlayerAppearance;
+}
+export interface TeleportPlayerRequest {
+    position: Vector3;
+    heading?: number;
+}
+export interface RespawnPlayerRequest {
+    position: Vector3;
+    heading?: number;
+    model?: string;
+}

package/dist/adapters/contracts/server/player-state/IPlayerStateSyncServer.d.ts

@@ -0,0 +1,6 @@
+export declare abstract class IPlayerStateSyncServer {
+    abstract getHealth(playerSrc: string): number;
+    abstract setHealth(playerSrc: string, health: number): void;
+    abstract getArmor(playerSrc: string): number;
+    abstract setArmor(playerSrc: string, armor: number): void;
+}

package/dist/adapters/contracts/server/player-state/IPlayerStateSyncServer.js

@@ -0,0 +1,2 @@
+export class IPlayerStateSyncServer {
+}

package/dist/adapters/contracts/server/player-state/index.d.ts

@@ -0,0 +1 @@
+export * from './IPlayerStateSyncServer';

package/dist/adapters/contracts/server/player-state/index.js

@@ -0,0 +1 @@
+export * from './IPlayerStateSyncServer';

package/dist/adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer.d.ts

@@ -0,0 +1,5 @@
+import type { CreateVehicleServerRequest, CreateVehicleServerResult, WarpPlayerIntoVehicleRequest } from './types';
+export declare abstract class IVehicleLifecycleServer {
+    abstract create(request: CreateVehicleServerRequest): Promise<CreateVehicleServerResult> | CreateVehicleServerResult;
+    abstract warpPlayerIntoVehicle(request: WarpPlayerIntoVehicleRequest): Promise<void> | void;
+}

package/dist/adapters/contracts/server/vehicle-lifecycle/IVehicleLifecycleServer.js

@@ -0,0 +1,2 @@
+export class IVehicleLifecycleServer {
+}

package/dist/adapters/contracts/server/vehicle-lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export * from './IVehicleLifecycleServer';
+export * from './types';

package/dist/adapters/contracts/server/vehicle-lifecycle/index.js

@@ -0,0 +1,2 @@
+export * from './IVehicleLifecycleServer';
+export * from './types';

package/dist/adapters/contracts/server/vehicle-lifecycle/types.d.ts

@@ -0,0 +1,16 @@
+import type { Vector3 } from '../../../../kernel/utils/vector3';
+export interface CreateVehicleServerRequest {
+    model: string;
+    modelHash: number;
+    position: Vector3;
+    heading: number;
+}
+export interface CreateVehicleServerResult {
+    handle: number;
+    networkId: number;
+}
+export interface WarpPlayerIntoVehicleRequest {
+    playerSrc: string;
+    networkId: number;
+    seatIndex: number;
+}

package/dist/adapters/contracts/transport/events.api.d.ts

@@ -1,6 +1,6 @@
 import { EventContext, RuntimeContext } from './context';
 import { Player } from '../../../runtime/server/entities/player';
-type EmitArgs<C extends RuntimeContext> = C extends 'server' ? [target: Player | number | number[] | 'all', ...args: any[]] : [...args: any[]];
+type EmitArgs<C extends RuntimeContext> = C extends 'server' ? [target: Player | number | number[] | 'all', ...args: unknown[]] : [...args: unknown[]];
 /**
  * broadcast and listen to events without relying on runtime. The adapter will be used.
  */
@@ -13,7 +13,7 @@ export declare abstract class EventsAPI<C extends RuntimeContext> {
      * Client:
      *   - triggered by server
      */
-    abstract on(event: string, handler: (ctx: EventContext, ...args: any[]) => void | Promise<void>): void;
+    abstract on<TArgs extends readonly unknown[]>(event: string, handler: (ctx: EventContext, ...args: TArgs) => void | Promise<void>): void;
     /**
      * Emit an event.
      *  SERVER → CLIENT
@@ -22,7 +22,7 @@ export declare abstract class EventsAPI<C extends RuntimeContext> {
      * Client:
      *   - sends to server, targetOrArg will be ignored
      */
-    abstract emit(event: string, target: Player | number | number[] | 'all', ...args: any[]): void;
+    abstract emit(event: string, target: Player | number | number[] | 'all', ...args: unknown[]): void;
     /**
      * Emit an event.
      *  CLIENT → SERVER

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

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

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

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