Skip to main content
rule CX Codex

tsl-complete-reference — Claude Code rule: Three.js TSL guide

The tsl-complete-reference rule for Claude Code provides a TSL reference for writing node shaders without invalid syntax.

MIT ★ 4,719 updated 2026-10-24

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

What tsl-complete-reference does

This rule supplies coding assistants with modern Three.js Shading Language (TSL) patterns. It provides clear code templates for moving away from raw GLSL strings toward JavaScript node-based shaders.

The file outlines scalar, vector, and matrix conversions alongside uniforms that trigger on render or frame events. It covers custom procedural functions created via Fn(), branching with select or capitalized If, and loops structured through Loop(). Reference tables also catalog geometry positions, normal vectors, camera matrices, and texture helpers like triplanarTexture.

Notice that conditional statements inside functions require capitalized If, as lowercase syntax will fail at runtime.

What it helps with

  • write node materials using the three/tsl module
  • bind uniform updates to object or frame lifecycles
  • assemble shader procedures with Fn()
  • implement coordinate transforms using built-in position nodes

Example prompts for the agent

  • Create a pulsing color shader using Fn and time in TSL
  • Set up a billboarded vertex node with horizontal rotation only
  • Write an array uniform with colors for dynamic indexing

How to install tsl-complete-reference

Manually: put the files in place

.claude/rules/tsl-complete-reference.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-complete-reference

How to install tsl-complete-reference in Claude Code?

Add the rule file to your repository at .claude/rules/tsl-complete-reference.md. Claude Code reads rules located in this folder automatically.

What does tsl-complete-reference do?

It guides the assistant through Three.js Shading Language conventions, covering built-in nodes, function syntax, conditionals, and texture functions.

Why does TSL use a capitalized If statement?

In TSL, If is a node-building function imported from three/tsl, so standard JavaScript if cannot be used inside Fn() blocks.

Source text

tsl-complete-reference.md · MIT
# TSL Complete Reference

Comprehensive reference for Three.js Shading Language (TSL) - the modern way to create shaders in Three.js.

## Type System

```javascript
// Scalar conversions
float(), int(), uint(), bool()

// Vector conversions
color(), vec2(), vec3(), vec4()

// Matrix conversions
mat2(), mat3(), mat4()

// Method-based conversion
positionWorld.toVec2()      // Access xy components
value.toFloat()             // Explicit conversion
value.toColor()             // Convert to color
```

## Uniforms with Update Events

```javascript
import { uniform } from 'three/tsl';

const myColor = uniform(new THREE.Color(0x0066FF));
material.colorNode = myColor;

// Update events
const posY = uniform(0);
posY.onObjectUpdate(({ object }) => object.position.y);  // Per object
posY.onRenderUpdate(() => value);                         // Per render pass
posY.onFrameUpdate(() => value);                          // Per frame
```

## Functions with Fn()

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

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

// Named parameters
const customColor = Fn(({ r, g, b }) => {
  return vec3(r, g, b);
});

material.colorNode = customColor({ r: 1, g: 0, b: 0 });
```

## Conditionals

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

// Ternary (inline) - GOOD for simple cases
const result = select(value.greaterThan(1), 1.0, value);

// If-Else (inside Fn) - NOTE: If with capital I
const limitedPosition = Fn(({ position }) => {
  const limit = 10;
  const result = vec3(position);

  If(result.y.greaterThan(limit), () => {
    result.y.assign(limit);
  });

  return result;
});

// Switch-Case
const col = color();
Switch(0)
  .Case(0, () => col.assign(color(1, 0, 0)))
  .Case(1, () => col.assign(color(0, 1, 0)))
  .Default(() => col.assign(color(1, 1, 1)));
```

## Loops

```javascript
// Basic loop
Loop(count, ({ i }) => {
  // Loop body
});

// Advanced configuration
Loop({ start: int(0), end: int(10), type: 'int', condition: '<' },
  ({ i }) => {}
);

// Nested loops
Loop(10, 5, ({ i, j }) => {});

// Boolean condition loop
const value = float(0);
Loop(value.lessThan(10), () => {
  value.addAssign(1);
});

// Flow control
Break();     // Exit loop
Continue();  // Next iteration
```

## Arrays

```javascript
// Creation
const colors = array([vec3(1, 0, 0), vec3(0, 1, 0)]);
const a = array('vec3', 2);                    // Fixed size
const a = vec3(0, 0, 1).toArray(2);           // Fill with value
const a = array([0, 1, 2], 'uint');           // Explicit type

// Access
const greenColor = colors.element(1);          // Dynamic index
const first = colors[0];                       // Constant index

// Uniform arrays
const tintColors = uniformArray(
  [new Color(1, 0, 0), new Color(0, 1, 0)],
  'color'
);
```

## Position Nodes

| Node | Description | Type |
|------|-------------|------|
| `positionGeometry` | Raw geometry position | `vec3` |
| `positionLocal` | Local transformed (post-skinning) | `vec3` |
| `positionWorld` | World space position | `vec3` |
| `positionWorldDirection` | Normalized world direction | `vec3` |
| `positionView` | View space position | `vec3` |
| `positionViewDirection` | Normalized view direction | `vec3` |

## Normal Nodes

| Node | Type |
|------|------|
| `normalGeometry` | `vec3` |
| `normalLocal` | `vec3` |
| `normalView` | `vec3` normalized |
| `normalWorld` | `vec3` normalized |
| `normalViewGeometry` | `vec3` |
| `normalWorldGeometry` | `vec3` |

## Camera Data

| Variable | Type |
|----------|------|
| `cameraNear`, `cameraFar` | `float` |
| `cameraProjectionMatrix`, `cameraViewMatrix`, `cameraWorldMatrix` | `mat4` |
| `cameraProjectionMatrixInverse` | `mat4` |
| `cameraNormalMatrix` | `mat3` |
| `cameraPosition` | `vec3` |

## Screen & Viewport

```javascript
// Screen (frame buffer in physical pixels)
screenUV           // Normalized coordinate (0-1)
screenCoordinate   // Physical pixels
screenSize         // Dimensions in physical pixels
screenDPR          // Device pixel ratio

// Viewport (from renderer.setViewport())
viewportUV         // Normalized coordinate
viewport           // vec4 dimensions
viewportCoordinate // Physical pixel coordinate
viewportSize       // Dimensions
viewportSharedTexture()   // Previously rendered content
viewportDepthTexture()    // Depth access
viewportLinearDepth       // Orthographic depth
```

## Texture Operations

```javascript
texture(texture, uv, level)          // vec4 with interpolation
textureLoad(texture, uv, level)      // vec4 without interpolation
textureStore(texture, uv, value)     // void
textureSize(texture, level)          // ivec2
textureBicubic(node, strength)       // vec4 bicubic filtering
cubeTexture(texture, uvw)            // vec4 from cube map
texture3D(texture, uvw)              // vec4 from 3D texture
triplanarTexture(texX, texY, texZ, scale, pos, normal)  // Triplanar mapping
```

## UV Utilities

```javascript
matcapUV                                    // vec2 for matcap
rotateUV(uv, rotation, center)             // vec2 rotated
spherizeUV(uv, strength, center)           // vec2 spherical distortion
spritesheetUV(count, uv, frame)            // vec2 for sprite animation
equirectUV(direction)                       // vec2 for equirectangular mapping
```

## Color Adjustments

```javascript
luminance(node)                  // Perceived brightness (float)
saturation(node, adjustment)     // Adjust saturation (color)
vibrance(node, adjustment)       // Enhance less saturated colors (color)
hue(node, adjustment)            // Rotate hue in radians (color)
posterize(node, steps)           // Reduce color levels (color)

material.colorNode = saturation(texture(map), 1.5);
material.colorNode = hue(texture(map), Math.PI / 2);
```

## Fog

```javascript
fog(color, factor)
rangeFogFactor(near, far)      // Linear fog
densityFogFactor(density)      // Exponential squared fog

scene.fogNode = fog(color(0x000000), rangeFogFactor(10, 100));
```

## Flow Control

```javascript
Discard()   // Discard current fragment
Return()    // Return from function
Break()     // Exit loop
Continue()  // Next iteration

const customFragment = Fn(() => {
  If(uv().x.lessThan(0.5), () => {
    Discard();
  });
  return vec4(1, 0, 0, 1);
});
```

## Utilities

```javascript
billboarding({ position, horizontal, vertical })  // Face camera
checker(coord)                                     // Checker pattern

// Full billboarding
material.vertexNode = billboarding();

// Horizontal only (for trees)
material.vertexNode = billboarding({ horizontal: true, vertical: false });
```

## Structs

```javascript
const BoundingBox = struct({ min: 'vec3', max: 'vec3' });

// Create instance
const bb = BoundingBox(vec3(0), vec3(1));
const bb2 = BoundingBox({ min: vec3(0), max: vec3(1) });

// Access members
const min = bb.get('min');
min.assign(vec3(-1));
```

## References

- [Three.js Wiki - TSL](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language)
- [Maxime Heckel's Field Guide to TSL](https://blog.maximeheckel.com/posts/field-guide-to-tsl-and-webgpu/)
- [sbcode.net TSL Tutorials](https://sbcode.net/tsl/getting-started/)

© 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 →
mobile-optimization mobile-optimization is a rule for accelerating Three.js scenes on smartphones and tablets. It reduces GPU load and memory use, helping maintain a stable frame rate. CX Codex +1 ★ 4,719repo stars webxr-setup The webxr-setup rule for Claude Code guides building VR and AR scenes in Three.js WebXR. It helps coding agents set up render loops, controllers, and hit-testing. CX Codex +1 ★ 4,719repo stars error-handling-recovery The error-handling-recovery rule covers WebGL context loss, resource rebuilding, and fallback UI. Use it when a Three.js scene must recover from graphics failures. CX Codex +1 ★ 4,719repo stars vc-industry-research vc-industry-research turns a prompt into a PE/VC-style industry report: sector deep-dive, investment memo or market analysis, in Chinese or English, PDF by default. CX Codex +1 ★ 4,719repo stars test-suite-architect test-suite-architect sets up QA infrastructure based on Google Testing Standards and OWASP: AAA test case templates, P0-P4 bug tracking, quality gate checks, and LLM test execution. CX Codex +1 ★ 4,719repo stars ssh-penetration-testing ssh-penetration-testing guides SSH service assessments, from configuration checks to credential testing and port forwarding. Use it to plan an authorized SSH security review. CX Codex +1 ★ 4,719repo stars tos-clause-scanner tos-clause-scanner takes a terms-of-service document or privacy policy and returns a structured audit: unfair clauses, hidden data permissions, auto-renewal traps. CX Codex +1 ★ 4,719repo stars xss-html-injection xss-html-injection guides web application assessments for stored, reflected, and DOM-based XSS, as well as HTML injection flaws. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open