Skip to main content
rule CX Codex

tsl-compute-shaders — Claude Code rule: what it does, how to install

tsl-compute-shaders guides the agent in writing WebGPU compute shaders with Three.js TSL for GPGPU tasks like particle systems and physics.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/tsl-compute-shaders.md
Open on GitHub

What tsl-compute-shaders does

This rule supplies conventions and reference patterns for Three.js Shading Language (TSL) compute shaders running on WebGPU. It guides the model on creating storage buffers with instancedArray, reading variables like instanceIndex or deltaTime, and dispatching calculations with renderer.compute().

The reference lists atomic functions such as atomicAdd and atomicStore, along with memory barriers like workgroupBarrier and storageBarrier. It also contains an explicit particle physics simulation with gravity and floor damping, contrasting compute shader performance with WebGL textures.

Simulations will fail on clients lacking WebGPU support unless an explicit WebGL fallback is configured. The instructions advise sizing workgroups in multiples of 64 to keep GPU hardware occupied.

What it helps with

  • Offload particle physics calculations from CPU to WebGPU using TSL
  • Coordinate memory access across threads with workgroup and storage barriers
  • Execute atomic operations on WebGPU storage buffers
  • Build a WebGL ping-pong render target fallback

Example prompts for the agent

  • Write a TSL compute shader to animate 100000 bouncing particles with gravity
  • Add an atomic counter update to our WebGPU compute pass using Three.js TSL
  • Create a WebGL fallback for this GPGPU simulation using ping-pong render targets

How to install tsl-compute-shaders

Manually: put the files in place

.claude/rules/tsl-compute-shaders.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about tsl-compute-shaders

How to install tsl-compute-shaders in Claude Code?

Add the rule file to .claude/rules/tsl-compute-shaders.md in your project root. Claude Code will pick up the shader instructions automatically.

What does the tsl-compute-shaders rule do?

It equips the coding agent with Three.js TSL syntax patterns, atomic functions, barrier commands, and sample code for WebGPU compute passes.

Does this rule cover browsers without WebGPU support?

Yes, it contains a fallback pattern that uses THREE.DataTexture, a custom THREE.ShaderMaterial, and alternating ping-pong render targets.

Source text

tsl-compute-shaders.md · MIT
# TSL Compute Shaders

GPU compute shaders using TSL for WebGPU - enables GPGPU operations like particle systems, physics, and simulations.

## Basic Compute Shader

```javascript
import { Fn, instancedArray, instanceIndex, deltaTime } from 'three/tsl';

const COUNT = 1000000; // 1 million particles

// Storage buffers
const positionBuffer = instancedArray(COUNT, 'vec3');
const velocityBuffer = instancedArray(COUNT, 'vec3');

// Define compute shader
const computeParticles = Fn(() => {
  const position = positionBuffer.element(instanceIndex);
  const velocity = velocityBuffer.element(instanceIndex);

  position.addAssign(velocity.mul(deltaTime));
})().compute(COUNT);

// Execute in render loop
renderer.compute(computeParticles);
```

## Atomic Operations

```javascript
// Available atomic functions
atomicAdd(buffer, value)
atomicSub(buffer, value)
atomicMax(buffer, value)
atomicMin(buffer, value)
atomicAnd(buffer, value)
atomicOr(buffer, value)
atomicXor(buffer, value)
atomicStore(buffer, value)
atomicLoad(buffer)
```

## Barriers

```javascript
// Synchronization barriers
workgroupBarrier()   // Sync within workgroup
storageBarrier()     // Sync storage buffer access
textureBarrier()     // Sync texture access
barrier()            // Full barrier
```

## Compute Variables

| Variable | Description |
|----------|-------------|
| `workgroupId` | ID of current workgroup |
| `localId` | Local invocation ID |
| `globalId` | Global invocation ID |
| `numWorkgroups` | Total number of workgroups |
| `subgroupSize` | Size of subgroup |

## Particle System Example

```javascript
import {
  Fn, instancedArray, instanceIndex, deltaTime,
  If, float, vec3
} from 'three/tsl';

const COUNT = 100000;

const positionBuffer = instancedArray(COUNT, 'vec3');
const velocityBuffer = instancedArray(COUNT, 'vec3');

// Initialize positions
for (let i = 0; i < COUNT; i++) {
  positionBuffer.array[i * 3 + 0] = (Math.random() - 0.5) * 100;
  positionBuffer.array[i * 3 + 1] = Math.random() * 100;
  positionBuffer.array[i * 3 + 2] = (Math.random() - 0.5) * 100;

  velocityBuffer.array[i * 3 + 0] = 0;
  velocityBuffer.array[i * 3 + 1] = -9.81; // Gravity
  velocityBuffer.array[i * 3 + 2] = 0;
}

// Compute shader with physics
const computeParticles = Fn(() => {
  const position = positionBuffer.element(instanceIndex);
  const velocity = velocityBuffer.element(instanceIndex);

  // Apply velocity
  position.addAssign(velocity.mul(deltaTime));

  // Bounce off ground
  If(position.y.lessThan(0), () => {
    velocity.y.assign(velocity.y.negate().mul(0.8)); // Damping
    position.y.assign(0);
  });
})().compute(COUNT);

// In render loop
function animate() {
  renderer.compute(computeParticles);
  renderer.render(scene, camera);
}
```

## GPGPU with Render Targets (WebGL Fallback)

For WebGL without compute shaders:

```javascript
// Create position texture
const size = 256; // 256x256 = 65536 particles
const data = new Float32Array(size * size * 4);
for (let i = 0; i < size * size; i++) {
  data[i * 4 + 0] = Math.random() * 100 - 50; // x
  data[i * 4 + 1] = Math.random() * 100 - 50; // y
  data[i * 4 + 2] = Math.random() * 100 - 50; // z
  data[i * 4 + 3] = 1; // w
}

const positionTexture = new THREE.DataTexture(
  data, size, size,
  THREE.RGBAFormat, THREE.FloatType
);
positionTexture.needsUpdate = true;

// Ping-pong render targets
const rtA = new THREE.WebGLRenderTarget(size, size, {
  type: THREE.FloatType,
  format: THREE.RGBAFormat
});
const rtB = rtA.clone();

// Update shader
const updateMaterial = new THREE.ShaderMaterial({
  uniforms: {
    positions: { value: positionTexture },
    time: { value: 0 }
  },
  fragmentShader: `
    uniform sampler2D positions;
    uniform float time;
    varying vec2 vUv;

    void main() {
      vec4 pos = texture2D(positions, vUv);
      pos.y += sin(time + pos.x * 0.1) * 0.01;
      gl_FragColor = pos;
    }
  `
});
```

## Performance Comparison

| Method | Particles at 60fps |
|--------|-------------------|
| CPU | ~50,000 |
| GPGPU (WebGL) | ~500,000 |
| Compute Shaders (WebGPU) | 1,000,000+ (<1ms update) |

## Best Practices

1. **Workgroup Size**: Use multiples of 64 for optimal GPU utilization

2. **Memory Access**: Coalesce memory access patterns when possible

3. **Barriers**: Only use barriers when synchronization is necessary

4. **Buffer Types**: Use appropriate buffer types for your data

5. **Fallback**: Provide WebGL fallback for browsers without WebGPU support

## References

- [Three.js WebGPU Compute Examples](https://threejs.org/examples/?q=compute)
- [WebGPU Compute Shaders Spec](https://www.w3.org/TR/webgpu/#compute-pass-encoder)

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
migration-checklist migration-checklist teaches the agent how to migrate code when Three.js updates. Lists breaking changes from r125 onwards and current import paths. CX Codex +1 ★ 4,719repo stars audio-spatial The audio-spatial rule for Claude Code provides Three.js 3D audio patterns for source positioning, distance falloff, and response to user interaction. CX Codex +1 ★ 4,719repo stars debug-devtools The debug-devtools rule guides an agent through adding diagnostics for Three.js performance, scene parameters, and WebGL context loss. Use it when tracking down a rendering bottleneck or inspecting a scene. CX Codex +1 ★ 4,719repo stars tsl-post-processing A reference rule for TSL post-processing in Three.js: chain effects onto postProcessing.outputNode instead of stacking EffectComposer passes. CX Codex +1 ★ 4,719repo stars animation-system animation-system — a practical guide to Three.js animation, from playing and blending clips to morph targets and bones. Useful when building scenes with animated models. CX Codex +1 ★ 4,719repo stars gltf-loading-optimization gltf-loading-optimization is a Claude Code rule with Three.js snippets and commands for glTF loading, decoder setup, progress reporting, lazy loading and model compression. CX Codex +1 ★ 4,719repo stars physics-integration physics-integration guides Three.js integration with Rapier and Cannon-es: Vite setup, collider primitives, and mesh synchronization patterns. CX Codex +1 ★ 4,719repo stars raycasting-optimization The raycasting-optimization rule covers ways to reduce Three.js raycasting work, from filtering objects by layer to using BVH or GPU picking. Useful when a scene has complex meshes or frequent pointer checks. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open