Skip to content

A free, open-source framework for cinematic, interactive 3D websites with AI-generated assets (Nano Banana 2 + Meshy 7.1 on fal). 20 example sites.

17.9 KB
Raw Blame
// Still Water — the pond surface.
//  RippleSim: height-field wave equation in ping-pong float targets, plus a derived surface texture (h, dh/dx, dh/dz, laplacian).
//  waterMaterial: the surface shader — screen-space refraction of the under-water pass with depth absorption,
//  fresnel reflection of sky and maple canopy, sun glints, moon and lantern reflections.
//  patchUnder: caustics + depth-in-alpha for every material that is drawn in the under-water pass.
import * as THREE from 'three';
import { bakeTexture } from '../../src/core/textures.js';
import { pondSDF } from './shape.js';

const quadGeo = new THREE.PlaneGeometry(2, 2);
const orthoCam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
const FS_VERT = 'varying vec2 vUv; void main(){ vUv = uv; gl_Position = vec4(position.xy, 0., 1.); }';

function pass(frag, uniforms) {
  const mat = new THREE.ShaderMaterial({ vertexShader: FS_VERT, fragmentShader: frag, uniforms, depthTest: false, depthWrite: false });
  const mesh = new THREE.Mesh(quadGeo, mat);
  mesh.frustumCulled = false;
  const scene = new THREE.Scene();
  scene.add(mesh);
  return { mat, scene, uniforms };
}

const MAX_DROPS = 24;

export class RippleSim {
  constructor(renderer, { res = 1024, x0 = -10, z0 = -8.5, size = 20 } = {}) {
    this.renderer = renderer;
    this.res = res;
    this.rect = new THREE.Vector4(x0, z0, size, size / res); // xmin, zmin, size, texel (m)
    const gl = renderer.getContext();
    const floatOK = !!gl.getExtension('EXT_color_buffer_float');
    const type = floatOK ? THREE.FloatType : THREE.HalfFloatType;
    const opts = { type, minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter, depthBuffer: false, stencilBuffer: false, wrapS: THREE.ClampToEdgeWrapping, wrapT: THREE.ClampToEdgeWrapping };
    this.a = new THREE.WebGLRenderTarget(res, res, opts);
    this.b = new THREE.WebGLRenderTarget(res, res, opts);
    this.surf = new THREE.WebGLRenderTarget(res, res, { type: THREE.HalfFloatType, minFilter: THREE.LinearFilter, magFilter: THREE.LinearFilter, depthBuffer: false, stencilBuffer: false });
    this.texture = this.surf.texture;

    // Land mask: waves reflect off the shore instead of running up the moss.
    const MR = 256, md = new Uint8Array(MR * MR * 4);
    for (let j = 0; j < MR; j++) for (let i = 0; i < MR; i++) {
      const x = x0 + (i + 0.5) / MR * size, z = z0 + (j + 0.5) / MR * size;
      const d = pondSDF(x, z);
      const m = Math.min(1, Math.max(0, (-d + 0.02) / 0.18));
      md.set([m * 255, m * 255, m * 255, 255], (j * MR + i) * 4);
    }
    this.mask = new THREE.DataTexture(md, MR, MR, THREE.RGBAFormat);
    this.mask.magFilter = this.mask.minFilter = THREE.LinearFilter;
    this.mask.needsUpdate = true;

    this.dropA = Array.from({ length: MAX_DROPS }, () => new THREE.Vector4());
    this.dropB = Array.from({ length: MAX_DROPS }, () => new THREE.Vector4());
    this.queue = [];
    this.stepPass = pass(/* glsl */`
      precision highp float;
      uniform sampler2D uPrev, uMask; uniform vec2 uTexel; uniform float uDamp;
      uniform vec4 uDropA[${MAX_DROPS}]; uniform vec4 uDropB[${MAX_DROPS}]; uniform int uN;
      varying vec2 vUv;
      void main(){
        vec4 info = texture2D(uPrev, vUv);
        float avg = (texture2D(uPrev, vUv - vec2(uTexel.x, 0.)).r + texture2D(uPrev, vUv + vec2(uTexel.x, 0.)).r +
                     texture2D(uPrev, vUv - vec2(0., uTexel.y)).r + texture2D(uPrev, vUv + vec2(0., uTexel.y)).r) * 0.25;
        info.g += (avg - info.r) * 2.0;
        info.g *= uDamp;
        info.r += info.g;
        info.r *= 0.99965;
        for (int i = 0; i < ${MAX_DROPS}; i++) {
          if (i >= uN) break;
          vec4 a = uDropA[i]; vec4 b = uDropB[i];
          vec2 pa = vUv - a.xy, ba = a.zw - a.xy;
          float t = clamp(dot(pa, ba) / max(dot(ba, ba), 1e-12), 0., 1.);
          float d = length(pa - ba * t) / b.x;
          if (d < 1.) info.r += (0.5 + 0.5 * cos(3.14159265 * d)) * b.y;
        }
        float m = texture2D(uMask, vUv).r;
        info.rg *= m;
        gl_FragColor = info;
      }`, {
      uPrev: { value: null }, uMask: { value: this.mask }, uTexel: { value: new THREE.Vector2(1 / res, 1 / res) }, uDamp: { value: 0.9955 },
      uDropA: { value: this.dropA }, uDropB: { value: this.dropB }, uN: { value: 0 },
    });
    this.surfPass = pass(/* glsl */`
      precision highp float;
      uniform sampler2D uSim; uniform vec2 uTexel; uniform float uTw;
      varying vec2 vUv;
      void main(){
        float h = texture2D(uSim, vUv).r;
        float l = texture2D(uSim, vUv - vec2(uTexel.x, 0.)).r, r = texture2D(uSim, vUv + vec2(uTexel.x, 0.)).r;
        float d = texture2D(uSim, vUv - vec2(0., uTexel.y)).r, u = texture2D(uSim, vUv + vec2(0., uTexel.y)).r;
        gl_FragColor = vec4(h, (r - l) / (2. * uTw), (u - d) / (2. * uTw), (l + r + u + d - 4. * h) / (uTw * uTw));
      }`, { uSim: { value: null }, uTexel: { value: new THREE.Vector2(1 / res, 1 / res) }, uTw: { value: size / res } });
    this.acc = 0;
    this.clear();
  }

  clear() {
    const r = this.renderer, prev = r.getRenderTarget();
    for (const t of [this.a, this.b, this.surf]) { r.setRenderTarget(t); r.setClearColor(0, 0); r.clear(); }
    r.setRenderTarget(prev);
  }

  /** A soft disc (or capsule from a to b) of displaced water, in world metres. strength in metres of height. */
  drop(x, z, radius = 0.06, strength = 0.01, x2 = x, z2 = z) {
    if (this.queue.length > 96) return;
    this.queue.push([x, z, x2, z2, radius, strength]);
  }

  step(dt) {
    const r = this.renderer;
    const prevTarget = r.getRenderTarget();
    const prevAuto = r.autoClear;
    r.autoClear = false;
    this.acc = Math.min(this.acc + dt * 60, 3);
    const R = this.rect;
    const toU = (x, z) => [(x - R.x) / R.z, (z - R.y) / R.z];
    let steps = 0;
    while (this.acc >= 1 || (steps === 0 && this.queue.length)) {
      this.acc = Math.max(0, this.acc - 1);
      const n = Math.min(MAX_DROPS, this.queue.length);
      for (let i = 0; i < n; i++) {
        const [x, z, x2, z2, rad, s] = this.queue.shift();
        const [u1, v1] = toU(x, z), [u2, v2] = toU(x2, z2);
        this.dropA[i].set(u1, v1, u2, v2);
        this.dropB[i].set(rad / R.z, s, 0, 0);
      }
      const u = this.stepPass.uniforms;
      u.uN.value = n;
      u.uPrev.value = this.a.texture;
      r.setRenderTarget(this.b);
      r.render(this.stepPass.scene, orthoCam);
      [this.a, this.b] = [this.b, this.a];
      steps++;
      if (steps > 3) break;
    }
    this.surfPass.uniforms.uSim.value = this.a.texture;
    r.setRenderTarget(this.surf);
    r.render(this.surfPass.scene, orthoCam);
    r.setRenderTarget(prevTarget);
    r.autoClear = prevAuto;
  }
}

// ─── Procedural textures ───────────────────────────────────────────────────────
export function causticTexture(renderer) {
  const t = bakeTexture(renderer, 1024, /* glsl */`
    vec2 h2(vec2 p){ p = mod(p, 7.0); return fract(sin(vec2(dot(p, vec2(127.1, 311.7)), dot(p, vec2(269.5, 183.3)))) * 43758.5453); }
    void main(){
      vec2 p = vUv * 7.0;
      p += vec2(fbm(vUv * 3., 3., 3, .5), fbm(vUv * 3. + 5.3, 3., 3, .5)) * 1.1;
      vec2 ip = floor(p), fp = fract(p);
      float f1 = 9., f2 = 9.;
      for (int j = -1; j <= 1; j++) for (int i = -1; i <= 1; i++) {
        vec2 g = vec2(float(i), float(j));
        vec2 r = g + h2(ip + g) * 0.9 + 0.05 - fp;
        float d = dot(r, r);
        if (d < f1) { f2 = f1; f1 = d; } else if (d < f2) f2 = d;
      }
      float e = sqrt(f2) - sqrt(f1);
      float c = pow(1.0 - smoothstep(0.0, 0.2, e), 2.2) + pow(1.0 - smoothstep(0.0, 0.5, e), 3.0) * 0.25;
      gl_FragColor = vec4(vec3(c), 1.);
    }`);
  return t;
}

/** Small wind ripples: RG = tangent-space slope, B = broad breeze patches. Tileable. */
export function microTexture(renderer) {
  return bakeTexture(renderer, 512, /* glsl */`
    float H(vec2 p){ return fbm(p * 5., 5., 3, .45); }
    void main(){
      float e = 1. / 512.;
      float hx = H(vUv + vec2(e, 0.)) - H(vUv - vec2(e, 0.));
      float hy = H(vUv + vec2(0., e)) - H(vUv - vec2(0., e));
      vec2 s = vec2(hx, hy) * 30.;
      float b = fbm(vUv * 2., 2., 4, .5) * .5 + .5;
      gl_FragColor = vec4(s * .5 + .5, b, 1.);
    }`);
}

// ─── Caustics + depth output for under-water materials ─────────────────────────
export const underShared = {
  uSurf: { value: null }, uSimRect: { value: new THREE.Vector4() }, uCaust: { value: null }, uTime: { value: 0 },
  uSunRefr: { value: new THREE.Vector2(0.2, 0.3) }, uCaustK: { value: 1 }, uDepthOut: { value: 0 }, uFocus: { value: 0.006 },
  uLightAbs: { value: new THREE.Vector3(0.55, 0.16, 0.3) },
  uCookie: { value: null }, uCanopyMat: { value: new THREE.Matrix3() }, uCanopyH: { value: 6.5 }, uKeyDir: { value: new THREE.Vector3(0, 1, 0) },
  uDappleK: { value: 1 }, uLeafLight: { value: 0.16 },
};
export const CAUSTIC_GLSL = /* glsl */`
  uniform sampler2D uSurf, uCaust, uCookie; uniform vec4 uSimRect; uniform float uTime, uCaustK, uDepthOut, uFocus, uCanopyH, uDappleK, uLeafLight;
  uniform vec2 uSunRefr; uniform vec3 uLightAbs, uKeyDir; uniform mat3 uCanopyMat;
  varying vec3 vWP;
  float dappleAt(vec3 wp){
    float t = (uCanopyH - wp.y) / max(uKeyDir.y, 0.08);
    vec2 cuv = (uCanopyMat * vec3(wp.xz + uKeyDir.xz * t, 1.)).xy;
    vec2 e = smoothstep(vec2(0.), vec2(0.08), cuv) * smoothstep(vec2(1.), vec2(0.92), cuv);
    float c = texture2D(uCookie, cuv, 0.6).r;
    return mix(1., mix(uLeafLight, 1., smoothstep(0.25, 0.85, c)), e.x * e.y * uDappleK);
  }
  vec3 causticsAt(vec3 wp){
    float depth = max(-wp.y, 0.);
    vec2 sp = wp.xz + uSunRefr * depth;
    vec4 s = texture2D(uSurf, (sp - uSimRect.xy) / uSimRect.z);
    vec2 p = sp * 0.42 + s.yz * depth * 0.08;
    float c1 = texture2D(uCaust, p + vec2(uTime * 0.013, uTime * 0.008)).r;
    float c2 = texture2D(uCaust, p * 1.17 + vec2(-uTime * 0.011, uTime * 0.012) + 0.37).r;
    float c = pow((c1 + c2) * 0.5, 1.2) * 1.45;
    float focus = clamp(-s.w * uFocus * min(depth, 1.2), -0.85, 2.5);
    float k = smoothstep(0.0, 0.18, depth) * uCaustK;
    return max(mix(1.0, (0.3 + c * 2.8) * (1.0 + focus), k), 0.0) * exp(-uLightAbs * depth);
  }
`;

/** Patch a standard material so it gets caustics under water and writes view distance to alpha in the under pass. */
export function patchUnder(mat, { extraVertexHead = '', extraFragHead = '', mapFragment = null, roughFragment = null, custom = null, key = '' } = {}) {
  const prev = mat.onBeforeCompile;
  mat.onBeforeCompile = (shader, r) => {
    Object.assign(shader.uniforms, underShared);
    custom?.uniforms && Object.assign(shader.uniforms, custom.uniforms);
    shader.vertexShader = shader.vertexShader
      .replace('#include <common>', '#include <common>\nvarying vec3 vWP;\n' + extraVertexHead)
      .replace('#include <worldpos_vertex>', `#include <worldpos_vertex>
        vec4 kwp = vec4(transformed, 1.0);
        #ifdef USE_INSTANCING
          kwp = instanceMatrix * kwp;
        #endif
        vWP = (modelMatrix * kwp).xyz;`);
    shader.fragmentShader = shader.fragmentShader
      .replace('#include <common>', '#include <common>\n' + CAUSTIC_GLSL + extraFragHead)
      .replace('#include <emissivemap_fragment>', '#include <emissivemap_fragment>\nfloat kDap = dappleAt(vWP); vec3 kCaust = mix(vec3(1.), causticsAt(vWP), smoothstep(0.25, 0.85, kDap)) * kDap;')
      .replace('#include <lights_fragment_begin>', THREE.ShaderChunk.lights_fragment_begin
        .replace('getDirectionalLightInfo( directionalLight, directLight );', 'getDirectionalLightInfo( directionalLight, directLight );\ndirectLight.color *= kCaust;'))
      .replace('#include <dithering_fragment>', '#include <dithering_fragment>\nif (uDepthOut > 0.5) gl_FragColor.a = length(vViewPosition);');
    if (mapFragment) shader.fragmentShader = shader.fragmentShader.replace('#include <map_fragment>', mapFragment);
    if (roughFragment) shader.fragmentShader = shader.fragmentShader.replace('#include <roughnessmap_fragment>', roughFragment);
    prev?.(shader, r);
    custom?.patch?.(shader);
  };
  const prevKey = mat.customProgramCacheKey?.bind(mat);
  mat.customProgramCacheKey = () => 'under' + key + (prevKey ? prevKey() : '');
  return mat;
}

// ─── The surface ───────────────────────────────────────────────────────────────
export function waterMaterial(u) {
  return new THREE.ShaderMaterial({
    uniforms: u,
    vertexShader: /* glsl */`
      varying vec3 vW;
      void main(){ vec4 w = modelMatrix * vec4(position, 1.); vW = w.xyz; gl_Position = projectionMatrix * viewMatrix * w; }`,
    fragmentShader: /* glsl */`
      precision highp float;
      uniform sampler2D uUnder, uSurf, uMicro, uCanopy, uCookie, uRefl; uniform mat4 uReflMat;
      uniform vec2 uUnderSize; uniform vec4 uSimRect;
      uniform mat3 uCanopyMat; uniform float uCanopyH;
      uniform vec3 uSunDir, uSunCol, uZenith, uHorizon, uAbsorb, uScatter, uMoonDir, uMoonCol, uLampPos, uLampCol, uLeafTint;
      uniform float uTime, uSlope, uRefr, uWind, uAutumn, uBare, uGlint, uCanopyK, uReflK, uDebug, uMicroK;
      varying vec3 vW;

      vec3 skyAt(vec3 R, vec3 R0, vec3 P, float blur){
        float up = max(R.y, 0.03);
        vec3 sky = mix(uHorizon, uZenith, pow(up, 0.55));
        float t = (uCanopyH - P.y) / up;
        vec2 q = P.xz + R.xz * t;
        vec2 cuv = (uCanopyMat * vec3(q, 1.)).xy;
        vec2 e = smoothstep(vec2(0.), vec2(0.08), cuv) * smoothstep(vec2(1.), vec2(0.92), cuv);
        float inside = e.x * e.y * uCanopyK;
        vec3 c = texture2D(uCanopy, cuv, blur).rgb;
        float lum = dot(c, vec3(0.3, 0.55, 0.15));
        float leaf = 1. - smoothstep(0.35, 0.9, lum);
        vec3 autumn = uLeafTint * (0.25 + lum * 1.6);
        vec3 tr = mix(c, mix(c, autumn, leaf), uAutumn);
        tr = mix(tr, vec3(1.), uBare * leaf * 0.75);
        sky *= mix(vec3(1.), tr, inside);
        float md = dot(R0, uMoonDir);
        sky += uMoonCol * (smoothstep(0.999969, 0.999982, md) * 70. + pow(max(md, 0.), 9000.) * 0.8 + pow(max(md, 0.), 60.) * 0.015);
        // a scatter of stars where the canopy opens
        vec2 sg = R0.xz / max(R0.y, 0.2) * 70.;
        float sh = fract(sin(dot(floor(sg), vec2(12.9898, 78.233))) * 43758.5453);
        vec2 sf = fract(sg) - 0.5;
        float star = smoothstep(0.9965, 1.0, sh) * smoothstep(0.32, 0.0, length(sf));
        sky += uMoonCol * star * 3.5 * (1. - inside * leaf);
        vec3 lp = uLampPos - P;
        float lg = max(dot(R0, normalize(lp)), 0.);
        sky += uLampCol * (pow(lg, 2600.) * 30. + pow(lg, 160.) * 0.5 + pow(lg, 12.) * 0.03);
        return sky;
      }

      void main(){
        vec2 suv = (vW.xz - uSimRect.xy) / uSimRect.z;
        vec4 s = texture2D(uSurf, suv);
        vec3 n = normalize(vec3(-s.y * uSlope, 1., -s.z * uSlope));
        vec3 m1 = texture2D(uMicro, vW.xz * 0.23 + uTime * vec2(0.011, 0.007)).xyz;
        vec3 m2 = texture2D(uMicro, vW.xz * 0.61 + uTime * vec2(-0.009, 0.013)).xyz;
        float breeze = smoothstep(0.52, 0.78, texture2D(uMicro, vW.xz * 0.018 + uTime * vec2(0.0045, 0.003)).b);
        vec2 mslope = (m1.xy * 2. - 1.) + (m2.xy * 2. - 1.) * 0.6;
        mslope *= uMicroK;
        n = normalize(n + vec3(mslope.x, 0., mslope.y) * (0.022 + breeze * uWind));

        vec3 V = normalize(cameraPosition - vW);
        float NdV = clamp(dot(n, V), 0., 1.);
        float F = (0.02 + 0.98 * pow(1. - NdV, 5.)) * uReflK;

        vec2 sc = gl_FragCoord.xy / uUnderSize;
        float dS = length(cameraPosition - vW);
        vec4 u0 = texture2D(uUnder, sc);
        float L0 = max(u0.a - dS, 0.);
        vec3 nv = mat3(viewMatrix) * vec3(n.x, 0., n.z);
        vec2 off = nv.xy * uRefr * min(L0 + 0.1, 1.4);
        vec2 ruv = sc - off;
        ruv = clamp(ruv, vec2(0.002), vec2(0.998));
        vec4 u1 = texture2D(uUnder, ruv);
        float L = u1.a - dS;
        if (L < 0.) { u1 = u0; L = L0; }
        vec3 Tr = exp(-uAbsorb * L);
        vec3 scat = uScatter * (1. - exp(-L * 1.3));
        vec3 refr = u1.rgb * Tr + scat;

        // ripples read in a photograph mostly through what they reflect: exaggerate the reflection normal
        vec3 nR = normalize(vec3(-s.y * uSlope * 2.6 + mslope.x * (0.03 + breeze * uWind), 1., -s.z * uSlope * 2.6 + mslope.y * (0.03 + breeze * uWind)));
        vec3 R = reflect(-V, nR);
        float blur = clamp(length(s.yz) * 1.5 + breeze * 1.5, 0., 5.);
        vec3 R0 = reflect(-V, n);
        vec3 refl = skyAt(R, R0, vW, blur);
        // the garden itself — banks, lantern, lotus, the maple limb — mirrored in the water
        vec4 rp = uReflMat * vec4(vW, 1.0);
        vec2 rduv = rp.xy / rp.w + (mat3(viewMatrix) * vec3(nR.x - n.x * 0.0, 0., nR.z)).xy * 0.09;
        vec4 ro = texture2D(uRefl, rduv, blur * 0.5);
        refl = mix(refl, ro.rgb, clamp(ro.a, 0., 1.));
        float slope = length(s.yz);
        F = max(F, 0.035 * uReflK) + smoothstep(0.03, 0.4, slope) * 0.05 * uReflK;
        vec3 col = mix(refr, refl, F);
        // lit and shaded flanks of each ripple, as the eye reads them on a still pond
        vec2 ld = normalize(uSunDir.xz + vec2(0.0001));
        col += uHorizon * 0.018 * clamp(dot(-s.yz, ld) * 1.6 + slope * 0.6, -0.6, 1.2);

        float tt = (uCanopyH - vW.y) / max(uSunDir.y, 0.08);
        vec2 cuv = (uCanopyMat * vec3(vW.xz + uSunDir.xz * tt, 1.)).xy;
        vec2 ce = smoothstep(vec2(0.), vec2(0.08), cuv) * smoothstep(vec2(1.), vec2(0.92), cuv);
        float lit = mix(1., smoothstep(0.3, 0.9, texture2D(uCookie, cuv).r), ce.x * ce.y * uCanopyK);
        float sd = max(dot(R, uSunDir), 0.);
        col += uSunCol * lit * uGlint * pow(sd, 2400.) * 140.;
        // shallow shoreline: a soft meniscus sheen
        col += refl * smoothstep(0.08, 0.0, L) * 0.08;
        if (uDebug > 0.5 && uDebug < 1.5) col = u0.rgb;
        if (uDebug > 1.5 && uDebug < 2.5) col = refl;
        if (uDebug > 2.5 && uDebug < 3.5) col = vec3(fract(u0.a), fract(dS), L * 0.3);
        gl_FragColor = vec4(col, 1.);
      }`,
  });
}