Assets

Looking for audio assets? AudioClip loading is documented separately in API: Audio.

Asset size limits

Sprite sheets, font atlases, and raw indexed buffers share the same decoded-size policy as render configuration (8192 pixels per side, 16,777,216 total pixels). Limits are enforced before canvas readback, CPU buffer retention, GPU texture creation, and software sprite loops.

• .btfont files may reference either a relative PNG path or an embedded PNG data URI.
• Embedded textures must use data:image/png;base64,... and stay within the embedded payload cap above.
• Other data: schemes (for example JPEG) are rejected before image decode.
• Decoded atlas dimensions use the same width, height, and pixel-area limits as sprite sheets.
• Prefer separate PNG files for large atlases so the JSON payload stays under the JSON size limit.

Loading assets

AssetLoader caches images by URL so repeated loads share the same HTMLImageElement. Oversized images are rejected as soon as the browser reports decoded dimensions.

import { AssetLoader } from 'blit386';

// Load a single image (cached by URL)
const image = await AssetLoader.loadImage('sprites.png');

// Load multiple images in parallel
const images = await AssetLoader.loadImages(['sprites.png', 'tiles.png']);

// Check cache before loading
if (AssetLoader.isLoaded('sprites.png')) {
  // already cached
}

// Drop a single URL's cache entry (manual reload or tests; blit386/vite watcher usually skips this)
AssetLoader.evict('sprites.png');

// Number of image loads currently in flight
AssetLoader.loadingCount;

AssetLoader.evict() is also the manual escape hatch for forcing a fresh load outside the blit386/vite plugin's automatic asset watcher - see Hot Reload.

For a loading-screen indicator that covers both images and audio clips, use BT.loadingAssetsCount - it sums AssetLoader.loadingCount and AudioClip.loadingCount (see API: Audio) and drops back to 0 once every in-flight load has settled:

if (BT.loadingAssetsCount > 0) {
  // show a spinner or progress bar
}

Sprite setup - preferred path

Use SpriteSheet.loadIndexed() for all standard sprite setup. It combines color registration, image loading, and palette indexization in one call.

import { BT, Palette, SpriteSheet, Vector2i } from 'blit386';

const palette = new Palette(256);

const indexed = await SpriteSheet.loadIndexed(
  'sprites/hero.png', // URL
  palette, // palette to populate
  10, // startSlot - first palette slot to write colors into
  { sort: 'luminance' }, // optional: color order in palette ('luminance' | 'none')
);

BT.paletteSet(palette); // activate AFTER loadIndexed returns

// Draw using the returned sheet and source rectangle:
BT.drawSprite(indexed.sheet, indexed.srcRect, new Vector2i(20, 20));

// indexed.colors - list of Color32 values registered into the palette
// indexed.srcRect - Rect2i spanning the full image

• Colors are sorted by perceived luminance (darkest-first) by default.
• Pass { sort: 'none' } to preserve row-major scan order.
• Slot 0 is never touched - transparent pixels in the image map to slot 0 at draw time.

Tile grids

Pass tileSize to loadIndexed (or load) when the image is a grid of equal cells. BT.drawTile and sheet.tileRect then find cells for you:

const { sheet } = await SpriteSheet.loadIndexed('/sprites/walk.png', palette, 1, { tileSize: new Vector2i(16, 24) });

const walkFrames = [0, 1, 2, 3].map((i) => sheet.tileRect(i)); // built once in init()
sheet.tileSize = 8; // or set or change it later; null removes the grid

Setting sheet.tileSize (or the tileSize load option) to anything but a positive whole number of at most 8192 (the largest sheet the engine accepts) on both axes throws a RangeError and leaves the grid unchanged. sheet.tileSize reads back as a frozen Vector2i (or null). The grid survives a hot-reload image swap, and lookups are checked against the sheet's current size. See Drawing tiles.

Sprite setup - manual path

Use this only when you need fine-grained control over the palette layout or want to load several sheets into the same palette sequentially.

import { BT, Palette, SpriteSheet } from 'blit386';

const palette = new Palette(256);

const colors = await SpriteSheet.loadColorsIntoPalette('hero.png', palette, 10);
const tileColors = await SpriteSheet.loadColorsIntoPalette('tiles.png', palette, 10 + colors.length);

const sheet = await SpriteSheet.load('hero.png');

sheet.indexize(palette);
BT.paletteSet(palette);

To create a sheet from raw palette-indexed pixel data (advanced / test use):

const sheet = SpriteSheet.fromIndexedPixels(width, height, indexedPixels);

Palette offset

Pass a paletteOffset (per-draw shift, not an absolute slot) to BT.drawSprite() and BT.printFont() to remap stored texel indices before palette lookup. Useful for team-color variations and damage flashes. Terminology and examples: Palette addressing. Draw semantics: API: Rendering.

BT.drawSprite(sheet, srcRect, pos, 16); // render in "blue team" color range

Bitmap fonts

Load .btfont files for proportional, palette-indexed bitmap fonts. After loading, register colors in the palette and indexize the font's internal sprite sheet before drawing (same pattern as manual sprite setup).

const palette = new Palette(256);
const font = await BitmapFont.load('fonts/MyFont.btfont');
font.getSpriteSheet().indexize(palette);
BT.paletteSet(palette);

BT.printFont(font, new Vector2i(10, 10), 'Hello!');
BT.printFont(font, new Vector2i(10, 10), 'Hello!', paletteOffset); // per-draw index shift

• Font rendering goes through the same sprite pipeline as BT.drawSprite() and is auto-batched.
• SpriteSheet helpers (after indexize): isIndexed(), getIndexedPixels() (defensive copy), getIndexedPixelsRef() (no copy, for hot-path CPU blitting - do not mutate the returned array), reindexize(palette) when palette layout changes. SpriteSheet.loadIndexed() returns IndexedSpriteLoadResult ({ sheet, srcRect, colors }).
• See Bitmap Fonts Guide for the .btfont format specification and the BMFont conversion workflow (pnpm run convert-font).

Hot-replacing assets

Under a Vite dev server with the blit386/vite plugin installed, editing a sprite sheet's source image or a .btfont file under a watched asset directory (public/ by default) updates the already-loaded asset in place - no page reload, and demo-held references (a SpriteSheet or BitmapFont instance, or an IndexedSpriteLoadResult.sheet) stay valid. A sprite sheet re-runs indexize() against the active palette when it was already indexized; a bitmap font rebuilds its glyph tables and texture.

Each SpriteSheet also exposes status ('loading' | 'ready' | 'failed') and progress (0 or 1) tracking a replacement fetch while it's in flight - useful for a per-sheet loading indicator, or combine with BT.loadingAssetsCount for a single engine-wide signal. A normally loaded sheet is always 'ready' with progress: 1.0, since its image has already resolved by the time the sheet is constructed.

sheet.status; // 'loading' | 'ready' | 'failed'
sheet.progress; // 0 while loading, 1.0 once ready

See Hot Reload for the full asset type matrix, including audio and the fallback-to-full-reload behavior for unrecognized file types.

System font

A built-in 6×14 monospace font covering printable ASCII (characters 32-126) plus a set of extra glyphs (dashes, accented Latin punctuation, media icons, arrows, Greek capitals, and more) - see scripts/system-font-extra-chars.mjs for the full list. No load step needed.

BT.systemPrint(new Vector2i(10, 10), paletteIndex, 'Score: 100');
BT.systemPrintMeasure('Score: 100'); // → Vector2i (pixel width, height)

• Use BT.systemPrint() for demo-specific HUD panels and labels. Call palette.applyHUD() at init so overlay and demo HUD share the same label/header/dim slot conventions - see API: Palette and Palette Presets - HUD.
• The engine draws its own overlay (present FPS, target FPS, draw calls, frame/update()/render() timings, backend, resolution, demo title) after each render() when isOverlayEnabled is true; see Overlay Guide.
• For styled variable-width text, use a bitmap font instead.

API history

See also

Last updated on October 18, 2026