@mesmotronic/three-retropass
TypeScript icon, indicating that this package has built-in type declarations

1.1.8 • Public • Published

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.

Screenshot 2025-05-16 at 22 51 38 Original

Screenshot 2025-05-16 at 23 16 33 320x200 2 colours (monochrome)

Screenshot 2025-05-16 at 22 51 52 320x200 4 colours (CGA mode 1)

Screenshot 2025-05-16 at 22 52 02 320x200 16 colours (MS VGA)

Screenshot 2025-05-16 at 22 52 14 320x200 256 colours (web safe) 320x200 256 colours (web safe)

Package Sidebar

Install

npm i @mesmotronic/three-retropass

Weekly Downloads

13

Version

1.1.8

License

BSD-2-Clause

Unpacked Size

23.5 kB

Total Files

13

Last publish

Collaborators

  • neilrackett