BLIT386 is a palette-first retro game engine for the web. Palette-first means you draw with numbered colors rather than RGBA pixels, so changing what color 3 means recolors everything drawn in it at once: a few bytes of palette upload, and water flows or the sky goes dark without a single pixel being redrawn. TypeScript throughout, WebGPU where the browser has it, an automatic Canvas 2D fallback where it does not. The design takes its cue from RetroBlit by Martin Cietwierkowski (@daafu).

Features

Quick start

The fastest way to begin is the scaffolder. It works with npm, pnpm, yarn, or bun and generates a ready-to-run Vite project with the engine installed, a starter game, and local docs:

npm create blit386@latest my-game

Prefer to wire it up by hand or add it to an existing project? Install the package and call bootstrap():

npm install blit386

import { bootstrap, BT, Color32, type IBTDemo, Rect2i } from 'blit386';

class MyGame implements IBTDemo {
  async init(): Promise<boolean> {
    // paletteCreate() returns a palette; paletteSet() installs it.
    const palette = BT.paletteCreate(16);

    palette.set(1, new Color32(32, 0, 128));
    palette.set(2, new Color32(255, 220, 90));

    BT.paletteSet(palette);

    return true;
  }

  update(): void {}

  render(): void {
    BT.clear(1);
    BT.drawRectFill(new Rect2i(10, 10, 40, 24), 2);
  }
}

void bootstrap(MyGame);

Featured demos

Hello WorldThe smallest possible BLIT386 program: one line of text, nothing else on screen.

BasicsYour first BLIT386 program: the engine lifecycle, a bouncing sprite, a palette, and text on the canvas.

PatternsAnimated mathematical art from primitives alone: spirals, Lissajous curves, waves, and a tunnel.

Sprite EffectsPalette offsets as game effects: damage flash, silhouette, ghost fade, team colors, and day or night.

StarfieldParallax scrolling stars at several speeds, so a flat two-dimensional field reads as real depth.

FlurryA retro screensaver port of the classic macOS Flurry: particle physics driving palette animation.

Palette CyclingAnimate entire scenes by rotating palette slots at runtime without touching a single pixel.

Snake GameA complete playable game: input handling, game-state loop, collision, and score rendering.

HypercubeA Fez-style rotating tesseract: watch a four-dimensional cube turn on a 256x256 PICO-8 sized canvas.

Coordinate PatternsAn endless world computed from hash1i, hash2i, and hash3i that stores no tiles, yet never changes.

NoiseValue, Perlin, and Simplex noise at matched settings, with an octaves slider and a terrain ramp.

Palette Exposure FadeThe plain palette fade and the camera-style exposure fade side by side, running on one shared palette.

View all demos

Where to go next

• Documentation - the full public API reference and guides.
• API: Core - bootstrap(), the game loop, camera, and core types.
• Input Guide - pointer, keyboard, and gamepad input.
• Interactive demos - runnable examples for every subsystem.

The engine source lives in the blit386 repository on GitHub.