Getting Started

There are two ways to start with BLIT386: the scaffolder (recommended) or a manual install into an existing project.

Scaffolder (recommended)

The quickest path 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, local docs, and the blit CLI:

npm create blit386@latest my-game

Then start the dev server:

cd my-game
npm install
npm run dev

The generated project includes a playable starter, an index.html, a Vite config, and a kid-friendly README.md. See create-blit386 for the scaffolder. The blit project CLI (blit run, blit doctor, blit upgrade, blit clean) lives in @blit386/kit.

Manual install

To add BLIT386 to an existing Vite (or other ESM bundler) project, install the package:

npm install blit386

Then implement a demo and start it with bootstrap(), which handles DOM ready, canvas lookup, backend selection (WebGPU with an automatic Canvas 2D fallback), and error display:

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

class Game implements IBTDemo {
  private x = 140;
  private speed = 1;

  async init(): Promise<boolean> {
    // Create a palette, fill the slots, then install it. Slot 0 is transparent.
    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 {
    this.x += this.speed;

    if (this.x < 0 || this.x > 280) {
      this.speed = -this.speed;
    }
  }

  render(): void {
    BT.clear(1);
    BT.drawRectFill(new Rect2i(this.x, 100, 40, 40), 2);
    BT.systemPrint(new Vector2i(108, 160), 2, 'HELLO BLIT386');
  }
}

void bootstrap(Game);

BT.paletteCreate() returns a palette; it does not install one. Call BT.paletteSet() with the result before the first draw call, and return true from init() so the engine knows startup succeeded.

bootstrap() defaults to a canvas with id blit386-canvas inside a canvas-container element. See API: Core for BootstrapOptions, the resolution model, the game loop, and the full configure surface.

Where to go next

• API: Core - bootstrap, the game loop, camera, Timer, and core types.
• API: Rendering - primitives, sprites, text, post-process, and frame capture.
• API: Audio - bus volume and mute, sound and music playback, the procedural synth.
• Palette Guide - the palette-first workflow.
• Input Guide - pointer, keyboard, and gamepad.
• Audio Guide - the bus layout and the browser user-gesture unlock rule.
• Interactive demos - runnable examples for every subsystem.

Requirements

• Node.js >= 22.18.0 and an ESM bundler (Vite, webpack, esbuild, or similar).
• A browser with WebGPU for the default backend; the engine falls back to a Canvas 2D software renderer otherwise. See Browser Support for the support matrix.