Skip to main content
rule CX Codex

tsl-why-use — Claude Code rule: TSL instead of onBeforeCompile

tsl-why-use — a rule that pushes the coding agent to build custom Three.js materials from TSL nodes rather than patching shaders through onBeforeCompile.

MIT ★ 4,719 updated 2026-10-24

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

What tsl-why-use does

Custom Three.js materials are the target. The rule steers the agent away from onBeforeCompile, where you splice uniforms and shader chunks into fragmentShader by string replacement, and toward node materials built from three/tsl.

What shows up in practice: colour animation from sin(time) on colorNode, vertex displacement through positionNode, repeated formulas wrapped in Fn. Nodes compose, so a second texture just multiplies into the colour node you already have instead of hunting for the right #include token.

The examples import from three/tsl and construct MeshStandardNodeMaterial, so code written under this rule needs a Three.js build that ships node materials. On an older version it will not run. String-level shader patches break when Three.js updates, which is the reason to keep the rule in the repo.

What it helps with

  • replace an onBeforeCompile shader patch with a TSL node material
  • layer a detail texture onto a standard material without editing fragmentShader
  • animate a material colour from time with a sine
  • displace vertices along a sine wave in positionNode
  • wrap a repeated formula in Fn and reuse it

Example prompts for the agent

  • Rewrite this fragmentShader patch with nodes from three/tsl.
  • Add a detail texture to the material in TSL, keep onBeforeCompile out of it.
  • Animate the material colour with a sine of time on colorNode.

How to install tsl-why-use

Manually: put the files in place

.claude/rules/tsl-why-use.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-why-use

How do I install tsl-why-use in Claude Code?

Create the rule file at .claude/rules/tsl-why-use.md. The rule text comes from the zebbern/claude-code-guide repository.

What does tsl-why-use do?

It tells the agent to assemble custom Three.js materials from three/tsl nodes and MeshStandardNodeMaterial instead of replacing strings inside onBeforeCompile.

Why prefer TSL over onBeforeCompile?

TSL nodes run on WebGL and WebGPU, are typed, and combine with each other. String-replacement patches in fragmentShader break when Three.js updates and clash with other edits.

Source text

tsl-why-use.md · MIT
# tsl-why-use

**Use TSL instead of onBeforeCompile hacks for custom materials.**

## Why It Matters

TSL (Three.js Shading Language) is the modern approach to shader creation in Three.js:

- Works with both WebGL and WebGPU backends
- No string manipulation or onBeforeCompile hacks
- Type-safe, composable shader nodes
- Automatic optimization and tree shaking
- Easier to maintain and debug

## Bad Example

```javascript
// OLD - onBeforeCompile (fragile, hard to maintain)
const material = new THREE.MeshStandardMaterial();
material.map = colorMap;
material.onBeforeCompile = (shader) => {
  shader.uniforms.detailMap = { value: detailMap };

  let token = '#define STANDARD';
  let insert = `uniform sampler2D detailMap;`;
  shader.fragmentShader = shader.fragmentShader.replace(token, token + insert);

  token = '#include <map_fragment>';
  insert = `diffuseColor *= texture2D(detailMap, vMapUv * 10.0);`;
  shader.fragmentShader = shader.fragmentShader.replace(token, token + insert);
};
```

Problems:
- String manipulation is error-prone
- Breaks with Three.js updates
- Hard to combine multiple modifications
- No type safety
- Difficult to debug

## Good Example

```javascript
// NEW - TSL (clean, composable)
import { texture, uv } from 'three/tsl';

const detail = texture(detailMap, uv().mul(10));

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = texture(colorMap).mul(detail);
```

Benefits:
- Clean, readable code
- Composable nodes
- Works with WebGL and WebGPU
- Type-safe with TypeScript
- Automatic optimization

## More TSL Examples

### Animated Color

```javascript
import { color, time, sin } from 'three/tsl';

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(0x00ff00).mul(sin(time).mul(0.5).add(0.5));
```

### Vertex Displacement

```javascript
import { positionLocal, sin, time } from 'three/tsl';

const material = new THREE.MeshStandardNodeMaterial();
material.positionNode = positionLocal.add(
  sin(time.add(positionLocal.y)).mul(0.1)
);
```

### Custom Function

```javascript
import { Fn, vec3, float } from 'three/tsl';

const oscSine = Fn(([t = time]) => {
  return t.add(0.75).mul(Math.PI * 2).sin().mul(0.5).add(0.5);
});

material.colorNode = vec3(oscSine(), 0, 0);
```

## References

- [Three.js TSL Documentation](https://threejs.org/docs/#api/en/nodes/TSL)
- [TSL Examples](https://threejs.org/examples/?q=tsl)

© 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 →
security-reviewer security-reviewer audits code changes for reachable exploits and trust boundary violations without editing project files. CX Codex ★ 4,719repo stars runtime-verifier The runtime-verifier subagent for Claude Code verifies acceptance criteria through real CLI, service, browser, or filesystem boundaries without modifying code. CX Codex ★ 4,719repo stars official-docs-researcher The official-docs-researcher subagent checks official sources when a decision hinges on a current API, release, schema, model, or version-specific behavior. CX Codex ★ 4,719repo stars change-implementer change-implementer — a subagent that carries one pre-approved change through to the end: edits the code, runs it for real, and reports what it observed. CX Codex ★ 4,719repo stars asset-compression Guides your AI coding agent through 3D asset compression for Three.js. Covers Draco, Meshopt, KTX2 textures, and LOD implementation. CX Codex +1 ★ 4,719repo stars perf-never-set-state-in-useframe perf-never-set-state-in-useframe — a react-three-fiber rule that bans setState inside useFrame and pushes you to mutate a ref instead, so animation stops triggering a React render every frame. CX Codex +1 ★ 4,719repo stars frame-delta-time frame-delta-time — a rule that makes every animated movement multiply by delta, so speed stops depending on the display's refresh rate. CX Codex +1 ★ 4,719repo stars draw-call-optimization The draw-call-optimization rule for Claude Code guides Three.js optimization, reducing draw calls to below 100 per frame through instancing, batching, and geometry merging. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open