@utsp/core 0.17.0-nightly.20260125201607.c6707a1 → 0.17.0-nightly.20260127111647.165f2b8

package/dist/index.d.ts

@@ -1476,6 +1476,75 @@ interface ImageFontBlockLoad {
  */
 type AnyLoad = ColorPaletteLoad | SpriteLoad | MulticolorSpriteLoad | SoundLoad | MacroLoad | ImageFontLoad | ImageFontBlockLoad;
 
+/**
+ * Public-facing types for Sprite Loading API
+ * These types hide internal implementation details like LoadType
+ * and support flexible input formats (strings, numbers, etc.)
+ */
+/**
+ * Single Multicolor Cell definition
+ */
+interface MulticolorSpriteCell {
+    /**
+     * Character as a string (first char used) or numeric char code (0-65535).
+     * Automatically converted to CP437 if a string is provided.
+     */
+    charCode: string | number;
+    /**
+     * Foreground color ID (0-255)
+     */
+    fgColorId: number;
+    /**
+     * Background color ID (0-255)
+     */
+    bgColorId: number;
+}
+/**
+ * Definition for a Unicolor Sprite
+ */
+interface UnicolorSpriteDefinition {
+    /**
+     * Unique sprite identifier (0-255)
+     */
+    spriteId: number;
+    /**
+     * Width in cells (1-255)
+     */
+    sizeX: number;
+    /**
+     * Height in cells (1-255)
+     */
+    sizeY: number;
+    /**
+     * Sprite data. Can be:
+     * - Flat array of numbers (char codes)
+     * - Single string (will be treated as a sequence of characters)
+     * - Array of strings (one per row)
+     */
+    data: number[] | string | string[];
+}
+/**
+ * Definition for a Multicolor Sprite
+ */
+interface MulticolorSpriteDefinition {
+    /**
+     * Unique sprite identifier (0-255)
+     */
+    spriteId: number;
+    /**
+     * Width in cells (1-255)
+     */
+    sizeX: number;
+    /**
+     * Height in cells (1-255)
+     */
+    sizeY: number;
+    /**
+     * Array of multicolor cells (row-major order, length = sizeX * sizeY)
+     */
+    data: MulticolorSpriteCell[];
+}
+
 /**
  * Central registry to manage unicolor and multicolor sprites
  *
@@ -1491,15 +1560,25 @@ declare class SpriteRegistry {
     private unicolorSprites;
     private multicolorSprites;
     /**
-     * Loads unicolor sprites from a LoadPacket
-     * Converts network format to optimized internal format
+     * Loads unicolor sprites from public definitions
+     * Supports strings, string arrays, and numbers
      */
-    loadUnicolorSprites(loadData: SpriteLoad): void;
+    loadUnicolorSprites(definitions: UnicolorSpriteDefinition[] | SpriteLoad): void;
     /**
-     * Loads multicolor sprites from a LoadPacket
-     * Converts network format to optimized internal format
+     * Internal method to load unicolor sprites from protocol packet
+     * @internal
+     */
+    loadUnicolorSpritesFromPacket(loadData: SpriteLoad): void;
+    /**
+     * Loads multicolor sprites from public definitions
+     * Supports string or number charCodes
+     */
+    loadMulticolorSprites(definitions: MulticolorSpriteDefinition[] | MulticolorSpriteLoad): void;
+    /**
+     * Internal method to load multicolor sprites from protocol packet
+     * @internal
      */
-    loadMulticolorSprites(loadData: MulticolorSpriteLoad): void;
+    loadMulticolorSpritesFromPacket(loadData: MulticolorSpriteLoad): void;
     /**
      * Retrieves a unicolor sprite by its ID
      */
@@ -8000,63 +8079,74 @@ declare class Core {
      */
     resetStats(): void;
     /**
-     * Loads unicolor sprites from a LoadPacket
+     * Loads unicolor sprites into the registry.
      *
-     * Unicolor sprites only store charCode (1 byte per cell).
-     * Colors are applied during rendering via Orders.
+     * Unicolor sprites store only character codes. Colors (fg/bg) are
+     * defined at render time via SpriteOrder.
      *
-     * @param loadData - Loading data from a LoadPacket (type 0x02)
+     * ✨ Supports strings for data (including row-by-row arrays) and auto-converts
+     * characters to CP437 automatically.
+     *
+     * @param definitions - Array of sprite definitions
      *
      * @example
      * ```typescript
-     * // Load a 4x4 unicolor sprite
-     * engine.loadUnicolorSprites({
-     *   sprites: [
-     *     {
-     *       spriteId: 1,
-     *       sizeX: 4,
-     *       sizeY: 4,
-     *       data: [
-     *         0x2588, 0x2588, 0x2588, 0x2588,
-     *         0x2588, 0x0020, 0x0020, 0x2588,
-     *         0x2588, 0x0020, 0x0020, 0x2588,
-     *         0x2588, 0x2588, 0x2588, 0x2588
-     *       ]
-     *     }
-     *   ]
-     * });
+     * // Load a 4x4 unicolor sprite using a flat string
+     * engine.loadUnicolorSprites([
+     *   {
+     *     spriteId: 1,
+     *     sizeX: 4,
+     *     sizeY: 4,
+     *     data: "#####  ##  #####"
+     *   }
+     * ]);
+     *
+     * // Load using a string array (row by row) - cleaner!
+     * engine.loadUnicolorSprites([
+     *   {
+     *     spriteId: 2,
+     *     sizeX: 4,
+     *     sizeY: 4,
+     *     data: [
+     *       "####",
+     *       "#  #",
+     *       "#  #",
+     *       "####"
+     *     ]
+     *   }
+     * ]);
      * ```
      */
-    loadUnicolorSprites(loadData: SpriteLoad): void;
+    loadUnicolorSprites(definitions: UnicolorSpriteDefinition[]): void;
     /**
-     * Loads multicolor sprites from a LoadPacket
+     * Loads multicolor sprites into the registry.
      *
-     * Multicolor sprites store charCode + fgColorId + bgColorId (3 bytes per cell).
+     * Multicolor sprites store charCode + fgColorId + bgColorId per cell.
      * Optimized for sprites with lots of visual detail.
      *
-     * @param loadData - Loading data from a LoadPacket (type 0x03)
+     * ✨ Supports string characters for charCode and auto-converts to CP437.
+     *
+     * @param definitions - Array of sprite definitions
      *
      * @example
      * ```typescript
      * // Load a 2x2 multicolor sprite
-     * engine.loadMulticolorSprites({
-     *   sprites: [
-     *     {
-     *       spriteId: 10,
-     *       sizeX: 2,
-     *       sizeY: 2,
-     *       data: [
-     *         { charCode: 0x2588, fgColorId: 12, bgColorId: 0 },
-     *         { charCode: 0x2588, fgColorId: 14, bgColorId: 0 },
-     *         { charCode: 0x2588, fgColorId: 14, bgColorId: 0 },
-     *         { charCode: 0x2588, fgColorId: 12, bgColorId: 0 }
-     *       ]
-     *     }
-     *   ]
-     * });
+     * engine.loadMulticolorSprites([
+     *   {
+     *     spriteId: 10,
+     *     sizeX: 2,
+     *     sizeY: 2,
+     *     data: [
+     *       { charCode: 'A', fgColorId: 12, bgColorId: 0 },
+     *       { charCode: 'B', fgColorId: 14, bgColorId: 0 },
+     *       { charCode: 'C', fgColorId: 14, bgColorId: 0 },
+     *       { charCode: 'D', fgColorId: 12, bgColorId: 0 }
+     *     ]
+     *   }
+     * ]);
      * ```
      */
-    loadMulticolorSprites(loadData: MulticolorSpriteLoad): void;
+    loadMulticolorSprites(definitions: MulticolorSpriteDefinition[]): void;
     /**
      * Load Font structure (allocate font)
      * Defines the font dimensions and allocates the atlas in memory (empty)