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

package/dist/index.d.ts

@@ -624,9 +624,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;
@@ -659,7 +659,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;
 
 /**
  * UTSP Macro System Types
@@ -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
      */
@@ -7633,8 +7712,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 }>
@@ -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)
@@ -9401,9 +9491,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.
      *
@@ -9601,7 +9691,7 @@ declare const SPRITECLOUD_ORDER_MIN_SIZE = 6;
 declare const SPRITECLOUD_MULTICOLOR_ORDER_MIN_SIZE = 4;
 declare const SPRITECLOUD_VARIED_ORDER_MIN_SIZE = 3;
 declare const SPRITECLOUD_VARIED_MULTICOLOR_ORDER_MIN_SIZE = 3;
-declare const CLEAR_ORDER_SIZE = 4;
+declare const FILL_ORDER_SIZE = 4;
 declare const FILLCHAR_ORDER_MIN_SIZE = 5;
 declare const FILLSPRITE_ORDER_SIZE = 4;
 declare const FILLSPRITE_MULTICOLOR_ORDER_SIZE = 2;
@@ -9727,9 +9817,9 @@ declare enum OrderType {
      */
     Polyline = 25,
     /**
-     * 0x13 - Clear: Fills entire layer with single character and colors
+     * 0x13 - Fill: Fills entire layer with single character and colors
      */
-    Clear = 19,
+    Fill = 19,
     /**
      * 0x14 - FillChar: Fills layer with repeating character pattern
      */
@@ -10189,5 +10279,5 @@ declare class PostProcessOrderDecoder {
     private decodeSetCellSizeOrder;
 }
 
-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, 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, GamepadVibrateFlags, ImageFont, ImageFontRegistry, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, MAX_ORDERS_PER_LAYER, MacroEngine, MacroEventType, MacroOrderType, MacroRegistry, MobileVibrateFlags, OrderBuilder, OrderType, POLYLINE_ORDER_MIN_SIZE, POSTPROCESS_SET_AMBIENT_EFFECT_SIZE, POSTPROCESS_SET_CELL_SIZE_SIZE, POSTPROCESS_SET_CONFIG_MIN_SIZE, POSTPROCESS_SET_GRID_SIZE, POSTPROCESS_SET_SCALING_MODE_SIZE, POSTPROCESS_SET_SCANLINES_SIZE, POSTPROCESS_SWITCH_PALETTE_SIZE, PlaySoundFlags, PostProcessOrderCollector, PostProcessOrderDecoder, PostProcessOrderType, 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, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, VibrationOrderCollector, VibrationOrderDecoder, VibrationOrderEncoder, VibrationOrderType, charCodeByteSize, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getAtlasColumns, getAtlasDimensions, getAudioOrderTypeName, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getMacroEventTypeName, getMacroOrderTypeName, getMaxCharCode, getOrderTypeName, hasChar, isValidAudioOrderType, isValidMacroEventType, isValidMacroOrderType, isValidOrderType };
+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, CHAR_ORDER_SIZE, CIRCLE_SHAPE_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, FILL_ORDER_SIZE, FULLFRAME_MULTICOLOR_ORDER_MIN_SIZE, FULLFRAME_ORDER_MIN_SIZE, FontType, GamepadVibrateFlags, ImageFont, ImageFontRegistry, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, MAX_ORDERS_PER_LAYER, MacroEngine, MacroEventType, MacroOrderType, MacroRegistry, MobileVibrateFlags, OrderBuilder, OrderType, POLYLINE_ORDER_MIN_SIZE, POSTPROCESS_SET_AMBIENT_EFFECT_SIZE, POSTPROCESS_SET_CELL_SIZE_SIZE, POSTPROCESS_SET_CONFIG_MIN_SIZE, POSTPROCESS_SET_GRID_SIZE, POSTPROCESS_SET_SCALING_MODE_SIZE, POSTPROCESS_SET_SCANLINES_SIZE, POSTPROCESS_SWITCH_PALETTE_SIZE, PlaySoundFlags, PostProcessOrderCollector, PostProcessOrderDecoder, PostProcessOrderType, 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, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, VibrationOrderCollector, VibrationOrderDecoder, VibrationOrderEncoder, VibrationOrderType, charCodeByteSize, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getAtlasColumns, getAtlasDimensions, getAudioOrderTypeName, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getMacroEventTypeName, getMacroOrderTypeName, getMaxCharCode, getOrderTypeName, hasChar, isValidAudioOrderType, isValidMacroEventType, isValidMacroOrderType, isValidOrderType };
 export type { AnyAudioOrder, AnyLoad, AnyMacroEvent, AnyMacroOrder, AnyPostProcessOrder, AnyVibrationOrder, AtlasBlocks, AudioOrder, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, ButtonBorderStyle, ButtonConfig, ButtonStateColors, Cell, ChangeEvent, CharCodeMode, CircleShape, ClickEvent, Color, ColorPaletteLoad, CompressedInputPacket, ConfigureSpatialOrder, CoreMode, CoreOptions, CreateInstanceConfig, CreateInstanceOrder, DisplayViewport, EffectMacroTemplate, EffectTransform, EllipseShape, FadeOutSoundOrder, GamepadCancelOrder, GamepadVibrateOrder, GamepadVibrationOrder, GlyphSize, ImageFontConfig, ImageFontLoad, ImageFontOptions, LineMacroTemplate, LineShape, MacroEntry, MacroEvent, MacroInstanceEntry, MacroLoad, MacroOrder, MacroTemplate, MacroTemplateBase, MacroType, MacroUpdateResult, MobileCancelOrder, MobileVibrateOrder, MobileVibrationOrder, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, ParticleConfig, ParticleEmitter, ParticleMacroTemplate, PauseSoundOrder, PlayGlobalSoundOrder, PlaySoundOrder, RectangleShape, RemoveInstanceOrder, RenderCommand, RenderPassConfig, ResumeSoundOrder, RevealCellDef, RevealContent, RevealContentType, RevealCursor, RevealDirection, RevealMacroTemplate, RevealPattern, RevealPause, SelectEvent, SetAmbientEffectOrder, SetConfigOrder, SetGridOrder, SetListenerPositionOrder, SetScalingModeOrder, SetScanlinesOrder, SetSoundEffectsOrder, ShapeData, SoundEntry, SoundLoad, SpriteLoad, StopSoundOrder, SubmitEvent, SwitchPaletteOrder, TickStats, TouchPosition, TriangleShape, UIMacroTemplate, UIState, UISubtype, UnicolorSprite, UpdateInstanceOrder, UpdatePacket, UserTickStats, VibrationOrder };