WebGPU Three.js TSL Skill

Features are optional capabilities (e.g., shader-f16 or subgroups) that are either present or absent on a GPU.

Three.js Behavior: Three.js automatically requests all features supported by the adapter, so manual feature management is generally unnecessary for most users.

To check for a specific feature in raw WebGPU, use the features.has() method on the adapter.

const adapter = await navigator.gpu?.requestAdapter();
// adapter.features is a Set
console.log(adapter.features.has('float32-filterable'));
console.log(adapter.features.has('shader-f16'));

For complex shaders, use a hybrid approach: implement heavy mathematical operations or noise algorithms in WGSL via wgslFn, and use TSL for high-level logic, texture sampling, and scene integration. This combines the performance of raw WGSL with the ease of use of TSL nodes.

// Complex math in WGSL
const complexMath = wgslFn(`
  fn complexOperation(a: vec3<f32>, b: vec3<f32>, t: f32) -> vec3<f32> {
    let blended = mix(a, b, t);
    let rotated = vec3<f32>(
      blended.x * cos(t) - blended.y * sin(t),
      blended.x * sin(t) + blended.y * cos(t),
      blended.z
    );
    return normalize(rotated);
  }
`);

// Simple logic in TSL
const finalColor = Fn(() => {
  const base = texture(diffuseMap).rgb;
  const processed = complexMath(base, vec3(1, 0, 0), time);
  return mix(base, processed, oscSine(time));
});

material.colorNode = finalColor();

When using this skill in Cursor, the .mdc rules are automatically attached to your files based on specific filename patterns (globs):

• webgpu-threejs-tsl.mdc: Entry point for JS/TS files.
• compute-shaders.mdc: Files matching *compute* or *particle*.
• post-processing.mdc: Files matching *post*, *effect*, or *bloom*.
• wgsl-integration.mdc: .wgsl files and files containing *wgsl* in the name.
• device-loss-and-limits.mdc: Files matching *renderer* or *webgpu*.

TSL uses a method-chaining syntax for mathematical and logical operations on nodes. This replaces traditional algebraic notation used in GLSL/WGSL.

// Instead of: sin(time * 2.0 + offset) * 0.5 + 0.5
time.mul(2.0).add(offset).sin().mul(0.5).add(0.5)

You can access and reorder vector components using swizzling, similar to GLSL. This allows you to extract specific components or create new vectors from existing ones.

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

Custom effects are created using the Fn function from three/tsl. You define a function that manipulates texture nodes or color values and then call that function to assign it to renderPipeline.outputNode. You can use utilities like screenUV, float, vec2, vec4, texture, and viewportSharedTexture within these functions.

import { Fn, screenUV, float, vec4 } from 'three/tsl';

const customEffect = Fn(() => {
  const color = scenePassColor.toVar();
  // Invert colors
  color.rgb.assign(float(1.0).sub(color.rgb));
  return color;
});

renderPipeline.outputNode = customEffect();

To ensure high performance in custom WGSL functions, follow these best practices:

1. Avoid Branching: Use mathematical functions like mix and step instead of if-else statements where possible to prevent execution divergence.

   • Instead of: if (x > 0.5) { result = a; } else { result = b; }
   • Use: result = mix(b, a, step(0.5, x));

2. Use Local Variables: Cache repeated calculations in let variables to avoid redundant computations.

   • Example: let p2 = p * p; let p4 = p2 * p2;

3. Minimize Texture Samples: Sample a texture once and reuse the result instead of calling textureSample multiple times for the same coordinate.

In recent versions (r183+), PostProcessing has been replaced by RenderPipeline. You create a pipeline, define passes (like a scene pass), and chain effects (like bloom) to the output node.

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();

When working with this skill, always use the specific WebGPU entry point for Three.js and the dedicated TSL module to ensure compatibility with the node-based shading system.

// Always use the WebGPU entry point
import * as THREE from 'three/webgpu';
import { /* TSL functions */ } from 'three/tsl';