Palette

Create and activate a palette

import { BT, Color32, Palette } from 'blit386';

const palette = Palette.c64(); // or new Palette(256)
palette.set(1, new Color32(20, 30, 40, 255)); // custom background slot
BT.paletteSet(palette);

Key rules:

• Slot 0 is always transparent.
• Valid sizes are 2, 4, 16, 32, 64, 128, 256.
• BT.paletteSet() activates a palette before the first draw (or when swapping to another Palette instance).
• After activation, edit colors with BT.palette.set(...); you do not need to call paletteSet() again for value-only changes (see Palette addressing).

Draw using absolute palette indices

Primitive and clear APIs take an absolute paletteIndex (the exact slot written to the framebuffer), not direct RGBA values. See Palette addressing.

BT.clear(1); // absolute paletteIndex 1
BT.drawRectFill(rect, 6); // absolute paletteIndex 6
BT.drawLine(start, end, 12); // absolute paletteIndex 12

When slot 6 changes in the active palette, every pixel drawn with absolute index 6 changes automatically.

Index sprites (preferred and manual flows)

const indexed = await SpriteSheet.loadIndexed('sprites/hero.png', palette, 32, { sort: 'luminance' });
BT.paletteSet(palette);
BT.drawSprite(indexed.sheet, indexed.srcRect, pos);

Per-draw palette offsets (zero-cost color variants)

BT.drawSprite(..., paletteOffset) adds a shift to each stored sprite index before lookup (not an absolute slot). See Palette addressing.

BT.drawSprite(heroSheet, heroSrc, leftTeamPos, 0); // base range
BT.drawSprite(heroSheet, heroSrc, rightTeamPos, 16); // same art, shifted color range

Use this for:

• Team colors
• Seasonal variants
• Damage-state tint sets
• Faction/UI themes

No duplicate textures required.

Runtime palette effects

Palette effects mutate slots over time. They advance once per fixed update, right after your update(), on the tick clock (BT.ticks * 1000 / BT.targetFPS) rather than on wall time, so they follow the fixed-step loop, not the display's refresh rate, and a BT.renderAt seek reproduces them exactly. An effect's time counts from the moment it was added, BT.ticksReset() pauses effects for one update instead of running them backwards, and a palette write made in render() lands after that frame's effects, not before them.

// Cycling: water/lava/plasma
BT.paletteCycle(240, 248, 4);

// Full-palette fade
BT.paletteFade(nightPalette, 2000, 'ease-in-out');

// Full-palette fade shaped like an iris pull
BT.paletteFadeExposure(nightPalette, 2000);

// Range-only fade
BT.paletteFadeRange(32, 63, dangerPalette, 400, 'ease-out');

// Temporary flash (slot 0 transparency preserved)
BT.paletteFlash(Color32.white, 120);

// Instant swap
BT.paletteSwap(10, 11);

// Cancel running effects
BT.paletteClearEffects();

Exposure fades vs. crossfades

paletteFade interpolates the encoded 8-bit values a palette stores. That is precisely what a post-production crossfade does: every color drops by the same proportion, the whole way, and the image sags uniformly into a muddy gray-black. A camera does not behave that way. Closing an iris multiplies light, and only then does the sensor encode it, so the image holds its brightness and then collapses near the end.

paletteFadeExposure works in that same linear light: it interpolates each entry's RGB between its starting color and its target there, rather than in the encoded values. Fading up from black or down to black - the case a cinematic fade almost always is - that interpolation reduces to scaling light up or down, exactly as an iris does.

Worth recording so nobody re-derives it wrong later: fading in linear light does not by itself make highlights linger relative to shadows. sRGB is close to a pure power curve, and a power curve is scale-invariant - multiplying linear light by k multiplies every encoded value by roughly the same factor. You get a better-shaped curve, not a differential between white and dark gray.

On real film that differential comes from headroom. A practical lamp in frame can sit far above diffuse white in linear scene terms, so stopping down two stops leaves it still clipping at pure white while everything else has visibly dropped. A palette engine has no headroom: 255 is the ceiling. So paletteFadeExposure approximates it by offsetting each entry's schedule by its luminance - bright entries start rising earlier and finish falling later, dark entries start late and crush early. That is the toe and shoulder behavior, with one knob (highlightLead).

Every entry still reaches the target exactly at the end, so nothing drifts and no color is left one step off after the fade lands.

Layout swap vs. value swap

Value swap (no sprite refresh)

If slot numbers stay the same and only RGB values change, do not refresh sprites.

Examples:

• Day/night tinting by editing slot colors
• Palette cycling/fade/flash effects
• Theme tweaks in place

Layout swap (refresh required)

If the same colors move to different slot indices, call:

BT.paletteSet(newLayoutPalette);
BT.spritesRefresh();

Why: sprite textures store indices. If your palette layout changes, old indices point to wrong colors until re-indexed.

Practical palette-first patterns

• Cycling water: reserve 8 contiguous slots and run paletteCycle.
• Damage flash: trigger paletteFlash(Color32.white, durationMs).
• Day/night: prebuild day/night palettes and use paletteFade.
• Title-card open: fade up from black with paletteFadeExposure so the highlights arrive first.
• HUD stability: reserve a dedicated slot range and avoid cycling over it.
• Variant economy: organize palette in fixed ranges and use sprite offsets instead of duplicate art.

Performance notes

Palette-first rendering minimizes color-update cost:

• Color changes are palette writes, not full scene texture rewrites.
• Sprite textures are indexed (one byte per pixel) rather than four-channel RGBA storage.
• Primitive and sprite draws reuse compact index-based pipelines.

For the benchmark and local comparison workflow, see Performance Testing.