@utsp/core 0.17.0-nightly.20260127101256.e83fcc8 → 0.17.0-nightly.20260127225451.86b0757

package/dist/benchmark.d.ts

@@ -340,9 +340,9 @@ interface PolylineOrder extends NetworkOrder {
     }>;
 }
 /**
- * 0x13 - Clear: Fills entire layer with single character and colors
+ * 0x13 - Fill: Fills entire layer with single character and colors
  */
-interface ClearOrder extends NetworkOrder {
+interface FillOrder extends NetworkOrder {
     type: 0x13;
     charCode: number;
     bgColorCode: number;
@@ -375,7 +375,7 @@ interface FillSpriteMultiColorOrder extends NetworkOrder {
     type: 0x16;
     spriteIndex: number;
 }
-type AnyNetworkOrder = CharOrder | TextOrder | TextMultilineOrder | SubFrameOrder | SubFrameMultiColorOrder | FullFrameOrder | FullFrameMultiColorOrder | SpriteOrder | SpriteMultiColorOrder | ColorMapOrder | ShapeOrder | DotCloudOrder | DotCloudMultiColorOrder | BitmaskOrder | Bitmask4Order | Bitmask16Order | PolylineOrder | SpriteCloudOrder | SpriteCloudMultiColorOrder | SpriteCloudVariedOrder | SpriteCloudVariedMultiColorOrder | ClearOrder | FillCharOrder | FillSpriteOrder | FillSpriteMultiColorOrder;
+type AnyNetworkOrder = CharOrder | TextOrder | TextMultilineOrder | SubFrameOrder | SubFrameMultiColorOrder | FullFrameOrder | FullFrameMultiColorOrder | SpriteOrder | SpriteMultiColorOrder | ColorMapOrder | ShapeOrder | DotCloudOrder | DotCloudMultiColorOrder | BitmaskOrder | Bitmask4Order | Bitmask16Order | PolylineOrder | SpriteCloudOrder | SpriteCloudMultiColorOrder | SpriteCloudVariedOrder | SpriteCloudVariedMultiColorOrder | Bitmask16Order | PolylineOrder | FillOrder | FillCharOrder | FillSpriteOrder | FillSpriteMultiColorOrder;
 
 /**
  * Encoder for UTSP network orders
@@ -419,7 +419,7 @@ declare class OrderEncoder {
     private encodeSpriteCloudMultiColorOrder;
     private encodeSpriteCloudVariedOrder;
     private encodeSpriteCloudVariedMultiColorOrder;
-    private encodeClearOrder;
+    private encodeFillOrder;
     private encodeFillCharOrder;
     private encodeFillSpriteOrder;
     private encodeFillSpriteMultiColorOrder;
@@ -2737,7 +2737,7 @@ declare class OrderDecoder {
     private decodeSpriteCloudMultiColorOrder;
     private decodeSpriteCloudVariedOrder;
     private decodeSpriteCloudVariedMultiColorOrder;
-    private decodeClearOrder;
+    private decodeFillOrder;
     private decodeFillCharOrder;
     private decodeFillSpriteOrder;
     private decodeFillSpriteMultiColorOrder;
@@ -3214,6 +3214,75 @@ interface MulticolorSprite {
     data: CellBuffer;
 }
 
+/**
+ * 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
  *
@@ -3229,15 +3298,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
      */
@@ -3448,7 +3527,7 @@ declare class LayerRasterizer {
      * 0x13 - Clear: Fills entire layer
      * OPTIMIZED: Uses clearWithColor() for fast uniform fill
      */
-    private rasterizeClear;
+    private rasterizeFill;
     /**
      * 0x14 - FillChar: Fills with a repeating pattern
      */
@@ -8059,8 +8138,8 @@ declare class Core {
      * 5. Returns a Map with split packets ready to send
      *
      * Network strategy:
-     * - STATIC Layers → Reliable channel (guaranteed delivery)
-     * - DYNAMIC Layers → Volatile channel (can drop packets for performance)
+     * - Reliable Layers → Reliable channel (guaranteed delivery)
+     * - Unreliable 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 }>
@@ -8426,63 +8505,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)
@@ -9936,9 +10026,9 @@ declare class OrderBuilder {
      * @param char - Character as string (' ') or numeric code (32).
      * @param fgColor - Foreground color (0-255).
      * @param bgColor - Background color (0-255).
-     * @returns Clear order.
+     * @returns Fill order.
      */
-    static clear(char?: string | number, fgColor?: number, bgColor?: number): ClearOrder;
+    static fill(char?: string | number, fgColor?: number, bgColor?: number): FillOrder;
     /**
      * Fills the layer with a repeating character pattern.
      *
@@ -10079,4 +10169,4 @@ declare class OrderBuilder {
 }
 
 export { BufferCompat, CellBuffer, Core, DisplayDecoder, DisplayEncoder, DisplayRasterizer, Layer, LayerDecoder, LayerEncoder, LayerRasterizer, LoadDecoder, LoadEncoder, MacroEventDecoder, MacroEventEncoder, MacroLoadDecoder, MacroLoadEncoder, MacroOrderDecoder, MacroOrderEncoder, OrderBuilder, OrderDecoder, OrderEncoder, ShapeType, SpriteRegistry, UpdatePacketDecoder, UpdatePacketEncoder };
-export type { Bitmask16Order, Bitmask4Order, BitmaskOrder, CharOrder, ClearOrder, ColorMapOrder, DotCloudMultiColorOrder, DotCloudOrder, FillCharOrder, FillSpriteMultiColorOrder, FillSpriteOrder, FullFrameMultiColorOrder, FullFrameOrder, PolylineOrder, ShapeOrder, SpriteCloudMultiColorOrder, SpriteCloudOrder, SpriteCloudVariedMultiColorOrder, SpriteCloudVariedOrder, SpriteMultiColorOrder, SpriteOrder, SubFrameMultiColorOrder, SubFrameOrder, TextMultilineOrder, TextOrder };
+export type { Bitmask16Order, Bitmask4Order, BitmaskOrder, CharOrder, ColorMapOrder, DotCloudMultiColorOrder, DotCloudOrder, FillCharOrder, FillOrder, FillSpriteMultiColorOrder, FillSpriteOrder, FullFrameMultiColorOrder, FullFrameOrder, PolylineOrder, ShapeOrder, SpriteCloudMultiColorOrder, SpriteCloudOrder, SpriteCloudVariedMultiColorOrder, SpriteCloudVariedOrder, SpriteMultiColorOrder, SpriteOrder, SubFrameMultiColorOrder, SubFrameOrder, TextMultilineOrder, TextOrder };