Post-processing

COLOR_LEVELS: { genesis, snes, ps1, poster }

How many steps a channel had on the machines this engine is aimed at.

A Mega Drive wrote three bits a channel, so eight steps. A SNES and a PlayStation wrote five, so thirty-two. poster is not a machine: it is the number that makes the effect obvious when you are looking at what it does rather than trying to be a console.

crt(options: { scanlines, mask, maskType, curvature, vignette }) => TBuiltinPostEffect<{ scanlines, mask, maskType, curvature, vignette }>

Makes the frame look as if it were on a CRT television: scanlines, a phosphor mask, the bulge of the glass and darker corners. Each part is a number, and a part at 0 is not there at all.

One scanline per row of the game, not of the screen. The lines follow the game's own pixels, the way a console's picture sat on the tube, so a game at 320 × 224 has 224 of them however large the canvas is drawn. When a game row is only one real pixel tall (pixelRatio: 1, the pixel-art default) a line cannot be drawn inside it, so alternate rows are darkened instead, which is what a console's picture looked like on a screen of the same height. At two or more real pixels per row every row gets its own soft line.

The mask is the coloured grid of the tube itself and works on real pixels, so it only looks like a mask at a pixelRatio of 3 or more; at 1 it reads as coloured columns. That is why it starts switched off.

It belongs last in a chain: a palette or a dither decides which colours exist, and the tube is what those colours are shown on.

usePostProcess(crt({ scanlines: 0.35, curvature: 0.08, vignette: 0.3 }));

dither(options: { levels, strength }) => TBuiltinPostEffect<{ levels, strength }>

Cuts each channel down to a few steps, hiding the bands with an ordered pattern.

This is what the machines of the era did, and doing it here rather than in the artwork means it applies to everything at once: the sprites, the lighting, the gradients a shader made up.

It works in the frame's own colours, with no trip through linear light and back. That is deliberate: the hardware it imitates had no notion of linear light, and a physically tidy version of this bands in the wrong places.

usePostProcess({ ...dither({ levels: COLOR_LEVELS.genesis }) });

lutGrade(options: { amount }) => TBuiltinPostEffect<{ amount }>

Looks every colour up in a grading table and mixes towards what it says.

This is grading, not limiting. A table moves colours about (warmer, colder, more contrast, a green night); a palette or a dither take colours away. They compose, and in one order only: grade first, limit last. The other way round grades colours the machine could not show and then picks a neighbour for them, which throws away the whole point of the grade.

paletteMatch(options: { dither }) => TBuiltinPostEffect<{ dither }>

Replaces every colour with the nearest one a palette actually holds.

This is the effect that makes a frame look like a particular machine rather than merely like an old one: a NES palette is fifty-four specific colours, and no amount of cutting channels into steps will land on them.

A small dither shakes each pixel by less than the gap between neighbours before the search, so a slow gradient breaks into a mix of two palette entries instead of a hard edge.

With no palette, or one of a single colour, it gives back what it was handed. A palette that has not arrived yet must cost you the palette and not the picture.

const nes = useLoadPalette({ src: '/palettes/nes.palette' });
usePostProcess({ ...paletteMatch(), palette: nes });

posterize(options: { levels }) => TBuiltinPostEffect<{ levels }>

The same cut as dither, with nothing to hide the seams.

It exists as the other half of the pair rather than as a lesser version: hard bands are a look, and it is the one that shows what the dithering is actually doing when you put the two side by side.

usePostProcess(options: TPostProcessOptions<U>) => TPostEffect<U>

Adds a full-screen effect: a shader that reads the finished frame and gives back what to show.

A material changes one thing; this changes the picture. That is what a palette reduction or a dither has to be, because "what colours may this frame use" is a question about the screen and not about any sprite on it.

The chain belongs to the game; the entry belongs to the scene. Opening a pause menu over a level does not change how the screen looks, so effects do not stack up as scenes do. But the scene that installed one takes it away when it closes.

Order is the order you ask, and order is the picture: each effect reads what the one before it produced. Grade first and limit last, or you will be grading colours the machine cannot show.

Everything but whether it is switched on is read every frame, so writing a number into the uniforms of what this gives back animates the effect with nothing reinstalled.

const Level = () => {
    const nes = useLoadPalette({ src: '/palettes/nes.palette' });

    usePostProcess({ ...paletteMatch(), palette: nes });

    return createScene();
};

One of the engine's own effects, ready to be spread into usePostProcess.

Both halves are required here, unlike a game's own effect. These are the engine's, and an engine effect that ran on one card and not the other would be a hole in the promise that the two backends draw the same thing, rather than the honest degradation a hand-written WGSL file gets.

TPostChain: TPostChainEntry[]

The whole chain, in order.

An array rather than a bag of named things, for the reason the input map shares: order is the meaning here. Each effect reads what the one before it produced, so grading before limiting and limiting before grading are two different pictures, not two spellings of one.

One effect as a project writes it down.

An entry names its effect one of two ways, and that split is the whole design:

• builtin is a key the engine already knows. There is no file to fetch and no path that can point at nothing, so a project that only reduces its colours needs no shaders/ folder at all.
• shader is a path to a .wgsl, exactly as a material names one.

The arithmetic the engine knows is a key; the look you invented is a file.

An effect the game has installed: a shader that reads the finished frame and gives back what should be shown instead.

This record is what crosses into the backend, by reference and never copied into something new. The compiled shader is cached against this object's identity, so building a fresh one each frame would mean compiling each frame and never once finding the cache.

Everything except enabled is read every frame, so changing a number in uniforms animates the effect with nothing reinstalled: the same rule a material's knobs follow.

It holds the palette or the table as the asset, not as an uploaded picture, because a file lands after the effect was installed. Keeping the picture here would mean keeping the null it was at the moment the effect was made.

What usePostProcess is asked for.

There are three ways to say what the effect is, and they are the same three a material has: write it here, name a file, or spread one of the engine's own.

declare const CRT_WGSL: string;
declare const CRT_GLSL: string;

usePostProcess({ fragment: CRT_WGSL, fragmentGlsl: CRT_GLSL, uniforms: { curve: 0.3 } });
usePostProcess({ effect: useLoadShader({ src: '/shaders/crt.wgsl' }) });
usePostProcess({ ...dither({ levels: COLOR_LEVELS.genesis }) });