@utsp/core 0.14.0 → 0.14.2

package/dist/benchmark.d.ts

@@ -1,5 +1,5 @@
 import * as _utsp_types from '@utsp/types';
-import { ScalingModeValue, Vector2, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, SetSoundEffectsCommand, IAudioProcessor, VibrationPattern, GamepadVibrationOptions, GamepadVibrationCommand, IGamepadVibrationProcessor, MobileVibrationCommand, IMobileVibrationProcessor, AudioAck, PostProcessConfig, PostProcessCommand, ScalingMode, GridConfig, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState, RenderState } from '@utsp/types';
+import { ScalingModeValue, Vector2, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, TouchZoneBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, SetSoundEffectsCommand, IAudioProcessor, VibrationPattern, GamepadVibrationOptions, GamepadVibrationCommand, IGamepadVibrationProcessor, MobileVibrationCommand, IMobileVibrationProcessor, AudioAck, PostProcessConfig, PostProcessCommand, ScalingMode, GridConfig, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState, RenderState } from '@utsp/types';
 export { Vector2 } from '@utsp/types';
 
 /**
@@ -3905,14 +3905,17 @@ declare class MacroRegistry {
  *
  * Allows to:
  * - Define axes and buttons (bindingId → name)
+ * - Define touch zones (virtual screen regions for mobile)
  * - Generate a JSON LoadPacket to send to client
  * - Decode compressed inputs received from client (future)
  */
 declare class InputBindingRegistry {
     private axes;
     private buttons;
+    private touchZones;
     private axisNameToId;
     private buttonNameToId;
+    private touchZoneNameToId;
     private version;
     /**
      * Defines an axis binding
@@ -3956,6 +3959,44 @@ declare class InputBindingRegistry {
      * ```
      */
     defineButton(bindingId: number, name: string, sources?: ButtonSource[], defaultValue?: boolean): void;
+    /**
+     * Defines a touch zone (virtual screen region for mobile touch input)
+     *
+     * Touch zones allow you to define regions of the screen that act as
+     * virtual buttons or joysticks. Each zone has:
+     * - A button state (pressed when any touch is in the zone)
+     * - X/Y axis values (last touch position within the zone, normalized to cell coords)
+     *
+     * @param zoneId - Unique zone ID (0-31)
+     * @param name - Zone name (e.g., "DPadUp", "ButtonA", "LeftJoystick")
+     * @param x - X position in grid cells
+     * @param y - Y position in grid cells
+     * @param width - Width in grid cells
+     * @param height - Height in grid cells
+     * @throws Error if zoneId or name already exists
+     *
+     * @example
+     * ```typescript
+     * // D-pad buttons (bottom-left corner)
+     * registry.defineTouchZone(0, "DPadUp", 2, 16, 4, 4);
+     * registry.defineTouchZone(1, "DPadDown", 2, 24, 4, 4);
+     * registry.defineTouchZone(2, "DPadLeft", 0, 20, 4, 4);
+     * registry.defineTouchZone(3, "DPadRight", 6, 20, 4, 4);
+     *
+     * // Action button (bottom-right)
+     * registry.defineTouchZone(4, "ButtonA", 74, 20, 6, 6);
+     *
+     * // Virtual joystick (large touch area)
+     * registry.defineTouchZone(10, "LeftJoystick", 0, 12, 20, 16);
+     *
+     * // Then bind them in button/axis sources:
+     * registry.defineButton(0, "Up", [
+     *   { sourceId: 0, type: InputDeviceType.Keyboard, key: KeyboardInput.ArrowUp },
+     *   { sourceId: 100, type: InputDeviceType.TouchZone, touchZoneId: 0 },
+     * ]);
+     * ```
+     */
+    defineTouchZone(zoneId: number, name: string, x: number, y: number, width: number, height: number): void;
     /**
      * Evaluates an axis by summing all its sources
      *
@@ -4106,6 +4147,13 @@ declare class InputBindingRegistry {
      * @returns true if defined
      */
     hasButton(bindingId: number): boolean;
+    /**
+     * Checks if a touch zone is defined
+     *
+     * @param zoneId - Zone ID
+     * @returns true if defined
+     */
+    hasTouchZone(zoneId: number): boolean;
     /**
      * Counts the number of defined axes
      *
@@ -4118,6 +4166,12 @@ declare class InputBindingRegistry {
      * @returns number of buttons
      */
     getButtonCount(): number;
+    /**
+     * Counts the number of defined touch zones
+     *
+     * @returns number of touch zones
+     */
+    getTouchZoneCount(): number;
     /**
      * Retrieves all axes
      *
@@ -4130,6 +4184,26 @@ declare class InputBindingRegistry {
      * @returns array of all button bindings
      */
     getAllButtons(): ButtonBinding[];
+    /**
+     * Retrieves all touch zones
+     *
+     * @returns array of all touch zone bindings
+     */
+    getAllTouchZones(): TouchZoneBinding[];
+    /**
+     * Retrieves a touch zone by ID
+     *
+     * @param zoneId - Zone ID
+     * @returns zone binding or null if not found
+     */
+    getTouchZone(zoneId: number): TouchZoneBinding | null;
+    /**
+     * Retrieves a touch zone ID from its name
+     *
+     * @param name - Zone name
+     * @returns zoneId or null if not found
+     */
+    getTouchZoneId(name: string): number | null;
     /**
      * Retrieves the current binding version
      *
@@ -4150,6 +4224,13 @@ declare class InputBindingRegistry {
      * @returns true if removed, false if not found
      */
     removeButton(bindingId: number): boolean;
+    /**
+     * Removes a touch zone
+     *
+     * @param zoneId - Zone ID to remove
+     * @returns true if removed, false if not found
+     */
+    removeTouchZone(zoneId: number): boolean;
     /**
      * Removes all axes
      */
@@ -4158,6 +4239,10 @@ declare class InputBindingRegistry {
      * Removes all buttons
      */
     clearButtons(): void;
+    /**
+     * Removes all touch zones
+     */
+    clearTouchZones(): void;
     /**
      * Completely resets the registry
      */
@@ -5726,6 +5811,40 @@ declare class User<TData = Record<string, any>> {
      * Get the number of sounds currently playing on the client
      */
     getPlayingSoundCount(): number;
+    /**
+     * Get audio loading state for this client
+     *
+     * Provides a summary of the client's audio loading progress,
+     * useful for showing loading screens or progress bars.
+     *
+     * @param totalExpected - Total number of sounds expected (from SoundRegistry)
+     * @returns Audio loading state
+     *
+     * @example
+     * ```typescript
+     * updateUser(core: Core, user: User): void {
+     *   const totalSounds = core.getSoundRegistry().getAll().length;
+     *   const audioState = user.getAudioLoadingState(totalSounds);
+     *
+     *   if (!audioState.isComplete) {
+     *     // Client still loading sounds
+     *     console.log(`Loading: ${audioState.loadedCount}/${audioState.totalExpected}`);
+     *   }
+     * }
+     * ```
+     */
+    getAudioLoadingState(totalExpected: number): {
+        /** Number of sounds successfully loaded on client */
+        loadedCount: number;
+        /** Total number of sounds expected */
+        totalExpected: number;
+        /** Number of sounds that failed to load */
+        errorCount: number;
+        /** Whether all expected sounds are loaded */
+        isComplete: boolean;
+        /** Names of sounds that failed to load */
+        errors: string[];
+    };
     /**
      * Load a macro template
      * The template will be sent to the client in the next config packet
@@ -7265,38 +7384,22 @@ declare class Core {
      *
      * This method:
      * 1. Encodes displays and layers of each user into binary packets
-     * 2. Increments tick counter
-     * 3. Returns a Map with packets ready to send
-     *
-     * Server/client can then send these packets over the network
-     *
-     * @returns Map<userId, packet> - Encoded packets for each user
-     *
-     * @example
-     * ```typescript
-     * const packets = engine.endTick();
-     * packets.forEach((packet, userId) => {
-     *   networkSend(userId, packet);
-     * });
-     * ```
-     */
-    endTick(): Map<string, Uint8Array>;
-    /**
-     * Ends tick and generates SEPARATE packets for static and dynamic layers
-     *
-     * This method allows sending:
-     * - STATIC Layers on a reliable Socket.IO channel (guaranteed delivery)
-     * - DYNAMIC Layers on a volatile Socket.IO channel (can drop packets)
+     * 2. Only sends layers that have called commit() (optimization)
+     * 3. Separates static and dynamic layers for network optimization
+     * 4. Increments tick counter
+     * 5. Returns a Map with split packets ready to send
      *
-     * Optimization: Static layers (background, pattern) must arrive,
-     * but dynamic layers (particles, trail) can skip frames.
+     * Network strategy:
+     * - STATIC Layers → Reliable channel (guaranteed delivery)
+     * - DYNAMIC Layers → Volatile channel (can drop packets for performance)
+     * - Audio/Vibration/Macro/PostProcess orders → Only in dynamic packet
      *
      * @returns Map<userId, { static: Uint8Array | null, dynamic: Uint8Array | null }>
      *
      * @example
      * ```typescript
-     * const splitPackets = engine.endTickSplit();
-     * splitPackets.forEach(({ static: staticPacket, dynamic: dynamicPacket }, userId) => {
+     * const packets = engine.endTick();
+     * packets.forEach(({ static: staticPacket, dynamic: dynamicPacket }, userId) => {
      *   if (staticPacket) {
      *     network.sendToClient(userId, 'update-static', staticPacket); // Reliable
      *   }
@@ -7306,7 +7409,7 @@ declare class Core {
      * });
      * ```
      */
-    endTickSplit(): Map<string, {
+    endTick(): Map<string, {
         static: Uint8Array | null;
         dynamic: Uint8Array | null;
     }>;
@@ -7589,6 +7692,25 @@ declare class Core {
      * @returns Array of encoded MacroLoad packets
      */
     generateMacroLoadPackets(userId: string): Uint8Array[];
+    /**
+     * Generates an initial update packet for a specific user (SERVER-SIDE)
+     *
+     * This is used to send any pending PostProcessCommands (like switchPalette)
+     * that were created during initUser() but before the first regular tick.
+     *
+     * @param userId - Target user ID
+     * @returns Encoded update packet, or null if no pending commands
+     *
+     * @example
+     * ```typescript
+     * // Server side - after initUser and load packets
+     * const initialPacket = core.generateInitialUpdatePacket(clientId);
+     * if (initialPacket) {
+     *   socket.emit('update', initialPacket);
+     * }
+     * ```
+     */
+    generateInitialUpdatePacket(userId: string): Uint8Array | null;
     /**
      * Applies Input Bindings to a user (CLIENT-SIDE)
      *
@@ -8763,14 +8885,19 @@ declare class Layer {
      * ```
      */
     commit(): void;
+    /**
+     * Returns a breakdown of order types for debugging
+     * @internal
+     */
+    private getOrdersBreakdown;
     /**
      * Checks if layer needs to be sent
-     * @internal - Used by Core.endTickSplit()
+     * @internal - Used by Core.endTick()
      */
     getNeedsCommit(): boolean;
     /**
      * Resets commit flag after sending
-     * @internal - Used by Core.endTickSplit()
+     * @internal - Used by Core.endTick()
      */
     resetCommit(): void;
 }