three-psx

PS1/PSX-style rendering for three.js: vertex snapping, affine texture mapping, gouraud lighting, ordered dithering, 15-bit color, and CRT-era post FX, all in one small instance-based toolkit, with an optional lil-gui tuning panel and React Three Fiber bindings.

What you get

• Vertex snapping. Positions quantized to the virtual screen grid (the PS1's GTE had no sub-pixel precision), with adjustable intensity
• Affine texture mapping. UVs interpolated without perspective correction, so textures warp and swim exactly like the hardware
• Gouraud lighting. One directional light + ambient + one per-vertex point light with quadratic falloff (for those warm lamp pools)
• Per-vertex fog, UV scrolling, texture repeat, alpha cutouts, time-quantized vertex wobble with "hold frames"
• Low-res pipeline. Renders to a 320×240 (or any PS1 video mode) target, upscaled with nearest-neighbor: fit (4:3 letterbox), integer (pixel-perfect), or stretch
• Post pass. Bayer 2×2/4×4/8×8 or interleaved-gradient-noise dithering, color-depth quantization (15-bit default), plus optional chunky low-res bloom, contrast, and saturation
• GLTF conventions. Name materials *_unlit, *_nofog, *_cutout in your DCC tool and applyToGLTF() wires them automatically

Install

npm install three-psx three
# optional extras
npm install lil-gui                       # for three-psx/gui
npm install react @react-three/fiber     # for three-psx/react

Quick start (vanilla)

import * as THREE from 'three';
import { PSX } from 'three-psx';

const psx = new PSX({ width: 320, height: 240 });
psx.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(psx.domElement);

psx.setFog(0x101018, 4, 30);
psx.setLight([-0.5, -1, -0.3], 0xffffff, 0x404050);

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, psx.viewAspect, 0.1, 100);

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(2, 2, 2),
  psx.material({ map: myTexture })   // snapping/affine/gouraud material
);
scene.add(cube);

function loop(ms) {
  requestAnimationFrame(loop);
  psx.render(scene, camera, ms / 1000);
}
requestAnimationFrame(loop);

Loading a Blender-authored model:

new GLTFLoader().load('scene.glb', (gltf) => {
  psx.applyToGLTF(gltf.scene); // honors *_unlit / *_nofog / *_cutout names
  scene.add(gltf.scene);
});

A warm lamp pool (per-vertex, so subdivide surfaces that should catch it):

psx.setPointLight([0, 2.2, 0], 0xffca80, 9);

GUI panel

import { createPSXGui } from 'three-psx/gui';
createPSXGui(psx); // press "h" to toggle

Resolution presets, color depth, dither algorithm, vertex FX, post FX, fog.

React Three Fiber

import { Canvas } from '@react-three/fiber';
import { PSXPipeline, usePSXMaterial } from 'three-psx/react';

function Cube() {
  const material = usePSXMaterial({ color: 0xd08040 });
  return (
    <mesh material={material}>
      <boxGeometry args={[2, 2, 2]} />
    </mesh>
  );
}

<Canvas gl={{ antialias: false }}>
  <PSXPipeline width={320} height={240} bloom={0.25}>
    <Cube />
  </PSXPipeline>
</Canvas>;

<PSXPipeline> takes over the R3F render loop and pushes every frame through the low-res pipeline. usePSX() gives you the context for setFog, setLight, setPointLight, etc.

Notes on authenticity

• Textures get NoColorSpace on purpose: the PS1 lit in gamma space, and the pipeline does no sRGB re-encode, so decoding would double-darken everything.
• Dither + quantization happen after bloom/grade, so even the "modern" post FX stays inside the period color pipeline.
• Floyd-Steinberg/Atkinson are error-diffusion algorithms and can't run per-fragment; the Noise (IGN) mode is the real-time stand-in.
• Affine warp scales with triangle size, so subdivide large floors/walls like the era's games did. That's a feature, not a bug.
• Vertex snapping needs vertices to snap. On coarse geometry with metres between vertices, long silhouettes crawl instead of shimmering, so dial psx.shared.jitter.value down (0 disables it) or subdivide.

Examples

npm install
npm run examples

• index.html is a minimal spinning cube with no assets
• busstop.html is a lone bus stop at night
• pool.html is an outdoor pool at golden hour
• rooftop.html is a neon rain rooftop at night
• react.html is an R3F smoke test

Roadmap

• 0.2: the Blender authoring companion (Python helpers that generate low-poly geometry, assign textures, and export GLBs with the name flags), more dither options, multiple point lights
• Suggestions and PRs welcome

License

MIT © codedgar