Choosing a Preset

bitmapped ships with 54 hardware presets spanning consoles, home computers, arcade boards, and fantasy systems. Each preset encodes the exact color limitations, resolution, and rendering quirks of its target hardware. This guide helps you pick the right one.

Overview

A preset controls six things:

• Palette — either a fixed look-up table (Game Boy, NES, CGA) or an RGB bit-depth defining how many bits each channel gets (Genesis, Amiga, VGA).
• Resolution — the native pixel grid of the system (e.g. 256x224 for NES, 320x200 for CGA).
• Pixel aspect ratio (PAR) — most retro systems had non-square pixels. The preset stores the correct ratio so output renders at the right proportions.
• Constraint type — hardware rules like attribute clash, per-tile palettes, hold-and-modify, or scanline limits.
• Display characteristics — CRT scanlines, LCD grid, composite color fringe, and bloom settings.
• Recommended dithering and distance algorithm — the dithering method and color distance metric that best suit the system.

Use getPreset(id) to load a single preset by its string ID. Use listPresets() to get all 54, or listPresetsByCategory(category) to filter by category.

import { getPreset, listPresets, listPresetsByCategory } from 'bitmapped/presets';
 
const nes = getPreset('nes-ntsc');
const allPresets = listPresets();
const nintendoPresets = listPresetsByCategory('nintendo');

Decision tree

Use the categories below to narrow down which preset fits your aesthetic goals.

Clean and colorful

Large palettes, high color counts, and few (or no) per-tile restrictions. Good for faithful reproductions with smooth gradients.

• SNES (snes) — 32,768 colors (15-bit), 256 simultaneous. Per-tile palette constraint allows rich, varied scenes.
• Game Boy Advance (gba) — 32,768 colors (15-bit), 512 simultaneous. Unconstrained bitmap mode produces clean output at 240x160.
• VGA Mode 13h (vga-mode13h) — 262,144 colors (18-bit DAC), 256 simultaneous. The classic 320x200 PC mode with no tile constraints.
• Amiga OCS (amiga-ocs) — 4,096 colors (12-bit), 32 simultaneous. Smooth output at 320x256 with programmable palettes.
• Neo Geo (neo-geo) — 65,536 colors (RGB555 + dark bit), 4,096 simultaneous. Arcade-grade color depth at 320x224.

Chunky and crunchy

Small palettes and low resolutions that produce a distinctly retro, blocky look.

• Game Boy DMG (gameboy-dmg) — 4 shades of green at 160x144. The iconic green-tinted LCD look.
• CGA Mode 4 (cga-mode4-pal0-low) — 4 colors at 320x200. Black plus three fixed colors. Multiple palette variants available.
• Atari 2600 (atari-2600-ntsc) — 128 total colors, but only 4 per scanline at 160x192. Extreme constraints force creative color use.
• ZX Spectrum (zx-spectrum) — 15 colors at 256x192. The limited palette creates a distinctive, saturated look.
• Amstrad CPC Mode 0 (cpc-mode0) — 16 simultaneous colors at a chunky 160x200 resolution with wide pixels.

Clash and character

Presets with attribute-block constraints that force color choices within small tile regions. These produce the characteristic “color clash” artifacts beloved by retro enthusiasts.

• ZX Spectrum (zx-spectrum) — 8x8 attribute cells, 2 colors per cell (ink + paper). The most famous attribute clash system.
• NES (nes-ntsc) — 16x16 attribute blocks, 4 colors each (from a pool of 25 simultaneous). Gives tile-based games their signature look.
• C64 Hires (c64-hires) — 8x8 cells, 2 colors per cell from a 16-color palette. Tight constraints at 320x200.
• C64 Multicolor (c64-multicolor) — 4x8 cells, 4 colors per cell (3 unique + 1 shared background) at 160x200 with double-wide pixels.
• MSX (msx) — Tile-based constraints similar to the NES family, producing structured color layouts.

Unique rendering

Presets with special display modes that produce distinctive visual artifacts.

• Amiga HAM6 (amiga-ham6) — Hold-And-Modify mode displays all 4,096 OCS colors by modifying one RGB channel per pixel. Produces characteristic fringing at color boundaries.
• Apple II Hi-Res (apple-ii-hires) — 6 artifact colors generated by NTSC decoding. Color depends on pixel position, creating horizontal color fringing.
• CGA Composite (cga-composite) — NTSC composite output blends adjacent pixels for extra perceived colors beyond the 16-color RGBI palette.
• PlayStation 1 (ps1) — 32,768 colors (15-bit) with the option to use PS1-style ordered dithering, reproducing the distinctive banding pattern of early 3D games.

Minimal

Monochrome and near-monochrome presets for stark, high-contrast results.

• Original Macintosh (macintosh) — 1-bit black and white at 512x342. Atkinson dithering was literally invented for this machine.
• Game Boy Pocket (gameboy-pocket) — 4 shades of grey at 160x144. Clean greyscale without the green tint of the DMG.
• Virtual Boy (virtual-boy) — 4 shades of red at 384x224. The LED-based monochrome display produces an eerie, unique aesthetic.

Quick comparison table

Palette modes

Presets use one of two palette modes. Understanding the difference matters when you want to customize or extend a preset’s palette.

Fixed LUT

Systems like the NES, Game Boy, C64, and CGA have a fixed look-up table of colors baked into their hardware. The preset.palette array contains every available color.

import { getPreset } from 'bitmapped/presets';
import { process } from 'bitmapped';
 
const nes = getPreset('nes-ntsc');
 
// palette is a PaletteColor[] with 64 entries
console.log(nes.palette.length); // 64
console.log(nes.palette[0]);     // { color: { r: 84, g: 84, b: 84 }, name: '$00' }
 
// Use the palette directly
const result = process(imageData, {
  blockSize: 4,
  palette: nes.palette,
  dithering: 'floyd-steinberg',
  distanceAlgorithm: 'redmean',
});

RGB bit-depth

Systems like the Genesis, Amiga, VGA, and SNES define colors through bits-per-channel. The preset.colorSpace field describes the bit depth. Use enumerateColorSpace() to generate the full palette at runtime.

import { getPreset, enumerateColorSpace } from 'bitmapped/presets';
 
const genesis = getPreset('genesis');
 
// colorSpace describes the bit-depth format
console.log(genesis.colorSpace);
// { type: 'programmable', bitsPerChannel: 3, totalBits: 9,
//   format: 'BGR333', maxSimultaneous: 61 }
 
// Generate all 512 colors in the Genesis color space
const fullPalette = enumerateColorSpace(genesis.colorSpace);
console.log(fullPalette.length); // 512
 
// The preset also ships with a representative sample palette
// that you can use directly for faster processing
console.log(genesis.palette.length); // 512

Browsing presets programmatically

List all presets

import { listPresets } from 'bitmapped/presets';
 
const all = listPresets();
console.log(`${all.length} presets available`); // 54 presets available
 
// Print a summary of each
for (const preset of all) {
  console.log(
    `${preset.id.padEnd(24)} ${preset.name.padEnd(30)} ${preset.resolution.width}x${preset.resolution.height}`
  );
}

Filter by category

import { listPresetsByCategory } from 'bitmapped/presets';
 
const nintendo = listPresetsByCategory('nintendo');
// Returns: gameboy-dmg, gameboy-pocket, gameboy-color,
//          nes-ntsc, nes-pal, snes, gba, virtual-boy
 
const computers = listPresetsByCategory('computer');
// Returns: c64-pepto, c64-colodore, c64-hires, c64-multicolor,
//          zx-spectrum, apple-ii-lores, apple-ii-hires, amiga-ocs,
//          amiga-ham6, amiga-ehb, vic-20, cpc-mode0, cpc-mode1,
//          bbc-micro-mode2, msx, msx2, atari-st, atari-ste,
//          thomson-mo5, macintosh

Find presets with a specific constraint

import { listPresets } from 'bitmapped/presets';
 
// Find all presets that use attribute-block constraints
const clashPresets = listPresets().filter(
  (p) => p.constraintType === 'attribute-block'
);
console.log(clashPresets.map((p) => p.id));
// ['zx-spectrum', 'nes-ntsc', 'nes-pal', 'c64-hires', 'c64-multicolor', ...]

Try it yourself

Upload an image and switch between presets to compare their visual output side by side.

Next steps

• Getting Started — Install bitmapped and process your first image
• Hardware Constraints — Deep dive into attribute clash, HAM, per-tile palettes, and other constraint solvers
• Dithering — Learn when to use Floyd-Steinberg vs Bayer vs Atkinson
• Preset reference pages — Detailed documentation for every preset