TSL Quick Reference

Imports

// WebGPU Three.js
import * as THREE from 'three/webgpu';

// Core TSL
import {
  float, int, uint, bool,
  vec2, vec3, vec4, color,
  mat2, mat3, mat4,
  uniform, texture, uv,
  Fn, If, Loop, Break, Continue,
  time, deltaTime
} from 'three/tsl';

Types

TSL	WGSL	Example
`float(1.0)`	`f32`	Scalar float
`int(1)`	`i32`	Signed integer
`uint(1)`	`u32`	Unsigned integer
`bool(true)`	`bool`	Boolean
`vec2(x, y)`	`vec2<f32>`	2D vector
`vec3(x, y, z)`	`vec3<f32>`	3D vector
`vec4(x, y, z, w)`	`vec4<f32>`	4D vector
`color(0xff0000)`	`vec3<f32>`	RGB color
`uniform(value)`	uniform	Dynamic value

Operators

Operation	TSL	GLSL Equivalent
Add	`a.add(b)`	`a + b`
Subtract	`a.sub(b)`	`a - b`
Multiply	`a.mul(b)`	`a * b`
Divide	`a.div(b)`	`a / b`
Modulo	`a.mod(b)`	`mod(a, b)`
Negate	`a.negate()`	`-a`
Less Than	`a.lessThan(b)`	`a < b`
Greater Than	`a.greaterThan(b)`	`a > b`
Equal	`a.equal(b)`	`a == b`
And	`a.and(b)`	`a && b`
Or	`a.or(b)`	`a \\|\\| b`
Assign	`a.assign(b)`	`a = b`
Add Assign	`a.addAssign(b)`	`a += b`

Swizzling

const v = vec3(1, 2, 3);
v.x        // 1
v.xy       // vec2(1, 2)
v.zyx      // vec3(3, 2, 1)
v.rgb      // same as xyz

Math Functions

Function	Description
`abs(x)`	Absolute value
`sign(x)`	Sign (-1, 0, 1)
`floor(x)`	Round down
`ceil(x)`	Round up
`fract(x)`	Fractional part
`min(a, b)`	Minimum
`max(a, b)`	Maximum
`clamp(x, lo, hi)`	Clamp to range
`mix(a, b, t)`	Linear interpolation
`step(edge, x)`	Step function
`smoothstep(a, b, x)`	Smooth step
`sin(x)`, `cos(x)`	Trigonometry
`pow(x, y)`	Power
`sqrt(x)`	Square root
`length(v)`	Vector length
`distance(a, b)`	Distance
`dot(a, b)`	Dot product
`cross(a, b)`	Cross product
`normalize(v)`	Unit vector
`reflect(i, n)`	Reflection

Geometry Nodes

Node	Description
`positionLocal`	Model space position
`positionWorld`	World space position
`positionView`	Camera space position
`normalLocal`	Model space normal
`normalWorld`	World space normal
`normalView`	Camera space normal
`uv()`	UV coordinates
`uv(1)`	Secondary UVs
`tangentLocal`	Tangent vector
`vertexColor()`	Vertex colors

Camera Nodes

Node	Description
`cameraPosition`	Camera world position
`cameraNear`	Near plane
`cameraFar`	Far plane
`cameraViewMatrix`	View matrix
`cameraProjectionMatrix`	Projection matrix
`screenUV`	Screen UV (0-1)
`screenSize`	Screen dimensions

Time

Node	Description
`time`	Seconds since start
`deltaTime`	Frame delta
`oscSine(t)`	Sine wave (0-1)
`oscSquare(t)`	Square wave
`oscTriangle(t)`	Triangle wave
`oscSawtooth(t)`	Sawtooth wave

Material Properties

const mat = new THREE.MeshStandardNodeMaterial();

// Basic
mat.colorNode = color(0xff0000);
mat.opacityNode = float(0.8);
mat.alphaTestNode = float(0.5);

// PBR
mat.roughnessNode = float(0.5);
mat.metalnessNode = float(0.0);
mat.emissiveNode = color(0x000000);
mat.normalNode = normalMap(tex);

// Physical (MeshPhysicalNodeMaterial)
mat.clearcoatNode = float(1.0);
mat.transmissionNode = float(0.9);
mat.iridescenceNode = float(1.0);
mat.sheenNode = float(1.0);

// Vertex
mat.positionNode = displaced;

Control Flow

// If-Else
If(condition, () => {
  // true
}).ElseIf(other, () => {
  // other true
}).Else(() => {
  // false
});

// Select (ternary)
const result = select(condition, trueVal, falseVal);

// Loop
Loop(10, ({ i }) => {
  // i = 0 to 9
});

// Loop control
Break();
Continue();
Discard();  // Fragment only

Custom Functions

// Basic function
const myFn = Fn(([a, b]) => {
  return a.add(b);
});

// With defaults
const myFn = Fn(([a = 1.0, b = 2.0]) => {
  return a.add(b);
});

// Usage
myFn(x, y);
myFn();  // uses defaults

Compute Shaders

// Storage buffers (read-write)
const positions = instancedArray(count, 'vec3');
const values = instancedArray(count, 'float');

// Read-only storage buffers
const lookupTable = attributeArray(data, 'float');

// Compute shader
const compute = Fn(() => {
  const pos = positions.element(instanceIndex);
  pos.addAssign(vec3(0.01, 0, 0));
})().compute(count);

// Execute (after await renderer.init())
renderer.compute(compute);

// Workgroup size
const compute2 = Fn(() => { /* ... */ })().compute(count, [64]);

Post-Processing

import { pass } from 'three/tsl';
import { bloom } from 'three/addons/tsl/display/BloomNode.js';

// Setup (RenderPipeline replaced PostProcessing in r183)
const renderPipeline = new THREE.RenderPipeline(renderer);
const scenePass = pass(scene, camera);
const color = scenePass.getTextureNode('output');

// Apply effects
const bloomPass = bloom(color);
renderPipeline.outputNode = color.add(bloomPass);

// Render
renderPipeline.render();

Common Patterns

Fresnel

const viewDir = cameraPosition.sub(positionWorld).normalize();
const fresnel = float(1).sub(normalWorld.dot(viewDir).saturate()).pow(3);

Animated UV

const animUV = uv().add(vec2(time.mul(0.1), 0));

Noise Hash

const noise = fract(position.dot(vec3(12.9898, 78.233, 45.543)).sin().mul(43758.5453));

Dissolve

const noise = hash(positionLocal.mul(50));
If(noise.lessThan(threshold), () => Discard());

Color Gradient

const gradient = mix(colorA, colorB, positionLocal.y.mul(0.5).add(0.5));

Node Materials

Material	Use Case
`MeshBasicNodeMaterial`	Unlit
`MeshStandardNodeMaterial`	PBR
`MeshPhysicalNodeMaterial`	Advanced PBR
`MeshPhongNodeMaterial`	Phong shading
`MeshToonNodeMaterial`	Cel shading
`PointsNodeMaterial`	Point clouds
`LineBasicNodeMaterial`	Lines
`SpriteNodeMaterial`	Sprites

Device Loss Handling

// Listen for device loss
renderer.backend.device.lost.then((info) => {
  if (info.reason === 'unknown') {
    // Unexpected loss - recover
    renderer.dispose();
    initWebGPU();  // Reinitialize
  }
});

// Simulate loss for testing
renderer.backend.device.destroy();

Loss Reason	Meaning
`'destroyed'`	Intentional via `destroy()`
`'unknown'`	Unexpected (driver crash, timeout, etc.)

Recovery tips:

Always get fresh adapter before new device
Save/restore application state (not transient data)
Use Chrome about:gpucrash to test real GPU crashes

Compute Shader Built-ins

Node	Description
`instanceIndex`	Current instance/invocation index
`vertexIndex`	Current vertex index
`drawIndex`	Current draw call index
`globalId`	Global invocation position (uvec3)
`localId`	Local workgroup position (uvec3)
`workgroupId`	Workgroup index (uvec3)
`numWorkgroups`	Number of workgroups dispatched (uvec3)
`subgroupSize`	Size of the subgroup

Device Limits

WebGPU devices use default minimums unless you request higher limits. This is critical for large buffers.

// Three.js: pass requiredLimits to the renderer
const renderer = new THREE.WebGPURenderer({
  requiredLimits: {
    maxBufferSize: 1024 * 1024 * 1024,            // 1 GiB
    maxStorageBufferBindingSize: 1024 * 1024 * 512, // 512 MiB
  },
});
await renderer.init();

Limit	Default	Common Need
`maxBufferSize`	256 MiB	Large vertex/storage buffers
`maxStorageBufferBindingSize`	128 MiB	Large compute buffers
`maxStorageBuffersPerShaderStage`	8	Many storage buffers

Check before requesting:

const adapter = await navigator.gpu?.requestAdapter();
if (adapter.limits.maxBufferSize >= desiredSize) {
  // Safe to request
}

See docs/limits-and-features.md for full details.

Version Notes

r178+:

PI2 is deprecated → use TWO_PI
transformedNormalView → use normalView
transformedNormalWorld → use normalWorld

r171+:

Recommended minimum version for stable TSL
Requires separate three/webgpu import map entry