@utsp/core 0.14.1 → 0.15.0-nightly.20251227200128.cdc09ed

package/dist/index.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 } 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 } from '@utsp/types';
 export { AxisBinding, AxisSource, ButtonBinding, ButtonSource, InputBindingLoadPacket, RenderState, RenderedCell, ScalingModeValue, UserRenderState, Vector2 } from '@utsp/types';
 
 /**
@@ -3279,14 +3279,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
@@ -3330,6 +3333,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
      *
@@ -3480,6 +3521,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
      *
@@ -3492,6 +3540,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
      *
@@ -3504,6 +3558,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
      *
@@ -3524,6 +3598,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
      */
@@ -3532,6 +3613,10 @@ declare class InputBindingRegistry {
      * Removes all buttons
      */
     clearButtons(): void;
+    /**
+     * Removes all touch zones
+     */
+    clearTouchZones(): void;
     /**
      * Completely resets the registry
      */
@@ -5124,6 +5209,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