# Stylized Water, Cel-Shading Ramps & Outlines in Three.js (r183)

> Three.js r183 NearestFilter DataTexture cel-shading ramps, BackSide normal-extruded outlines, and analytical Gerstner wave water ShaderMaterial with cellular foam.

- **Canonical page:** https://gamecrew.ai/techniques/three/stylized-water-toon-shaders
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Three.js
- **Category:** shaders
- **Tags:** `water`, `toon`, `cel`, `outline`, `gerstner`, `foam`, `shadermaterial`, `meshtoonmaterial`, `stylized`
- **Verification:** Compile-verified pattern

## When to Use & Field Best Practices

Stylized browser slices read immediately more intentional than default `MeshStandardMaterial` boxes when pairing:
1. **Crisp 3-Band `MeshToonMaterial` with `DataTexture` (`NearestFilter`)**: In Three.js r183, `MeshToonMaterial.gradientMap` requires `minFilter = THREE.NearestFilter`, `magFilter = THREE.NearestFilter`, and `generateMipmaps = false` (`RedFormat` or `RGBAFormat`); otherwise linear filtering blurs the cel band back into standard Gouraud/Lambert shading!
2. **`BackSide` Hull Outline Helper**: Add a lightweight child mesh sharing the exact same `BufferGeometry` with a `BackSide` normal-extruding `ShaderMaterial` for hero characters, pickups, and interactive props.
3. **Analytical Gerstner Water `ShaderMaterial`**: Displaces a subdivided `PlaneGeometry` with 3 trochoidal waves and renders dual-scrolling cellular crests + Fresnel sky reflection in one transparent pass.

## Mathematical & Algorithmic Core

- **Discrete Toon Ramp**: $N$-texel `Uint8Array` (`[72, 168, 255]`) sampled with `NearestFilter` quantizes diffuse irradiance into crisp shadow, midtone, and highlight bands while keeping full Three.js directional/point light and shadow-map support!
- **Gerstner Wave**: $\Delta \mathbf{p} = (Q A D_x \cos\theta,\; A \sin\theta,\; Q A D_z \cos\theta)$, analytical normal $\mathbf{N} = \mathrm{normalize}(\mathbf{B} \times \mathbf{T})$.

## Engine Implementation

### Strict TypeScript Toon, Outline & Water Kit (`Assets/Game/stylized-materials.ts`)

```ts
import * as THREE from 'three';
import type { Game } from 'ccgd';

let sharedRamp: THREE.DataTexture | undefined;

export function getToonRamp(): THREE.DataTexture {
  if (sharedRamp) return sharedRamp;
  const data = new Uint8Array([
    82, 82, 98, 255,
    172, 172, 182, 255,
    255, 255, 255, 255,
  ]);
  const tex = new THREE.DataTexture(data, 3, 1, THREE.RGBAFormat);
  tex.minFilter = THREE.NearestFilter;
  tex.magFilter = THREE.NearestFilter;
  tex.generateMipmaps = false;
  tex.needsUpdate = true;
  sharedRamp = tex;
  return tex;
}

export function createCelMaterial(color: number, emissive = 0x000000): THREE.MeshToonMaterial {
  return new THREE.MeshToonMaterial({
    color,
    emissive,
    gradientMap: getToonRamp(),
  });
}

export function attachHullOutline(mesh: THREE.Mesh, thickness = 0.035, outlineColor = 0x16121f): THREE.Mesh {
  const mat = new THREE.ShaderMaterial({
    uniforms: {
      uThickness: { value: thickness },
      uColor: { value: new THREE.Color(outlineColor) },
    },
    vertexShader: /* glsl */ `
      uniform float uThickness;
      void main() {
        vec3 displaced = position + normal * uThickness;
        gl_Position = projectionMatrix * modelViewMatrix * vec4(displaced, 1.0);
      }
    `,
    fragmentShader: /* glsl */ `
      uniform vec3 uColor;
      void main() {
        gl_FragColor = vec4(uColor, 1.0);
        #include <colorspace_fragment>
      }
    `,
    side: THREE.BackSide,
  });
  const hull = new THREE.Mesh(mesh.geometry, mat);
  hull.name = 'HullOutline';
  hull.castShadow = false;
  hull.receiveShadow = false;
  mesh.add(hull);
  return hull;
}

export function createStylizedWater(
  game: Game,
  opts: { width?: number; depth?: number; y?: number; shallow?: number; deep?: number } = {}
) {
  const width = opts.width ?? 120;
  const depth = opts.depth ?? 120;
  const segX = Math.min(96, Math.max(24, Math.round(width / 1.8)));
  const segZ = Math.min(96, Math.max(24, Math.round(depth / 1.8)));
  const geom = new THREE.PlaneGeometry(width, depth, segX, segZ);
  geom.rotateX(-Math.PI / 2);

  const uniforms = {
    uTime: { value: 0 },
    uShallow: { value: new THREE.Color(opts.shallow ?? 0x26b7bd) },
    uDeep: { value: new THREE.Color(opts.deep ?? 0x0b3563) },
    uFoam: { value: new THREE.Color(0xf4fbff) },
    uSunDir: { value: new THREE.Vector3(0.45, 0.72, 0.35).normalize() },
  };

  const mat = new THREE.ShaderMaterial({
    uniforms,
    transparent: true,
    depthWrite: false,
    vertexShader: /* glsl */ `
      uniform float uTime;
      varying vec3 vWorldPos;
      varying vec3 vNormalWS;

      vec3 gerstner(vec4 w, vec3 p, inout vec3 t, inout vec3 b) {
        float steep = w.z;
        float k = 6.2831853 / w.w;
        float c = sqrt(9.81 / k);
        vec2 d = normalize(w.xy);
        float f = k * (dot(d, p.xz) - c * uTime);
        float a = steep / k;
        t += vec3(-d.x * d.x * steep * sin(f), d.x * steep * cos(f), -d.x * d.y * steep * sin(f));
        b += vec3(-d.x * d.y * steep * sin(f), d.y * steep * cos(f), -d.y * d.y * steep * sin(f));
        return vec3(d.x * a * cos(f), a * sin(f), d.y * a * cos(f));
      }

      void main() {
        vec3 wp = (modelMatrix * vec4(position, 1.0)).xyz;
        vec3 t = vec3(1.0, 0.0, 0.0);
        vec3 b = vec3(0.0, 0.0, 1.0);
        vec3 disp = gerstner(vec4(0.86, 0.5, 0.18, 12.0), wp, t, b)
                  + gerstner(vec4(-0.42, 0.91, 0.12, 6.2), wp, t, b);
        wp += disp;
        vWorldPos = wp;
        vNormalWS = normalize(cross(b, t));
        gl_Position = projectionMatrix * viewMatrix * vec4(wp, 1.0);
      }
    `,
    fragmentShader: /* glsl */ `
      precision highp float;
      uniform float uTime;
      uniform vec3 uShallow;
      uniform vec3 uDeep;
      uniform vec3 uFoam;
      uniform vec3 uSunDir;
      varying vec3 vWorldPos;
      varying vec3 vNormalWS;

      float hash21(vec2 p) {
        p = fract(p * vec2(123.34, 456.21));
        p += dot(p, p + 45.32);
        return fract(p.x * p.y);
      }

      float cells(vec2 uv) {
        vec2 i = floor(uv);
        vec2 f = fract(uv);
        float m = 1.0;
        for (int y = -1; y <= 1; y++) {
          for (int x = -1; x <= 1; x++) {
            vec2 nb = vec2(float(x), float(y));
            float h = hash21(i + nb);
            vec2 pt = 0.5 + 0.42 * sin(uTime * 1.3 + 6.2831 * vec2(h, hash21(i + nb + 3.7)));
            m = min(m, length(nb + pt - f));
          }
        }
        return m;
      }

      void main() {
        vec3 N = normalize(vNormalWS);
        vec3 V = normalize(cameraPosition - vWorldPos);
        float fresnel = pow(1.0 - clamp(dot(N, V), 0.0, 1.0), 4.0);
        vec3 base = mix(uShallow, uDeep, clamp(0.35 + fresnel * 0.65, 0.0, 1.0));

        float c1 = cells(vWorldPos.xz * 0.55 + uTime * vec2(0.14, 0.09));
        float c2 = cells(vWorldPos.xz * 0.95 - uTime * vec2(0.11, 0.16));
        float crest = clamp((vWorldPos.y - 0.08) * 2.2, 0.0, 0.45);
        float foam = step(0.56, (c1 + c2) * 0.48 + crest);

        vec3 H = normalize(normalize(uSunDir) + V);
        float spec = pow(clamp(dot(N, H), 0.0, 1.0), 96.0) * 0.7;

        vec3 col = mix(base, uFoam, foam) + vec3(spec);
        gl_FragColor = vec4(col, mix(0.84, 1.0, foam));
        #include <colorspace_fragment>
      }
    `,
  });

  const mesh = new THREE.Mesh(geom, mat);
  mesh.position.y = opts.y ?? 0;
  mesh.name = 'StylizedWater';
  game.scene.add(mesh);

  game.onUpdate(() => {
    uniforms.uTime.value = game.time;
  });

  return { mesh, uniforms };
}
```

## Browser, Mobile & Software-Renderer Budgets

- **Reuse Shared `DataTexture` & Materials**: Share `getToonRamp()` across all `MeshToonMaterial` instances; keep `attachHullOutline` to key silhouettes (player, enemies, interactables) rather than giant terrain meshes.
- **Shadow Budget**: Keep shadow casting to one `DirectionalLight` (`shadow.mapSize.set(1024, 1024)`).

## Verification Checklist

1. Run `compile` to verify zero TypeScript or WebGL shader errors.
2. Open `Captures/*.png` to confirm crisp 3-step shading bands and clean dark silhouettes.

## Official references

- Jerry Tessendorf (SIGGRAPH 2001 — Gerstner Ocean Waves)
- Junya Motomura (GDC 2015 — Cel Shading & Outlines)
- Three.js r183 MeshToonMaterial & Color Management Architecture
