Making of PolyFish

A deep dive into building a real-time underwater ecosystem with Three.js - from verlet physics and procedural animation to documentary-style cinematography.

PolyFish is a real-time aquatic ecosystem simulation built entirely in the browser with Three.js and WebAssembly physics. Fish hunt plankton, dolphins hunt fish, manatees graze kelp - and eventually, everything dies. This is the story of how it was made.

What started as a simple fish tank demo evolved into a full documentary-style nature simulation, complete with procedural animation, spatial audio, and a cinematic camera system that shoots the scene like a wildlife film. Along the way we solved problems in soft-body physics, GPU instancing, creature AI, and ecosystem balancing.

Each chapter of this site walks through a major system in the game, with interactive WebGL demos you can play with directly in the browser.

Chapters

Click a chapter to explore the tech behind it.

Origins & Remaster

From a beer fermentation VR experiment in 2014 to a Three.js underwater documentary - the story of how PolyFish came to be.

Unity Porting History

Ecosystem & Food Chain

Spatial hashing, reproduction mechanics, energy metabolism, and population dynamics - how we balanced a self-sustaining food web.

Spatial Hash Population Balance

Three species with distinct behaviors - staggered AI ticks, thrust engines, dash mechanics, oxygen systems, and vertex-shader swim animation.

AI Vertex Shader Locomotion

Kelp & Verlet Physics

How soft-body kelp forests sway with ocean currents using position-based dynamics, impulse propagation, and procedural bone rigging.

Verlet Soft-body Procedural Rig

Rendering & Shaders

Caustic light patterns, GPU water surface animation, instanced creature rendering, and marine snow - all via shader injection into standard materials.

GLSL Instancing Caustics

Cinematic Camera

A documentary-style camera system with a Director, Cinematographer, and Ecosystem Scout - 10 shot types that tell a visual story.

Camera State Machine DOF

Audio & Narration

Web Audio API spatial sound, timed narration triggers, music ducking, and the challenges of autoplay on mobile browsers.

Web Audio Spatial Narration

Object pooling, spatial hashing, GPU instancing, LOD systems, and budget-driven throttling - how we keep 60fps with hundreds of active entities.

Pooling Instancing 60fps