<!-- Three.js WebGPU 程序化木材材质演示
🎯 总体功能
这是一个基于 Three.js + WebGPU 的 程序化木材材质生成器，通过纯着色器代码动态生成逼真的多种木材纹理。程序展示了不同木材种类（橡木、枫木等）与不同表面处理（抛光、哑光等）的组合效果，并提供了一个可实时调节参数的自定义木材编辑器。

📊 核心功能模块
1. 网格化展示系统
2D网格布局：X轴展示不同木材种类，Y轴展示不同表面处理

预设材质库：展示多种预设的木材材质组合

标签系统：自动为每行每列生成文本标签

2. 程序化木材生成
参数化控制：通过20+个参数控制木材纹理

多层级细节：大尺度纹理、年轮、细胞结构、斑点瑕疵

实时更新：所有参数可实时调节并立即看到效果

3. 交互与调试
轨道控制器：鼠标拖拽、滚轮缩放查看场景

GUI调试面板：实时调节自定义木材的所有参数

响应式布局：自适应窗口大小变化

4. 视觉效果
HDR环境照明：使用高质量环境贴图提供真实光照

网格背景：纯着色器生成的无限分辨率网格

清漆效果：模拟不同表面处理的光泽度

🔧 主要技术点
1. WebGPU渲染引擎
javascript
// 使用下一代图形API WebGPU
renderer = new THREE.WebGPURenderer({ antialias: true });
优势：相比WebGL有更好的性能和多线程支持

兼容性：自动检测浏览器支持，降级处理

2. Three.js着色器语言(TSL)
javascript
// 使用节点式着色器编程
const gridPattern = gridXZ(1.0, 0.03, 0.005);
声明式编程：类似Shader节点编辑器

自动优化：Three.js负责着色器编译优化

抗锯齿：使用fwidth()函数实现屏幕空间抗锯齿

3. 程序化纹理生成
木材纹理算法
多重噪声叠加：大尺度、中尺度、精细尺度三级扭曲

年轮生成：基于距离场的同心圆 + 随机变化

细胞结构：Voronoi噪声模拟木材微观结构

颜色渐变：深色/浅色纹理的智能混合

着色器函数示例
javascript
// 网格背景的着色器函数
const gridXZ = TSL.Fn(([gridSize, dotWidth, lineWidth]) => {
    const coord = TSL.positionWorld.xz.div(gridSize);
    const grid = TSL.fract(coord); // 创建重复网格
    // ... 抗锯齿处理
});
4. 性能优化技术
几何体共享
javascript
// 所有木块使用同一个几何体实例
blockGeometry = new RoundedBoxGeometry(0.125, 0.9, 0.9, 10, 0.02);
异步加载策略
javascript
// 分批创建对象，避免卡顿
await new Promise(resolve => setTimeout(resolve, 0));
智能渲染设置
javascript
renderer.setPixelRatio(1.0); // 固定像素比确保性能
5. 现代JavaScript特性
ES6模块：import/export语法

异步/等待：async/await处理资源加载

导入映射：importmap标准实现模块别名

6. 3D图形学技术
相机与投影
javascript
// 透视相机模拟人眼视角
camera = new THREE.PerspectiveCamera(75, aspect, 0.1, 1000);
环境光照
javascript
// HDR环境贴图提供全局照明
scene.environment = texture;
scene.environmentIntensity = 2;
材质系统
javascript
// 基于物理的渲染(PBR)材质
const customMaterial = new WoodNodeMaterial({
    clearcoat: 1,                  // 清漆层
    clearcoatRoughness: 0.2        // 粗糙度控制
});
7. 木材材质的具体实现技术
纹理扭曲系统
text
大尺度扭曲 (0.32)    → 整体纹理走向
中尺度扭曲 (2.0)     → 区域不规则性  
精细扭曲 (32.8)      → 表面细节
年轮生成算法
javascript
ringThickness: 1/34,        // 年轮厚度（每年生长厚度）
ringBias: 0.03,             // 非同心偏移
ringSizeVariance: 0.03,     // 年轮厚度变化
细胞结构模拟
javascript
cellScale: 910,             // 细胞密度
cellSize: 0.1,              // 细胞大小
8. UI/UX设计
布局算法
javascript
// 自动居中网格布局
y: (finishIndex - Finishes.length / 2) * 1.0
交互反馈
实时参数调节即时反馈

平滑的相机控制

视觉层次分明的界面设计

📈 技术架构特点
模块化设计
text
src/
├── 核心Three.js组件
├── 着色器模块(TSL)
├── 材质系统
├── 几何体系统
└── UI控制系统
可扩展性
易于添加新的木材种类

可扩展的表面处理类型

模块化的参数系统

跨平台兼容
自动检测WebGPU支持

响应式设计适应不同屏幕

渐进式加载策略

🎨 视觉效果技术
1. 色调映射
javascript
renderer.toneMapping = THREE.NeutralToneMapping;
renderer.toneMappingExposure = 1.0;
2. 抗锯齿策略
几何边缘抗锯齿

着色器内置抗锯齿(fwidth)

屏幕空间抗锯齿(SSAA)

3. 透明度处理
javascript
material.transparent = true;
plane.renderOrder = -1; // 渲染顺序控制
🔍 调试与开发工具
内置检查器
javascript
renderer.inspector = new Inspector();
gui = renderer.inspector.createParameters('参数设置');
实时预览
所有参数实时更新

即时着色器重编译

无刷新页面更新

🚀 性能特点
GPU优化
最小化CPU到GPU的数据传输

着色器常量优化

批量渲染处理

内存管理
几何体实例化共享

纹理资源复用

按需加载策略 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<!-- 页面标题：Three.js WebGPU - 程序化木材材质演示 -->
		<title>Three.js WebGPU - 程序化木材材质演示</title>
		<!-- 
			视口配置：
			- width=device-width: 宽度等于设备宽度
			- user-scalable=no: 禁止用户手动缩放页面
			- minimum-scale=1.0, maximum-scale=1.0: 固定缩放比例为1倍
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 作者信息 -->
		<meta name="author" content="Logan Seeley"/>
		<!-- 引入外部CSS样式表，用于页面基本样式 -->
		<link type="text/css" rel="stylesheet" href="example.css">
		<!-- 
			内联CSS样式：
			设置body元素的字体颜色为深灰色
			rgb(55, 55, 55) 相当于 #373737
		-->
		<style>
			body {
				color: rgb(55, 55, 55);
			}
		</style>
	</head>
	<body>
		<!-- 
			页面信息区域：
			- id="info": 用于CSS和JavaScript选择器识别
			- class="invert": 反转样式类，可能用于深色/浅色主题切换
		-->
		<div id="info" class="invert">
			<!-- 
				Three.js Logo链接：
				- href: 指向Three.js官方网站
				- target="_blank": 在新标签页打开链接
				- rel="noopener": 安全属性，防止新页面访问window.opener
				- class="logo-link": 样式类，可能包含Logo背景图像
			-->
			<a href="https://threejs.org/" target="_blank" rel="noopener" class="logo-link"></a>

			<!-- 标题包装器，包含主标题和副标题 -->
			<div class="title-wrapper">
				<!-- Three.js主标题链接 -->
				<a href="https://threejs.org/" target="_blank" rel="noopener">Three.js</a>
				<!-- 页面副标题：程序化木材材质 -->
				<span>程序化木材材质</span>
			</div>

			<!-- 
				作者和参考信息：
				- <small>: 小号字体标签
				- By Logan Seeley: 原始作者
				- based on...: 基于Lance Phan的Blender教程
			-->
			<small>
				作者：Logan Seeley，基于 <a href="https://www.youtube.com/watch?v=n7e0vxgBS8A">Lance Phan的Blender教程</a>实现
			</small>
		</div>

		<!-- 
			ImportMap配置：
			现代浏览器中的模块导入映射系统，允许定义模块别名和路径
			type="importmap": 声明这是一个importmap脚本
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.webgpu.js",
					"three/webgpu": "../build/three.webgpu.js",
					"three/tsl": "../build/three.tsl.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module": 声明这是一个ES6模块，支持import/export语法
			模块中的代码具有自己的作用域，不会污染全局
		-->
		<script type="module">
			// ==================== 模块导入区域 ====================
			
			// 导入Three.js核心库的所有导出，THREE是常用的命名约定
			import * as THREE from 'three';
			
			// 导入Three.js着色器语言(Three Shader Language)
			// TSL允许在JavaScript中编写着色器代码，类似于GLSL但更友好
			import * as TSL from 'three/tsl';

			// 导入调试检查器，用于创建实时参数调节面板
			import { Inspector } from 'three/addons/inspector/Inspector.js';

			// 导入WebGPU兼容性检查模块，检测浏览器是否支持WebGPU
			import WebGPU from 'three/addons/capabilities/WebGPU.js';

			// 导入轨道控制器，允许用户用鼠标拖拽、缩放来查看场景
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入HDR(高动态范围)加载器，用于加载HDR环境贴图
			import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
			
			// 导入字体加载器，用于从JSON文件加载字体
			import { FontLoader } from 'three/addons/loaders/FontLoader.js';
			
			// 导入文本几何体生成器，将文本转换为3D几何体
			import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';

			// 导入圆角盒子几何体，创建带有圆角的立方体
			import { RoundedBoxGeometry } from 'three/addons/geometries/RoundedBoxGeometry.js';
			
			// 导入程序化木材材质相关组件：
			// - WoodNodeMaterial: 木材材质类
			// - WoodGenuses: 预定义的木材种类数组(如橡木、枫木等)
			// - Finishes: 预定义的表面处理类型数组(如抛光、哑光等)
			import { WoodNodeMaterial, WoodGenuses, Finishes } from 'three/addons/materials/WoodNodeMaterial.js';

			// ==================== 全局变量声明 ====================
			
			// scene: 3D场景容器，包含所有3D对象、灯光、相机等
			let scene;
			
			// base: 基础组，作为所有木材块和标签的父容器，便于整体变换
			let base;
			
			// camera: 相机对象，定义观察3D场景的视角
			let camera;
			
			// renderer: 渲染器，负责将3D场景渲染到2D画布上
			let renderer;
			
			// controls: 轨道控制器实例，处理用户交互
			let controls;
			
			// font: 加载的字体对象，用于生成3D文本
			let font;
			
			// blockGeometry: 共享的几何体，所有木材块使用相同的几何体以节省内存
			let blockGeometry;
			
			// gui: GUI(图形用户界面)实例，用于创建参数调节面板
			let gui;

			// ==================== 工具函数定义 ====================

			/**
			 * 计算网格中木块的位置
			 * 该函数创建一个2D网格布局，x轴表示木材种类，y轴表示表面处理
			 * 
			 * @param {number} woodIndex - 木材种类在WoodGenuses数组中的索引
			 * @param {number} finishIndex - 表面处理在Finishes数组中的索引
			 * @returns {Object} 包含x、y、z坐标的JavaScript对象
			 * 
			 * 计算原理：
			 * 1. x坐标固定为0，因为所有物体在x轴上是居中的
			 * 2. y坐标 = (finishIndex - 中点) * 间距，实现垂直等距排列
			 * 3. z坐标 = (woodIndex - 中点 + 偏移) * 间距，实现水平等距排列
			 * 
			 * 示例：如果有5种木材，中点=2.5，索引0的木材z坐标 = (0-2.5+0.45)*1.0 = -2.05
			 */
			function getGridPosition(woodIndex, finishIndex) {
				return {
					x: 0,  // 固定x坐标，所有物体在x轴上对齐
					y: (finishIndex - Finishes.length / 2) * 1.0,  // 垂直位置
					z: (woodIndex - WoodGenuses.length / 2 + 0.45) * 1.0  // 水平位置，+0.45是微调偏移
				};
			}

			/**
			 * 创建网格背景平面
			 * 使用Three.js着色器语言(TSL)动态生成网格图案
			 * 优点：纯着色器生成，无需纹理贴图，无限分辨率
			 * 
			 * @returns {THREE.Mesh} 包含网格图案的平面网格对象
			 * 
			 * 实现原理：
			 * 1. 使用TSL.Fn创建可重用的着色器函数
			 * 2. gridXZ: 生成XZ平面上的网格图案
			 * 3. radialGradient: 创建径向渐变，使边缘淡出
			 * 4. 将网格图案与渐变混合，创建最终效果
			 */
			function createGridPlane() {
				// 创建基础节点材质，支持TSL着色器节点
				const material = new THREE.MeshBasicNodeMaterial();

				/**
				 * gridXZ函数：生成XZ平面网格图案
				 * 使用屏幕空间导数(fwidth)实现自动抗锯齿
				 * 
				 * @param {TSLNode} gridSize - 网格单元大小，控制网格密度
				 * @param {TSLNode} dotWidth - 网格点宽度，控制点的大小
				 * @param {TSLNode} lineWidth - 网格线宽度，控制线的粗细
				 * @returns {TSLNode} 网格图案的alpha值(0-1)
				 */
				const gridXZ = TSL.Fn(([
					gridSize = TSL.float(1.0),    // 默认网格大小1.0单位
					dotWidth = TSL.float(0.1),    // 默认点宽度0.1
					lineWidth = TSL.float(0.02)   // 默认线宽度0.02
				]) => {
					// 获取世界坐标的XZ分量，除以网格大小得到标准化坐标
					const coord = TSL.positionWorld.xz.div(gridSize);
					
					// 取小数部分：fract函数返回坐标的小数部分(0-1)
					// 这创建了无限的重复网格，无论坐标多大都只显示0-1范围内的图案
					const grid = TSL.fract(coord);

					// 计算屏幕空间导数用于抗锯齿
					// fwidth计算当前像素在屏幕空间中的变化率
					// 当网格线很细时，在远处或斜视时会出现锯齿，fwidth可以平滑过渡
					const fw = TSL.fwidth(coord);
					const smoothing = TSL.max(fw.x, fw.y).mul(0.5);

					// 创建网格点：在每个单元格中心画一个正方形点
					// 计算到单元格中心的曼哈顿距离(取x和y方向的最大值)
					const squareDist = TSL.max(
						TSL.abs(grid.x.sub(0.5)),  // x方向到中心的距离
						TSL.abs(grid.y.sub(0.5))   // y方向到中心的距离
					);
					
					// smoothstep创建平滑过渡：在dotWidth±smoothing范围内从0过渡到1
					// 这样点的边缘会有抗锯齿效果
					const dots = TSL.smoothstep(
						dotWidth.add(smoothing),   // 外边缘
						dotWidth.sub(smoothing),   // 内边缘
						squareDist                 // 输入距离
					);

					// 创建网格线：沿x和y方向画线
					const lineX = TSL.smoothstep(
						lineWidth.add(smoothing),
						lineWidth.sub(smoothing),
						TSL.abs(grid.x.sub(0.5))  // x方向的线
					);
					const lineZ = TSL.smoothstep(
						lineWidth.add(smoothing),
						lineWidth.sub(smoothing),
						TSL.abs(grid.y.sub(0.5))  // y方向的线
					);
					
					// 合并x和y方向的线
					const lines = TSL.max(lineX, lineZ);

					// 合并点和线：取两者的最大值
					// 这样可以同时显示点和线，且不会相互覆盖
					return TSL.max(dots, lines);
				});

				/**
				 * radialGradient函数：创建径向渐变
				 * 用于使平面边缘淡出，创建聚焦中心的效果
				 * 
				 * @param {TSLNode} radius - 渐变开始半径
				 * @param {TSLNode} falloff - 渐变衰减范围
				 * @returns {TSLNode} 渐变值(0-1)，1为完全显示，0为完全透明
				 */
				const radialGradient = TSL.Fn(([
					radius = TSL.float(10.0),    // 默认半径10单位
					falloff = TSL.float(1.0)     // 默认衰减范围1单位
				]) => {
					// 计算当前位置到世界原点的距离
					const distance = TSL.length(TSL.positionWorld);
					
					// 使用smoothstep创建平滑渐变：
					// 从radius开始衰减，到radius-falloff完全透明
					return TSL.smoothstep(
						radius,                 // 开始衰减的距离
						radius.sub(falloff),    // 完全透明的距离
						distance                // 当前距离
					);
				});

				// 创建网格图案实例：调用gridXZ函数，传入具体参数
				const gridPattern = gridXZ(1.0, 0.03, 0.005);
				
				// 定义颜色：基础色(透明)和网格色(灰色)
				const baseColor = TSL.vec4(1.0, 1.0, 1.0, 0.0);   // RGBA: 白色，完全透明
				const gridColor = TSL.vec4(0.5, 0.5, 0.5, 1.0);   // RGBA: 灰色，完全不透明

				// 设置材质颜色节点：
				// 1. mix函数：根据gridPattern的alpha值混合baseColor和gridColor
				// 2. mul函数：乘以径向渐变，使边缘淡出
				material.colorNode = gridPattern.mix(baseColor, gridColor).mul(radialGradient(30.0, 20.0));
				
				// 启用透明材质，这样alpha通道才会生效
				material.transparent = true;

				// 创建圆形平面几何体，半径40单位，足够覆盖场景
				const plane = new THREE.Mesh(new THREE.CircleGeometry(40), material);
				
				// 旋转平面：-90度使其水平放置(XZ平面)
				plane.rotation.x = -Math.PI / 2;
				
				// 设置渲染顺序为-1，确保在其他3D对象后面渲染
				// 这样网格平面不会遮挡前面的木材块
				plane.renderOrder = -1;

				return plane;
			}

			/**
			 * 创建3D文本标签
			 * 将文本字符串转换为3D网格对象，用于标注木材种类和表面处理
			 * 
			 * @param {string} text - 要显示的文本内容
			 * @param {THREE.Font} font - 字体对象，包含字形数据
			 * @param {THREE.Material} material - 文本材质
			 * @param {THREE.Vector3} position - 文本在场景中的位置
			 * 
			 * 实现步骤：
			 * 1. 使用TextGeometry将文本转换为3D几何体
			 * 2. 计算几何体边界框并居中
			 * 3. 创建Group容器并添加文本网格
			 * 4. 应用旋转和位置变换
			 * 5. 添加到base组中
			 */
			function createLabel(text, font, material, position) {
				// 创建文本几何体
				const txt_geo = new TextGeometry(text, {
					font: font,               // 使用的字体
					size: 0.1,                // 字体大小：0.1单位
					depth: 0.001,             // 挤出深度：0.001单位（很薄）
					curveSegments: 12,        // 曲线分段数：越高越平滑，性能消耗越大
					bevelEnabled: false       // 禁用倒角：减少几何复杂度
				});

				// 计算边界框：获取几何体的最小和最大坐标
				txt_geo.computeBoundingBox();
				
				// 计算居中偏移量：
				// 边界框的max-min得到尺寸，除以2得到中心偏移
				const offx = -0.5 * (txt_geo.boundingBox.max.x - txt_geo.boundingBox.min.x);
				const offy = -0.5 * (txt_geo.boundingBox.max.y - txt_geo.boundingBox.min.y);
				const offz = -0.5 * (txt_geo.boundingBox.max.z - txt_geo.boundingBox.min.z);
				
				// 平移几何体使其中心位于原点
				txt_geo.translate(offx, offy, offz);

				// 创建Group容器：便于整体变换
				const label = new THREE.Group();
				const mesh = new THREE.Mesh(txt_geo);
				label.add(mesh);

				// 应用默认旋转：-90度绕Y轴，使文本朝向相机
				label.rotateY(-Math.PI / 2);

				// 设置材质：Group的第一个子元素的材质
				label.children[0].material = material;
				
				// 设置位置
				label.position.copy(position);
				
				// 添加到base组中
				base.add(label);
			}

			// ==================== 主初始化函数 ====================

			/**
			 * 初始化函数 - 程序的主要入口点
			 * 异步函数：因为需要加载字体、HDR纹理等资源
			 * 
			 * 初始化流程：
			 * 1. 创建场景、相机、渲染器
			 * 2. 设置控制器和GUI
			 * 3. 加载字体和几何体
			 * 4. 创建背景平面
			 * 5. 加载环境贴图
			 * 6. 创建所有标签和木材块
			 * 7. 添加自定义木材块
			 */
			async function init() {
				// ---------- 步骤1：创建场景 ----------
				scene = new THREE.Scene();
				scene.background = new THREE.Color(0xffffff);  // 白色背景

				// ---------- 步骤2：创建相机 ----------
				// 透视相机：模拟人眼视角，近大远小
				camera = new THREE.PerspectiveCamera(
					75,                                // 视野角度(FOV)：75度
					window.innerWidth / window.innerHeight, // 宽高比：窗口比例
					0.1,                               // 近裁剪面：0.1单位
					1000                               // 远裁剪面：1000单位
				);
				// 设置相机位置：稍微偏移以便看到整个场景
				camera.position.set(-0.1, 5, 0.548);

				// ---------- 步骤3：创建渲染器 ----------
				renderer = new THREE.WebGPURenderer({ 
					antialias: true  // 启用抗锯齿：平滑边缘
				});
				// 设置像素比：1.0固定值，确保性能稳定
				// 如果设置为window.devicePixelRatio，在高DPI屏幕上会更清晰但性能更低
				renderer.setPixelRatio(1.0);
				
				// 设置渲染器大小为窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				
				// 设置色调映射：NeutralToneMapping保持颜色自然
				renderer.toneMapping = THREE.NeutralToneMapping;
				
				// 设置曝光度：1.0为默认值
				renderer.toneMappingExposure = 1.0;
				
				// 附加检查器：用于调试
				renderer.inspector = new Inspector();
				
				// 设置动画循环：每帧调用render函数
				renderer.setAnimationLoop(render);
				
				// 将渲染器的canvas元素添加到DOM中
				document.body.appendChild(renderer.domElement);

				// ---------- 步骤4：创建控制器 ----------
				controls = new OrbitControls(camera, renderer.domElement);
				// 设置控制焦点：用户旋转缩放时围绕的点
				controls.target.set(0, 0, 0.548);

				// ---------- 步骤5：创建GUI ----------
				gui = renderer.inspector.createParameters('参数设置');
			
				// ---------- 步骤6：异步加载字体 ----------
				// FontLoader加载字体JSON文件，返回字体对象
				font = await new FontLoader().loadAsync('./fonts/helvetiker_regular.typeface.json');

				// ---------- 步骤7：创建共享几何体 ----------
				// 圆角盒子几何体参数：
				// 宽度0.125, 高度0.9, 深度0.9, 分段数10, 圆角半径0.02
				blockGeometry = new RoundedBoxGeometry(0.125, 0.9, 0.9, 10, 0.02);

				// ---------- 步骤8：创建基础容器组 ----------
				base = new THREE.Group();
				// 旋转组：-90度绕Z轴，调整整体朝向
				base.rotation.set(0, 0, -Math.PI / 2);
				// 设置位置：与控制器焦点相同
				base.position.set(0, 0, 0.548);
				scene.add(base);

				// ---------- 步骤9：创建文本材质 ----------
				const text_mat = new THREE.MeshStandardMaterial();
				// 使用TSL设置颜色节点：纯黑色
				text_mat.colorNode = TSL.color('#000000');

				// ---------- 步骤10：创建表面处理标签(左侧列) ----------
				// 遍历所有表面处理类型，为每种创建一个标签
				for (let y = 0; y < Finishes.length; y++) {
					// 使用woodIndex=-1表示左侧列
					createLabel(Finishes[y], font, text_mat, getGridPosition(-1, y));
				}

				// ---------- 步骤11：创建并添加网格平面 ----------
				const plane = createGridPlane();
				scene.add(plane);

				// ---------- 步骤12：异步加载HDR环境贴图 ----------
				// HDR贴图提供高质量的环境照明和反射
				await new HDRLoader()
					.setPath('textures/equirectangular/')  // 设置资源路径
					.loadAsync('san_giuseppe_bridge_2k.hdr')  // 异步加载HDR文件
					.then((texture) => {
						// 设置纹理映射方式：等距柱状投影(球形映射)
						texture.mapping = THREE.EquirectangularReflectionMapping;
						
						// 设置为场景环境贴图：提供全局照明和反射
						scene.environment = texture;
						
						// 设置环境光强度：2.0使环境更亮
						scene.environmentIntensity = 2;
					});

				// ---------- 步骤13：创建木材种类标签(顶部行) ----------
				// 遍历所有木材种类，为每种创建一个标签
				for (let x = 0; x < WoodGenuses.length; x++) {
					// 使用finishIndex=-1表示顶部行
					createLabel(WoodGenuses[x], font, text_mat, getGridPosition(x, -1));
				}

				// ---------- 步骤14：创建所有木材块(网格布局) ----------
				// 双重循环：遍历所有木材种类 × 所有表面处理
				for (let x = 0; x < WoodGenuses.length; x++) {
					for (let y = 0; y < Finishes.length; y++) {
						// 从预设创建木材材质：WoodGenuses[x] + Finishes[y]
						const material = WoodNodeMaterial.fromPreset(WoodGenuses[x], Finishes[y]);
						
						// 创建网格对象：使用共享几何体和创建的材质
						const cube = new THREE.Mesh(blockGeometry, material);

						// 设置位置：根据网格索引计算
						cube.position.copy(getGridPosition(x, y));
						
						// 设置材质的变换矩阵：添加随机偏移，使木材纹理看起来更自然
						material.transformationMatrix = new THREE.Matrix4().setPosition(
							new THREE.Vector3(-0.1, 0, Math.random())
						);
						
						// 添加到base组中
						base.add(cube);

						// 短暂延迟：让主线程有机会处理其他任务
						// 避免一次性创建太多对象导致页面卡顿
						await new Promise(resolve => setTimeout(resolve, 0));
					}
				}

				// ---------- 步骤15：添加自定义木材块 ----------
				add_custom_wood(text_mat);
			}

			/**
			 * 渲染循环函数
			 * 每一帧浏览器重绘时调用
			 * 这是Three.js动画的核心
			 */
			function render() {
				// 更新控制器：处理用户输入（鼠标拖拽、滚轮缩放）
				controls.update();
				
				// 渲染场景：将3D场景绘制到2D画布上
				renderer.render(scene, camera);
			}

			// ==================== 事件监听器 ====================

			/**
			 * 窗口大小变化事件监听器
			 * 当浏览器窗口改变大小时，需要更新相机和渲染器
			 */
			window.addEventListener('resize', () => {
				// 更新相机宽高比：根据新的窗口尺寸
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机投影矩阵：必须调用此方法使宽高比生效
				camera.updateProjectionMatrix();
				
				// 更新渲染器大小：使canvas填满窗口
				renderer.setSize(window.innerWidth, window.innerHeight);
			});

			// ==================== 程序启动 ====================

			/**
			 * 检查WebGPU支持并启动应用
			 * WebGPU是现代浏览器的下一代图形API，比WebGL更高效
			 */
			if (WebGPU.isAvailable()) {
				// WebGPU可用，启动应用
				init();
			} else {
				// WebGPU不可用，显示错误信息
				// getErrorMessage()返回一个包含错误信息的DOM元素
				document.body.appendChild(WebGPU.getErrorMessage());
			}

			// ==================== 自定义木材函数 ====================

			/**
			 * 添加自定义木材块和GUI控件
			 * 创建用户可调节参数的木材材质，并添加到场景中
			 * 
			 * @param {THREE.Material} text_mat - 文本材质，用于创建"custom"标签
			 * 
			 * 功能：
			 * 1. 创建"custom"标签
			 * 2. 创建自定义木材材质
			 * 3. 为材质添加GUI控件
			 * 4. 创建自定义木材块并添加到场景
			 */
			function add_custom_wood(text_mat) {
				// ---------- 步骤1：创建"Custom"标签 ----------
				// 计算标签位置：位于网格布局的最右侧
				const customLabelPosition = getGridPosition(
					Math.round(WoodGenuses.length / 2 - 1),  // 木材种类中点
					5  // 固定在第5行（假设Finishes.length >= 6）
				);
				createLabel('自定义', font, text_mat, customLabelPosition);

				// ---------- 步骤2：创建自定义木材材质 ----------
				// 使用WoodNodeMaterial构造函数，传入自定义参数
				const customMaterial = new WoodNodeMaterial({
					// 中心区域参数
					centerSize: 1.11,              // 心材区域大小：1.0为默认
					
					// 纹理扭曲参数（模拟木材自然生长的不规则性）
					largeWarpScale: 0.32,          // 大尺度扭曲：影响整体纹理走向
					largeGrainStretch: 0.24,       // 大纹理拉伸：使纹理沿特定方向拉伸
					smallWarpStrength: 0.059,      // 小扭曲强度：添加细节层次的不规则性
					smallWarpScale: 2,             // 小扭曲尺度：控制小扭曲的频率
					fineWarpStrength: 0.006,       // 精细扭曲强度：最细微的纹理变化
					fineWarpScale: 32.8,           // 精细扭曲尺度：高频细节
					
					// 年轮参数（木材的核心特征）
					ringThickness: 1 / 34,         // 年轮厚度：每年生长的厚度
					ringBias: 0.03,                // 年轮偏移：使年轮不完全同心
					ringSizeVariance: 0.03,        // 年轮大小变化：每年厚度不同
					ringVarianceScale: 4.4,        // 年轮变化尺度：控制变化的频率
					
					// 树皮参数
					barkThickness: 0.3,            // 树皮厚度：边缘的深色区域
					
					// 斑点参数（模拟木材的天然瑕疵）
					splotchScale: 0.2,             // 斑点尺度：斑点的大小
					splotchIntensity: 0.541,       // 斑点强度：斑点的明显程度
					
					// 细胞结构参数（木材的微观结构）
					cellScale: 910,                // 细胞尺度：细胞图案的重复频率
					cellSize: 0.1,                 // 细胞大小：单个细胞的尺寸
					
					// 颜色参数
					darkGrainColor: new THREE.Color('#0c0504'),    // 深色纹理：接近黑色
					lightGrainColor: new THREE.Color('#926c50'),   // 浅色纹理：棕色
					
					// 表面处理参数
					clearcoat: 1,                  // 清漆层强度：1.0为完全光泽
					clearcoatRoughness: 0.2        // 清漆层粗糙度：0.0为镜面，1.0为磨砂
				});

				// ---------- 步骤3：为自定义材质添加GUI控件 ----------
				// GUI允许用户实时调节参数，无需重新加载页面
				
				// 中心区域参数控件
				gui.add(customMaterial, 'centerSize', 0.0, 2.0, 0.01)
				   .name('中心区域大小');
				
				// 扭曲参数控件
				gui.add(customMaterial, 'largeWarpScale', 0.0, 1.0, 0.001)
				   .name('大扭曲尺度');
				gui.add(customMaterial, 'largeGrainStretch', 0.0, 1.0, 0.001)
				   .name('大纹理拉伸');
				gui.add(customMaterial, 'smallWarpStrength', 0.0, 0.2, 0.001)
				   .name('小扭曲强度');
				gui.add(customMaterial, 'smallWarpScale', 0.0, 5.0, 0.01)
				   .name('小扭曲尺度');
				gui.add(customMaterial, 'fineWarpStrength', 0.0, 0.05, 0.001)
				   .name('精细扭曲强度');
				gui.add(customMaterial, 'fineWarpScale', 0.0, 50.0, 0.1)
				   .name('精细扭曲尺度');
				
				// 年轮参数控件
				gui.add(customMaterial, 'ringThickness', 0.0, 0.1, 0.001)
				   .name('年轮厚度');
				gui.add(customMaterial, 'ringBias', -0.2, 0.2, 0.001)
				   .name('年轮偏移');
				gui.add(customMaterial, 'ringSizeVariance', 0.0, 0.2, 0.001)
				   .name('年轮大小变化');
				gui.add(customMaterial, 'ringVarianceScale', 0.0, 10.0, 0.1)
				   .name('年轮变化尺度');
				
				// 树皮参数控件
				gui.add(customMaterial, 'barkThickness', 0.0, 1.0, 0.01)
				   .name('树皮厚度');
				
				// 斑点参数控件
				gui.add(customMaterial, 'splotchScale', 0.0, 1.0, 0.01)
				   .name('斑点尺度');
				gui.add(customMaterial, 'splotchIntensity', 0.0, 1.0, 0.01)
				   .name('斑点强度');
				
				// 细胞结构参数控件
				gui.add(customMaterial, 'cellScale', 100, 2000, 1)
				   .name('细胞尺度');
				gui.add(customMaterial, 'cellSize', 0.01, 0.5, 0.001)
				   .name('细胞大小');
				
				// 颜色参数控件（颜色选择器）
				gui.addColor({ darkGrainColor: '#0c0504' }, 'darkGrainColor')
				   .name('深色纹理')
				   .onChange(v => customMaterial.darkGrainColor.set(v));  // 颜色改变时更新材质
				gui.addColor({ lightGrainColor: '#926c50' }, 'lightGrainColor')
				   .name('浅色纹理')
				   .onChange(v => customMaterial.lightGrainColor.set(v));
				
				// 表面处理参数控件
				gui.add(customMaterial, 'clearcoat', 0.0, 1.0, 0.01)
				   .name('清漆强度');
				gui.add(customMaterial, 'clearcoatRoughness', 0.0, 1.0, 0.01)
				   .name('清漆粗糙度');

				// ---------- 步骤4：创建自定义木材块 ----------
				const cube = new THREE.Mesh(blockGeometry, customMaterial);
				
				// 设置材质的变换矩阵（与预设木材块相同）
				customMaterial.transformationMatrix = new THREE.Matrix4().setPosition(
					new THREE.Vector3(-0.1, 0, Math.random())
				);
				
				// 计算自定义木材块的位置：位于"Custom"标签右侧
				cube.position.copy(getGridPosition(Math.round(WoodGenuses.length / 2), 5));
				
				// 添加到base组中
				base.add(cube);
			}

		</script>
	</body>
</html>