Robpayot/tslda / .agents/skills
TSL conversion
VerifiedUse it when you need to convert a Threejs Material using GLSL shaders to TSL node materials
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 29.5 KB |
SKILL.md
View on GitHub---
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` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |