Threejs Impl Webgpu

threejs-impl-webgpu

> EXPERIMENTAL — The WebGPU renderer and TSL are under active development. > API surfaces may change between Three.js releases. Pin your Three.js version.

Quick Reference

WebGPURenderer Setup

import * as THREE from 'three/webgpu';

const renderer = new THREE.WebGPURenderer({ antialias: true });
await renderer.init(); // MUST await before first render
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setAnimationLoop(animate);
document.body.appendChild(renderer.domElement);

ALWAYS call await renderer.init() before the first renderer.render() call. ALWAYS use renderer.setAnimationLoop(callback) instead of requestAnimationFrame. NEVER call renderer.render() before init() resolves — this throws a runtime error.

Browser Support

| Browser | Version | Status | |---------|---------|--------| | Chrome | 113+ | Full support | | Edge | 113+ | Full support | | Safari | 18+ | Supported | | Firefox | Experimental | Behind flag (dom.webgpu.enabled) |

Feature Detection and Fallback

import { WebGPU } from 'three/webgpu';

if (WebGPU.isAvailable()) {
  const renderer = new THREE.WebGPURenderer({ antialias: true });
  await renderer.init();
} else {
  const renderer = new THREE.WebGLRenderer({ antialias: true });
}

ALWAYS check WebGPU.isAvailable() before creating a WebGPURenderer. ALWAYS provide a WebGLRenderer fallback for unsupported browsers.

Critical Warnings

NEVER write raw GLSL or WGSL strings — ALWAYS use TSL functions. WebGPU compiles TSL to WGSL automatically. GLSL is NOT supported by the WebGPU backend.

NEVER use ShaderMaterial with WebGPURenderer — use NodeMaterial with TSL instead.

NEVER use requestAnimationFrame with WebGPURenderer — ALWAYS use renderer.setAnimationLoop().

NEVER use EffectComposer (three/examples) with WebGPURenderer — use the PostProcessing class with TSL nodes instead.

---

Node Materials

Every classic Three.js material has a node-based equivalent. Classic materials auto-convert when used with WebGPURenderer, but node materials provide full TSL customization.

Material Mapping

| Classic Material | Node Material | |-----------------|---------------| | MeshBasicMaterial | MeshBasicNodeMaterial | | MeshStandardMaterial | MeshStandardNodeMaterial | | MeshPhysicalMaterial | MeshPhysicalNodeMaterial | | MeshPhongMaterial | MeshPhongNodeMaterial | | MeshLambertMaterial | MeshLambertNodeMaterial | | LineBasicMaterial | LineBasicNodeMaterial | | LineDashedMaterial | LineDashedNodeMaterial | | PointsMaterial | PointsNodeMaterial | | SpriteMaterial | SpriteNodeMaterial |

ALWAYS import node materials from 'three/webgpu', not from 'three'.

NodeMaterial Input Properties

All properties accept TSL node values. All are optional and override defaults.

Common inputs (all node materials):

| Property | TSL Type | Purpose | |----------|----------|---------| | .colorNode | vec4 | Base color | | .opacityNode | float | Opacity | | .normalNode | vec3 | Normal map replacement | | .emissiveNode | color | Emissive output | | .positionNode | vec3 | Vertex displacement | | .fragmentNode | vec4 | Full fragment shader replacement | | .vertexNode | vec4 | Full vertex shader replacement | | .outputNode | vec4 | Final output override | | .aoNode | float | Ambient occlusion | | .alphaTestNode | float | Alpha test threshold | | .depthNode | float | Custom depth | | .castShadowNode | vec4 | Shadow casting override |

Standard/Physical inputs:

| Property | TSL Type | Purpose | |----------|----------|---------| | .metalnessNode | float | Metalness | | .roughnessNode | float | Roughness | | .envNode | color | Environment map | | .lightsNode | — | Lighting model override |

Physical-only inputs: .clearcoatNode, .clearcoatRoughnessNode, .clearcoatNormalNode, .sheenNode, .iridescenceNode, .iridescenceIORNode, .iridescenceThicknessNode, .specularIntensityNode, .specularColorNode, .iorNode, .transmissionNode, .thicknessNode, .attenuationDistanceNode, .attenuationColorNode, .dispersionNode, .anisotropyNode.

---

TSL (Three Shading Language)

TSL is a JavaScript-based node graph system that compiles to GLSL (WebGL2) and WGSL (WebGPU). It replaces raw shader strings entirely.

Type System

| Category | Functions | |----------|-----------| | Scalars | float(), int(), uint(), bool() | | Vectors | vec2(), vec3(), vec4(), ivec2(), ivec3(), ivec4(), uvec2(), uvec3(), uvec4() | | Matrices | mat2(), mat3(), mat4() | | Color | color() | | Conversion | .toFloat(), .toVec3(), .toColor() |

Variables and Uniforms

| Function | Purpose | |----------|---------| | uniform(value) | GPU-side dynamic value | | toVar(node) | Reusable shader variable | | toConst(node) | Inline constant | | varying(node) | Vertex-to-fragment interpolation | | vertexStage(node) | Force computation in vertex shader | | attribute(name, type) | Access buffer attributes |

Uniforms support callbacks: .onRenderUpdate(fn), .onFrameUpdate(fn), .onObjectUpdate(fn).

Operators

All operators are chainable on TSL nodes:

• Arithmetic: .add(), .sub(), .mul(), .div(), .mod()
• Comparison: .equal(), .notEqual(), .lessThan(), .greaterThan(), .lessThanEqual(), .greaterThanEqual()
• Logical: .and(), .or(), .not(), .xor()
• Assignment: .assign(), .addAssign(), .subAssign(), .mulAssign(), .divAssign()
• Bitwise: .bitAnd(), .bitOr(), .bitXor(), .shiftLeft(), .shiftRight()

Geometry Nodes

| Category | Nodes | |----------|-------| | Position | positionGeometry, positionLocal, positionWorld, positionView, positionWorldDirection, positionViewDirection | | Normal | normalGeometry, normalLocal, normalView, normalWorld | | Tangent | tangentGeometry, tangentLocal, tangentView, tangentWorld | | UV | uv(index) | | Screen | screenUV, screenCoordinate, screenSize | | Viewport | viewportUV, viewportCoordinate, viewportSize |

Camera and Model Nodes

• Camera: cameraNear, cameraFar, cameraPosition, cameraProjectionMatrix, cameraViewMatrix, cameraWorldMatrix, cameraNormalMatrix
• Model: modelViewMatrix, modelNormalMatrix, modelWorldMatrix, modelPosition, modelScale, modelDirection

Animation Nodes

| Node | Purpose | |------|---------| | time | Elapsed seconds since start | | deltaTime | Frame delta in seconds | | oscSine(timer) | Sine oscillator (0-1) | | oscSquare(timer) | Square wave oscillator | | oscTriangle(timer) | Triangle wave oscillator | | oscSawtooth(timer) | Sawtooth oscillator |

Texture Operations

| Function | Purpose | |----------|---------| | texture(tex, uv, level) | Sample with interpolation | | textureLoad(tex, uv, level) | Sample without interpolation | | textureStore(tex, uv, value) | Write to storage texture | | textureSize(tex, level) | Get texture dimensions | | cubeTexture(tex, uvw, level) | Sample cube map | | triplanarTexture(texX, texY, texZ, scale, position, normal) | Triplanar mapping |

Control Flow

ALWAYS use capital If — lowercase if is JavaScript, not TSL.

If(condition, () => {
  // true branch
}).ElseIf(otherCondition, () => {
  // else-if branch
}).Else(() => {
  // false branch
});

• select(condition, trueVal, falseVal) — ternary operator
• Loop(count, ({ i }) => { }) — GPU loop, supports Break(), Continue()
• Switch(value).Case(val, fn).Default(fn) — no fallthrough
• Discard() — discard fragment
• Return() — early return

Function Definition

const myFn = Fn(([param1, param2]) => {
  return param1.add(param2);
});
// Call: myFn(nodeA, nodeB)

---

Compute Shaders

WebGPU enables general-purpose GPU compute via TSL. Compute shaders are NOT available in WebGL fallback mode.

Setup

import { compute, storage } from 'three/webgpu';

const computeNode = compute(shaderFn, count, workgroupSize);
await renderer.computeAsync(computeNode);

ALWAYS use await renderer.computeAsync() — compute dispatch is asynchronous.

Storage and Atomics

• Storage: storage(attribute, type, count), storageTexture(texture)
• Atomics: atomicAdd(), atomicSub(), atomicMax(), atomicMin(), atomicAnd(), atomicOr(), atomicXor(), atomicStore(), atomicLoad()
• Barriers: workgroupBarrier(), storageBarrier(), textureBarrier()
• Built-in IDs: workgroupId, localId, globalId, numWorkgroups, subgroupSize

---

WebGPU Post-Processing

NEVER use the WebGL EffectComposer with WebGPURenderer. Use the PostProcessing class instead.

import { PostProcessing } from 'three/webgpu';
import { bloom, renderOutput } from 'three/tsl';

const postProcessing = new PostProcessing(renderer);
const scenePass = renderOutput(scene, camera);
postProcessing.outputNode = bloom(scenePass);

Available Post-Processing Nodes

bloom(), dof(), fxaa(), smaa(), gaussianBlur(), ssr(), ssgi(), ao(), chromaticAberration(), film(), dotScreen(), sobel(), afterImage(), anamorphic(), denoise(), lut3D(), motionBlur(), outline(), rgbShift(), transition(), traa(), renderOutput()

Color Operations

luminance(), saturation(), vibrance(), hue(), posterize(), grayscale(), sepia()

Blend Modes

blendBurn(), blendDodge(), blendOverlay(), blendScreen(), blendColor()

---

WebGL to WebGPU Migration

| Step | Action | |------|--------| | 1 | Replace import * as THREE from 'three' with import * as THREE from 'three/webgpu' | | 2 | Replace new WebGLRenderer() with new WebGPURenderer() and add await renderer.init() | | 3 | Replace classic materials with NodeMaterial equivalents (or keep classic — they auto-convert) | | 4 | Replace EffectComposer with PostProcessing class and TSL post-processing nodes | | 5 | Replace raw GLSL ShaderMaterial with TSL-based NodeMaterial | | 6 | Replace requestAnimationFrame with renderer.setAnimationLoop() |

ALWAYS make the entry point async when using WebGPURenderer — renderer.init() returns a Promise.

---

Reference Links

• [references/methods.md](references/methods.md) — API signatures for WebGPURenderer, NodeMaterial, TSL, compute
• [references/examples.md](references/examples.md) — Working code examples for WebGPU scenes
• [references/anti-patterns.md](references/anti-patterns.md) — Common mistakes and how to avoid them

Official Sources

• https://threejs.org/docs/
• https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language
• https://threejs.org/examples/?q=webgpu

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Three.js-Claude-Skill-Package
• License: MIT
• Homepage: https://threejs.org/

Install and usage instructions live in the source repository linked above.