FAQ

Answers to the questions that come up most often. For live discussion, see the Community page.

WebGPU availability and browser support

Which browsers support WebGPU?

Recent Chrome, Edge, Firefox, and Safari releases ship WebGPU; older versions either gate it behind a flag or lack it entirely, in which case the engine falls back to the Canvas 2D software renderer.

The exact per-browser matrix is maintained with the engine and published at Browser Support - that page is the single source of truth, so it is not duplicated here.

What happens in a browser where WebGPU is not available?

The engine detects the missing API at startup and switches to the Canvas 2D software renderer automatically. No code change is required. Use BT.activeBackend at runtime to check which backend is running (webgpu or software).

Can I force the software renderer even in a WebGPU-capable browser?

Yes. Pass backend: 'software' in HardwareSettings when calling bootstrap(), or append ?backend=software to the page URL during development.

Does BLIT386 use WebGL instead of WebGPU?

No. The two backends are WebGPU and Canvas 2D. There is no WebGL backend. WebGPU and WebGL can coexist in the same browser, but BLIT386 does not use WebGL.

Software fallback

Are all features available in the software renderer?

Most are. The notable exception is post-process effects: calling BT.effectAdd() in software mode throws an error because the effect pipeline requires WebGPU compute and render passes. Gate effect registration on BT.activeBackend === 'webgpu'. See API: Rendering for the full list.

Does the software renderer look different from the WebGPU renderer?

Palette resolution, integer coordinates, and sprite rendering are designed to match. The software renderer does not support post-process effects (CRT scanlines, bloom, barrel distortion, etc.), so scenes that rely on those effects will look different when the fallback is active. The engine overlay shows the active backend in its renderer diagnostics bar.

How do I test fallback behavior locally?

Append ?backend=software to the dev-server URL, or set backend: 'software' in HardwareSettings. The Software Fallback Smoke Matrix lists the manual checklist used to verify parity.

Setup and installation

What is the minimum Node.js version?

Node.js >= 22.18.0 (LTS). The engine is published as an ESM package and requires a bundler such as Vite, webpack, or esbuild to serve it in a browser.

What is the quickest way to start a new project?

Use the scaffolder:

npm create blit386@latest my-game

This generates a ready-to-run Vite project with the engine, a starter game, and the blit project CLI. See Getting Started for the full walkthrough.

The demo page is blank and there is no error in the console. What should I check?

• Verify that bootstrap() is called and that the canvas element ID matches BootstrapOptions.canvasID (default: blit386-canvas).
• Check that BT.paletteSet() is called in init() before any draw calls in render().
• Open the browser DevTools Network tab and confirm that sprite sheets and font files loaded successfully.
• Check BT.activeBackend - if it is null, the engine has not finished initializing yet.

I am getting a TypeScript error about unknown properties on HardwareSettings. What is happening?

Some configuration fields were renamed in 1.1.1 to follow the is*/has* boolean-naming convention (1.2.0 was a different change: the npm package rename from blit-tech to blit386). The old names are available as compatibility aliases until the next major release. See the Deprecation Timeline for the full mapping and the Changelog for the release history.

Audio

Why is there no sound?

Browsers refuse to start audio until the user interacts with the page, so BLIT386 starts in a locked state. On BT.init() the engine installs one-shot pointerdown, keydown, and touchstart listeners on the canvas; the first gesture unlocks the audio context for the rest of the session and BT.isAudioUnlocked flips to true.

The two playback paths behave differently while still locked:

• BT.soundPlay() is dropped - it returns an inert SoundRef and no voice is allocated.
• BT.musicPlay() is remembered and starts automatically the moment the context unlocks.

Loading is unaffected: AudioClip.load() and AudioClip.synth() both work while locked, because decoding does not need an unlocked context. If a game must make noise immediately, either wait for BT.isAudioUnlocked, or prompt for a click or key press first. See the Audio Guide.

Does audio work in the software renderer?

Yes. Audio is Web Audio only and never touches the GPU, so it behaves identically on the WebGPU and Canvas 2D backends. Post-process effects remain the only WebGPU-only feature.

Reporting

Where do I report bugs or ask questions?

Open an issue on GitHub or start a thread in GitHub Discussions. Please include your browser version, operating system, and a minimal reproduction.

See also