@mesmotronic/three-retropass

RetroPass for Three.js

Inspired by STDOOM, RetroPass is a WebGL post-processing effect for Three.js that enables you to give your project a retro look and feel, with pixelation and colour quantisation for a nostalgic, low-res aesthetic — ideal for games or apps evoking classic video game vibes.

You can choose from the default 2, 4, 16, 64, 256, 512 and 4096 colour palettes, or create a custom palette of any any size from 2 to 4096 colours.

See it in action.

Installation

npm install @mesmotronic/three-retropass

Requires three as a peer dependency.

Colour palettes

By default, palettes of up to 64 colours can be arbitrary, but larger palettes are expected to be a uniform quantized RGB cube (e.g. 8×8×8 for 512 colours) to ensure best performance.

Custom palettes above 64 colours are supported by setting quantizeEnabled to false, but this may significantly reduce performance.

Usage

Here’s an example of how to use RetroPass in your Three.js project, showing a basic scene with a retro effect at 320x200 resolution with 16 colours and dithering enabled.

import * as THREE from "three";
import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
import { RenderPass } from "three/addons/postprocessing/RenderPass.js";
import { RetroPass } from "@mesmotronic/three-retropass";

// Scene setup
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);

// Composer setup
const composer = new EffectComposer(renderer);
const renderPass = new RenderPass(scene, camera);
composer.addPass(renderPass);

// Add RetroPass
const retroPass = new RetroPass({ resolution: new THREE.Vector2(320, 200), colorCount: 16, dithering: true });
composer.addPass(retroPass);

// Render loop
function animate() {
  requestAnimationFrame(animate);
  composer.render();
}
animate();

API Reference

Name	Description	Constructor	Property
resolution	THREE.Vector2 object specifying the resolution of the retro effect (default: 320x200).	✓	✓
colorCount	Number indicating the number of colours in the palette (default: 16).	✓	✓
colorPalette	Array of THREE.Color objects defining the colour palette (default: predefined palette).	✓	✓
dithering	Boolean to enable or disable dithering (default: true).	✓	✓
pixelRatio	Number for the pixel ratio, used to override resolution if set (default: 0).	✓	✓

Screenshots

Example screenshots using default palettes with Littlest Tokyo by Glen Fox, CC Attribution.

Original

320x200 2 colours (monochrome)

320x200 4 colours (CGA mode 1)

320x200 16 colours (MS VGA)

320x200 256 colours (web safe) 320x200 256 colours (web safe)