@utsp/core 0.9.0-nightly.20251210150441.b1cbb1e → 0.9.0-nightly.20251211152508.63e8b0d

package/dist/index.d.ts

@@ -4,15 +4,49 @@ export { AxisBinding, AxisSource, ButtonBinding, ButtonSource, InputBindingLoadP
 
 /**
  * Font system for UTSP Core
- * Supports WebFont (CSS-based) and BitmapFont (pixel-based)
+ * Supports WebFont (CSS-based), BitmapFont (pixel-based), and ImageFont (PNG atlas-based)
  */
 /**
  * Font type enumeration
  */
 declare enum FontType {
     Web = "web",
-    Bitmap = "bitmap"
+    Bitmap = "bitmap",
+    Image = "image"
 }
+/**
+ * Number of 256-char blocks in an atlas
+ * - 1 block = 16×16 grid = 256 chars (8-bit)
+ * - 4 blocks = 32×32 grid = 1024 chars (10-bit)
+ * - 16 blocks = 64×64 grid = 4096 chars (12-bit)
+ */
+type AtlasBlocks = 1 | 4 | 16;
+/**
+ * Glyph size in pixels (uniform within an atlas)
+ */
+type GlyphSize = 8 | 16 | 32;
+/**
+ * Get the number of columns in an atlas grid
+ * @param blocks Number of atlas blocks (1, 4, or 16)
+ * @returns Number of columns (16, 32, or 64)
+ */
+declare function getAtlasColumns(blocks: AtlasBlocks): number;
+/**
+ * Get the maximum character code for an atlas configuration
+ * @param blocks Number of atlas blocks (1, 4, or 16)
+ * @returns Maximum charCode (255, 1023, or 4095)
+ */
+declare function getMaxCharCode(blocks: AtlasBlocks): number;
+/**
+ * Get atlas dimensions in pixels
+ * @param blocks Number of atlas blocks
+ * @param glyphSize Size of each glyph in pixels
+ * @returns Atlas dimensions { width, height }
+ */
+declare function getAtlasDimensions(blocks: AtlasBlocks, glyphSize: GlyphSize): {
+    width: number;
+    height: number;
+};
 /**
  * WebFont configuration
  * For CSS-based fonts rendered by the browser
@@ -147,6 +181,234 @@ declare class BitmapFont {
      */
     getCharCodes(): number[];
 }
+/**
+ * ImageFont configuration
+ * For PNG atlas-based fonts with pre-rendered glyphs
+ */
+interface ImageFontConfig {
+    glyphWidth: number;
+    glyphHeight: number;
+    cellWidth?: number;
+    cellHeight?: number;
+    atlasBlocks: AtlasBlocks;
+    imageData: Uint8Array;
+}
+/**
+ * ImageFont class
+ * Represents a PNG atlas-based font for extended character sets
+ * Corresponds to LoadType 0x08 (ImageFont) in UTSP protocol
+ *
+ * Atlas layout for atlasBlocks=4 (1024 chars, 32×32 grid):
+ * ```
+ * ┌─────────┬─────────┐
+ * │ 0-255   │ 256-511 │
+ * │ (Bloc 0)│ (Bloc 1)│
+ * ├─────────┼─────────┤
+ * │ 512-767 │768-1023 │
+ * │ (Bloc 2)│ (Bloc 3)│
+ * └─────────┴─────────┘
+ * ```
+ *
+ * CharCode to UV mapping:
+ * - col = charCode % atlasColumns
+ * - row = floor(charCode / atlasColumns)
+ * - u = col / atlasColumns
+ * - v = row / atlasColumns
+ */
+declare class ImageFont {
+    private fontId;
+    private config;
+    private readonly atlasColumns;
+    private readonly maxCharCode;
+    constructor(fontId: number, config: ImageFontConfig);
+    /**
+     * Get the unique font ID
+     */
+    getFontId(): number;
+    /**
+     * Get the full configuration (copy with new imageData reference)
+     */
+    getConfig(): ImageFontConfig;
+    /**
+     * Get the glyph width in pixels
+     */
+    getGlyphWidth(): number;
+    /**
+     * Get the glyph height in pixels
+     */
+    getGlyphHeight(): number;
+    /**
+     * Get the target cell width in pixels (rendering size)
+     */
+    getCellWidth(): number;
+    /**
+     * Get the target cell height in pixels (rendering size)
+     */
+    getCellHeight(): number;
+    /**
+     * Get the number of atlas blocks
+     */
+    getAtlasBlocks(): AtlasBlocks;
+    /**
+     * Get the number of columns in the atlas grid
+     */
+    getAtlasColumns(): number;
+    /**
+     * Get the maximum supported charCode
+     */
+    getMaxCharCode(): number;
+    /**
+     * Get the PNG image data
+     */
+    getImageData(): Uint8Array;
+    /**
+     * Get the atlas dimensions in pixels
+     */
+    getAtlasDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get UV coordinates for a character code
+     * @param charCode Character code (0 to maxCharCode)
+     * @returns UV coordinates { u1, v1, u2, v2 } or null if out of range
+     */
+    getCharUV(charCode: number): {
+        u1: number;
+        v1: number;
+        u2: number;
+        v2: number;
+    } | null;
+    /**
+     * Check if a charCode is valid for this atlas
+     */
+    isValidCharCode(charCode: number): boolean;
+}
+
+/**
+ * ImageFontRegistry - Registry for PNG atlas-based fonts
+ */
+
+/**
+ * Options for loading an ImageFont
+ */
+interface ImageFontOptions {
+    /** Width of each glyph in pixels (8, 16, or 32) */
+    glyphWidth: number;
+    /** Height of each glyph in pixels (8, 16, or 32) */
+    glyphHeight: number;
+    /** Target cell width for rendering (default: glyphWidth) */
+    cellWidth?: number;
+    /** Target cell height for rendering (default: glyphHeight) */
+    cellHeight?: number;
+    /** Number of 256-char blocks: 1, 4, or 16 (default: 1) */
+    atlasBlocks?: AtlasBlocks;
+}
+/**
+ * Registry for managing ImageFont instances
+ * Each font is identified by a unique fontId (0-255) and a human-readable name
+ * ImageFonts correspond to LoadType 0x08 (ImageFont) in UTSP protocol
+ */
+declare class ImageFontRegistry {
+    private fonts;
+    private nameToId;
+    private nextId;
+    /**
+     * Allocate the next available font ID
+     * @param name Font name (for error messages)
+     * @returns Allocated font ID
+     * @throws Error if no IDs available
+     */
+    private allocateId;
+    /**
+     * Register a new ImageFont with auto-assigned ID
+     * @param name Human-readable name for the font
+     * @param options Font options (glyph size, atlas blocks)
+     * @param imageData PNG image data
+     * @returns The assigned font ID (0-255)
+     * @throws Error if name already exists
+     */
+    registerFont(name: string, options: ImageFontOptions, imageData: Uint8Array): number;
+    /**
+     * Load a new ImageFont into the registry with specific ID (low-level API)
+     * @param fontId Unique font identifier (0-255)
+     * @param config ImageFont configuration
+     * @throws Error if font ID already exists
+     */
+    loadFont(fontId: number, config: ImageFontConfig): void;
+    /**
+     * Get an ImageFont by ID
+     * @param fontId Font identifier
+     * @returns ImageFont instance or undefined if not found
+     */
+    getFont(fontId: number): ImageFont | undefined;
+    /**
+     * Get an ImageFont by name
+     * @param name Font name
+     * @returns ImageFont instance or undefined if not found
+     */
+    getFontByName(name: string): ImageFont | undefined;
+    /**
+     * Get font ID by name
+     * @param name Font name
+     * @returns Font ID or undefined if not found
+     */
+    getFontId(name: string): number | undefined;
+    /**
+     * Get font name by ID
+     * @param fontId Font ID
+     * @returns Font name or undefined if not found
+     */
+    getFontName(fontId: number): string | undefined;
+    /**
+     * Check if a font exists in the registry by ID
+     * @param fontId Font identifier
+     * @returns true if font exists, false otherwise
+     */
+    hasFont(fontId: number): boolean;
+    /**
+     * Check if a font exists in the registry by name
+     * @param name Font name
+     * @returns true if font exists, false otherwise
+     */
+    hasFontByName(name: string): boolean;
+    /**
+     * Remove an ImageFont from the registry
+     * @param fontId Font identifier
+     * @returns true if font was removed, false if not found
+     */
+    unloadFont(fontId: number): boolean;
+    /**
+     * Remove an ImageFont from the registry by name
+     * @param name Font name
+     * @returns true if font was removed, false if not found
+     */
+    unloadFontByName(name: string): boolean;
+    /**
+     * Remove all fonts from the registry
+     */
+    clearFonts(): void;
+    /**
+     * Get all font IDs in the registry
+     * @returns Array of font IDs, sorted in ascending order
+     */
+    getFontIds(): number[];
+    /**
+     * Get all font names in the registry
+     * @returns Array of font names
+     */
+    getFontNames(): string[];
+    /**
+     * Get all ImageFont instances in the registry
+     * @returns Array of ImageFont instances, sorted by font ID
+     */
+    getAllFonts(): ImageFont[];
+    /**
+     * Get the number of fonts in the registry
+     * @returns Number of fonts
+     */
+    getFontCount(): number;
+}
 
 /**
  * Base interface for all network orders
@@ -1023,14 +1285,26 @@ declare function getMacroOrderTypeName(type: MacroOrderType): string;
  */
 declare function getMacroEventTypeName(type: MacroEventType): string;
 
+/**
+ * CharCode mode for layers
+ * - '8bit': Uses Uint8Array, limited to 256 characters (ASCII/CP437), optimized bandwidth
+ * - '16bit': Uses Uint16Array, supports 65536 characters (Unicode BMP), universal
+ */
+type CharCodeMode = '8bit' | '16bit';
 interface Cell {
     charCode: number;
     fgColorCode: number;
     bgColorCode: number;
 }
 /**
- * Optimized buffer for 65,536 cells with TypedArray
- * Interleaved structure: [char0, fg0, bg0, char1, fg1, bg1, ...]
+ * Optimized buffer for cells with TypedArray
+ * Separate arrays for charCodes and colors for optimal memory layout
+ *
+ * CharCode storage depends on mode:
+ * - 8-bit mode: Uint8Array (1 byte per charCode) - network optimized
+ * - 16-bit mode: Uint16Array (2 bytes per charCode) - full Unicode BMP
+ *
+ * Colors are always 8-bit (256 palette colors)
  *
  * Performance:
  * - clear(): ~5-10μs (vs 826μs with object array)
@@ -1038,9 +1312,17 @@ interface Cell {
  * - Less GC pressure
  */
 declare class CellBuffer {
-    private data;
+    private charCodes;
+    private fgColors;
+    private bgColors;
     private size;
-    constructor(size?: number);
+    private is16bit;
+    /**
+     * Creates a new CellBuffer
+     * @param size - Number of cells (default: 65536)
+     * @param is16bit - true for 16-bit charCodes, false for 8-bit (default: false)
+     */
+    constructor(size?: number, is16bit?: boolean);
     /**
      * Optimized clear: fills with "skip" values
      * - charCode = 0 (no character)
@@ -1074,7 +1356,6 @@ declare class CellBuffer {
      * Writes only characters at multiple positions with uniform fg/bg colors
      *
      * Performance: 2-3x faster than individual set() calls for uniform colors
-     * Reduces memory writes by 66% (writes chars only, then batch-fills colors)
      *
      * @param indices - Array of cell indices to fill
      * @param charCode - Character to write at all positions
@@ -1117,20 +1398,33 @@ declare class CellBuffer {
     getFgColorCode(index: number): number;
     getBgColorCode(index: number): number;
     /**
-     * Direct TypedArray access for batch operations
+     * Direct TypedArray access for charCodes (batch operations)
      */
-    getRawData(): Uint8Array;
+    getRawCharCodes(): Uint8Array | Uint16Array;
+    /**
+     * Direct TypedArray access for foreground colors
+     */
+    getRawFgColors(): Uint8Array;
+    /**
+     * Direct TypedArray access for background colors
+     */
+    getRawBgColors(): Uint8Array;
     /**
      * Buffer size (number of cells)
      */
     getSize(): number;
+    /**
+     * Returns true if buffer uses 16-bit charCodes
+     */
+    is16BitMode(): boolean;
 }
 /**
  * Optimized buffer to store only charcodes (unicolor sprites)
  * Simple structure: [char0, char1, char2, ...]
+ * Always uses 16-bit charCodes to support full Unicode BMP
  *
  * Performance:
- * - 3x less memory than CellBuffer (1 byte vs 3 bytes per cell)
+ * - Less memory than CellBuffer (2 bytes vs 4 bytes per cell)
  * - Ideal for unicolor sprites where colors are defined at render time
  * - Cache-friendly with TypedArray
  */
@@ -1153,7 +1447,7 @@ declare class CharCodeBuffer {
     /**
      * Direct TypedArray access for batch operations
      */
-    getRawData(): Uint8Array;
+    getRawData(): Uint16Array;
     /**
      * Buffer size (number of cells)
      */
@@ -1208,6 +1502,7 @@ interface MacroLoad {
  * UTSP Load Packet Types
  * Based on UTSP Protocol v0.1 - Section 4: Load Section
  */
+
 /**
  * LoadType enumeration
  */
@@ -1215,10 +1510,11 @@ declare enum LoadType {
     ColorPalette = 1,
     Sprite = 2,
     MulticolorSprite = 3,
-    BitmapFont = 4,// Formerly "Charset" - pixel-based fonts
+    BitmapFont = 4,// Formerly "Charset" - pixel-based fonts (bitpacking)
     Sound = 5,
     WebFont = 6,// CSS-based fonts for browser rendering
-    Macro = 7
+    Macro = 7,// Macro template for client-side feedback
+    ImageFont = 8
 }
 /**
  * Color definition with RGBA+E values
@@ -1318,11 +1614,34 @@ interface SoundLoad {
         midiData: Uint8Array;
     }>;
 }
+/**
+ * ImageFont Load (LoadType 0x08)
+ * PNG atlas-based fonts for extended character sets (256, 1024, or 4096 chars)
+ *
+ * Atlas layout (example for 4 blocks = 1024 chars):
+ * ```
+ * ┌─────────┬─────────┐
+ * │ 0-255   │ 256-511 │  32×32 grid
+ * ├─────────┼─────────┤  = 1024 chars
+ * │ 512-767 │768-1023 │
+ * └─────────┴─────────┘
+ * ```
+ */
+interface ImageFontLoad {
+    loadType: LoadType.ImageFont;
+    fontId: number;
+    glyphWidth: number;
+    glyphHeight: number;
+    cellWidth: number;
+    cellHeight: number;
+    atlasBlocks: AtlasBlocks;
+    imageData: Uint8Array;
+}
 
 /**
  * Union type for all load types
  */
-type AnyLoad = ColorPaletteLoad | SpriteLoad | MulticolorSpriteLoad | BitmapFontLoad | SoundLoad | WebFontLoad | MacroLoad;
+type AnyLoad = ColorPaletteLoad | SpriteLoad | MulticolorSpriteLoad | BitmapFontLoad | SoundLoad | WebFontLoad | MacroLoad | ImageFontLoad;
 
 /**
  * Central registry to manage unicolor and multicolor sprites
@@ -2049,6 +2368,13 @@ interface NetworkLayer {
     height: number;
     orderCount: number;
     orders: AnyNetworkOrder[];
+    /**
+     * CharCode mode for this layer
+     * - false: 8-bit charCodes (0-255)
+     * - true: 16-bit charCodes (0-65535)
+     * Encoded in updateFlags bit 6
+     */
+    is16bit: boolean;
 }
 
 /**
@@ -2342,6 +2668,23 @@ declare class Display {
     setSize(size: Vector2): void;
 }
 
+/**
+ * Layer configuration options
+ */
+interface LayerOptions {
+    /**
+     * CharCode mode for this layer (immutable after creation)
+     * - '8bit': Uses Uint8Array, limited to 256 characters (ASCII/CP437), optimized bandwidth
+     * - '16bit': Uses Uint16Array, supports 65536 characters (Unicode BMP), universal
+     * @default '8bit'
+     */
+    charCodeMode?: CharCodeMode;
+    /**
+     * Static layer (sent only once to client)
+     * @default false
+     */
+    isStatic?: boolean;
+}
 declare class Layer {
     private id;
     private origin;
@@ -2353,13 +2696,35 @@ declare class Layer {
     private isStatic;
     private spriteRegistry?;
     private mode;
+    private charCodeMode;
     private previousOrigin;
     private previousZOrder;
     private enabled;
     private useSetMode;
     private needsCommit;
     private static rasterizer;
-    constructor(origin: Vector2, zOrder: number, width: number, height: number, isStatic?: boolean);
+    /**
+     * Creates a new Layer
+     *
+     * @param origin - Layer origin in world space
+     * @param zOrder - Z-order for layer stacking (higher = on top)
+     * @param width - Layer width in cells (1-256)
+     * @param height - Layer height in cells (1-256)
+     * @param options - Layer options (charCodeMode, isStatic)
+     *
+     * @example
+     * // 8-bit layer (default) - optimized for ASCII/CP437 text
+     * const gameLayer = new Layer(new Vector2(0, 0), 0, 80, 25);
+     *
+     * // 16-bit layer - full Unicode support (emoji, CJK, symbols)
+     * const unicodeLayer = new Layer(new Vector2(0, 0), 10, 40, 10, { charCodeMode: '16bit' });
+     */
+    constructor(origin: Vector2, zOrder: number, width: number, height: number, options?: LayerOptions | boolean);
+    /**
+     * Gets the layer's charCode mode (immutable)
+     * @returns '8bit' or '16bit'
+     */
+    getCharCodeMode(): CharCodeMode;
     /**
      * Configures the layer's execution mode (called by User)
      * @internal
@@ -5152,6 +5517,7 @@ declare class Core {
     private spriteRegistry;
     private webFontRegistry;
     private bitmapFontRegistry;
+    private imageFontRegistry;
     private soundRegistry;
     private audioOrderCollector;
     private postProcessOrderCollector;
@@ -5159,6 +5525,7 @@ declare class Core {
     private _renderCallCount;
     private onPaletteChangedCallback?;
     private onBitmapFontChangedCallback?;
+    private onImageFontChangedCallback?;
     /**
      * Creates a new UTSP engine instance
      *
@@ -6591,6 +6958,261 @@ declare class Core {
      * ```
      */
     getBitmapFontIds(): number[];
+    /**
+     * Loads an image font from a PNG file path
+     *
+     * Works identically on server (Node.js) and client (browser).
+     * The PNG is loaded and registered with an auto-assigned ID.
+     *
+     * @param name - Human-readable name for the font (e.g., 'tileset', 'icons')
+     * @param path - Path to the PNG atlas file
+     * @param options - Font configuration options
+     * @returns Promise resolving to the assigned font ID (0-255)
+     *
+     * @example
+     * ```typescript
+     * // In init() - same code works on server and client
+     * async init(core: Core): Promise<void> {
+     *   await core.loadImageFont('tileset', './fonts/tileset.png', {
+     *     glyphWidth: 16,
+     *     glyphHeight: 16,
+     *     atlasBlocks: 4,  // 1024 chars
+     *   });
+     * }
+     *
+     * // Later, use by name or ID
+     * const id = core.getImageFontId('tileset');
+     * ```
+     */
+    loadImageFont(name: string, path: string, options: ImageFontOptions): Promise<number>;
+    /**
+     * Loads multiple image fonts at once
+     *
+     * @param fonts - Object mapping font names to { path, options }
+     * @returns Promise resolving to object mapping names to IDs
+     *
+     * @example
+     * ```typescript
+     * async init(core: Core): Promise<void> {
+     *   await core.loadImageFonts({
+     *     tileset: {
+     *       path: './fonts/tileset.png',
+     *       options: { glyphWidth: 16, glyphHeight: 16, atlasBlocks: 4 }
+     *     },
+     *     icons: {
+     *       path: './fonts/icons.png',
+     *       options: { glyphWidth: 8, glyphHeight: 8, atlasBlocks: 1 }
+     *     }
+     *   });
+     * }
+     * ```
+     */
+    loadImageFonts(fonts: Record<string, {
+        path: string;
+        options: ImageFontOptions;
+    }>): Promise<Record<string, number>>;
+    /**
+     * Loads image data from path (isomorphic: Node.js or browser)
+     */
+    private loadImageData;
+    /**
+     * Gets the font ID for a named image font
+     *
+     * @param name - Font name
+     * @returns Font ID or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const id = core.getImageFontId('tileset');
+     * if (id !== undefined) {
+     *   console.log(`Tileset font ID: ${id}`);
+     * }
+     * ```
+     */
+    getImageFontId(name: string): number | undefined;
+    /**
+     * Gets an image font by its name
+     *
+     * @param name - Font name
+     * @returns The ImageFont instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const font = core.getImageFontByName('tileset');
+     * if (font) {
+     *   console.log(`Max charCode: ${font.getMaxCharCode()}`);
+     * }
+     * ```
+     */
+    getImageFontByName(name: string): ImageFont | null;
+    /**
+     * Registers a callback for image font changes
+     *
+     * Called when an image font is loaded.
+     *
+     * @param callback - Function called with the fontId
+     *
+     * @example
+     * ```typescript
+     * core.onImageFontChanged((fontId) => {
+     *   const font = core.getImageFont(fontId);
+     *   if (font) renderer.setImageFont(font.getImageData(), ...);
+     * });
+     * ```
+     */
+    onImageFontChanged(callback: (fontId: number) => void): void;
+    /**
+     * Gets the image font registry (low-level API)
+     *
+     * @returns The ImageFontRegistry instance
+     *
+     * @example
+     * ```typescript
+     * const registry = engine.getImageFontRegistry();
+     * const font = registry.getFont(1);
+     * ```
+     */
+    getImageFontRegistry(): ImageFontRegistry;
+    /**
+     * Loads an image font (PNG atlas) by ID (low-level API)
+     *
+     * Prefer using loadImageFont() with a name for simpler usage.
+     *
+     * @param fontId - Unique font ID (0-255)
+     * @param config - Image font configuration
+     * @throws Error if fontId is already in use
+     *
+     * @example
+     * ```typescript
+     * engine.loadImageFontById(1, {
+     *   glyphWidth: 16,
+     *   glyphHeight: 16,
+     *   atlasBlocks: 4,
+     *   imageData: pngBuffer
+     * });
+     * ```
+     */
+    loadImageFontById(fontId: number, config: ImageFontConfig): void;
+    /**
+     * Gets an image font by its ID
+     *
+     * @param fontId - Font ID (0-255)
+     * @returns The ImageFont instance or null if not found
+     *
+     * @example
+     * ```typescript
+     * const font = engine.getImageFont(1);
+     * if (font) {
+     *   console.log(`Atlas blocks: ${font.getAtlasBlocks()}`);
+     *   console.log(`Max charCode: ${font.getMaxCharCode()}`);
+     * }
+     * ```
+     */
+    getImageFont(fontId: number): ImageFont | null;
+    /**
+     * Checks if an image font exists by ID
+     *
+     * @param fontId - Font ID (0-255)
+     * @returns true if font exists
+     *
+     * @example
+     * ```typescript
+     * if (engine.hasImageFont(1)) {
+     *   console.log("ImageFont 1 is loaded");
+     * }
+     * ```
+     */
+    hasImageFont(fontId: number): boolean;
+    /**
+     * Checks if an image font exists by name
+     *
+     * @param name - Font name
+     * @returns true if font exists
+     *
+     * @example
+     * ```typescript
+     * if (engine.hasImageFontByName('tileset')) {
+     *   console.log("Tileset font is loaded");
+     * }
+     * ```
+     */
+    hasImageFontByName(name: string): boolean;
+    /**
+     * Unloads an image font from the registry by ID
+     *
+     * @param fontId - Font ID to unload (0-255)
+     * @returns true if font was unloaded
+     *
+     * @example
+     * ```typescript
+     * const removed = engine.unloadImageFont(1);
+     * if (removed) {
+     *   console.log("ImageFont 1 unloaded");
+     * }
+     * ```
+     */
+    unloadImageFont(fontId: number): boolean;
+    /**
+     * Unloads an image font from the registry by name
+     *
+     * @param name - Font name to unload
+     * @returns true if font was unloaded
+     *
+     * @example
+     * ```typescript
+     * const removed = engine.unloadImageFontByName('tileset');
+     * if (removed) {
+     *   console.log("Tileset font unloaded");
+     * }
+     * ```
+     */
+    unloadImageFontByName(name: string): boolean;
+    /**
+     * Clears all image fonts
+     *
+     * @example
+     * ```typescript
+     * engine.clearImageFonts();
+     * console.log("All image fonts cleared");
+     * ```
+     */
+    clearImageFonts(): void;
+    /**
+     * Counts the number of loaded image fonts
+     *
+     * @returns Number of image fonts in memory
+     *
+     * @example
+     * ```typescript
+     * const count = engine.getImageFontCount();
+     * console.log(`${count} image fonts loaded`);
+     * ```
+     */
+    getImageFontCount(): number;
+    /**
+     * Gets all loaded image font IDs
+     *
+     * @returns Array of fontIds (0-255)
+     *
+     * @example
+     * ```typescript
+     * const fontIds = engine.getImageFontIds();
+     * console.log(`Loaded image fonts: ${fontIds.join(", ")}`);
+     * ```
+     */
+    getImageFontIds(): number[];
+    /**
+     * Gets all loaded image font names
+     *
+     * @returns Array of font names
+     *
+     * @example
+     * ```typescript
+     * const names = engine.getImageFontNames();
+     * console.log(`Loaded image fonts: ${names.join(", ")}`);
+     * ```
+     */
+    getImageFontNames(): string[];
 }
 
 /**
@@ -6935,13 +7557,14 @@ interface ColorOptions {
  */
 declare class OrderBuilder {
     /**
-     * Convert string or number to 8-bit character code
-     * @param char - Either a string (first character used) or a number (0-255)
-     * @returns 8-bit character code (0-255)
+     * Convert string or number to character code
+     * @param char - Either a string (first character used) or a number (0-65535)
+     * @returns Character code (0-65535)
      * @example
      * toCharCode('#')   // → 0x23 (35)
      * toCharCode(0x23)  // → 0x23 (35)
      * toCharCode('ABC') // → 0x41 (65, first char only)
+     * toCharCode(256)   // → 256 (preserved for 16-bit layers)
      */
     static toCharCode(char: string | number): number;
     /**
@@ -7308,6 +7931,12 @@ declare const LAYER_CELL_COUNT = 65536;
  * - Engine forces ColorID 255 = rgba(0,0,0,0) at startup (transparency)
  */
 declare const COLOR_SKIP = 255;
+/**
+ * Get byte size for charCode based on layer mode
+ * @param is16bit - true for 16-bit mode, false for 8-bit mode
+ * @returns 2 for 16-bit, 1 for 8-bit
+ */
+declare const charCodeByteSize: (is16bit: boolean) => number;
 declare const UPDATE_PACKET_HEADER_SIZE = 9;
 declare const DISPLAY_HEADER_SIZE = 5;
 declare const LAYER_HEADER_SIZE = 13;
@@ -8054,5 +8683,5 @@ declare class PostProcessOrderCollector {
     private parseColor;
 }
 
-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, BitmapFont, BitmapFontRegistry, 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, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, MacroEngine, MacroEventType, MacroOrderType, MacroRegistry, OrderBuilder, OrderType, POLYLINE_ORDER_MIN_SIZE, POSTPROCESS_SET_AMBIENT_EFFECT_SIZE, POSTPROCESS_SET_CONFIG_MIN_SIZE, POSTPROCESS_SET_GRID_SIZE, POSTPROCESS_SET_SCALING_MODE_SIZE, POSTPROCESS_SET_SCANLINES_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, TRIGGERGLOBALSOUND_ORDER_SIZE, TRIGGERSOUND_ORDER_SIZE, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, WebFont, WebFontRegistry, createASCII8x8FontLoad, createEmptyCompressedInputPacket, decodeCompressedInput, decodeInt8ToAxis, encodeAxisToInt8, encodeCompressedInput, getASCII8x8FontConfig, getAllCharCodes, getAudioOrderTypeName, getButtonByteCount, getCharBitmap, getCompressedPacketSize, getMacroEventTypeName, getMacroOrderTypeName, getOrderTypeName, hasChar, isValidAudioOrderType, isValidMacroEventType, isValidMacroOrderType, isValidOrderType };
-export type { AnyAudioOrder, AnyLoad, AnyMacroEvent, AnyMacroOrder, AnyPostProcessOrder, AudioOrder, BitmapFontConfig, BitmapFontLoad, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, ButtonBorderStyle, ButtonConfig, ButtonStateColors, Cell, ChangeEvent, CircleShape, ClickEvent, Color, ColorPaletteLoad, CompressedInputPacket, ConfigureSpatialOrder, CoreMode, CoreOptions, CreateInstanceConfig, CreateInstanceOrder, EffectMacroTemplate, EffectTransform, EllipseShape, FadeOutSoundOrder, LineMacroTemplate, LineShape, MacroEntry, MacroEvent, MacroInstanceEntry, MacroLoad, MacroOrder, MacroTemplate, MacroTemplateBase, MacroType, MacroUpdateResult, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, ParticleConfig, ParticleEmitter, ParticleMacroTemplate, PauseSoundOrder, PlayGlobalSoundOrder, PlaySoundOrder, RectangleShape, RemoveInstanceOrder, RenderCommand, ResumeSoundOrder, RevealCellDef, RevealContent, RevealContentType, RevealCursor, RevealDirection, RevealMacroTemplate, RevealPattern, RevealPause, SelectEvent, SetAmbientEffectOrder, SetConfigOrder, SetGridOrder, SetListenerPositionOrder, SetScalingModeOrder, SetScanlinesOrder, SetSoundEffectsOrder, ShapeData, SoundEntry, SoundLoad, SpriteLoad, StopSoundOrder, SubmitEvent, TickStats, TriangleShape, UIMacroTemplate, UIState, UISubtype, UnicolorSprite, UpdateInstanceOrder, UpdatePacket, UserTickStats, WebFontConfig, WebFontLoad };
+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, BitmapFont, BitmapFontRegistry, 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, ImageFont, ImageFontRegistry, InputBindingRegistry, LAYER_CELL_COUNT, LAYER_HEADER_SIZE, LAYER_SIZE, LINE_SHAPE_SIZE, Layer, LoadType, MacroEngine, MacroEventType, MacroOrderType, MacroRegistry, OrderBuilder, OrderType, POLYLINE_ORDER_MIN_SIZE, POSTPROCESS_SET_AMBIENT_EFFECT_SIZE, POSTPROCESS_SET_CONFIG_MIN_SIZE, POSTPROCESS_SET_GRID_SIZE, POSTPROCESS_SET_SCALING_MODE_SIZE, POSTPROCESS_SET_SCANLINES_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, TRIGGERGLOBALSOUND_ORDER_SIZE, TRIGGERSOUND_ORDER_SIZE, UPDATE_PACKET_HEADER_SIZE, UpdateFlags, UpdateFlagsHelper, UpdatePacketDecoder, User, UserStats, WebFont, WebFontRegistry, charCodeByteSize, createASCII8x8FontLoad, 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, AtlasBlocks, AudioOrder, BitmapFontConfig, BitmapFontLoad, Bitmask16Order, Bitmask16Variant, Bitmask4Order, Bitmask4Variant, BitmaskOrder, ButtonBorderStyle, ButtonConfig, ButtonStateColors, Cell, ChangeEvent, CharCodeMode, CircleShape, ClickEvent, Color, ColorPaletteLoad, CompressedInputPacket, ConfigureSpatialOrder, CoreMode, CoreOptions, CreateInstanceConfig, CreateInstanceOrder, EffectMacroTemplate, EffectTransform, EllipseShape, FadeOutSoundOrder, GlyphSize, ImageFontConfig, ImageFontLoad, ImageFontOptions, LineMacroTemplate, LineShape, MacroEntry, MacroEvent, MacroInstanceEntry, MacroLoad, MacroOrder, MacroTemplate, MacroTemplateBase, MacroType, MacroUpdateResult, MulticolorCell, MulticolorSprite, MulticolorSpriteLoad, NetworkDisplay, NetworkLayer, ParticleConfig, ParticleEmitter, ParticleMacroTemplate, PauseSoundOrder, PlayGlobalSoundOrder, PlaySoundOrder, RectangleShape, RemoveInstanceOrder, RenderCommand, ResumeSoundOrder, RevealCellDef, RevealContent, RevealContentType, RevealCursor, RevealDirection, RevealMacroTemplate, RevealPattern, RevealPause, SelectEvent, SetAmbientEffectOrder, SetConfigOrder, SetGridOrder, SetListenerPositionOrder, SetScalingModeOrder, SetScanlinesOrder, SetSoundEffectsOrder, ShapeData, SoundEntry, SoundLoad, SpriteLoad, StopSoundOrder, SubmitEvent, TickStats, TriangleShape, UIMacroTemplate, UIState, UISubtype, UnicolorSprite, UpdateInstanceOrder, UpdatePacket, UserTickStats, WebFontConfig, WebFontLoad };