Skip to content

Robpayot/tslda / .agents/skills

TSL conversion

Verified

Use it when you need to convert a Threejs Material using GLSL shaders to TSL node materials

FileKindSize
SKILL.mdskill md29.5 KB
---
name: TSL conversion
description: Use it when you need to convert a Threejs Material using GLSL shaders to TSL node materials
---

# My Skill
You're the best TSL developer in the world

# TSL (Three.js Shading Language) Rules for AI

Always check the doc! @.cursor/skills/tsl/references/TSL-DOC.md and @.cursor/skills/tsl/references/TSL-WIKI.md


**STOP. Read this section first. These will cause errors or warnings.**

| ❌ DO NOT USE | ✅ USE INSTEAD |
|---------------|----------------|
| `timerGlobal` | `time` |
| `timerLocal` | `time` |
| `timerDelta` | `deltaTime` |
| `import from 'three/nodes'` | `import from 'three/tsl'` |
| `import * as THREE from 'three'` | `import * as THREE from 'three/webgpu'` |
| `oscSine(timerGlobal)` | `oscSine(time)` or `oscSine()` |
| `oscSquare(timerGlobal)` | `oscSquare(time)` or `oscSquare()` |
| `oscTriangle(timerGlobal)` | `oscTriangle(time)` or `oscTriangle()` |
| `oscSawtooth(timerGlobal)` | `oscSawtooth(time)` or `oscSawtooth()` |

---

## CRITICAL: What TSL Is

TSL is JavaScript that builds shader node graphs. Code executes at TWO times:
- **Build time**: JavaScript runs, constructs node graph
- **Run time**: Compiled WGSL/GLSL executes on GPU

    // BUILD TIME: JavaScript conditional (runs once when shader compiles)
    if (material.transparent) { return transparent_shader; }

    // RUN TIME: TSL conditional (runs every pixel/vertex on GPU)
    If(value.greaterThan(0.5), () => { result.assign(1.0); });

---

## TSL conversion

- Please comment anything related to shadow casting for now

- Please run `npm run dev` and check for JS errors after conversion.

- To avoid this error: "THREE.TSL: NodeError: THREE.TSL: `texture( value )` function expects a valid instance of THREE.Texture()." Please pass textures in uniform().

## Imports

### NPM (Preferred)

    import * as THREE from 'three/webgpu';
    import { Fn, vec3, float, uniform, /* ... */ } from 'three/tsl';


### WRONG Import Patterns

    // WRONG: Old path
    import { vec3 } from 'three/nodes';
    // CORRECT:
    import { vec3 } from 'three/tsl';

    // WRONG: WebGL renderer with TSL
    import * as THREE from 'three';
    // CORRECT: WebGPU renderer
    import * as THREE from 'three/webgpu';

---

## Renderer Initialization

**CRITICAL: Always await renderer.init() before first render or compute.**

    const renderer = new THREE.WebGPURenderer({ antialias: true });
    renderer.setSize(window.innerWidth, window.innerHeight);
    document.body.appendChild(renderer.domElement);

    // REQUIRED before any rendering
    await renderer.init();

    // Now safe to render/compute
    renderer.render(scene, camera);

---

## Type Constructors

| Constructor | Input | Output |
|-------------|-------|--------|
| `float(x)` | number, node | float |
| `int(x)` | number, node | int |
| `uint(x)` | number, node | uint |
| `bool(x)` | boolean, node | bool |
| `vec2(x,y)` | numbers, nodes, Vector2 | vec2 |
| `vec3(x,y,z)` | numbers, nodes, Vector3, Color | vec3 |
| `vec4(x,y,z,w)` | numbers, nodes, Vector4 | vec4 |
| `color(hex)` | hex number | vec3 |
| `color(r,g,b)` | numbers 0-1 | vec3 |
| `ivec2/3/4` | integers | signed int vector |
| `uvec2/3/4` | integers | unsigned int vector |
| `mat2/3/4` | numbers, Matrix | matrix |

### Type Conversions

    node.toFloat()  node.toInt()  node.toUint()  node.toBool()
    node.toVec2()   node.toVec3() node.toVec4()  node.toColor()

---

## Operators

### Arithmetic (method chaining)

    a.add(b)      // a + b (supports multiple: a.add(b, c, d))
    a.sub(b)      // a - b
    a.mul(b)      // a * b
    a.div(b)      // a / b
    a.mod(b)      // a % b
    a.negate()    // -a

### Assignment (for mutable variables)

    v.assign(x)        // v = x
    v.addAssign(x)     // v += x
    v.subAssign(x)     // v -= x
    v.mulAssign(x)     // v *= x
    v.divAssign(x)     // v /= x

### Comparison (returns bool node)

    a.equal(b)           // a == b
    a.notEqual(b)        // a != b
    a.lessThan(b)        // a < b
    a.greaterThan(b)     // a > b
    a.lessThanEqual(b)   // a <= b
    a.greaterThanEqual(b)// a >= b

### Logical

    a.and(b)   a.or(b)   a.not()   a.xor(b)

### Bitwise

    a.bitAnd(b)  a.bitOr(b)  a.bitXor(b)  a.bitNot()
    a.shiftLeft(n)  a.shiftRight(n)

### Swizzle

    v.x  v.y  v.z  v.w          // single component
    v.xy  v.xyz  v.xyzw         // multiple components
    v.zyx  v.bgr                // reorder
    v.xxx                       // duplicate
    // Aliases: xyzw = rgba = stpq

---

## Variables

### RULE: TSL nodes are immutable by default

    // WRONG: Cannot modify immutable node
    const pos = positionLocal;
    pos.y = pos.y.add(1);  // ERROR

    // CORRECT: Use .toVar() for mutable variable
    const pos = positionLocal.toVar();
    pos.y.assign(pos.y.add(1));  // OK

### Variable Types

    const v = expr.toVar();           // mutable variable
    const v = expr.toVar('name');     // named mutable variable
    const c = expr.toConst();         // inline constant
    const p = property('float');      // uninitialized property

---

## Uniforms

    // Create
    const u = uniform(initialValue);
    const u = uniform(new THREE.Color(0xff0000));
    const u = uniform(new THREE.Vector3(1, 2, 3));
    const u = uniform(0.5);

    // Update from JS
    u.value = newValue;

    // Auto-update callbacks
    u.onFrameUpdate(() => value);                    // once per frame
    u.onRenderUpdate(({ camera }) => value);         // once per render
    u.onObjectUpdate(({ object }) => object.position.y); // per object

---

## Functions

### Fn() Syntax

    // Array parameters
    const myFn = Fn(([a, b, c]) => { return a.add(b).mul(c); });

    // Object parameters
    const myFn = Fn(({ color = vec3(1), intensity = 1.0 }) => {
      return color.mul(intensity);
    });

    // With defaults
    const myFn = Fn(([t = time]) => { return t.sin(); });

    // Access build context (second param or first if no inputs)
    const myFn = Fn(([input], { material, geometry, object, camera }) => {
      // JS conditionals here run at BUILD time
      if (material.transparent) { return input.mul(0.5); }
      return input;
    });

### Calling Functions

    myFn(a, b, c)           // array params
    myFn({ color: red })    // object params
    myFn()                  // use defaults

### Inline Functions (no Fn wrapper)

    // OK for simple expressions, no variables/conditionals
    const simple = (t) => t.sin().mul(0.5).add(0.5);

---

## Conditionals

### If/ElseIf/Else (CAPITAL I)

    // WRONG
    if(condition, () => {})    // lowercase 'if' is JavaScript

    // CORRECT (inside Fn())
    If(a.greaterThan(b), () => {
      result.assign(a);
    }).ElseIf(a.lessThan(c), () => {
      result.assign(c);
    }).Else(() => {
      result.assign(b);
    });

### Switch/Case

    Switch(mode)
      .Case(0, () => { out.assign(red); })
      .Case(1, () => { out.assign(green); })
      .Case(2, 3, () => { out.assign(blue); })  // multiple values
      .Default(() => { out.assign(white); });
    // NOTE: No fallthrough, implicit break

### select() - Ternary (Preferred)

    // Works outside Fn(), returns value directly
    const result = select(condition, valueIfTrue, valueIfFalse);

    // EQUIVALENT TO: condition ? valueIfTrue : valueIfFalse

    // Example: clamp value with custom logic
    const clamped = select(x.greaterThan(max), max, x);

### Math-Based (Preferred for Performance)

    step(edge, x)           // x < edge ? 0 : 1
    mix(a, b, t)            // a*(1-t) + b*t
    smoothstep(e0, e1, x)   // smooth 0→1 transition
    clamp(x, min, max)      // constrain range
    saturate(x)             // clamp(x, 0, 1)

    // Pattern: conditional selection without branching
    mix(valueA, valueB, step(threshold, selector))

---

## Loops

    // Basic
    Loop(count, ({ i }) => { /* i is loop index */ });

    // With options
    Loop({ start: int(0), end: int(10), type: 'int', condition: '<' }, ({ i }) => {});

    // Nested
    Loop(10, 5, ({ i, j }) => {});

    // Backward
    Loop({ start: 10 }, ({ i }) => {});  // counts down

    // While-style
    Loop(value.lessThan(10), () => { value.addAssign(1); });

    // Control
    Break();     // exit loop
    Continue();  // skip iteration

---

## Math Functions

    // All available as: func(x) OR x.func()

    // Basic
    abs(x) sign(x) floor(x) ceil(x) round(x) trunc(x) fract(x)
    mod(x,y) min(x,y) max(x,y) clamp(x,min,max) saturate(x)

    // Interpolation
    mix(a,b,t) step(edge,x) smoothstep(e0,e1,x)

    // Trig
    sin(x) cos(x) tan(x) asin(x) acos(x) atan(y,x)

    // Exponential
    pow(x,y) exp(x) exp2(x) log(x) log2(x) sqrt(x) inverseSqrt(x)

    // Vector
    length(v) distance(a,b) dot(a,b) cross(a,b) normalize(v)
    reflect(I,N) refract(I,N,eta) faceforward(N,I,Nref)

    // Derivatives (fragment only)
    dFdx(x) dFdy(x) fwidth(x)

    // TSL extras (not in GLSL)
    oneMinus(x)     // 1 - x
    negate(x)       // -x
    saturate(x)     // clamp(x, 0, 1)
    reciprocal(x)   // 1/x
    cbrt(x)         // cube root
    lengthSq(x)     // squared length (no sqrt)
    difference(x,y) // abs(x - y)
    equals(x,y)     // x == y
    pow2(x) pow3(x) pow4(x) // x^2, x^3, x^4

---

## Oscillators

    oscSine(t = time)      // sine wave 0→1→0
    oscSquare(t = time)    // square wave 0/1
    oscTriangle(t = time)  // triangle wave
    oscSawtooth(t = time)  // sawtooth wave

---

## Blend Modes

    blendBurn(a, b)    // color burn
    blendDodge(a, b)   // color dodge
    blendScreen(a, b)  // screen
    blendOverlay(a, b) // overlay
    blendColor(a, b)   // normal blend

---

## UV Utilities

    uv()                                        // default UV coordinates (vec2, 0-1)
    uv(index)                                   // specific UV channel
    matcapUV                                    // matcap texture coords
    rotateUV(uv, rotation, center = vec2(0.5))  // rotate UVs
    spherizeUV(uv, strength, center = vec2(0.5))// spherical distortion
    spritesheetUV(count, uv = uv(), frame = 0)  // sprite animation
    equirectUV(direction = positionWorldDirection) // equirect mapping

---

## Reflect

    reflectView    // reflection in view space
    reflectVector  // reflection in world space

---

## Interpolation Helpers

    remap(node, inLow, inHigh, outLow = 0, outHigh = 1)      // remap range
    remapClamp(node, inLow, inHigh, outLow = 0, outHigh = 1) // remap + clamp

---

## Random

    hash(seed)      // pseudo-random float [0,1]
    range(min, max) // random attribute per instance

---

## Arrays

    // Constant array
    const arr = array([vec3(1,0,0), vec3(0,1,0), vec3(0,0,1)]);
    arr.element(i)    // dynamic index
    arr[0]            // constant index only

    // Uniform array (updatable from JS)
    const arr = uniformArray([new THREE.Color(0xff0000)], 'color');
    arr.array[0] = new THREE.Color(0x00ff00);  // update

---

## Varyings

    // Compute in vertex, interpolate to fragment
    const v = varying(expression, 'name');

    // Optimize: force vertex computation
    const v = vertexStage(expression);

---

## Textures

    texture(tex)                    // sample at default UV
    texture(tex, uv)                // sample at UV
    texture(tex, uv, level)         // sample with LOD
    cubeTexture(tex, direction)     // cubemap
    triplanarTexture(texX, texY, texZ, scale, pos, normal)

---

## Shader Inputs

### Position

    positionGeometry      // raw attribute
    positionLocal         // after skinning/morphing
    positionWorld         // world space
    positionView          // camera space
    positionWorldDirection // normalized
    positionViewDirection  // normalized

### Normal

    normalGeometry   normalLocal   normalView   normalWorld

### Camera

    cameraPosition  cameraNear  cameraFar
    cameraViewMatrix  cameraProjectionMatrix  cameraNormalMatrix

### Screen

    screenUV          // normalized [0,1]
    screenCoordinate  // pixels
    screenSize        // pixels
    viewportUV  viewport  viewportCoordinate  viewportSize

### Time

    time              // elapsed time in seconds (float)
    deltaTime         // time since last frame (float)

### Model

    modelDirection         // vec3
    modelViewMatrix        // mat4
    modelNormalMatrix      // mat3
    modelWorldMatrix       // mat4
    modelPosition          // vec3
    modelScale             // vec3
    modelViewPosition      // vec3
    modelWorldMatrixInverse // mat4

### Other

    uv()  uv(index)           // texture coordinates
    vertexColor()             // vertex colors
    attribute('name', 'type') // custom attribute
    instanceIndex             // instance/thread ID (for instancing and compute)

---

## NodeMaterial Types

### Available Materials

    MeshBasicNodeMaterial      // unlit, fastest
    MeshStandardNodeMaterial   // PBR with roughness/metalness
    MeshPhysicalNodeMaterial   // PBR + clearcoat, transmission, etc.
    MeshPhongNodeMaterial      // Blinn-Phong shading
    MeshLambertNodeMaterial    // Lambert diffuse
    MeshToonNodeMaterial       // cel-shaded
    MeshMatcapNodeMaterial     // matcap shading
    MeshNormalNodeMaterial     // visualize normals
    SpriteNodeMaterial         // billboarded quads
    PointsNodeMaterial         // point clouds
    LineBasicNodeMaterial      // solid lines
    LineDashedNodeMaterial     // dashed lines

### All Materials - Common Properties

    .colorNode      // vec4 - base color
    .opacityNode    // float - opacity
    .positionNode   // vec3 - vertex position (local space)
    .normalNode     // vec3 - surface normal
    .outputNode     // vec4 - final output
    .fragmentNode   // vec4 - replace entire fragment stage
    .vertexNode     // vec4 - replace entire vertex stage

### MeshStandardNodeMaterial

    .roughnessNode  // float
    .metalnessNode  // float
    .emissiveNode   // vec3 color
    .aoNode         // float
    .envNode        // vec3 color

### MeshPhysicalNodeMaterial (extends Standard)

    .clearcoatNode  .clearcoatRoughnessNode  .clearcoatNormalNode
    .sheenNode  .transmissionNode  .thicknessNode
    .iorNode  .iridescenceNode  .iridescenceThicknessNode
    .anisotropyNode  .specularColorNode  .specularIntensityNode

### SpriteNodeMaterial

    .positionNode   // vec3 - world position of sprite center
    .colorNode      // vec4 - color and alpha
    .scaleNode      // float - sprite size (or vec2 for non-uniform)
    .rotationNode   // float - rotation in radians

### PointsNodeMaterial

    .positionNode   // vec3 - point position
    .colorNode      // vec4 - color and alpha
    .sizeNode       // float - point size in pixels

---

## Compute Shaders

### Basic Compute (Standalone)

    import { Fn, instanceIndex, storage } from 'three/tsl';

    // Create storage buffer
    const count = 1024;
    const array = new Float32Array(count * 4);
    const bufferAttribute = new THREE.StorageBufferAttribute(array, 4);
    const buffer = storage(bufferAttribute, 'vec4', count);

    // Define compute shader
    const computeShader = Fn(() => {
      const idx = instanceIndex;
      const data = buffer.element(idx);
      buffer.element(idx).assign(data.mul(2));
    })().compute(count);

    // Execute
    renderer.compute(computeShader);              // synchronous (per-frame)
    await renderer.computeAsync(computeShader);   // async (heavy one-off tasks)

### Compute → Render Pipeline

When compute shader output needs to be rendered (e.g., simulations, procedural geometry), use `StorageInstancedBufferAttribute` with `storage()` for writing and `attribute()` for reading.

    import { Fn, instanceIndex, storage, attribute, vec4 } from 'three/tsl';

    const COUNT = 1000;

    // 1. Create typed array and storage attribute
    const dataArray = new Float32Array(COUNT * 4);
    const dataAttribute = new THREE.StorageInstancedBufferAttribute(dataArray, 4);

    // 2. Create storage node for compute shader (write access)
    const dataStorage = storage(dataAttribute, 'vec4', COUNT);

    // 3. Define compute shader
    const computeShader = Fn(() => {
      const idx = instanceIndex;
      const current = dataStorage.element(idx);

      // Modify data...
      const newValue = current.xyz.add(vec3(0.01, 0, 0));

      dataStorage.element(idx).assign(vec4(newValue, current.w));
    })().compute(COUNT);

    // 4. Attach attribute to geometry for rendering
    const geometry = new THREE.BufferGeometry();
    // ... set up base geometry ...
    geometry.setAttribute('instanceData', dataAttribute);

    // 5. Read in material using attribute()
    const material = new THREE.MeshBasicNodeMaterial();
    material.positionNode = Fn(() => {
      const data = attribute('instanceData', 'vec4');
      return positionLocal.add(data.xyz);
    })();

    // 6. Create mesh
    const mesh = new THREE.InstancedMesh(geometry, material, COUNT);
    scene.add(mesh);

    // 7. Animation loop
    await renderer.init();
    function animate() {
      renderer.compute(computeShader);
      renderer.render(scene, camera);
      requestAnimationFrame(animate);
    }
    animate();

### Updating Buffers from JavaScript

    // Modify the underlying array
    for (let i = 0; i < COUNT; i++) {
      dataArray[i * 4] = Math.random();
    }
    // Flag for GPU upload
    dataAttribute.needsUpdate = true;

---

## Example: Basic Material Shader

    import * as THREE from 'three/webgpu';
    import { Fn, uniform, vec3, vec4, float, uv, time,
             normalWorld, positionWorld, cameraPosition,
             mix, pow, dot, normalize, max } from 'three/tsl';

    // Uniforms
    const baseColor = uniform(new THREE.Color(0x4488ff));
    const fresnelPower = uniform(3.0);

    // Create material
    const material = new THREE.MeshStandardNodeMaterial();

    // Custom color with fresnel rim lighting
    material.colorNode = Fn(() => {
      // Calculate fresnel
      const viewDir = normalize(cameraPosition.sub(positionWorld));
      const NdotV = max(dot(normalWorld, viewDir), 0.0);
      const fresnel = pow(float(1.0).sub(NdotV), fresnelPower);

      // Mix base color with white rim
      const rimColor = vec3(1.0, 1.0, 1.0);
      const finalColor = mix(baseColor, rimColor, fresnel);

      return vec4(finalColor, 1.0);
    })();

    // Animated vertex displacement
    material.positionNode = Fn(() => {
      const pos = positionLocal.toVar();
      const wave = sin(pos.x.mul(4.0).add(time.mul(2.0))).mul(0.1);
      pos.y.addAssign(wave);
      return pos;
    })();

---

## Example: Compute Shader Structure

    import * as THREE from 'three/webgpu';
    import { Fn, instanceIndex, storage, uniform, vec4, float, sin, time } from 'three/tsl';

    const COUNT = 10000;

    // Storage buffer
    const dataArray = new Float32Array(COUNT * 4);
    const dataAttribute = new THREE.StorageBufferAttribute(dataArray, 4);
    const dataBuffer = storage(dataAttribute, 'vec4', COUNT);

    // Uniforms for compute
    const speed = uniform(1.0);

    // Compute shader
    const updateCompute = Fn(() => {
      const idx = instanceIndex;
      const data = dataBuffer.element(idx);

      // Read current values
      const position = data.xyz.toVar();
      const phase = data.w;

      // Update logic
      const offset = sin(time.mul(speed).add(phase)).mul(0.1);
      position.y.addAssign(offset);

      // Write back
      dataBuffer.element(idx).assign(vec4(position, phase));
    });

    const computeNode = updateCompute().compute(COUNT);

    // In animation loop:
    // renderer.compute(computeNode);

---

## Common Error Patterns

### ERROR: "If is not defined"

    // WRONG
    if(condition, () => {})
    // CORRECT
    If(condition, () => {})  // capital I

### ERROR: Cannot assign

    // WRONG
    const v = vec3(1,2,3);
    v.x = 5;
    // CORRECT
    const v = vec3(1,2,3).toVar();
    v.x.assign(5);

### ERROR: Type mismatch

    // WRONG
    sqrt(intValue)
    // CORRECT
    sqrt(intValue.toFloat())

### ERROR: Uniform not changing

    // WRONG
    myUniform = newValue;
    // CORRECT
    myUniform.value = newValue;

### ERROR: Import not found

    // WRONG
    import { vec3 } from 'three/nodes';
    import * as THREE from 'three';
    // CORRECT
    import { vec3 } from 'three/tsl';
    import * as THREE from 'three/webgpu';

### ERROR: Compute data not visible in render

    // WRONG: Using storage() in render material
    material.positionNode = storage(attr, 'vec4', count).element(idx).xyz;

    // CORRECT: Use attribute() to read in render shaders
    geometry.setAttribute('myData', attr);
    material.positionNode = attribute('myData', 'vec4').xyz;

### ERROR: Nothing renders

    // WRONG: Rendering before init
    renderer.render(scene, camera);

    // CORRECT: Always await init first
    await renderer.init();
    renderer.render(scene, camera);

---

## Quick Patterns

### Fresnel

    const fresnel = Fn(() => {
      const NdotV = normalize(cameraPosition.sub(positionWorld)).dot(normalWorld).max(0);
      return pow(float(1).sub(NdotV), 5);
    });

### Wave Displacement

    material.positionNode = Fn(() => {
      const p = positionLocal.toVar();
      p.y.addAssign(sin(p.x.mul(5).add(time)).mul(0.2));
      return p;
    })();

### UV Scroll

    material.colorNode = texture(map, uv().add(vec2(time.mul(0.1), 0)));

### Conditional Value

    const result = select(value.greaterThan(0.5), valueA, valueB);
    // OR branchless:
    const result = mix(valueB, valueA, step(0.5, value));

### Gradient Mapping

    const t = smoothstep(float(0.0), float(1.0), inputValue);
    const colorA = vec3(0.1, 0.2, 0.8);
    const colorB = vec3(1.0, 0.5, 0.2);
    const gradient = mix(colorA, colorB, t);

### Soft Falloff

    // Exponential falloff (good for glow, attenuation)
    const falloff = exp(distance.negate().mul(rate));

    // Inverse square falloff
    const attenuation = float(1.0).div(distance.mul(distance).add(1.0));

### Circular Mask (for sprites/points)

    const uvCentered = uv().sub(0.5).mul(2.0);  // -1 to 1
    const dist = length(uvCentered);
    const circle = smoothstep(float(1.0), float(0.8), dist);

---

## OceanHeightMap — Synchronizing Elements with the Ocean Surface

The project uses a render-to-texture heightmap (`OceanHeightMap`) to encode the live ocean surface height. Any element that needs to follow the ocean (waves, foam, floating objects, etc.) should sample this texture in its vertex shader.

### How the HeightMap Works

- An orthographic camera renders a `PlaneGeometry(1, 1, 200, 200)` scaled to `SCALE_OCEAN` (3000) in the XY plane.
- The vertex shader computes a wave `depth` from a sum-of-sines surface function and encodes it into varyings.
- The fragment shader writes to a `WebGLRenderTarget`:
  - **R** = `(depth + yStrength) / (2 * yStrength)` — normalized height [0,1]
  - **G** = same as R (average, for future use)
  - **B** = `yStrength / 100` — strength scaling factor
  - **A** = 1.0

### Uniforms Updated Each Frame (from Ocean `update()`)

    OceanHeightMap.uTimeWave.value  = this.uTimeWave.value
    OceanHeightMap.uDirTex.value    = GridManager.offsetUV
    OceanHeightMap.uYScale.value    = yScale
    OceanHeightMap.uYStrength.value = yStrength

### Sampling the HeightMap in a TSL positionNode

#### 1. Get the heightmap texture reference (at build time)

    import OceanHeightMap from '../Ocean/OceanHeightMap'
    const heightMapTex = OceanHeightMap.heightMap?.texture  // THREE.Texture from WebGLRenderTarget

#### 2. Map world X,Z to heightmap UV

The heightmap covers `[-SCALE_OCEAN/2, SCALE_OCEAN/2]` in world X and Z.

    // For a regular Mesh or Points:
    const wPos = modelWorldMatrix.mul(vec4(positionLocal, 1.0))

    // For an InstancedMesh — sample at instance CENTER, NOT per-vertex:
    const wCenter = modelWorldMatrix.mul(vec4(0.0, 0.0, 0.0, 1.0))

    const uScaleOcean = uniform(SCALE_OCEAN)
    const uvGrid = vec2(
      float(0.5).add(wCenter.x.div(uScaleOcean)),
      float(0.5).sub(wCenter.z.div(uScaleOcean)),
    )

**CRITICAL for InstancedMesh**: Use `vec4(0,0,0,1)` (instance origin) as the sampling point. Using `positionLocal` would sample at each vertex corner (±0.5 after scale), causing the quad to warp instead of displacing uniformly. The original GLSL `Points` shader used `position` which was the point center — `vec4(0,0,0,1)` is the equivalent for instanced geometry.

#### 3. 5-tap cross average (reduces flicker)

    const off = float(0.01)
    const hmC  = texture(heightMapTex, uvGrid)
    const hm1A = texture(heightMapTex, vec2(uvGrid.x.add(off), uvGrid.y))
    const hm1B = texture(heightMapTex, vec2(uvGrid.x, uvGrid.y.add(off)))
    const hm2A = texture(heightMapTex, vec2(uvGrid.x.sub(off), uvGrid.y))
    const hm2B = texture(heightMapTex, vec2(uvGrid.x, uvGrid.y.sub(off)))
    const avgH = hmC.r.add(hm1A.r).add(hm1B.r).add(hm2A.r).add(hm2B.r).div(5.0)

#### 4. Compute world-space Y displacement

    // Decode: (avgH - 0.5) * 2 * yStrength = depth (actual wave height)
    // B channel * 100 recovers yStrength
    const disp = avgH.sub(0.5).mul(2.0).mul(hmC.b.mul(100.0))

> **Note**: The original GLSL `waves.vert` used `(avgH - 0.5) * 2 * (B*100) * 2` because it applied the displacement in **clip space** (`gl_Position.y +=`), where the trailing `*2` gets naturally attenuated by perspective divide. In world space, omit the trailing `*2`.

#### 5. Apply displacement

**For a standard Mesh** (local Y ≈ world Y):

    const pos = positionLocal.toVar()
    pos.y.addAssign(disp)
    return pos

**For a billboarded InstancedMesh** (local Y ≠ world Y due to billboard rotation):

    // Transform world-Y displacement to instance-local space
    const worldDispVec = vec4(0.0, disp, 0.0, 0.0)  // w=0 for direction
    const localDisp = modelWorldMatrixInverse.mul(worldDispVec)
    return positionLocal.add(localDisp.xyz)

Required imports for this pattern:

    import { positionLocal, modelWorldMatrix, modelWorldMatrixInverse } from 'three/tsl'

### Complete positionNode Example (InstancedMesh with Billboard)

    const positionNodeFn = Fn(() => {
      const pos = positionLocal
      const wCenter = modelWorldMatrix.mul(vec4(0.0, 0.0, 0.0, 1.0))

      const uvGrid = vec2(
        float(0.5).add(wCenter.x.div(uScaleOcean)),
        float(0.5).sub(wCenter.z.div(uScaleOcean)),
      )

      const off = float(0.01)
      const hmC  = texture(heightMapTex, uvGrid)
      const hm1A = texture(heightMapTex, vec2(uvGrid.x.add(off), uvGrid.y))
      const hm1B = texture(heightMapTex, vec2(uvGrid.x, uvGrid.y.add(off)))
      const hm2A = texture(heightMapTex, vec2(uvGrid.x.sub(off), uvGrid.y))
      const hm2B = texture(heightMapTex, vec2(uvGrid.x, uvGrid.y.sub(off)))

      const avgH = hmC.r.add(hm1A.r).add(hm1B.r).add(hm2A.r).add(hm2B.r).div(5.0)
      const disp = avgH.sub(0.5).mul(2.0).mul(hmC.b.mul(100.0))

      const worldDispVec = vec4(0.0, disp, 0.0, 0.0)
      const localDisp = modelWorldMatrixInverse.mul(worldDispVec)
      return pos.add(localDisp.xyz)
    })

    material.positionNode = positionNodeFn()

### Points → InstancedMesh Migration Notes

WebGPU does not support `gl_PointCoord` or variable `gl_PointSize` like WebGL. When converting `Points`-based effects:

1. Replace `Points` with `InstancedMesh` using `PlaneGeometry(1, 1)`.
2. Replace `gl_PointCoord` with `uv()`.
3. Use `instanceIndex` for per-instance variation instead of custom attributes (more reliable in WebGPU). Use `hash(instanceIndex)` for pseudo-random per-instance values.
4. Billboard rotation must be done on CPU (update instance matrices each frame with `lookAt` toward camera).
5. When billboarding on CPU, UV Y may need flipping: `float(1).sub(uv().y)`.
6. For transparent instances, sort back-to-front by camera depth each frame.

### Converting `gl_PointSize` to World-Space Scale

The original `gl_PointSize` formula gives a pixel size that shrinks with distance:

    gl_PointSize = uSize * (perspectiveFactor / -mvPosition.z)

For `InstancedMesh`, the quad scale is in **world units** and perspective is handled by the camera projection. Both `gl_PointSize` and world-space objects scale as `1/distance`, so the conversion is a constant factor.

**Formula:**

    SPRITE_SCALE = uSize * perspectiveFactor * 2 * tan(fov / 2) / screenHeight

Since `fov` and `screenHeight` are runtime values, derive the conversion factor `C` from one known-good conversion and apply to others:

    C = knownWorldScale / (knownUSize * knownPerspectiveFactor)
    newWorldScale = newUSize * newPerspectiveFactor * C

**This project's reference** (FOV = 50°):

| Component  | Original `uSize` | Perspective factor | K = uSize × factor | World scale (`SPRITE_SCALE`) |
|------------|-------------------|--------------------|---------------------|-------------------------------|
| Waves      | 450               | 100                | 45,000              | 15                            |
| Lightnings | 1000              | 400                | 400,000             | 133                           |
| Stars      | 50                | 100                | 5,000               | ~2                            |

    C = 15 / 45000 = 1/3000  →  SPRITE_SCALE = K / 3000

---

## GLSL → TSL Migration

| GLSL | TSL |
|------|-----|
| `position` | `positionGeometry` |
| `transformed` | `positionLocal` |
| `transformedNormal` | `normalLocal` |
| `vWorldPosition` | `positionWorld` |
| `vColor` | `vertexColor()` |
| `vUv` / `uv` | `uv()` |
| `vNormal` | `normalView` |
| `viewMatrix` | `cameraViewMatrix` |
| `modelMatrix` | `modelWorldMatrix` |
| `modelViewMatrix` | `modelViewMatrix` |
| `projectionMatrix` | `cameraProjectionMatrix` |
| `diffuseColor` | `material.colorNode` |
| `gl_FragColor` | `material.fragmentNode` |
| `texture2D(tex, uv)` | `texture(tex, uv)` |
| `textureCube(tex, dir)` | `cubeTexture(tex, dir)` |
| `gl_FragCoord` | `screenCoordinate` |
| `gl_PointCoord` | `uv()` in SpriteNodeMaterial/PointsNodeMaterial |
| `gl_InstanceID` | `instanceIndex` |
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall