@utsp/types 0.17.0-nightly.20260125163743.7efddab → 0.17.0-nightly.20260127101256.e83fcc8

package/dist/index.d.ts

@@ -1998,61 +1998,131 @@ interface ISoundLoader {
     has(nameOrId: string | number): boolean;
 }
 
+/**
+ * Common interface for all UTSP Runtimes (Server, Client, Standalone).
+ * Allows IApplication to interact with the underlying execution environment
+ * in a type-safe way.
+ */
+interface IRuntime {
+    /**
+     * Get the current execution mode
+     */
+    getMode(): string;
+    /**
+     * Check if the runtime is currently running
+     */
+    isRunning(): boolean;
+    /**
+     * Get current tick rate (TPS)
+     */
+    getTickRate(): number;
+    /**
+     * Set the tick rate (TPS)
+     */
+    setTickRate(tickRate: number): void;
+    /**
+     * Disconnect a user from the game
+     * In Server mode: Kicks the specified user.
+     * In Client mode: Usually only applicable to the local user or ignored.
+     *
+     * @param userId - ID of the user to disconnect
+     * @param reason - Optional reason for disconnection
+     * @returns true if the disconnection was initiated
+     */
+    disconnectUser(userId: string, reason?: string): boolean;
+    /**
+     * Get runtime statistics
+     */
+    getStats(): any;
+    /**
+     * Shutdown the runtime
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Metadata associated with a user when they connect to a runtime.
+ * Includes both authentication info and client-provided preferences.
+ */
+interface UserMetadata {
+    /**
+     * User name (e.g. 'Player1', 'Admin')
+     */
+    username: string;
+    /**
+     * Authentication token or object (optional)
+     */
+    token?: string | Record<string, unknown>;
+    /**
+     * Client-specific preferences or state (optional)
+     */
+    preferences?: Record<string, unknown>;
+    /**
+     * Any other context-specific data
+     */
+    [key: string]: any;
+}
+
 /**
  * Application lifecycle interface for games, dashboards, signage, etc.
  * Supports single-user (local) and multi-user (networked) scenarios.
  *
  * @template TCore - Core type (typically Core)
  * @template TUser - User type (typically User)
- * @template TRuntime - Runtime type (optional)
  */
-interface IApplication<TCore = any, TUser = any, TRuntime = unknown> {
+interface IApplication<TCore = any, TUser = any> {
     /**
      * Initialize application (called once at startup, before users)
      * Can be async if you need to load resources.
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
-     * @param runtime - Runtime instance (optional)
      */
-    init(core: TCore, runtime?: TRuntime): void | Promise<void>;
+    init(runtime: IRuntime, core: TCore): void | Promise<void>;
     /**
      * Update global logic (called every frame, runs once) (optional)
      * Use this for logic that doesn't depend on specific users.
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param deltaTime - Time since last update (seconds)
      */
-    update?(core: TCore, deltaTime: number): void;
+    update?(runtime: IRuntime, core: TCore, deltaTime: number): void;
     /**
      * Initialize new user (called when user connects/joins)
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param user - User instance
      * @param metadata - Optional user metadata (username, preferences, etc.)
      */
-    initUser(core: TCore, user: TUser, metadata?: UserMetadata): void;
+    initUser(runtime: IRuntime, core: TCore, user: TUser, metadata?: UserMetadata): void;
     /**
      * Update user-specific logic (called every frame per user)
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param user - User instance
      * @param deltaTime - Time since last update (seconds)
      */
-    updateUser(core: TCore, user: TUser, deltaTime: number): void;
+    updateUser(runtime: IRuntime, core: TCore, user: TUser, deltaTime: number): void;
     /**
      * Cleanup when user disconnects (optional)
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param user - User instance
      * @param reason - Disconnect reason (optional)
      */
-    destroyUser?(core: TCore, user: TUser, reason?: string): void;
+    destroyUser?(runtime: IRuntime, core: TCore, user: TUser, reason?: string): void;
     /**
      * Cleanup when application shuts down (optional)
+     * @param runtime - Runtime instance
      */
-    destroy?(): void;
+    destroy?(runtime: IRuntime): void;
     /**
      * Commit changes after all updates (optional)
      * Called after update() and all updateUser() to trigger render/broadcast.
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param deltaTime - Time since last update (seconds)
      */
-    onCommit?(core: TCore, deltaTime: number): void;
+    onCommit?(runtime: IRuntime, core: TCore, deltaTime: number): void;
     /**
      * Handle audio acknowledgments from clients (optional, server mode only)
      *
@@ -2062,13 +2132,14 @@ interface IApplication<TCore = any, TUser = any, TRuntime = unknown> {
      * - Tracking playback state across clients
      * - Handling audio errors gracefully
      *
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param user - User who sent the ACK
      * @param ack - The audio acknowledgment
      *
      * @example
      * ```typescript
-     * onAudioAck(core, user, ack) {
+     * onAudioAck(core, user, runtime, ack) {
      *   if (ack.type === 'sound-loaded') {
      *     console.log(`User ${user.id} loaded sound ${ack.name}`);
      *     // Now safe to play this sound for this user
@@ -2078,7 +2149,7 @@ interface IApplication<TCore = any, TUser = any, TRuntime = unknown> {
      * }
      * ```
      */
-    onAudioAck?(core: TCore, user: TUser, ack: AudioAck): void;
+    onAudioAck?(runtime: IRuntime, core: TCore, user: TUser, ack: AudioAck): void;
     /**
      * Handle bridge messages from clients (optional, server mode only)
      *
@@ -2093,6 +2164,7 @@ interface IApplication<TCore = any, TUser = any, TRuntime = unknown> {
      * - Debug/admin commands
      * - Integration with external systems
      *
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param user - User who sent the message
      * @param channel - The bridge channel name (e.g., 'chat', 'lobby', 'debug')
@@ -2100,7 +2172,7 @@ interface IApplication<TCore = any, TUser = any, TRuntime = unknown> {
      *
      * @example
      * ```typescript
-     * onBridgeMessage(core, user, channel, data) {
+     * onBridgeMessage(core, user, runtime, channel, data) {
      *   if (channel === 'chat') {
      *     const { message } = data as { message: string };
      *     console.log(`[Chat] ${user.id}: ${message}`);
@@ -2112,39 +2184,21 @@ interface IApplication<TCore = any, TUser = any, TRuntime = unknown> {
      * }
      * ```
      */
-    onBridgeMessage?(core: TCore, user: TUser, channel: string, data: unknown): void;
+    onBridgeMessage?(runtime: IRuntime, core: TCore, user: TUser, channel: string, data: unknown): void;
     /**
      * Handle errors during execution (optional)
+     * @param runtime - Isomorphic runtime instance
      * @param core - Core instance
      * @param error - The error that occurred
      * @param context - Error context (phase, user, timestamp)
      * @returns true to continue, false to stop runtime
      */
-    onError?(core: TCore, error: Error, context: {
+    onError?(runtime: IRuntime, core: TCore, error: Error, context: {
         phase: 'init' | 'update' | 'initUser' | 'updateUser' | 'destroyUser' | 'destroy';
         user?: TUser;
         timestamp: number;
     }): boolean;
 }
-/**
- * User metadata for initUser
- */
-interface UserMetadata {
-    /** Display name */
-    username?: string;
-    /** Avatar/skin ID */
-    avatar?: string | number;
-    /** Team/faction */
-    team?: string | number;
-    /** Color preference */
-    color?: number;
-    /** Theme preference */
-    theme?: string;
-    /** Auth token */
-    token?: string;
-    /** Custom data */
-    [key: string]: unknown;
-}
 
 /**
  * Vibration types for tactile feedback
@@ -2253,4 +2307,4 @@ interface IGamepadVibrationProcessor {
 type GamepadVibrationPreset = 'tap' | 'impact' | 'heavy' | 'success' | 'error' | 'explosion' | 'engine' | 'heartbeat';
 
 export { GRID_DEFAULTS, GamepadInput, InputDeviceType, KeyboardInput, MouseInput, NetworkEvent, NetworkState, NetworkTransportType, POST_PROCESS_DEFAULTS, ScalingMode, ScalingModeValue, TVRemoteInput, TouchInput, TouchZoneInput, Vector2, Vector3, createInputDescriptor, deserializeInputDescriptor, gamepadAxisIndexToInput, gamepadButtonIndexToInput, getTouchXAxis, getTouchYAxis, getTouchZoneXAxis, getTouchZoneYAxis, inputDescriptorToString, isAxis, isButton, isGamepadAxis, isGamepadButton, isMouseAxis, isMouseButton, isNetworkEvent, isTVRemoteAxis, isTVRemoteButton, isTouchButton, isTouchGesture, isTouchPosition, isTouchZoneButton, isTouchZonePosition, keyCodeToKeyboardInput, keyboardInputToKeyCode, parseInputDescriptor, scalingModeToValue, serializeInputDescriptor, valueToScalingMode };
-export type { AmbientEffectConfig, AnyNetworkMessage, AnySoundLoadPacket, AudioAck, AudioAckBase, AudioAckHandler, AudioAckType, AudioConfigCommand, AudioPlayOptions, AudioPlayResult, AudioSpatialOptions, AxisBinding, AxisSource, BridgeClientHandler, BridgeServerHandler, ButtonBinding, ButtonSource, CancelVibrationCommand, ChatMessage, ClientInfo, ConfigureSpatialCommand, ConnectionHandler, DisconnectionHandler, ErrorMessage, FadeOutSoundCommand, GamepadCancelVibrationCommand, GamepadInputDescriptor, GamepadVibrateCommand, GamepadVibrationCommand, GamepadVibrationOptions, GamepadVibrationPreset, GridConfig, IApplication, IAudioProcessor, IColorPalette, IGamepadVibrationProcessor, IInputSystem, IMobileVibrationProcessor, INetworkClient, INetworkServer, IRenderer, ISoundLoader, InputBindingLoadPacket, InputDescriptor, InputEnum, InputMessage, JoinMessage, JoinResponseMessage, KeyboardInputDescriptor, LeaveMessage, LoadMessage, MessageType, MobileVibrationCommand, MobileVibrationPreset, MouseInputDescriptor, NetworkClientOptions, NetworkEventHandler, NetworkMessage, NetworkServerOptions, PauseSoundCommand, PingMessage, PlaySoundCommand, PlaybackEndedAck, PlaybackErrorAck, PlaybackStartedAck, PongMessage, PostProcessCommand, PostProcessCommandType, PostProcessConfig, RGBColor, RenderPassState, RenderState, RenderedCell, ResumeSoundCommand, ScanlinesConfig, ServerEventHandler, SetListenerPositionCommand, SetSoundEffectsCommand, SignalingInfo, SoundErrorAck, SoundExternalEntry, SoundExternalLoadPacket, SoundFileEntry, SoundFormat, SoundInstanceId, SoundLoadPacket, SoundLoadType, SoundLoadedAck, SpatialAudioConfig, StopSoundCommand, TVRemoteInputDescriptor, TouchInputDescriptor, TouchZoneBinding, TypedInputDescriptor, UpdateMessage, UserMetadata, UserRenderState, VibrateCommand, VibrationPattern };
+export type { AmbientEffectConfig, AnyNetworkMessage, AnySoundLoadPacket, AudioAck, AudioAckBase, AudioAckHandler, AudioAckType, AudioConfigCommand, AudioPlayOptions, AudioPlayResult, AudioSpatialOptions, AxisBinding, AxisSource, BridgeClientHandler, BridgeServerHandler, ButtonBinding, ButtonSource, CancelVibrationCommand, ChatMessage, ClientInfo, ConfigureSpatialCommand, ConnectionHandler, DisconnectionHandler, ErrorMessage, FadeOutSoundCommand, GamepadCancelVibrationCommand, GamepadInputDescriptor, GamepadVibrateCommand, GamepadVibrationCommand, GamepadVibrationOptions, GamepadVibrationPreset, GridConfig, IApplication, IAudioProcessor, IColorPalette, IGamepadVibrationProcessor, IInputSystem, IMobileVibrationProcessor, INetworkClient, INetworkServer, IRenderer, IRuntime, ISoundLoader, InputBindingLoadPacket, InputDescriptor, InputEnum, InputMessage, JoinMessage, JoinResponseMessage, KeyboardInputDescriptor, LeaveMessage, LoadMessage, MessageType, MobileVibrationCommand, MobileVibrationPreset, MouseInputDescriptor, NetworkClientOptions, NetworkEventHandler, NetworkMessage, NetworkServerOptions, PauseSoundCommand, PingMessage, PlaySoundCommand, PlaybackEndedAck, PlaybackErrorAck, PlaybackStartedAck, PongMessage, PostProcessCommand, PostProcessCommandType, PostProcessConfig, RGBColor, RenderPassState, RenderState, RenderedCell, ResumeSoundCommand, ScanlinesConfig, ServerEventHandler, SetListenerPositionCommand, SetSoundEffectsCommand, SignalingInfo, SoundErrorAck, SoundExternalEntry, SoundExternalLoadPacket, SoundFileEntry, SoundFormat, SoundInstanceId, SoundLoadPacket, SoundLoadType, SoundLoadedAck, SpatialAudioConfig, StopSoundCommand, TVRemoteInputDescriptor, TouchInputDescriptor, TouchZoneBinding, TypedInputDescriptor, UpdateMessage, UserMetadata, UserRenderState, VibrateCommand, VibrationPattern };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utsp/types",
-  "version": "0.17.0-nightly.20260125163743.7efddab",
+  "version": "0.17.0-nightly.20260127101256.e83fcc8",
   "description": "Type definitions and interfaces for UTSP (Universal Tile Stream Protocol)",
   "author": "THP Software",
   "license": "MIT",