webgpu-threejs-tsl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WebGPU Three.js with TSL

TSL (Three.js Shading Language) is a node-based shader abstraction that lets you write GPU shaders in JavaScript instead of GLSL/WGSL strings.

TSL（Three.js Shading Language）是一种基于节点的着色器抽象层，让你可以用JavaScript而非GLSL/WGSL字符串编写GPU着色器。

Quick Start

快速开始

javascript

import * as THREE from 'three/webgpu';
import { color, time, oscSine } from 'three/tsl';

const renderer = new THREE.WebGPURenderer();
await renderer.init();

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(0xff0000).mul(oscSine(time));

javascript

import * as THREE from 'three/webgpu';
import { color, time, oscSine } from 'three/tsl';

const renderer = new THREE.WebGPURenderer();
await renderer.init();

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(0xff0000).mul(oscSine(time));

Skill Contents

技能内容

Documentation

文档

```
docs/core-concepts.md
```
- Types, operators, uniforms, control flow
```
docs/materials.md
```
- Node materials and all properties
```
docs/compute-shaders.md
```
- GPU compute with instanced arrays
```
docs/post-processing.md
```
- Built-in and custom effects
```
docs/wgsl-integration.md
```
- Custom WGSL functions
```
docs/device-loss.md
```
- Handling GPU device loss and recovery

```
docs/core-concepts.md
```
- 类型、运算符、Uniforms、控制流
```
docs/materials.md
```
- 节点材质及所有属性
```
docs/compute-shaders.md
```
- 结合实例化数组的GPU计算
```
docs/post-processing.md
```
- 内置与自定义效果
```
docs/wgsl-integration.md
```
- 自定义WGSL函数
```
docs/device-loss.md
```
- GPU设备丢失与恢复的处理

Examples

示例

```
examples/basic-setup.js
```
- Minimal WebGPU project
```
examples/custom-material.js
```
- Custom shader material
```
examples/particle-system.js
```
- GPU compute particles
```
examples/post-processing.js
```
- Effect pipeline
```
examples/earth-shader.js
```
- Complete Earth with atmosphere

```
examples/basic-setup.js
```
- 最简WebGPU项目
```
examples/custom-material.js
```
- 自定义着色器材质
```
examples/particle-system.js
```
- GPU计算粒子系统
```
examples/post-processing.js
```
- 效果管线
```
examples/earth-shader.js
```
- 带大气层的完整地球示例

Templates

模板

```
templates/webgpu-project.js
```
- Starter project template
```
templates/compute-shader.js
```
- Compute shader template

```
templates/webgpu-project.js
```
- 项目启动模板
```
templates/compute-shader.js
```
- 计算着色器模板

Reference

参考

```
REFERENCE.md
```
- Quick reference cheatsheet

```
REFERENCE.md
```
- 速查 cheat sheet

Key Concepts

核心概念

Import Pattern

导入模式

javascript

// Always use the WebGPU entry point
import * as THREE from 'three/webgpu';
import { /* TSL functions */ } from 'three/tsl';

javascript

// Always use the WebGPU entry point
import * as THREE from 'three/webgpu';
import { /* TSL functions */ } from 'three/tsl';

Node Materials

节点材质

Replace standard material properties with TSL nodes:

javascript

material.colorNode = texture(map);        // instead of material.map
material.roughnessNode = float(0.5);      // instead of material.roughness
material.positionNode = displaced;         // vertex displacement

用TSL节点替换标准材质属性：

javascript

material.colorNode = texture(map);        // instead of material.map
material.roughnessNode = float(0.5);      // instead of material.roughness
material.positionNode = displaced;         // vertex displacement

Method Chaining

方法链式调用

TSL uses method chaining for operations:

javascript

// Instead of: sin(time * 2.0 + offset) * 0.5 + 0.5
time.mul(2.0).add(offset).sin().mul(0.5).add(0.5)

TSL使用方法链式调用实现操作：

javascript

// Instead of: sin(time * 2.0 + offset) * 0.5 + 0.5
time.mul(2.0).add(offset).sin().mul(0.5).add(0.5)

Custom Functions

自定义函数

Use

Fn()

for reusable shader logic:

javascript

const fresnel = Fn(([power = 2.0]) => {
  const nDotV = normalWorld.dot(viewDir).saturate();
  return float(1.0).sub(nDotV).pow(power);
});

使用

Fn()

创建可复用的着色器逻辑：

javascript

const fresnel = Fn(([power = 2.0]) => {
  const nDotV = normalWorld.dot(viewDir).saturate();
  return float(1.0).sub(nDotV).pow(power);
});

When to Use This Skill

何时使用本技能

Setting up Three.js with WebGPU renderer
Creating custom shader materials with TSL
Writing GPU compute shaders
Building post-processing pipelines
Migrating from GLSL to TSL
Implementing visual effects (particles, water, terrain, etc.)

搭建基于WebGPU渲染器的Three.js项目
使用TSL创建自定义着色器材质
编写GPU计算着色器
构建后期处理管线
从GLSL迁移至TSL
实现视觉效果（粒子、水体、地形等）

Resources

资源

Three.js TSL Wiki
WebGPU Examples (files prefixed with
```
webgpu_
```
)

Three.js TSL Wiki - Three.js TSL 维基
WebGPU Examples（文件以
```
webgpu_
```
为前缀）