@utsp/core 0.5.0-nightly.20251203194806.f816057 → 0.5.0-nightly.20251204224035.7a07d4b

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _utsp_types from '@utsp/types';
-import { Vector2, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, IAudioProcessor, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState } from '@utsp/types';
+import { Vector2, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, SetSoundEffectsCommand, IAudioProcessor, AudioAck, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState } from '@utsp/types';
 export { AxisBinding, AxisSource, ButtonBinding, ButtonSource, InputBindingLoadPacket, RenderState, RenderedCell, UserRenderState, Vector2 } from '@utsp/types';
 
 /**
@@ -148,6 +148,356 @@ declare class BitmapFont {
     getCharCodes(): number[];
 }
 
+/**
+ * UTSP Audio Order Types Enumeration
+ *
+ * Audio orders are separate from render orders and have their own type space.
+ * They are included in the UpdatePacket but processed by the AudioProcessor,
+ * not the Rasterizer.
+ *
+ * This separation ensures:
+ * - Clear distinction between visual and audio orders
+ * - Independent type numbering (0x01 audio ≠ 0x01 render)
+ * - Extensibility without conflicts
+ *
+ * @example
+ * ```typescript
+ * import { AudioOrderType } from '@utsp/core';
+ *
+ * const order = { type: AudioOrderType.PlaySound, soundId: 0, volume: 200 };
+ * ```
+ */
+declare enum AudioOrderType {
+    /**
+     * 0x01 - PlaySound: Play a sound with optional spatial position
+     *
+     * Parameters: soundId, instanceId, flags, volume?, pitch?, fadeIn?, posX?, posY?
+     */
+    PlaySound = 1,
+    /**
+     * 0x02 - PlayGlobalSound: Play a non-positional (global) sound
+     *
+     * Parameters: soundId, instanceId, flags, volume?, pitch?, fadeIn?
+     */
+    PlayGlobalSound = 2,
+    /**
+     * 0x03 - StopSound: Stop a sound immediately
+     *
+     * Parameters: targetType, target (instanceId, soundId, or 'all')
+     */
+    StopSound = 3,
+    /**
+     * 0x04 - FadeOutSound: Fade out and stop a sound
+     *
+     * Parameters: targetType, target, duration
+     */
+    FadeOutSound = 4,
+    /**
+     * 0x05 - PauseSound: Pause a playing sound
+     *
+     * Parameters: targetType, target
+     */
+    PauseSound = 5,
+    /**
+     * 0x06 - ResumeSound: Resume a paused sound
+     *
+     * Parameters: targetType, target
+     */
+    ResumeSound = 6,
+    /**
+     * 0x07 - SetListenerPosition: Set the listener position for spatial audio
+     *
+     * Parameters: x, y (16-bit each)
+     */
+    SetListenerPosition = 7,
+    /**
+     * 0x08 - ConfigureSpatial: Configure spatial audio parameters
+     *
+     * Parameters: maxDistance, referenceDistance, rolloffFactor, panSpread
+     */
+    ConfigureSpatial = 8,
+    /**
+     * 0x09 - SetSoundEffects: Set audio effects on a playing sound
+     *
+     * Parameters: instanceId, flags, lowpass?, highpass?, reverb?
+     */
+    SetSoundEffects = 9
+}
+/**
+ * Target type for stop/pause/resume/fadeout commands
+ */
+declare enum AudioTargetType {
+    /** Target a specific instance by ID */
+    InstanceId = 0,
+    /** Target all instances of a sound by soundId */
+    SoundId = 1,
+    /** Target all sounds */
+    All = 2
+}
+/**
+ * Type guard to check if a number is a valid AudioOrderType
+ */
+declare function isValidAudioOrderType(type: number): type is AudioOrderType;
+/**
+ * Get human-readable name for an AudioOrderType
+ */
+declare function getAudioOrderTypeName(type: AudioOrderType | number): string;
+
+/**
+ * UTSP Audio Orders
+ *
+ * Binary-encoded audio commands included in UpdatePacket.
+ * Processed by AudioProcessor on client, synchronized with render orders.
+ *
+ * Each order has a specific binary structure optimized for network transmission.
+ */
+
+/**
+ * Base interface for all audio orders
+ */
+interface AudioOrder {
+    /** Audio order type identifier */
+    type: AudioOrderType;
+}
+/**
+ * Flags for PlaySound/PlayGlobalSound orders
+ * Packed into a single byte to minimize bandwidth
+ */
+declare enum PlaySoundFlags {
+    /** Sound should loop */
+    Loop = 1,
+    /** Volume is specified (otherwise default 100%) */
+    HasVolume = 2,
+    /** Pitch is specified (otherwise default 1.0x) */
+    HasPitch = 4,
+    /** FadeIn duration is specified (otherwise instant) */
+    HasFadeIn = 8,
+    /** Position is specified (only for PlaySound, not PlayGlobalSound) */
+    HasPosition = 16,
+    /** Low-pass filter is specified */
+    HasLowpass = 32,
+    /** High-pass filter is specified */
+    HasHighpass = 64,
+    /** Reverb mix is specified */
+    HasReverb = 128
+}
+/**
+ * 0x01 - PlaySound: Play a sound with optional spatial position
+ *
+ * Binary structure (variable size, 4-15 bytes):
+ * - type: 1 byte (0x01)
+ * - soundId: 1 byte (0-255)
+ * - instanceId: 2 bytes (big-endian, unique ID for this playback)
+ * - flags: 1 byte (PlaySoundFlags bitfield)
+ * - volume?: 1 byte (0-255, maps to 0.0-1.0) - if HasVolume
+ * - pitch?: 1 byte (0-255, maps to 0.25x-4.0x, 128=1.0x) - if HasPitch
+ * - fadeIn?: 1 byte (0-255, duration in 1/10 seconds, 0=instant) - if HasFadeIn
+ * - posX?: 2 bytes (big-endian, 0-65535) - if HasPosition
+ * - posY?: 2 bytes (big-endian, 0-65535) - if HasPosition
+ * - lowpass?: 1 byte (0-255, * 100 = Hz cutoff) - if HasLowpass
+ * - highpass?: 1 byte (0-255, * 100 = Hz cutoff) - if HasHighpass
+ * - reverb?: 1 byte (0-255, / 255 = wet mix 0.0-1.0) - if HasReverb
+ */
+interface PlaySoundOrder extends AudioOrder {
+    type: AudioOrderType.PlaySound;
+    /** Sound ID (0-255) */
+    soundId: number;
+    /** Unique instance ID for this playback */
+    instanceId: number;
+    /** Flags bitfield */
+    flags: number;
+    /** Volume (0-255, maps to 0.0-1.0). Present if HasVolume flag set */
+    volume?: number;
+    /** Pitch (0-255, 128=1.0x). Present if HasPitch flag set */
+    pitch?: number;
+    /** Fade in duration in 1/10 seconds. Present if HasFadeIn flag set */
+    fadeIn?: number;
+    /** X position (0-65535). Present if HasPosition flag set */
+    posX?: number;
+    /** Y position (0-65535). Present if HasPosition flag set */
+    posY?: number;
+    /** Low-pass filter cutoff (0-255, * 100 = Hz). Present if HasLowpass flag set */
+    lowpass?: number;
+    /** High-pass filter cutoff (0-255, * 100 = Hz). Present if HasHighpass flag set */
+    highpass?: number;
+    /** Reverb wet mix (0-255, / 255 = 0.0-1.0). Present if HasReverb flag set */
+    reverb?: number;
+}
+/**
+ * 0x02 - PlayGlobalSound: Play a non-positional sound
+ *
+ * Binary structure (variable size, 4-10 bytes):
+ * - type: 1 byte (0x02)
+ * - soundId: 1 byte (0-255)
+ * - instanceId: 2 bytes (big-endian)
+ * - flags: 1 byte (PlaySoundFlags, but HasPosition is ignored)
+ * - volume?: 1 byte - if HasVolume
+ * - pitch?: 1 byte - if HasPitch
+ * - fadeIn?: 1 byte - if HasFadeIn
+ * - lowpass?: 1 byte - if HasLowpass
+ * - highpass?: 1 byte - if HasHighpass
+ * - reverb?: 1 byte - if HasReverb
+ */
+interface PlayGlobalSoundOrder extends AudioOrder {
+    type: AudioOrderType.PlayGlobalSound;
+    /** Sound ID (0-255) */
+    soundId: number;
+    /** Unique instance ID for this playback */
+    instanceId: number;
+    /** Flags bitfield (HasPosition ignored) */
+    flags: number;
+    /** Volume (0-255). Present if HasVolume flag set */
+    volume?: number;
+    /** Pitch (0-255, 128=1.0x). Present if HasPitch flag set */
+    pitch?: number;
+    /** Fade in duration in 1/10 seconds. Present if HasFadeIn flag set */
+    fadeIn?: number;
+    /** Low-pass filter cutoff (0-255, * 100 = Hz). Present if HasLowpass flag set */
+    lowpass?: number;
+    /** High-pass filter cutoff (0-255, * 100 = Hz). Present if HasHighpass flag set */
+    highpass?: number;
+    /** Reverb wet mix (0-255, / 255 = 0.0-1.0). Present if HasReverb flag set */
+    reverb?: number;
+}
+/**
+ * 0x03 - StopSound: Stop a sound immediately
+ *
+ * Binary structure (3-4 bytes):
+ * - type: 1 byte (0x03)
+ * - targetType: 1 byte (AudioTargetType)
+ * - target: 1-2 bytes (instanceId=2B, soundId=1B, all=0B)
+ */
+interface StopSoundOrder extends AudioOrder {
+    type: AudioOrderType.StopSound;
+    /** Type of target */
+    targetType: AudioTargetType;
+    /** Target value (instanceId, soundId, or undefined for 'all') */
+    target?: number;
+}
+/**
+ * 0x04 - FadeOutSound: Fade out and stop a sound
+ *
+ * Binary structure (4-5 bytes):
+ * - type: 1 byte (0x04)
+ * - targetType: 1 byte
+ * - duration: 1 byte (1/10 seconds, 0-25.5s)
+ * - target: 1-2 bytes
+ */
+interface FadeOutSoundOrder extends AudioOrder {
+    type: AudioOrderType.FadeOutSound;
+    /** Type of target */
+    targetType: AudioTargetType;
+    /** Fade duration in 1/10 seconds (0-255 = 0-25.5 seconds) */
+    duration: number;
+    /** Target value */
+    target?: number;
+}
+/**
+ * 0x05 - PauseSound: Pause a playing sound
+ *
+ * Binary structure (2-4 bytes):
+ * - type: 1 byte (0x05)
+ * - targetType: 1 byte
+ * - target: 0-2 bytes
+ */
+interface PauseSoundOrder extends AudioOrder {
+    type: AudioOrderType.PauseSound;
+    /** Type of target */
+    targetType: AudioTargetType;
+    /** Target value */
+    target?: number;
+}
+/**
+ * 0x06 - ResumeSound: Resume a paused sound
+ *
+ * Binary structure (2-4 bytes):
+ * - type: 1 byte (0x06)
+ * - targetType: 1 byte
+ * - target: 0-2 bytes
+ */
+interface ResumeSoundOrder extends AudioOrder {
+    type: AudioOrderType.ResumeSound;
+    /** Type of target */
+    targetType: AudioTargetType;
+    /** Target value */
+    target?: number;
+}
+/**
+ * 0x07 - SetListenerPosition: Set listener position for spatial audio
+ *
+ * Binary structure (5 bytes):
+ * - type: 1 byte (0x07)
+ * - x: 2 bytes (big-endian, 0-65535)
+ * - y: 2 bytes (big-endian, 0-65535)
+ */
+interface SetListenerPositionOrder extends AudioOrder {
+    type: AudioOrderType.SetListenerPosition;
+    /** X position (0-65535) */
+    x: number;
+    /** Y position (0-65535) */
+    y: number;
+}
+/**
+ * 0x08 - ConfigureSpatial: Configure spatial audio parameters
+ *
+ * Binary structure (5 bytes):
+ * - type: 1 byte (0x08)
+ * - maxDistance: 1 byte (0-255, scaled appropriately)
+ * - referenceDistance: 1 byte (0-255)
+ * - rolloffFactor: 1 byte (0-255, maps to 0.0-2.55)
+ * - panSpread: 1 byte (0-255, maps to 0.0-1.0)
+ */
+interface ConfigureSpatialOrder extends AudioOrder {
+    type: AudioOrderType.ConfigureSpatial;
+    /** Maximum audible distance (encoded, 0-255) */
+    maxDistance: number;
+    /** Reference distance for full volume (encoded, 0-255) */
+    referenceDistance: number;
+    /** Rolloff factor (0-255, maps to 0.0-2.55) */
+    rolloffFactor: number;
+    /** Pan spread factor (0-255, maps to 0.0-1.0) */
+    panSpread: number;
+}
+/**
+ * Flags for SetSoundEffects order
+ */
+declare enum SoundEffectsFlags {
+    /** Low-pass filter is specified */
+    HasLowpass = 1,
+    /** High-pass filter is specified */
+    HasHighpass = 2,
+    /** Reverb mix is specified */
+    HasReverb = 4
+}
+/**
+ * 0x09 - SetSoundEffects: Update audio effects on a playing sound
+ *
+ * Binary structure (variable size, 4-7 bytes):
+ * - type: 1 byte (0x09)
+ * - instanceId: 2 bytes (big-endian)
+ * - flags: 1 byte (SoundEffectsFlags bitfield)
+ * - lowpass?: 1 byte (0-255, * 100 = Hz cutoff) - if HasLowpass
+ * - highpass?: 1 byte (0-255, * 100 = Hz cutoff) - if HasHighpass
+ * - reverb?: 1 byte (0-255, / 255 = wet mix 0.0-1.0) - if HasReverb
+ */
+interface SetSoundEffectsOrder extends AudioOrder {
+    type: AudioOrderType.SetSoundEffects;
+    /** Target instance ID */
+    instanceId: number;
+    /** Flags bitfield */
+    flags: number;
+    /** Low-pass filter cutoff (0-255, * 100 = Hz). Present if HasLowpass flag set */
+    lowpass?: number;
+    /** High-pass filter cutoff (0-255, * 100 = Hz). Present if HasHighpass flag set */
+    highpass?: number;
+    /** Reverb wet mix (0-255, / 255 = 0.0-1.0). Present if HasReverb flag set */
+    reverb?: number;
+}
+/**
+ * Union of all audio order types
+ */
+type AnyAudioOrder = PlaySoundOrder | PlayGlobalSoundOrder | StopSoundOrder | FadeOutSoundOrder | PauseSoundOrder | ResumeSoundOrder | SetListenerPositionOrder | ConfigureSpatialOrder | SetSoundEffectsOrder;
+
 /**
  * Network representation of a display
  * Layers are NO LONGER under displays - they are at User level
@@ -557,12 +907,20 @@ interface NetworkLayer {
 
 /**
  * Update packet according to the new UTSP protocol
- * Layers are at the User level, not under displays
+ *
+ * Structure:
+ * - Tick (8 bytes): Frame counter for synchronization
+ * - Displays: Viewport definitions
+ * - Layers: Render orders for visual output
+ * - Audio Orders: Audio commands synchronized with the frame
+ *
+ * Audio orders are in the same packet as render orders to ensure
+ * perfect frame-level synchronization between visuals and sound.
  */
 interface UpdatePacket {
     /** Tick counter (8 bytes) */
     tick: number;
-    /** Number of displays (2 bytes) */
+    /** Number of displays (1 byte) */
     displayCount: number;
     /** List of displays with their origins */
     displays: NetworkDisplay[];
@@ -570,6 +928,10 @@ interface UpdatePacket {
     layerCount: number;
     /** List of layers (shared across all displays) */
     layers: NetworkLayer[];
+    /** Number of audio orders (1 byte) */
+    audioOrderCount: number;
+    /** List of audio orders (synchronized with this frame) */
+    audioOrders: AnyAudioOrder[];
 }
 
 /**
@@ -1580,6 +1942,9 @@ declare class User<TData = Record<string, any>> {
     private lastListenerY;
     private pendingSendSounds;
     private audioProcessor?;
+    private loadedSounds;
+    private soundLoadErrors;
+    private playingSounds;
     /**
      * Application-specific data storage
      * Use this to store game state, player data, or any custom information
@@ -2243,6 +2608,9 @@ declare class User<TData = Record<string, any>> {
      *
      * // Spatial audio (x/y position 0-65535)
      * user.playSound('explosion', { x: 10000, y: 32768 });
+     *
+     * // With audio effects
+     * user.playSound('voice', { lowpass: 2000, reverb: 0.3 });
      * ```
      */
     playSound(sound: string | number, options?: {
@@ -2252,6 +2620,12 @@ declare class User<TData = Record<string, any>> {
         fadeIn?: number;
         x?: number;
         y?: number;
+        /** Low-pass filter cutoff in Hz (100-25500, 0 = disabled) */
+        lowpass?: number;
+        /** High-pass filter cutoff in Hz (100-25500, 0 = disabled) */
+        highpass?: number;
+        /** Reverb wet/dry mix (0.0-1.0, 0 = disabled) */
+        reverb?: number;
     }): SoundInstanceId;
     /**
      * Stop a sound immediately by instance ID or name
@@ -2365,6 +2739,34 @@ declare class User<TData = Record<string, any>> {
      * ```
      */
     resumeAllSounds(): void;
+    /**
+     * Set audio effects on a playing sound instance
+     *
+     * This allows updating filters and reverb on a sound that's already playing.
+     * Pass 0 to disable a specific effect, or omit it to leave unchanged.
+     *
+     * @param instanceId - The instance ID returned by playSound()
+     * @param options - Effects to set
+     *
+     * @example
+     * ```typescript
+     * const musicId = user.playSound('music', { loop: true });
+     *
+     * // Later, add effects when entering a cave
+     * user.setSoundEffects(musicId, { lowpass: 1500, reverb: 0.5 });
+     *
+     * // Remove effects when leaving the cave
+     * user.setSoundEffects(musicId, { lowpass: 0, reverb: 0 });
+     * ```
+     */
+    setSoundEffects(instanceId: SoundInstanceId, options: {
+        /** Low-pass filter cutoff in Hz (100-25500, 0 = disabled) */
+        lowpass?: number;
+        /** High-pass filter cutoff in Hz (100-25500, 0 = disabled) */
+        highpass?: number;
+        /** Reverb wet/dry mix (0.0-1.0, 0 = disabled) */
+        reverb?: number;
+    }): void;
     /**
      * Set the listener position for spatial audio
      *
@@ -2430,7 +2832,7 @@ declare class User<TData = Record<string, any>> {
      * @returns Array of sound commands to send
      * @internal
      */
-    flushSoundCommands(): Array<PlaySoundCommand | StopSoundCommand | FadeOutSoundCommand | PauseSoundCommand | ResumeSoundCommand>;
+    flushSoundCommands(): Array<PlaySoundCommand | StopSoundCommand | FadeOutSoundCommand | PauseSoundCommand | ResumeSoundCommand | SetSoundEffectsCommand>;
     /**
      * Check if there are pending sound commands
      *
@@ -2509,7 +2911,7 @@ declare class User<TData = Record<string, any>> {
      * @param commands - Array of sound commands
      * @internal
      */
-    applyAudioCommands(commands: Array<PlaySoundCommand | StopSoundCommand | FadeOutSoundCommand | PauseSoundCommand | ResumeSoundCommand>): void;
+    applyAudioCommands(commands: Array<PlaySoundCommand | StopSoundCommand | FadeOutSoundCommand | PauseSoundCommand | ResumeSoundCommand | SetSoundEffectsCommand>): void;
     /**
      * Apply audio configuration commands (listener position, spatial config)
      *
@@ -2523,6 +2925,88 @@ declare class User<TData = Record<string, any>> {
      * @internal
      */
     applyAudioConfigCommands(commands: AudioConfigCommand[]): void;
+    /**
+     * Apply audio orders from an UpdatePacket (BINARY PROTOCOL)
+     *
+     * This method processes decoded audio orders from the binary UpdatePacket.
+     * Audio orders use soundId (number) rather than sound names for efficiency.
+     *
+     * Order types:
+     * - PlaySound/PlayGlobalSound: Play a sound
+     * - StopSound: Stop a sound
+     * - FadeOutSound: Fade out and stop
+     * - PauseSound: Pause playback
+     * - ResumeSound: Resume playback
+     * - SetListenerPosition: Set listener for spatial audio
+     * - ConfigureSpatial: Configure spatial audio parameters
+     *
+     * @param orders - Array of decoded audio orders from UpdatePacket
+     * @internal
+     */
+    applyAudioOrders(orders: AnyAudioOrder[]): void;
+    /**
+     * Handle an audio ACK from the client
+     *
+     * Called by ServerRuntime when receiving 'audio-ack' messages.
+     * Updates internal tracking of the client's audio state.
+     *
+     * @param ack - The audio acknowledgment
+     * @internal
+     */
+    handleAudioAck(ack: AudioAck): void;
+    /**
+     * Check if a sound is loaded on the client
+     *
+     * @param soundId - The sound ID to check
+     * @returns true if the sound is loaded
+     */
+    isSoundLoaded(soundId: number): boolean;
+    /**
+     * Check if a sound failed to load on the client
+     *
+     * @param soundId - The sound ID to check
+     * @returns Error message if failed, undefined otherwise
+     */
+    getSoundLoadError(soundId: number): string | undefined;
+    /**
+     * Get all loaded sounds on the client
+     *
+     * @returns Map of soundId to load info
+     */
+    getLoadedSounds(): ReadonlyMap<number, {
+        name: string;
+        loadedAt: number;
+    }>;
+    /**
+     * Get all sound load errors
+     *
+     * @returns Map of soundId to error info
+     */
+    getSoundLoadErrors(): ReadonlyMap<number, {
+        name: string;
+        error: string;
+        at: number;
+    }>;
+    /**
+     * Check if a sound instance is currently playing on the client
+     *
+     * @param instanceId - The instance ID to check
+     * @returns true if the instance is playing
+     */
+    isSoundPlaying(instanceId: SoundInstanceId): boolean;
+    /**
+     * Get all currently playing sounds on the client
+     *
+     * @returns Map of instanceId to playback info
+     */
+    getPlayingSounds(): ReadonlyMap<SoundInstanceId, {
+        soundId: number;
+        startedAt: number;
+    }>;
+    /**
+     * Get the number of sounds currently playing on the client
+     */
+    getPlayingSoundCount(): number;
 }
 
 /**
@@ -2998,6 +3482,7 @@ declare class Core {
     private webFontRegistry;
     private bitmapFontRegistry;
     private soundRegistry;
+    private audioOrderCollector;
     private activeWebFontId;
     private _renderCallCount;
     private onPaletteChangedCallback?;
@@ -5094,6 +5579,15 @@ declare const FILLSPRITE_ORDER_SIZE = 4;
 declare const FILLSPRITE_MULTICOLOR_ORDER_SIZE = 2;
 declare const TRIGGERSOUND_ORDER_SIZE = 5;
 declare const TRIGGERGLOBALSOUND_ORDER_SIZE = 3;
+declare const AUDIO_PLAY_SOUND_MIN_SIZE = 5;
+declare const AUDIO_PLAY_GLOBAL_SOUND_MIN_SIZE = 5;
+declare const AUDIO_STOP_SOUND_MIN_SIZE = 2;
+declare const AUDIO_FADEOUT_SOUND_MIN_SIZE = 3;
+declare const AUDIO_PAUSE_SOUND_MIN_SIZE = 2;
+declare const AUDIO_RESUME_SOUND_MIN_SIZE = 2;
+declare const AUDIO_SET_LISTENER_POSITION_SIZE = 5;
+declare const AUDIO_CONFIGURE_SPATIAL_SIZE = 5;
+declare const AUDIO_SET_SOUND_EFFECTS_MIN_SIZE = 4;
 
 /**
  * UTSP Order Types Enumeration
@@ -5398,6 +5892,7 @@ declare namespace UpdateFlagsHelper {
 declare class UpdatePacketDecoder {
     private displayDecoder;
     private layerDecoder;
+    private audioOrderDecoder;
     constructor();
     /**
      * Decodes an UpdatePacket from binary buffer
@@ -5408,8 +5903,10 @@ declare class UpdatePacketDecoder {
      * - Displays: variable (DisplayId + OriginX + OriginY + SizeX + SizeY = 7 bytes each)
      * - LayerCount: 2 bytes (big-endian, 16-bit unsigned integer)
      * - Layers: variable (encoded layers)
+     * - AudioOrderCount: 1 byte (max 255 audio orders)
+     * - AudioOrders: variable (encoded audio orders)
      *
-     * Minimum packet size: 11 bytes (Tick + DisplayCount + LayerCount)
+     * Minimum packet size: 12 bytes (Tick + DisplayCount + LayerCount + AudioOrderCount)
      */
     decode(data: Uint8Array, offset?: number): UpdatePacket;
     /**
@@ -5418,16 +5915,254 @@ declare class UpdatePacketDecoder {
      */
     isValid(data: Uint8Array, offset?: number): boolean;
     /**
-     * Decodes only the tick and counts without decoding the displays/layers
+     * Decodes only the tick and counts without decoding the displays/layers/audio
      * Useful for quick inspection of packet metadata
      */
     decodeHeader(data: Uint8Array, offset?: number): {
         tick: number;
         displayCount: number;
         layerCount: number;
+        audioOrderCount?: number;
     };
     private checkSize;
 }
 
-export { ASCII_8X8_FONT, BITMASK16_ORDER_MIN_SIZE, BITMASK4_ORDER_MIN_SIZE, BITMASK_ORDER_MIN_SIZE, BitmapFont, BitmapFontRegistry, CHAR_ORDER_SIZE, CIRCLE_SHAPE_SIZE, CLEAR_ORDER_SIZE, COLORMAP_ORDER_MIN_SIZE, COLOR_SKIP, CellBuffer, CharCodeBuffer, Core, CoreStats, DISPLAY_HEADER_SIZE, DOTCLOUD_MULTICOLOR_ORDER_MIN_SIZE, DOTCLOUD_ORDER_MIN_SIZE, Display, ELLIPSE_SHAPE_SIZE, FILLCHAR_ORDER_MIN_SIZE, FILLSPRITE_MULTICOLOR_ORDER_SIZE, FILLSPRITE_ORDER_SIZE, FULLFRAME_MULTICOLOR_ORDER_MIN_SIZE, FULLFRAME_ORDER_MIN_SIZE, FontType, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, OrderBuilder, OrderType, RECTANGLE_SHAPE_SIZE, SHAPE_ORDER_MIN_SIZE, SPRITECLOUD_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_ORDER_MIN_SIZE, SPRITE_MULTICOLOR_ORDER_SIZE, SPRITE_ORDER_SIZE, SUBFRAME_MULTICOLOR_ORDER_MIN_SIZE, SUBFRAME_ORDER_MIN_SIZE, ShapeType, SoundRegistry, SpriteRegistry, TEXT_MULTILINE_ORDER_MIN_SIZE, TEXT_ORDER_MIN_SIZE, TRIANGLE_SHAPE_SIZE, TRIGGERGLOBALSOUND_ORDER_SIZE, TRIGGERSOUND_ORDER_SIZE, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, WebFont, WebFontRegistry, createASCII8x8FontLoad, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getOrderTypeName, hasChar, isValidOrderType };
-export type { AnyLoad, BitmapFontConfig, BitmapFontLoad, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, Cell, CircleShape, Color, ColorPaletteLoad, CompressedInputPacket, CoreMode, CoreOptions, EllipseShape, LineShape, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, RectangleShape, ShapeData, SoundEntry, SoundLoad, SpriteLoad, TickStats, TriangleShape, UnicolorSprite, UpdatePacket, UserTickStats, WebFontConfig, WebFontLoad };
+/**
+ * BufferCompat - Node.js AND browser compatible abstraction
+ *
+ * Replaces Buffer (Node.js only) with Uint8Array + DataView
+ * which are standard APIs available everywhere.
+ */
+/**
+ * Cross-platform compatible class for manipulating binary data
+ * Uses Uint8Array (standard) instead of Buffer (Node.js only)
+ */
+declare class BufferCompat {
+    private data;
+    private view;
+    constructor(size: number);
+    /**
+     * Creates a BufferCompat from an existing Uint8Array
+     */
+    static from(array: Uint8Array): BufferCompat;
+    /**
+     * Allocates an uninitialized buffer (equivalent to Buffer.allocUnsafe)
+     */
+    static allocUnsafe(size: number): BufferCompat;
+    /**
+     * Returns the buffer length
+     */
+    get length(): number;
+    /**
+     * Returns the underlying Uint8Array
+     */
+    toUint8Array(): Uint8Array;
+    readUInt8(offset: number): number;
+    readInt8(offset: number): number;
+    readUInt16BE(offset: number): number;
+    readInt16BE(offset: number): number;
+    readUInt16LE(offset: number): number;
+    readInt16LE(offset: number): number;
+    readUInt32BE(offset: number): number;
+    readInt32BE(offset: number): number;
+    readUInt32LE(offset: number): number;
+    readInt32LE(offset: number): number;
+    readBigUInt64BE(offset: number): bigint;
+    readBigInt64BE(offset: number): bigint;
+    readBigUInt64LE(offset: number): bigint;
+    readBigInt64LE(offset: number): bigint;
+    writeUInt8(value: number, offset: number): void;
+    writeInt8(value: number, offset: number): void;
+    writeUInt16BE(value: number, offset: number): void;
+    writeInt16BE(value: number, offset: number): void;
+    writeUInt16LE(value: number, offset: number): void;
+    writeInt16LE(value: number, offset: number): void;
+    writeUInt32BE(value: number, offset: number): void;
+    writeInt32BE(value: number, offset: number): void;
+    writeUInt32LE(value: number, offset: number): void;
+    writeInt32LE(value: number, offset: number): void;
+    writeBigUInt64BE(value: bigint, offset: number): void;
+    writeBigInt64BE(value: bigint, offset: number): void;
+    writeBigUInt64LE(value: bigint, offset: number): void;
+    writeBigInt64LE(value: bigint, offset: number): void;
+    /**
+     * Copies data from this buffer to another
+     * @param target Destination buffer
+     * @param targetStart Starting position in destination buffer
+     * @param sourceStart Starting position in this buffer (optional)
+     * @param sourceEnd Ending position in this buffer (optional)
+     */
+    copy(target: BufferCompat, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;
+    /**
+     * Returns a portion of the buffer
+     */
+    slice(start?: number, end?: number): BufferCompat;
+    /**
+     * Returns a view on a portion of the buffer (without copying)
+     */
+    subarray(start?: number, end?: number): BufferCompat;
+    /**
+     * Converts to Node.js Buffer (if available) or returns the Uint8Array
+     */
+    toBuffer(): Buffer | Uint8Array;
+    /**
+     * Creates a BufferCompat from a Node.js Buffer or Uint8Array
+     */
+    static fromNodeBuffer(buffer: Buffer | Uint8Array): BufferCompat;
+}
+
+/**
+ * UTSP Audio Order Decoder
+ *
+ * Decodes audio orders from binary format received in UpdatePacket.
+ * Audio orders are processed by AudioProcessor on client, not Rasterizer.
+ */
+
+/**
+ * Result of decoding an audio order from a buffer
+ */
+interface AudioDecodeResult<T = AnyAudioOrder> {
+    order: T;
+    bytesRead: number;
+}
+/**
+ * Decoder for UTSP audio orders
+ * Converts binary buffers to audio order interfaces
+ */
+declare class AudioOrderDecoder {
+    /**
+     * Main entry point - decodes any audio order type from binary buffer
+     * Returns the decoded order and the number of bytes consumed
+     */
+    decode(buffer: BufferCompat, offset?: number): AudioDecodeResult;
+    private decodePlaySoundOrder;
+    private decodePlayGlobalSoundOrder;
+    private decodeStopSoundOrder;
+    private decodeFadeOutSoundOrder;
+    private decodePauseSoundOrder;
+    private decodeResumeSoundOrder;
+    private decodeSetListenerPositionOrder;
+    private decodeConfigureSpatialOrder;
+    private decodeSetSoundEffectsOrder;
+    private checkSize;
+}
+
+/**
+ * AudioOrderCollector - Converts high-level audio commands to binary AudioOrders
+ *
+ * This class bridges the gap between the User's high-level audio API
+ * (playSound, stopSound, etc.) and the binary AudioOrder protocol.
+ *
+ * It takes SoundRegistry to resolve sound names to IDs, and produces
+ * AudioOrders ready for binary encoding in UpdatePacket.
+ *
+ * @example
+ * ```typescript
+ * const collector = new AudioOrderCollector(soundRegistry);
+ *
+ * // Convert User's pending commands to orders
+ * const audioOrders = collector.collectFromUser(user);
+ *
+ * // audioOrders can now be added to UpdatePacket
+ * ```
+ */
+
+/**
+ * Collects and converts audio commands to binary AudioOrders
+ */
+declare class AudioOrderCollector {
+    private soundRegistry;
+    constructor(soundRegistry: SoundRegistry);
+    /**
+     * Collect all pending audio orders from a user
+     *
+     * This flushes the user's sound and config command queues,
+     * converts them to binary AudioOrders, and returns them.
+     *
+     * @param user - The user to collect orders from
+     * @returns Array of AudioOrders ready for encoding
+     */
+    collectFromUser(user: User): AnyAudioOrder[];
+    /**
+     * Convert a sound command to an AudioOrder
+     */
+    private convertSoundCommand;
+    /**
+     * Convert PlaySoundCommand to PlaySoundOrder or PlayGlobalSoundOrder
+     */
+    private convertPlayCommand;
+    /**
+     * Convert StopSoundCommand to StopSoundOrder
+     */
+    private convertStopCommand;
+    /**
+     * Convert FadeOutSoundCommand to FadeOutSoundOrder
+     */
+    private convertFadeOutCommand;
+    /**
+     * Convert PauseSoundCommand to PauseSoundOrder
+     */
+    private convertPauseCommand;
+    /**
+     * Convert ResumeSoundCommand to ResumeSoundOrder
+     */
+    private convertResumeCommand;
+    /**
+     * Convert SetSoundEffectsCommand to SetSoundEffectsOrder
+     */
+    private convertSetEffectsCommand;
+    /**
+     * Convert AudioConfigCommand to SetListenerPositionOrder or ConfigureSpatialOrder
+     */
+    private convertConfigCommand;
+    /**
+     * Resolve sound name or ID to a numeric soundId
+     */
+    private resolveSoundId;
+    /**
+     * Resolve target (instanceId, soundName, or 'all') to targetType and value
+     */
+    private resolveTarget;
+    /**
+     * Encode volume (0.0-1.0) to byte (0-255)
+     */
+    private encodeVolume;
+    /**
+     * Encode pitch (0.25x-4.0x) to byte (0-255, 128=1.0x)
+     * Formula: pitch = 0.25 * 2^(byte/64)
+     * Inverse: byte = 64 * log2(pitch / 0.25)
+     */
+    private encodePitch;
+    /**
+     * Encode fade time (seconds) to byte (1/10 seconds, 0-25.5s)
+     */
+    private encodeFadeTime;
+    /**
+     * Encode distance for spatial audio (scale: 0-25500 → 0-255)
+     */
+    private encodeDistance;
+    /**
+     * Encode rolloff factor (0.0-2.55 → 0-255)
+     */
+    private encodeRolloff;
+    /**
+     * Encode pan spread (0.0-1.0 → 0-255)
+     */
+    private encodePanSpread;
+    /**
+     * Encode position coordinate for spatial audio (clamp to 0-65535 for Uint16)
+     */
+    private encodePosition;
+    /**
+     * Encode filter frequency (100-25500 Hz) to byte (1-255, * 100 = Hz)
+     * 0 means disabled
+     */
+    private encodeFilterFreq;
+    /**
+     * Encode reverb wet mix (0.0-1.0) to byte (0-255)
+     */
+    private encodeReverb;
+}
+
+export { ASCII_8X8_FONT, AUDIO_CONFIGURE_SPATIAL_SIZE, AUDIO_FADEOUT_SOUND_MIN_SIZE, AUDIO_PAUSE_SOUND_MIN_SIZE, AUDIO_PLAY_GLOBAL_SOUND_MIN_SIZE, AUDIO_PLAY_SOUND_MIN_SIZE, AUDIO_RESUME_SOUND_MIN_SIZE, AUDIO_SET_LISTENER_POSITION_SIZE, AUDIO_SET_SOUND_EFFECTS_MIN_SIZE, AUDIO_STOP_SOUND_MIN_SIZE, AudioOrderCollector, AudioOrderDecoder, AudioOrderType, AudioTargetType, BITMASK16_ORDER_MIN_SIZE, BITMASK4_ORDER_MIN_SIZE, BITMASK_ORDER_MIN_SIZE, BitmapFont, BitmapFontRegistry, CHAR_ORDER_SIZE, CIRCLE_SHAPE_SIZE, CLEAR_ORDER_SIZE, COLORMAP_ORDER_MIN_SIZE, COLOR_SKIP, CellBuffer, CharCodeBuffer, Core, CoreStats, DISPLAY_HEADER_SIZE, DOTCLOUD_MULTICOLOR_ORDER_MIN_SIZE, DOTCLOUD_ORDER_MIN_SIZE, Display, ELLIPSE_SHAPE_SIZE, FILLCHAR_ORDER_MIN_SIZE, FILLSPRITE_MULTICOLOR_ORDER_SIZE, FILLSPRITE_ORDER_SIZE, FULLFRAME_MULTICOLOR_ORDER_MIN_SIZE, FULLFRAME_ORDER_MIN_SIZE, FontType, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, OrderBuilder, OrderType, PlaySoundFlags, RECTANGLE_SHAPE_SIZE, SHAPE_ORDER_MIN_SIZE, SPRITECLOUD_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_MULTICOLOR_ORDER_MIN_SIZE, SPRITECLOUD_VARIED_ORDER_MIN_SIZE, SPRITE_MULTICOLOR_ORDER_SIZE, SPRITE_ORDER_SIZE, SUBFRAME_MULTICOLOR_ORDER_MIN_SIZE, SUBFRAME_ORDER_MIN_SIZE, ShapeType, SoundEffectsFlags, SoundRegistry, SpriteRegistry, TEXT_MULTILINE_ORDER_MIN_SIZE, TEXT_ORDER_MIN_SIZE, TRIANGLE_SHAPE_SIZE, TRIGGERGLOBALSOUND_ORDER_SIZE, TRIGGERSOUND_ORDER_SIZE, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, WebFont, WebFontRegistry, createASCII8x8FontLoad, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getAudioOrderTypeName, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getOrderTypeName, hasChar, isValidAudioOrderType, isValidOrderType };
+export type { AnyAudioOrder, AnyLoad, AudioOrder, BitmapFontConfig, BitmapFontLoad, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, Cell, CircleShape, Color, ColorPaletteLoad, CompressedInputPacket, ConfigureSpatialOrder, CoreMode, CoreOptions, EllipseShape, FadeOutSoundOrder, LineShape, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, PauseSoundOrder, PlayGlobalSoundOrder, PlaySoundOrder, RectangleShape, ResumeSoundOrder, SetListenerPositionOrder, SetSoundEffectsOrder, ShapeData, SoundEntry, SoundLoad, SpriteLoad, StopSoundOrder, TickStats, TriangleShape, UnicolorSprite, UpdatePacket, UserTickStats, WebFontConfig, WebFontLoad };