writing-tsl-and-passes
Writes or changes TSL shaders, compute kernels, render passes and GPU buffers on three.js's WebGPURenderer without the failures that give no error, such as a shader that draws nothing, a helper emitted with another shader's uniform names, derivatives taken in a branch, a stage over WebGPU's limits, a pass whose input was discarded, a draw skipped while its pipeline compiles, or a few pixels that change between equivalent builds. Before writing, reads the project's page of three.js behaviour for what the change touches; builds the shaders to WGSL in Node.js to see what three.js generated; runs the renderer's small test scenes before the full scene; then runs the checks that detect each silent failure. Use with three.js WebGPURenderer (three/webgpu, three/tsl) whenever TSL, a node material, a compute kernel, a render pass, a render target or a GPU buffer is written or changed.
HuberyLL · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add HuberyLL/ponlai --skill writing-tsl-and-passes技能说明
name: writing-tsl-and-passes description: Writes or changes TSL shaders, compute kernels, render passes and GPU buffers on three.js's WebGPURenderer without the failures that give no error, such as a shader that draws nothing, a helper emitted with another shader's uniform names, derivatives taken in a branch, a stage over WebGPU's limits, a pass whose input was discarded, a draw skipped while its pipeline compiles, or a few pixels that change between equivalent builds. Before writing, reads the project's page of three.js behaviour for what the change touches; builds the shaders to WGSL in Node.js to see what three.js generated; runs the renderer's small test scenes before the full scene; then runs the checks that detect each silent failure. Use with three.js WebGPURenderer (three/webgpu, three/tsl) whenever TSL, a node material, a compute kernel, a render pass, a render target or a GPU buffer is written or changed.
Writing TSL and passes
Most of what goes wrong in TSL and WebGPU passes gives no error: the console stays clean and the frame is wrong, or it is right today and wrong after an unrelated edit. This skill is the working method around the project's page of three.js behaviour: read the entries for what you touch, look at the code three.js generated, test on small scenes, run the checks that detect silent failures, and record what you find.
Rules most often broken without notice
- Read the behaviour page's entries for each thing the change touches before you write a line (step 1). Most of them fail without an error.
- No error is not success. A shader that builds can draw nothing, read undefined derivatives or be skipped. Judge a change by the WGSL that three.js generated and by what the frame shows.
- The behaviour is version-bound. Entries were written against one three.js release; on another, treat every version-marked entry as unverified until its check has run (step 2).
- Take derivatives and implicitly filtered samples (
dFdx,fwidth,texture()without a level) only in uniform control flow: take them before anyIf,Looporselect(), and inside a branch, sample with an explicit level. WGSL makes this an error by default (derivative_uniformity), but three.js's WGSL builder turns that diagnostic off at r186. A wrong one therefore compiles, and its pixels change with unrelated edits. - A helper used by several shaders takes the uniforms it reads as arguments. A laid-out
Fnthat reads a uniform in its body can be emitted with the first build's uniform names, and the second shader fails to compile only where both are built. - Add new per-frame GPU work as a pass of the renderer's frame graph, with every read declared. Never add it as a render-to-texture call inside a material or a render call outside the graph. The attachment load and store operations can discard an undeclared read.
- A pass or kernel that keeps state across frames (a history, an accumulation, a bake drawn once) follows the project's rules for the test mode and scene jumps (step 3).
- Never start a GPU tool to see its options: read its header. A GPU run goes through the project's GPU rules (binding: Checks).
The project's facts: the binding
Steps marked "(binding: X)" need facts about the project: where its behaviour page is and which of
its entries go with which kind of work, the pinned three.js version, how to build WGSL in Node.js,
its test scenes, its checks and where a new finding is written. Read section X of
docs/bindings/writing-tsl-and-passes.md when you reach the step. If the project's AGENTS.md or
CLAUDE.md names another file for this skill, that file wins.
No binding: find each fact in the project (a docs page on three.js or WebGPU pitfalls, the shader
rules in AGENTS.md, the tools folder, the three.js version in package.json) and ask the user for
what you cannot find. If the project keeps no behaviour page, start one with the first silent
failure you meet (step 7). When the work ends, offer to write what you found as the binding, one
section per step.
Workflow
Copy this checklist and keep it up to date:
- [ ] 1. Name what the change touches and read first
- [ ] 2. Check the three.js version
- [ ] 3. Write it in the forms that do not fail silently
- [ ] 4. Build to WGSL and read what three.js generated
- [ ] 5. Small test scenes first
- [ ] 6. The checks that see silent failures
- [ ] 7. Record what you found
1. Name what the change touches and read first (binding: Read first)
- List what the change touches: TSL nodes in a material, a shared helper
Fn, a varying, multiple render targets (MRT), a compute kernel, a full-screen pass, a render target or depth texture, a history, a storage buffer, instancing, an index or attribute buffer, raw WebGPU calls, timestamp queries. - For each, read its entries on the behaviour page (the binding maps each kind to its sections), and the header comment of each module you change.
- Read how the renderer takes new work (the project's guide for adding a pass, a plant kind or a light): what each must declare.
2. Check the three.js version (binding: Version)
- Compare the installed three.js (
node_modules/three/package.json) with the version the behaviour page names. If they match, go on. - If they differ, every entry marked with the old version is unverified. Run each entry's check
before you rely on it, and follow the project's upgrade guide; the three.js migration guide lists
the breaking changes per release (
X → Y).
3. Write it in the forms that do not fail silently (binding: Write)
The behaviour page gives each form and the reason for it. These are the ones you meet most often:
- Write TSL's
mix,stepandsmoothstepin the function form: the method forms take the receiver out of order (t.mix( a, b )ismix( a, b, t )). - Make
select()pick between values built before it (.toVar()inside the sameFn). A node