@utsp/types 0.4.0-nightly.20251201222332.2d9d7a5 → 0.4.0

package/dist/index.d.ts

@@ -1045,10 +1045,11 @@ type MessageType = AnyNetworkMessage['type'];
 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;
+    init(core: TCore, runtime?: TRuntime): void | Promise<void>;
     /**
      * Update global logic (called every frame, runs once)
      * @param core - Core instance
@@ -1120,5 +1121,368 @@ interface UserMetadata {
     [key: string]: unknown;
 }
 
+/**
+ * Audio types for UTSP
+ * @packageDocumentation
+ */
+/**
+ * Supported audio file formats
+ */
+type SoundFormat = 'mp3' | 'wav' | 'ogg' | 'webm' | 'aac';
+/**
+ * Sound loading type
+ */
+type SoundLoadType = 'file' | 'external';
+/**
+ * A single sound to load via File mode (embedded data)
+ */
+interface SoundFileEntry {
+    /** Unique sound identifier (0-255) */
+    soundId: number;
+    /** Human-readable name for playback (e.g., 'coin', 'explosion') */
+    name: string;
+    /** Audio format */
+    format: SoundFormat;
+    /** Raw audio data */
+    data: Uint8Array;
+}
+/**
+ * A single sound to load via External mode (URL reference)
+ */
+interface SoundExternalEntry {
+    /** Unique sound identifier (0-255) */
+    soundId: number;
+    /** Human-readable name for playback */
+    name: string;
+    /** Audio format */
+    format: SoundFormat;
+    /** URL to fetch the audio from (CDN, external server, etc.) */
+    url: string;
+    /** Expected file size in bytes (optional, for progress tracking) */
+    size?: number;
+    /** Checksum for validation (optional) */
+    checksum?: string;
+}
+/**
+ * Sound Load packet - File mode
+ * Audio data is embedded in the packet and sent via UTSP
+ */
+interface SoundLoadPacket {
+    type: 'sound';
+    mode: 'file';
+    sounds: SoundFileEntry[];
+}
+/**
+ * Sound External Load packet - External mode
+ * Only URLs are sent, client downloads from external sources
+ */
+interface SoundExternalLoadPacket {
+    type: 'sound';
+    mode: 'external';
+    sounds: SoundExternalEntry[];
+}
+/**
+ * Union of all sound load packet types
+ */
+type AnySoundLoadPacket = SoundLoadPacket | SoundExternalLoadPacket;
+/**
+ * Client acknowledgment that an external sound was loaded
+ * Sent after successfully downloading and decoding an external sound
+ */
+interface SoundLoadedAck {
+    /** Sound ID that was loaded */
+    soundId: number;
+    /** Loading status */
+    status: 'loaded' | 'error';
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Unique identifier for a playing sound instance
+ * Allows multiple instances of the same sound to play simultaneously
+ * and be controlled independently
+ */
+type SoundInstanceId = number;
+/**
+ * Command to play a sound on the client
+ * Sent from server to trigger sound playback
+ */
+interface PlaySoundCommand {
+    /** Sound ID or name to play */
+    sound: number | string;
+    /** Unique instance ID for this playback (allows stopping specific instances) */
+    instanceId?: SoundInstanceId;
+    /** Volume multiplier (0.0 to 1.0) */
+    volume?: number;
+    /** Pitch/playback rate (0.5 = octave down, 2.0 = octave up) */
+    pitch?: number;
+    /** Loop the sound */
+    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;
+    };
+}
+/**
+ * Command to stop a sound on the client
+ */
+interface StopSoundCommand {
+    /**
+     * What to stop:
+     * - SoundInstanceId (number > 0): Stop specific instance
+     * - Sound name (string): Stop all instances of that sound
+     * - 'all': Stop all sounds
+     */
+    sound: SoundInstanceId | string | 'all';
+}
+/**
+ * Command to fade out a sound on the client
+ */
+interface FadeOutSoundCommand {
+    /** Marker to identify this as a fade-out command */
+    fadeOut: true;
+    /**
+     * What to fade out:
+     * - SoundInstanceId (number > 0): Fade out specific instance
+     * - Sound name (string): Fade out all instances of that sound
+     * - 'all': Fade out all sounds
+     */
+    sound: SoundInstanceId | string | 'all';
+    /** Fade out duration in seconds */
+    duration: number;
+}
+/**
+ * Command to pause a sound on the client
+ */
+interface PauseSoundCommand {
+    /** Marker to identify this as a pause command */
+    pause: true;
+    /**
+     * What to pause:
+     * - SoundInstanceId (number > 0): Pause specific instance
+     * - Sound name (string): Pause all instances of that sound
+     * - 'all': Pause all sounds
+     */
+    sound: SoundInstanceId | string | 'all';
+}
+/**
+ * Command to resume a paused sound on the client
+ */
+interface ResumeSoundCommand {
+    /** Marker to identify this as a resume command */
+    resume: true;
+    /**
+     * What to resume:
+     * - SoundInstanceId (number > 0): Resume specific instance
+     * - Sound name (string): Resume all instances of that sound
+     * - 'all': Resume all paused sounds
+     */
+    sound: SoundInstanceId | string | 'all';
+}
+/**
+ * Command to set the listener position for spatial audio
+ */
+interface SetListenerPositionCommand {
+    type: 'set-listener-position';
+    /** X position (0-65535) */
+    x: number;
+    /** Y position (0-65535) */
+    y: number;
+}
+/**
+ * Command to configure spatial audio parameters
+ */
+interface ConfigureSpatialCommand {
+    type: 'configure-spatial';
+    /** Maximum audible distance */
+    maxDistance?: number;
+    /** Reference distance (full volume) */
+    referenceDistance?: number;
+    /** Rolloff factor */
+    rolloffFactor?: number;
+    /** Pan spread (0-1) */
+    panSpread?: number;
+}
+/**
+ * Union of all audio configuration commands
+ */
+type AudioConfigCommand = SetListenerPositionCommand | ConfigureSpatialCommand;
+/**
+ * Configuration for 2D spatial audio (listener position)
+ */
+interface SpatialAudioConfig {
+    /** Listener X position (0-65535) - where the "ear" is */
+    listenerX: number;
+    /** Listener Y position (0-65535) - where the "ear" is */
+    listenerY: number;
+    /** Maximum audible distance (beyond this, volume = 0) */
+    maxDistance: number;
+    /** Reference distance (volume = 1.0 at this distance) */
+    referenceDistance: number;
+    /** Rolloff factor for distance attenuation (higher = faster falloff) */
+    rolloffFactor: number;
+    /** Pan spread factor (how much X offset affects stereo pan, 0-1) */
+    panSpread: number;
+}
+/**
+ * Options for playing a sound via IAudioProcessor
+ */
+interface AudioPlayOptions {
+    /** Volume multiplier (0.0 to 1.0, default: 1.0) */
+    volume?: number;
+    /** Playback rate / pitch (0.5 = octave down, 2.0 = octave up, default: 1.0) */
+    pitch?: number;
+    /** Loop the sound (default: false) */
+    loop?: boolean;
+    /** Fade in duration in seconds (0 = no fade, default: 0) */
+    fadeIn?: number;
+    /** Spatial position for 2D positional audio */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Instance ID (provided by server in connected mode, auto-generated otherwise) */
+    instanceId?: number;
+}
+/**
+ * Result of playing a sound
+ */
+interface AudioPlayResult {
+    /** Unique instance ID for this playback */
+    instanceId: number;
+}
+/**
+ * Spatial audio configuration options
+ */
+interface AudioSpatialOptions {
+    /** Maximum audible distance */
+    maxDistance?: number;
+    /** Reference distance (full volume) */
+    referenceDistance?: number;
+    /** Rolloff factor */
+    rolloffFactor?: number;
+    /** Pan spread (0-1) */
+    panSpread?: number;
+}
+/**
+ * Interface for audio playback processing
+ *
+ * Implemented by AudioManager in @utsp/audio.
+ * Used by User in @utsp/core to play sounds without direct dependency on AudioManager.
+ *
+ * This abstraction allows:
+ * - Standalone mode: ClientRuntime injects AudioManager
+ * - Connected mode: NetworkSync uses the same interface via User
+ * - No circular dependency: Core → Types ← Audio
+ *
+ * @example
+ * ```typescript
+ * // In ClientRuntime
+ * user.setAudioProcessor(audioManager);
+ *
+ * // In User.applyAudioCommands()
+ * this.audioProcessor?.play('coin', { volume: 0.8 });
+ * ```
+ */
+interface IAudioProcessor {
+    /**
+     * Play a sound by name or ID
+     * @param sound - Sound name (string) or ID (number)
+     * @param options - Playback options
+     * @returns Play result with instanceId, or null if sound not found
+     */
+    play(sound: string | number, options?: AudioPlayOptions): AudioPlayResult | null;
+    /**
+     * Stop sound(s) immediately
+     * @param target - Instance ID (number) to stop specific instance,
+     *                 or sound name (string) to stop all instances of that sound
+     * @returns Number of instances stopped
+     */
+    stop(target: number | string): number;
+    /**
+     * Fade out and stop sound(s)
+     * @param target - Instance ID (number) to fade specific instance,
+     *                 or sound name (string) to fade all instances of that sound,
+     *                 or 'all' to fade all sounds
+     * @param duration - Fade duration in seconds
+     * @returns Number of instances being faded
+     */
+    fadeOut(target: number | string | 'all', duration: number): number;
+    /**
+     * Stop all playing sounds immediately
+     * @returns Number of instances stopped
+     */
+    stopAll(): number;
+    /**
+     * Pause sound(s)
+     * @param target - Instance ID (number) to pause specific instance,
+     *                 or sound name (string) to pause all instances of that sound,
+     *                 or 'all' to pause all sounds
+     * @returns Number of instances paused
+     */
+    pause(target: number | string | 'all'): number;
+    /**
+     * Resume paused sound(s)
+     * @param target - Instance ID (number) to resume specific instance,
+     *                 or sound name (string) to resume all instances of that sound,
+     *                 or 'all' to resume all paused sounds
+     * @returns Number of instances resumed
+     */
+    resume(target: number | string | 'all'): number;
+    /**
+     * Set the listener position for spatial audio
+     * @param x - X position (0-65535)
+     * @param y - Y position (0-65535)
+     */
+    setListenerPosition(x: number, y: number): void;
+    /**
+     * Configure spatial audio parameters
+     * @param config - Spatial audio options
+     */
+    configureSpatial(config: AudioSpatialOptions): void;
+}
+/**
+ * Interface for loading sounds into the audio system
+ *
+ * Implemented by SoundBank in @utsp/audio.
+ * Abstracts the difference between Browser (Web Audio API) and Node.js environments.
+ *
+ * @example
+ * ```typescript
+ * // File mode - embedded data
+ * await soundLoader.loadFromData(0, 'coin', audioData);
+ *
+ * // External mode - URL
+ * await soundLoader.loadFromUrl(1, 'music', 'https://cdn.example.com/music.mp3');
+ * ```
+ */
+interface ISoundLoader {
+    /**
+     * Load a sound from binary data (File mode)
+     * @param soundId - Unique sound identifier (0-255)
+     * @param name - Human-readable name for playback
+     * @param data - Raw audio data (mp3, wav, ogg, etc.)
+     */
+    loadFromData(soundId: number, name: string, data: Uint8Array): Promise<void>;
+    /**
+     * Load a sound from a URL (External mode)
+     * @param soundId - Unique sound identifier (0-255)
+     * @param name - Human-readable name for playback
+     * @param url - URL to fetch the audio from
+     */
+    loadFromUrl(soundId: number, name: string, url: string): Promise<void>;
+    /**
+     * Check if a sound is loaded
+     * @param nameOrId - Sound name or ID
+     * @returns true if sound is loaded and ready to play
+     */
+    has(nameOrId: string | number): boolean;
+}
+
 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, AxisBinding, AxisSource, ButtonBinding, ButtonSource, ChatMessage, ClientInfo, ConnectionHandler, DisconnectionHandler, ErrorMessage, GamepadInputDescriptor, IApplication, IColorPalette, IInputSystem, INetworkClient, INetworkServer, IRenderer, InputBindingLoadPacket, InputDescriptor, InputEnum, InputMessage, JoinMessage, JoinResponseMessage, KeyboardInputDescriptor, LeaveMessage, LoadMessage, MessageType, MouseInputDescriptor, NetworkClientOptions, NetworkEventHandler, NetworkMessage, NetworkServerOptions, PingMessage, PongMessage, RGBColor, RenderState, RenderedCell, ServerEventHandler, TVRemoteInputDescriptor, TouchInputDescriptor, TypedInputDescriptor, UpdateMessage, UserMetadata, UserRenderState };
+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 };

package/package.json

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