@utsp/types 0.4.0 → 0.5.0-nightly.20251204224035.7a07d4b

package/dist/index.d.ts

@@ -1034,93 +1034,6 @@ type AnyNetworkMessage = InputMessage | UpdateMessage | LoadMessage | JoinMessag
 /** Message type literals */
 type MessageType = AnyNetworkMessage['type'];
 
-/**
- * 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> {
-    /**
-     * Initialize application (called once at startup, before users)
-     * Can be async if you need to load resources.
-     * @param core - Core instance
-     * @param runtime - Runtime instance (optional)
-     */
-    init(core: TCore, runtime?: TRuntime): void | Promise<void>;
-    /**
-     * Update global logic (called every frame, runs once)
-     * @param core - Core instance
-     * @param deltaTime - Time since last update (seconds)
-     */
-    update(core: TCore, deltaTime: number): void;
-    /**
-     * Initialize new user (called when user connects/joins)
-     * @param core - Core instance
-     * @param user - User instance
-     * @param metadata - Optional user metadata (username, preferences, etc.)
-     */
-    initUser(core: TCore, user: TUser, metadata?: UserMetadata): void;
-    /**
-     * Update user-specific logic (called every frame per user)
-     * @param core - Core instance
-     * @param user - User instance
-     * @param deltaTime - Time since last update (seconds)
-     */
-    updateUser(core: TCore, user: TUser, deltaTime: number): void;
-    /**
-     * Cleanup when user disconnects (optional)
-     * @param core - Core instance
-     * @param user - User instance
-     * @param reason - Disconnect reason (optional)
-     */
-    destroyUser?(core: TCore, user: TUser, reason?: string): void;
-    /**
-     * Cleanup when application shuts down (optional)
-     */
-    destroy?(): void;
-    /**
-     * Commit changes after all updates (optional)
-     * Called after update() and all updateUser() to trigger render/broadcast.
-     * @param core - Core instance
-     * @param deltaTime - Time since last update (seconds)
-     */
-    onCommit?(core: TCore, deltaTime: number): void;
-    /**
-     * Handle errors during execution (optional)
-     * @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: {
-        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;
-}
-
 /**
  * Audio types for UTSP
  * @packageDocumentation
@@ -1186,17 +1099,78 @@ interface SoundExternalLoadPacket {
  */
 type AnySoundLoadPacket = SoundLoadPacket | SoundExternalLoadPacket;
 /**
- * Client acknowledgment that an external sound was loaded
- * Sent after successfully downloading and decoding an external sound
+ * Audio ACK types
+ */
+type AudioAckType = 'sound-loaded' | 'sound-error' | 'playback-started' | 'playback-ended' | 'playback-error';
+/**
+ * Base interface for all audio acknowledgments
+ */
+interface AudioAckBase {
+    /** Type of acknowledgment */
+    type: AudioAckType;
+}
+/**
+ * ACK: Sound successfully loaded (file or external)
  */
-interface SoundLoadedAck {
+interface SoundLoadedAck extends AudioAckBase {
+    type: 'sound-loaded';
     /** Sound ID that was loaded */
     soundId: number;
-    /** Loading status */
-    status: 'loaded' | 'error';
-    /** Error message if status is 'error' */
-    error?: string;
+    /** Sound name */
+    name: string;
 }
+/**
+ * ACK: Sound failed to load
+ */
+interface SoundErrorAck extends AudioAckBase {
+    type: 'sound-error';
+    /** Sound ID that failed */
+    soundId: number;
+    /** Sound name */
+    name: string;
+    /** Error message */
+    error: string;
+}
+/**
+ * ACK: Sound playback started
+ */
+interface PlaybackStartedAck extends AudioAckBase {
+    type: 'playback-started';
+    /** Instance ID of the playing sound */
+    instanceId: SoundInstanceId;
+    /** Sound ID being played */
+    soundId: number;
+}
+/**
+ * ACK: Sound playback ended (natural end, not stopped)
+ */
+interface PlaybackEndedAck extends AudioAckBase {
+    type: 'playback-ended';
+    /** Instance ID that ended */
+    instanceId: SoundInstanceId;
+    /** Sound ID that was playing */
+    soundId: number;
+}
+/**
+ * ACK: Sound playback failed
+ */
+interface PlaybackErrorAck extends AudioAckBase {
+    type: 'playback-error';
+    /** Instance ID that failed (if known) */
+    instanceId?: SoundInstanceId;
+    /** Sound ID or name that was requested */
+    sound: number | string;
+    /** Error message */
+    error: string;
+}
+/**
+ * Union of all audio ACK types
+ */
+type AudioAck = SoundLoadedAck | SoundErrorAck | PlaybackStartedAck | PlaybackEndedAck | PlaybackErrorAck;
+/**
+ * Callback type for audio ACK events on server
+ */
+type AudioAckHandler = (userId: string, ack: AudioAck) => void;
 /**
  * Unique identifier for a playing sound instance
  * Allows multiple instances of the same sound to play simultaneously
@@ -1220,13 +1194,16 @@ interface PlaySoundCommand {
     loop?: boolean;
     /** Fade in duration in seconds (0 = no fade, default: 0) */
     fadeIn?: number;
-    /** Spatial position (if set, enables 2D positional audio) */
-    position?: {
-        /** X position (0-65535, 16-bit) */
-        x: number;
-        /** Y position (0-65535, 16-bit) */
-        y: number;
-    };
+    /** X position for spatial audio (0-65535, 16-bit). Must be set with y. */
+    x?: number;
+    /** Y position for spatial audio (0-65535, 16-bit). Must be set with x. */
+    y?: number;
+    /** Low-pass filter cutoff frequency in Hz (100-25500, 0 or undefined = disabled) */
+    lowpass?: number;
+    /** High-pass filter cutoff frequency in Hz (100-25500, 0 or undefined = disabled) */
+    highpass?: number;
+    /** Reverb wet/dry mix (0.0-1.0, 0 or undefined = disabled) */
+    reverb?: number;
 }
 /**
  * Command to stop a sound on the client
@@ -1284,6 +1261,21 @@ interface ResumeSoundCommand {
      */
     sound: SoundInstanceId | string | 'all';
 }
+/**
+ * Command to update audio effects on a playing sound
+ */
+interface SetSoundEffectsCommand {
+    /** Marker to identify this as a set-effects command */
+    setEffects: true;
+    /** Target instance ID */
+    instanceId: SoundInstanceId;
+    /** Low-pass filter cutoff frequency in Hz (100-25500, 0 = disable) */
+    lowpass?: number;
+    /** High-pass filter cutoff frequency in Hz (100-25500, 0 = disable) */
+    highpass?: number;
+    /** Reverb wet/dry mix (0.0-1.0, 0 = disable) */
+    reverb?: number;
+}
 /**
  * Command to set the listener position for spatial audio
  */
@@ -1348,6 +1340,12 @@ interface AudioPlayOptions {
     };
     /** Instance ID (provided by server in connected mode, auto-generated otherwise) */
     instanceId?: number;
+    /** Low-pass filter cutoff frequency in Hz (100-25500, 0 = disable) */
+    lowpass?: number;
+    /** High-pass filter cutoff frequency in Hz (100-25500, 0 = disable) */
+    highpass?: number;
+    /** Reverb wet/dry mix (0.0-1.0, 0 = disable) */
+    reverb?: number;
 }
 /**
  * Result of playing a sound
@@ -1445,6 +1443,14 @@ interface IAudioProcessor {
      * @param config - Spatial audio options
      */
     configureSpatial(config: AudioSpatialOptions): void;
+    /**
+     * Set audio effects on a playing sound
+     * @param instanceId - The sound instance ID
+     * @param lowpass - Low-pass filter cutoff Hz (0 = disable)
+     * @param highpass - High-pass filter cutoff Hz (0 = disable)
+     * @param reverb - Reverb mix 0.0-1.0 (0 = disable)
+     */
+    setEffects(instanceId: number, lowpass?: number, highpass?: number, reverb?: number): void;
 }
 /**
  * Interface for loading sounds into the audio system
@@ -1484,5 +1490,118 @@ interface ISoundLoader {
     has(nameOrId: string | number): boolean;
 }
 
+/**
+ * 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> {
+    /**
+     * Initialize application (called once at startup, before users)
+     * Can be async if you need to load resources.
+     * @param core - Core instance
+     * @param runtime - Runtime instance (optional)
+     */
+    init(core: TCore, runtime?: TRuntime): void | Promise<void>;
+    /**
+     * Update global logic (called every frame, runs once)
+     * @param core - Core instance
+     * @param deltaTime - Time since last update (seconds)
+     */
+    update(core: TCore, deltaTime: number): void;
+    /**
+     * Initialize new user (called when user connects/joins)
+     * @param core - Core instance
+     * @param user - User instance
+     * @param metadata - Optional user metadata (username, preferences, etc.)
+     */
+    initUser(core: TCore, user: TUser, metadata?: UserMetadata): void;
+    /**
+     * Update user-specific logic (called every frame per user)
+     * @param core - Core instance
+     * @param user - User instance
+     * @param deltaTime - Time since last update (seconds)
+     */
+    updateUser(core: TCore, user: TUser, deltaTime: number): void;
+    /**
+     * Cleanup when user disconnects (optional)
+     * @param core - Core instance
+     * @param user - User instance
+     * @param reason - Disconnect reason (optional)
+     */
+    destroyUser?(core: TCore, user: TUser, reason?: string): void;
+    /**
+     * Cleanup when application shuts down (optional)
+     */
+    destroy?(): void;
+    /**
+     * Commit changes after all updates (optional)
+     * Called after update() and all updateUser() to trigger render/broadcast.
+     * @param core - Core instance
+     * @param deltaTime - Time since last update (seconds)
+     */
+    onCommit?(core: TCore, deltaTime: number): void;
+    /**
+     * Handle audio acknowledgments from clients (optional, server mode only)
+     *
+     * Called when a client sends an audio-ack message (sound loaded, playback started/ended, error).
+     * Useful for:
+     * - Waiting for sounds to load before playing them
+     * - Tracking playback state across clients
+     * - Handling audio errors gracefully
+     *
+     * @param core - Core instance
+     * @param user - User who sent the ACK
+     * @param ack - The audio acknowledgment
+     *
+     * @example
+     * ```typescript
+     * onAudioAck(core, user, ack) {
+     *   if (ack.type === 'sound-loaded') {
+     *     console.log(`User ${user.id} loaded sound ${ack.name}`);
+     *     // Now safe to play this sound for this user
+     *   } else if (ack.type === 'playback-ended') {
+     *     console.log(`Sound instance ${ack.instanceId} finished`);
+     *   }
+     * }
+     * ```
+     */
+    onAudioAck?(core: TCore, user: TUser, ack: AudioAck): void;
+    /**
+     * Handle errors during execution (optional)
+     * @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: {
+        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;
+}
+
 export { GamepadInput, InputDeviceType, KeyboardInput, MouseInput, NetworkState, TVRemoteInput, TouchInput, Vector2, Vector3, createInputDescriptor, deserializeInputDescriptor, gamepadAxisIndexToInput, gamepadButtonIndexToInput, getTouchXAxis, getTouchYAxis, inputDescriptorToString, isAxis, isButton, isGamepadAxis, isGamepadButton, isMouseAxis, isMouseButton, isTVRemoteAxis, isTVRemoteButton, isTouchButton, isTouchGesture, isTouchPosition, keyCodeToKeyboardInput, keyboardInputToKeyCode, parseInputDescriptor, serializeInputDescriptor };
-export type { AnyNetworkMessage, AnySoundLoadPacket, AudioConfigCommand, AudioPlayOptions, AudioPlayResult, AudioSpatialOptions, AxisBinding, AxisSource, ButtonBinding, ButtonSource, ChatMessage, ClientInfo, ConfigureSpatialCommand, ConnectionHandler, DisconnectionHandler, ErrorMessage, FadeOutSoundCommand, GamepadInputDescriptor, IApplication, IAudioProcessor, IColorPalette, IInputSystem, INetworkClient, INetworkServer, IRenderer, ISoundLoader, InputBindingLoadPacket, InputDescriptor, InputEnum, InputMessage, JoinMessage, JoinResponseMessage, KeyboardInputDescriptor, LeaveMessage, LoadMessage, MessageType, MouseInputDescriptor, NetworkClientOptions, NetworkEventHandler, NetworkMessage, NetworkServerOptions, PauseSoundCommand, PingMessage, PlaySoundCommand, PongMessage, RGBColor, RenderState, RenderedCell, ResumeSoundCommand, ServerEventHandler, SetListenerPositionCommand, SoundExternalEntry, SoundExternalLoadPacket, SoundFileEntry, SoundFormat, SoundInstanceId, SoundLoadPacket, SoundLoadType, SoundLoadedAck, SpatialAudioConfig, StopSoundCommand, TVRemoteInputDescriptor, TouchInputDescriptor, TypedInputDescriptor, UpdateMessage, UserMetadata, UserRenderState };
+export type { AnyNetworkMessage, AnySoundLoadPacket, AudioAck, AudioAckBase, AudioAckHandler, AudioAckType, AudioConfigCommand, AudioPlayOptions, AudioPlayResult, AudioSpatialOptions, AxisBinding, AxisSource, ButtonBinding, ButtonSource, ChatMessage, ClientInfo, ConfigureSpatialCommand, ConnectionHandler, DisconnectionHandler, ErrorMessage, FadeOutSoundCommand, GamepadInputDescriptor, IApplication, IAudioProcessor, IColorPalette, IInputSystem, INetworkClient, INetworkServer, IRenderer, ISoundLoader, InputBindingLoadPacket, InputDescriptor, InputEnum, InputMessage, JoinMessage, JoinResponseMessage, KeyboardInputDescriptor, LeaveMessage, LoadMessage, MessageType, MouseInputDescriptor, NetworkClientOptions, NetworkEventHandler, NetworkMessage, NetworkServerOptions, PauseSoundCommand, PingMessage, PlaySoundCommand, PlaybackEndedAck, PlaybackErrorAck, PlaybackStartedAck, PongMessage, RGBColor, RenderState, RenderedCell, ResumeSoundCommand, ServerEventHandler, SetListenerPositionCommand, SetSoundEffectsCommand, SoundErrorAck, SoundExternalEntry, SoundExternalLoadPacket, SoundFileEntry, SoundFormat, SoundInstanceId, SoundLoadPacket, SoundLoadType, SoundLoadedAck, SpatialAudioConfig, StopSoundCommand, TVRemoteInputDescriptor, TouchInputDescriptor, TypedInputDescriptor, UpdateMessage, UserMetadata, UserRenderState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utsp/types",
-  "version": "0.4.0",
+  "version": "0.5.0-nightly.20251204224035.7a07d4b",
   "description": "Type definitions and interfaces for UTSP (Universal Text Stream Protocol)",
   "author": "THP Software",
   "license": "MIT",