Skill: Use the palette (colors)

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.

BLIT386 is palette-first: fill numbered color slots once, then draw with the slot numbers. Change a slot and everything drawn with it changes.

When to use

Use whenever you set up colors, the user mentions colors or themes, or you need to recolor things at runtime.

Make a palette in init()

async init() {
    this.palette = BT.paletteCreate(16); // room for 16 colors; slot 0 is transparent

    this.palette.set(1, new Color32(230, 80, 60)); // each channel 0..255
    this.palette.set(2, new Color32(20, 24, 40)); // background
    this.palette.set(3, Color32.white); // named presets are getters (no parentheses)

    BT.paletteSet(this.palette); // from now on, draw with slot numbers
    return true;
}

Fill a run of slots in one call (engine 1.7.0+)

When a block of slots is built from one list of colors - a dimmed copy for shadows, a tinted copy for a night theme - use fillBlock instead of writing the loop:

// fillBlock(start, source, transform) writes transform(source[i], i) into slot start + i,
// and returns the next free slot after the block.
// Slots 1..3 are taken above, so this darker copy starts at 4 and must fit inside the 16 slots.
const next = this.palette.fillBlock(
  4,
  this.baseColors,
  (color) => new Color32(color.r >> 1, color.g >> 1, color.b >> 1),
);

Chain from the return value to lay a second block down straight after the first, so no slot numbers are counted by hand.

Change a color later (the palette is live)

update() {
    if (this.hurt) {
        this.palette.set(1, new Color32(255, 255, 255)); // everything in slot 1 flashes white next frame
    }
}

Key calls

• BT.paletteCreate(size?) (method) - new palette (default 256 slots).
• palette.set(index, color) / palette.get(index) (methods) - write / read a slot.
• palette.fillBlock(start, source, transform) (method, engine 1.7.0+) - write a transformed block of colors into contiguous slots; returns start + source.length.
• BT.paletteSet(palette) (method) - make a palette active.
• palette.applyHUD(startSlot?) (method) - fill six ready-made HUD colors (white, background, label, header, dim, code) in one call.
• Built-in retro palettes: Palette.vga(), Palette.cga(), Palette.c64(), Palette.nes(), Palette.gameboy(), Palette.pico8().
• Color32 presets are getters (no parentheses): Color32.white, Color32.black, Color32.red, Color32.green, Color32.blue, Color32.yellow, Color32.cyan, Color32.magenta. Also Color32.fromHex('#ff8800') and named colors via Color32.resolveNamedColor('cornflowerblue').

Notes

• Slot 0 is always transparent - start visible colors at slot 1.
• new Color32(r, g, b) or new Color32(r, g, b, a) (alpha 0..255).
• Recoloring by changing slots is cheaper than redrawing. For animated color motion see the animate-the-palette skill.

See docs/palette.md.