tsl-why-use — правило для Claude Code: TSL вместо onBeforeCompile
Правило tsl-why-use для Claude Code и Codex: кастомные материалы в Three.js собираются из нод TSL, а не через патч onBeforeCompile. Применяется в проектах со своими шейдерами.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/tsl-why-use.mdЧто делает tsl-why-use
Правило задаёт, как агент пишет кастомные материалы в Three.js. Вместо onBeforeCompile — где униформы и куски шейдера вставляются в fragmentShader заменой строк — он собирает материал из нод three/tsl.
Что это даёт на практике: анимация цвета через sin(time) в colorNode, смещение вершин в positionNode, повторяющаяся формула в Fn. Ноды складываются друг с другом, поэтому вторая текстура просто умножается на готовый colorNode, без поиска нужного токена #include.
Примеры импортируют three/tsl и создают MeshStandardNodeMaterial, так что код по этому правилу требует сборки Three.js с нодовыми материалами. На старой версии он не запустится. Патчи на замене строк ломаются при обновлении Three.js, и это как раз причина держать правило в проекте.
Какие задачи решает
- переписать кастомный материал на ноды TSL вместо патча
fragmentShader - добавить вторую текстуру в стандартный материал без правки шейдера
- сделать анимацию цвета материала синусоидой по времени
- сместить вершины геометрии в
positionNode - вынести повторяющуюся формулу в
Fnи переиспользовать её
Примеры запросов агенту
- Добавь в материал текстуру детализации через TSL, без
onBeforeCompile. - Сделай анимацию цвета материала синусоидой по времени на
colorNode. - Перепиши этот патч
fragmentShaderна ноды изthree/tsl.
Как установить tsl-why-use
Вручную: положить файлы
.claude/rules/tsl-why-use.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/tsl-why-use.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/tsl-why-use.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/tsl-why-use.mdВручную: положить файлы
.clinerules/tsl-why-use.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о tsl-why-use
Как установить tsl-why-use в Claude Code?
Положите файл правила по пути .claude/rules/tsl-why-use.md. Текст берётся из репозитория zebbern/claude-code-guide.
Что делает tsl-why-use?
Направляет агента: кастомные материалы Three.js собираются из нод three/tsl и MeshStandardNodeMaterial, а не через замену строк в onBeforeCompile.
Чем TSL отличается от onBeforeCompile?
Ноды TSL работают и в WebGL, и в WebGPU, типизированы и складываются друг с другом. Патч через замену строк в fragmentShader ломается при обновлении Three.js и плохо сочетается с другими правками.
Исходный текст
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