Skill: Fix a runtime error

Written for blit386 1.8.0. The rest of blit386.dev documents the newest engine, so an API you find there may be missing from a game pinned to 1.8.0.

Diagnose and fix a BLIT386 game error using the local docs.

When to use

Use when the game crashes, shows a blank screen, throws an error in the browser console, or behaves unexpectedly.

Steps

1. Open docs/when-something-breaks.md first. It covers the most common beginner errors with concrete fixes.
2. On a blank screen: ensure BT.paletteSet(palette) was called in init() before any draw call.
3. If you see "Cannot read properties of undefined": you likely forgot await before sprite or font load calls.
4. Note: 0 is not a valid palette index - slot 0 is always transparent; use slot 1 or higher.
5. Check AGENTS.md for correct engine API usage - getters have no (), methods do.
6. Post-process effects require WebGPU - confirm BT.activeBackend is not 'software' (the Canvas 2D fallback does not run effects). Keep starters free of post-process effects.

What to check

• update() is for logic only; render() is for drawing only. Drawing in update() causes visual glitches.
• If key or button taps feel randomly missed: isKeyPressed/isKeyReleased/inputString/isPressed/isReleased must be read in update(). Reading them in render() can miss the one-frame edge; see docs/input.md.
• All screen coordinates must be whole numbers (Vector2i, Rect2i). Fractions cause off-by-one pixel issues.
• A sprite that will not stretch into a Rect2i, or an error about a Rect2i destination: the stretch form of BT.drawSprite needs an options object as the 4th argument ({} is enough), with scale at 1 and no pivot (engine 1.8.0+). A palette fade at the wrong speed, or a slot set in render() that snaps back: palette effects now step once per update(), so change slots in update() / init(). Both are in docs/when-something-breaks.md.
• If you see {{ or }} in a file, a template placeholder was not substituted - this is a scaffolding bug, not a game bug.
• After a save that breaks init(), hot reload should leave the previous game running - fix the typo and save again (see docs/hot-reload.md). If every tiny edit full-reloads the page, confirm vite.config.js has plugins: [blit386()] and blit386 is 1.4.0+.