Rendering

All draw calls require a palette to be active (BT.paletteSet(palette) before the first BT.drawSprite, BT.drawRectFill, etc.). All coordinates are integer pixels - use Vector2i and Rect2i, never floats.

Palette addressing: primitives and BT.systemPrint use an absolute paletteIndex. Sprites and BT.printFont use an optional paletteOffset added to stored texel indices. See Palette addressing.

Primitives

BT.clear(paletteIndex); // fill entire display
BT.clearRect(rect, paletteIndex); // fill rectangular region

BT.drawPixel(pos, paletteIndex); // Vector2i overload
BT.drawPixel(x, y, paletteIndex); // numeric overload

BT.drawLine(p0, p1, paletteIndex); // pixel-perfect, no antialiasing
BT.drawRect(rect, paletteIndex); // outline only
BT.drawRectFill(rect, paletteIndex); // filled

All primitives write palette indices, not RGBA - the active palette resolves colors at frame end.

Two more primitive-drawing demos: pixel art from number grids, and animated mathematical patterns.

Sprites

Drawing

BT.drawSprite(sheet, srcRect, destPos);
BT.drawSprite(sheet, srcRect, destPos, paletteOffset);

• sheet - an indexed SpriteSheet (must have been prepared via loadIndexed or indexize).
• srcRect - source region within the sheet in pixels.
• destPos - top-left destination in display coordinates.
• paletteOffset - shift added to every stored pixel index before palette lookup (default 0).

Palette offset semantics

Stored sprite indices start at 1; index 0 is always transparent and discarded. The offset shifts every stored index before the palette lookup, so a pixel stored at index i renders as palette[i + paletteOffset]:

This drives palette-swap effects such as team colors or damage flashes - point the same sprite at a different band of the palette without re-uploading texels.

• Validation: paletteOffset must be a non-negative integer below the active palette size, or the draw throws.
• Clamping: the WebGPU sprite shader computes combined = storedIndex + paletteOffset and clamps with index = min(combined, 255u), so any sum past 255 maps to palette slot 255.

BT.drawSprite(sheet, srcRect, new Vector2i(10, 10)); // normal
BT.drawSprite(sheet, srcRect, new Vector2i(10, 10), 16); // blue-team shift

Draws are auto-batched by texture. Group draws from the same sheet to minimize GPU state changes.

Drawing tiles

Most retro sprite sheets are grids of equal cells. Give the sheet a tile size once, then draw cells by index or by column and row - no Rect2i math:

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

BT.drawTile(sheet, frame, new Vector2i(40, 60)); // row-major index: 0 is top-left
BT.drawTile(sheet, 2, 1, new Vector2i(40, 60)); // column 2, row 1
BT.drawTile(sheet, 2, 1, new Vector2i(40, 60), 16); // with a palette offset

A sheet with no grid can still be drawn by passing the tile size before the position:

BT.drawTile(sheet, 2, 1, 8, new Vector2i(40, 60)); // 8×8 tiles
BT.drawTile(sheet, 2, 1, new Vector2i(16, 24), new Vector2i(40, 60)); // 16×24 tiles

• Grid: tileSize is a number for square tiles or a Vector2i for width × height. Set it with the tileSize option of SpriteSheet.load / loadIndexed, or sheet.tileSize = 16 at any time. See Assets.
• Whole tiles only: a 40-pixel-wide sheet of 16-pixel tiles has 2 columns; the 8-pixel strip at the edge is not a tile.
• Errors: a tile outside the grid, a negative or fractional index, column, or row, a tile size that is not a positive whole number, or a grid form on a sheet with no tile size all show an error instead of drawing.
• Watch the argument order: BT.drawTile(sheet, col, row, new Vector2i(16, 16)) is the grid form with a destination, not the explicit-size form with a missing destination.
• No allocation: BT.drawTile reuses one internal source rectangle, so it is safe in a hot loop.
• sheet.tileRect(index) / sheet.tileRect(col, row) return the same rectangle as a new Rect2i - use them in init() to build frame lists. Rect2i.fromTile(col, row, tileSize) does the math with no sheet at all.
• To flip or rotate a tile, use BT.drawSprite(sheet, sheet.tileRect(i), dest, params) - see Flipping, rotating, and scaling sprites. drawTile has no params object and no tint.

Flipping, rotating, and scaling sprites

Pass a SpriteDrawParams object as the 4th argument instead of a number to flip a sprite or turn it in quarter turns. One sprite sheet frame then covers every facing direction:

// Allocate once, outside the draw loop, with every field present.
const params: SpriteDrawParams = { flags: 0, pivot: undefined, scale: 1, paletteOffset: 0 };

params.flags = isFacingLeft ? BT.FLIP_H : 0;
BT.drawSprite(sheet, srcRect, destPos, params);

params.flags = BT.ROT_90_CW | BT.FLIP_V; // combine bits with |
BT.drawSprite(sheet, srcRect, destPos, params);

params.flags = 0;
params.scale = 2; // twice as big, nearest-neighbor
BT.drawSprite(sheet, srcRect, destPos, params);

params.scale = new Vector2i(3, 1); // three times as wide
BT.drawSprite(sheet, srcRect, destPos, params);

params.scale = 1;
BT.drawSprite(sheet, srcRect, new Rect2i(10, 40, 50, 12), params); // stretch into a box

To place a sprite by a point other than its top-left - its feet, its center - set pivot:

const params: SpriteDrawParams = { flags: 0, pivot: new Vector2i(8, 16), scale: 2, paletteOffset: 0 };

// Bottom center of the 16×16 source lands on `feet`, at any scale.
BT.drawSprite(sheet, srcRect, feet, params);

params.pivot = undefined; // back to top-left placement

The sprites demo walks through every SpriteDrawParams field: recolor, flip, quarter turns, scale, pivot, and stretch.

BT.FLIP_H; // horizontal flip
BT.FLIP_V; // vertical flip
BT.ROT_90_CW; // rotate 90° clockwise
BT.ROT_180_CW; // rotate 180°
BT.ROT_270_CW; // rotate 270° clockwise

// 1. Fast path. Unchanged since 0.1.0.
declare function drawSprite(sheet: SpriteSheet, srcRect: Rect2i, destPos: Vector2i, paletteOffset?: number): void;

// 2. Params object (1.8.0). `params` is required here: without it, a call is overload 1.
declare function drawSprite(sheet: SpriteSheet, src: Rect2i, dest: Vector2i | Rect2i, params: SpriteDrawParams): void;

interface SpriteDrawParams {
  flags?: number; // any combination of BT.FLIP_* / BT.ROT_* bits (default 0)
  pivot?: Vector2i | undefined; // source pixels, before flags (default undefined: top-left placement)
  scale?: number | Vector2i; // positive integers, screen axes, after flags (default 1)
  paletteOffset?: number; // same meaning as the fast-path 4th argument (default 0)
}

• The params object is read, never mutated or retained. The engine copies the numbers it needs before returning, so a hot loop can allocate params once and write fields between draws. Create it with every field present so its shape never changes. In TypeScript, annotate it as SpriteDrawParams so scale can later hold a Vector2i.
• With a Vector2i dest and no pivot, dest is the top-left of the post-flags, post-scale footprint. A 16×32 sprite with ROT_90_CW covers 32×16, growing down and right from dest; with scale: 2 it covers 64×32.
• pivot is a point in source pixels relative to the source rect's top-left, in [0, sw] x [0, sh] (corner coordinates, not texel indices). It goes through the flags (the "Point map" column in Transform order and flags), is multiplied by scale, and that point lands on dest. Values outside the sprite are fine. The result is an integer move of the footprint, so pixels are identical on both backends.
• An explicit pivot of (0, 0) is not the same as no pivot. It is the source's top-left corner, which moves when the sprite is flipped or turned. For a 16×16 sprite with FLIP_H, no pivot draws the footprint at dest, while pivot: new Vector2i(0, 0) draws it 16 pixels to the left, because the source's left edge is now on the right. To return a reused params object to top-left placement, assign params.pivot = undefined.
• With a Rect2i dest, the rectangle is that footprint already: flags only remap texels into it, they do not resize it. Any scale other than undefined, 1, or (1, 1) shows an error, because the rect already fixes the box. A defined pivot shows an error too, whatever the scale. The neutral scale: 1 keeps one reused params object valid for both dest kinds. An empty or negative source or destination rect draws nothing.
• scale is a positive integer (number or Vector2i). scale: 2 and scale: new Vector2i(2, 2) match, and scale.x is on-screen width even after a 90-degree turn. 0, negatives, and non-integers show an error that points at a Rect2i dest for uneven sizes.
• paletteOffset works exactly as on the fast path, with the same validation. The only recolor control is paletteOffset: on the fast path or inside params, never both.
• The flipped draw is the same on both backends, pixel for pixel. The fast path (a number or nothing as the 4th argument) is untouched: two typeof checks and no allocation.

Dispatch

Runtime dispatch reads argument 2, then argument 4:

1. A Rect2i source: if argument 4 is an object, it is SpriteDrawParams; null and arrays show an error. Otherwise (number or undefined, defaulting to 0) it is paletteOffset and the fast path.
2. A string source (a named frame) or raw source numbers show an error for now - see Planned: sprite draw params.

With params, dest instanceof Rect2i is the stretch box and dest instanceof Vector2i is a point; anything else shows an error. A Rect2i dest needs the params form: drawSprite(sheet, src, destRect) and drawSprite(sheet, src, destRect, 0) are type errors - write drawSprite(sheet, src, destRect, {}). In development builds the fast path also shows an error for a Rect2i from untyped code, instead of drawing it unscaled at the rectangle's top-left; release builds skip the check.

Transform order and flags

• params.flags uses the BT.FLIP_* / BT.ROT_* bits (values unchanged since 0.1.0). Booleans are not accepted.
• Every combination inside 0x1f is valid and composes in one fixed order: FLIP_H, then FLIP_V, then clockwise quarter turns, counting ROT_90_CW as 1, ROT_180_CW as 2, and ROT_270_CW as 3, summed modulo 4. So ROT_90_CW | ROT_180_CW is ROT_270_CW, and ROT_180_CW | FLIP_H | FLIP_V is the identity. Only bits outside 0x1f (and non-integers) show an error, naming the constants.
• The 32 possible masks reduce to the 8 orientations below. The engine resolves a mask through one 32-entry lookup; the software texel remap and the GPU UV corner order both read the same per-orientation table.
• Arbitrary-angle rotation is not supported. There is no rotation field, so a leftover rotation on an object literal is a type error rather than a silent no-op.

The 8 orientations for a 3×2 source ABC / DEF (sw = 3, sh = 2). "Point map" sends a point (x, y) in [0, sw] x [0, sh] to the post-flags footprint:

Texel remap uses the same point map on the texel center: source texel (i, j) lands on footprint texel map(i + 0.5, j + 0.5) - (0.5, 0.5), which is the point map with sw - 1 and sh - 1 in place of sw and sh. For example, FLIP_H sends column 0 to column sw - 1.

Stretch sampling

Nearest-neighbor for a post-flags footprint (fw, fh) stretched into (dw, dh) samples each destination pixel at its center, with exact ties rounding down. All operands are non-negative integers, so the division truncates:

const footprintX = Math.floor(((2 * dx + 1) * fw - 1) / (2 * dw));
const footprintY = Math.floor(((2 * dy + 1) * fh - 1) / (2 * dh));

The footprint texel then maps back to a source texel through the orientation's texel remap.

• For dw = fw and for every integer scale (dw = fw * scale) this gives floor(dx * fw / dw), so 1:1 and integer-scale output equal the plain block copy. Only uneven Rect2i stretches depend on the center rule.
• A GPU samples at pixel centers too, but in float32 an exact tie can land on either texel. The WebGPU path removes that risk without shader changes: shift both footprint-space UV edges by -1 / (4 * dw) texels on x (and -1 / (4 * dh) on y) before sending them through the orientation's point map. Every non-tie sample sits at least 1 / (2 * dw) texels from a texel edge, so the shift moves ties down and leaves other samples on their texel.
• A float32 simulation of that shifted interpolation, using normalized UVs on a 1024-wide sheet, matched the formula on 964,800 of 964,800 cases (source widths 1-48, destination widths 1-200). Center sampling without the shift missed 7,466 of them. The simulation is not a GPU run. The visual-regression suite renders uneven stretches on both backends and compares them pixel for pixel.
• The 1:1 fast path keeps today's UV and blit math. Scaled and stretched quads use a separate emission path so 1:1 vertices stay identical.

Nine-slice panels

A nine-slice splits one sprite region into 4 corners, 4 edges, and a center, so a single piece of panel art fills boxes of any size. Corners always draw at 1:1. Edges and center either stretch or tile.

// init(): build once. Both rects are in sheet coordinates; inner marks the center.
const panel = NineSlice.fromSheet(sheet, new Rect2i(0, 0, 16, 16), new Rect2i(4, 4, 8, 8), {
  edges: 'tile', // default 'stretch'
  center: 'stretch', // default 'stretch'
});

// render(): any box, every frame; drawNineSlice itself allocates nothing.
BT.drawNineSlice(panel, new Rect2i(20, 20, 120, 64));
BT.drawNineSlice(panel, new Rect2i(20, 100, 120, 64), 16); // palette offset, as in drawSprite

• NineSlice.fromSheet(sheet, outer, inner, options?) copies and freezes both rects. outer must lie inside the sheet, inner inside outer and at least 1×1. Invalid arguments throw. inner may touch outer: a zero-size top and bottom gives a horizontal three-slice bar.
• 'stretch' fills the box with the stretch sampling rule, so it matches drawSprite with a Rect2i dest pixel for pixel on both backends. Edges stretch only along their length.
• 'tile' repeats the strip at 1:1 from the box's top-left corner. The last tile on the right and bottom is cropped, so nothing draws outside destRect.
• When destRect is smaller than the two corners on an axis, the corners share it in proportion to their sizes (left and top take the floor) and are cropped from their outer side; the edges between them disappear. A panel can animate open from size 0 and keep its outline.
• An empty or negative destRect draws nothing. Recolor is paletteOffset only - there is no tint.
• Each tile is one quad. Tiling a 1-pixel strip across a large box costs one quad per pixel and can fill the sprite buffer; stretch flat fills and tile only patterned art.

Planned: sprite draw params

All transform features hang off one reusable params object. Separate methods stay separate: BT.drawTile and BT.drawNineSlice are not further drawSprite overloads. There is no drawSpriteScaled, no tint, and no arbitrary-angle rotation field in v1.

// 1. Shipped. Unchanged.
declare function drawSprite(sheet: SpriteSheet, srcRect: Rect2i, destPos: Vector2i, paletteOffset?: number): void;

// 2. Shipped (1.8.0).
declare function drawSprite(sheet: SpriteSheet, src: Rect2i, dest: Vector2i | Rect2i, params: SpriteDrawParams): void;

// 3. Planned named frame (BT-271). Always takes the params path, so `params` may be omitted.
declare function drawSprite(
  pack: SpritePack,
  frameName: string,
  dest: Vector2i | Rect2i,
  params?: SpriteDrawParams,
): void;

// 4. Reserved for BT-262 (milestone 2.0.0). Not added to the 1.8.0 types.
declare function drawSprite(
  sheet: SpriteSheet,
  srcX: number,
  srcY: number,
  srcW: number,
  srcH: number,
  destX: number,
  destY: number,
  paletteOffsetOrParams?: number | SpriteDrawParams,
): void;

interface SpriteDrawParams {
  flags?: number; // shipped
  pivot?: Vector2i | undefined; // shipped: source pixels, before flags; assign undefined to reset
  scale?: number | Vector2i; // shipped
  paletteOffset?: number; // shipped
}

// Planned (BT-271). Returned by SpritePack.frame(name).
interface SpriteFrame {
  readonly sheet: SpriteSheet; // the page this frame lives on
  readonly rect: Rect2i; // frozen
  readonly pivot?: Vector2i; // frozen; filled from Aseprite slice data by BT-364, never applied implicitly
}

| undefined on pivot is deliberate: a reused params object returns to the default pivot with params.pivot = undefined, and that assignment must type-check under exactOptionalPropertyTypes.

Planned dispatch

The shipped dispatch extends as follows:

• typeof src === 'string': overload 3. typeof src === 'number': overload 4. Both throw until their tickets ship.
• Create a reused params object with every field present, so its shape never changes, annotated as SpriteDrawParams: const params: SpriteDrawParams = { flags: 0, pivot: undefined, scale: 1, paletteOffset: 0 }.
• Overload 3 is SpritePack.frame(name) followed by overload 2 with frame.sheet and frame.rect. A missing name throws. frame(name) returns the same frozen SpriteFrame on every call, so a hot loop resolves it once and calls BT.drawSprite(frame.sheet, frame.rect, dest) (overload 1) or adds params (overload 2) - no per-draw string lookup. Carrying the sheet on the frame keeps multi-page packs correct and makes a rect from the wrong sheet impossible. frame.pivot is data only: pass params.pivot = frame.pivot to use it. There is no raw-number form for names.
• Overload 4, when it exists, cannot express a destination rectangle, so stretched draws (a Rect2i dest) use overload 2. Raw numbers occupy arguments 2-7; argument 8 is paletteOffset or SpriteDrawParams, same split as the fast path, so flags, integer scale, and pivot work as on overload 2 with a point dest.
• Planned transform order: flags, then integer scale, then placement. scale multiplies the post-flags footprint in screen axes, so scale.x is on-screen width even after a 90-degree turn. If a later ticket adds an arbitrary angle, the unit is degrees, and the software renderer throws until it can match pixel-for-pixel.

Color

The only recolor control is paletteOffset, on the fast path or inside params, never both and never stacked. There is no tint field. Older sketches that used Color32 / ColorArg as a 4th argument are stale.

Software-renderer parity

No accepted field degrades. The software blit is the pixel spec; WebGPU must match it. The 1:1 path stays today's blitIndexedRect / UV quad emission.

GPU note for implementers: the vertex shader already passes UVs through. Flags and scale are CPU-side corner and UV writes into the existing 5-value vertex, with the orientation table choosing which source corner goes to which quad corner. Do not add a flags uniform on the 1:1 path.

Refreshing after a palette-layout swap

BT.paletteSet(newLayoutPalette);
BT.spritesRefresh(); // re-maps all tracked sheets to the new slot positions

Text

System font

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.

BT.systemFont returns the same BitmapFont instance BT.systemPrint draws with, as a live reference. Read codePoints on it to see every Unicode code point it covers, or pass it to BT.printFont directly.

BT.systemPrint(pos, paletteIndex, text); // draw text at pos
BT.systemPrintMeasure(text); // → Vector2i (pixel width × height)
BT.systemFont.codePoints.length; // how many characters the system font covers
BT.systemFont.hasGlyph('é'); // test one character before drawing it

Bitmap fonts

Variable-width fonts from .btfont files. The font's sprite sheet must be indexized before use.

const font = await BitmapFont.load('fonts/MyFont.btfont');
BT.printFont(font, pos, text);
BT.printFont(font, pos, text, paletteOffset); // palette-swap variant

See Bitmap Fonts Guide for the .btfont format spec and BMFont conversion.

Post-process effects

Two-tier fullscreen effect pipeline - a pixel tier and a display tier - running between scene render and swap-chain present, with a palette-resolve-and-upscale step bridging the two:

1. Pixel tier - operates on the logical r8uint framebuffer (one palette index per pixel). Effects here stay palette-native (chunky glitch, mosaic).
2. Palette resolve + upscale - PaletteResolveUpscalePass converts indices to RGBA through the active palette LUT and upscales to drawingBufferSize.
3. Display tier - operates on the RGBA output image. Hosts CRT scanlines, barrel distortion, bloom, etc. Requires drawingBufferSize in hardware settings.

Both chains add zero cost when empty.

// Add effect - routed to pixel or display chain by Effect.tier automatically
BT.effectAdd(new BarrelDistortion());
BT.effectAdd(new Scanlines());
BT.effectAdd(new Bloom());
BT.effectAdd(new PixelGlitch()); // pixel-tier effect

// Remove or clear
BT.effectRemove(effect); // remove one; no-op if not found
BT.effectClear(); // remove all from both chains

// One-line presets (return arrays of Effect)
for (const fx of BT.preset.crtPipBoy()) BT.effectAdd(fx);
for (const fx of BT.preset.amber()) BT.effectAdd(fx);
for (const fx of BT.preset.green()) BT.effectAdd(fx);

// Equivalent standalone imports also work:
import { crtPipBoy, amber, green } from 'blit386';
for (const fx of crtPipBoy()) BT.effectAdd(fx);

Built-in effects:

All effect classes are exported from 'blit386'. Each instance owns its own GPU resources and may be mutated each frame from demo code.

See Post-Process Effects Guide for parameter reference, the Effect interface, EffectTier, the FullscreenEffect base class, and how to write a custom effect.

Frame capture

Capture the current rendered frame as a PNG.

// Resolves after the next render pass completes
const blob = await BT.captureFrame();
const url = URL.createObjectURL(blob);

// Convenience: capture and trigger a browser download
await BT.downloadFrame();
await BT.downloadFrame('screenshot-001.png'); // custom filename

// Exact game pixels: one PNG pixel per logical pixel, at BT.displaySize
const exact = await BT.captureFrame({ size: 'display' });
await BT.downloadFrame('exact.png', { size: 'display' });

Which size?

FrameCaptureOptions.size picks the resolution, and with it what the PNG contains:

A game with no configure() inherits the default 640×480 drawing buffer for a 320×240 logical display, so BT.captureFrame() returns a 640×480 PNG where every game pixel is a 2×2 block. { size: 'display' } returns the 320×240 original. Neither size is affected by how the browser scales the canvas on screen.

While BT.renderAt holds the loop stopped, BT.captureFrame() re-renders the seeked frame to capture it instead of waiting for a loop frame that never comes, and runs after every renderAt called before it - see Seeking a frame with renderAt.

The display-size capture has its own pending slot on the renderer, separate from the F9 / Shift+F9 dev shortcuts, so an agent's capture and a keypress in the same frame both resolve. Two { size: 'display' } requests in the same frame still reject the earlier one, as two BT.captureFrame() calls always have.

The F9 / Shift+F9 dev-mode capture shortcuts use the same logical-size path as { size: 'display' }, from their own pending slot - see the resolution model in Core for details.

API history

See also

Last updated on October 18, 2026