<!-- Three.js 随机UV纹理和溶解效果示例 - 功能与技术详解
🎯 一、项目核心功能
1. 随机UV纹理效果（无平铺纹理）
问题解决：传统纹理重复使用时，会出现明显的重复图案和接缝

实现方式：通过噪声贴图或程序化噪声为每个纹理坐标添加随机偏移

视觉表现：使重复的纹理看起来更像一个连续、自然的大表面

可调参数：

启用/禁用随机效果

使用噪声贴图或程序化噪声

选择标准方法或Suslik改进方法

调试模式可视化噪声分布

2. 动态溶解效果
效果描述：模拟物体从固态逐渐溶解消失的过程

控制机制：

溶解程度：从0（完整）到1（完全溶解）

溶解阈值：控制溶解边缘的锐利或模糊程度

多材质同步：外部和内部材质同步溶解，地面透明度也随之变化

3. 交互式3D展示环境
模型展示：ShaderBall专业着色器测试模型

环境照明：HDR全景环境贴图提供真实光照

用户交互：鼠标拖拽旋转、缩放、平移视角

实时控制：GUI面板调整所有视觉效果参数

🔧 二、主要技术架构
1. Three.js核心框架
text
场景图结构：
├── 场景(Scene)
│   ├── 透视相机(PerspectiveCamera)
│   ├── 平行光(DirectionalLight) + 阴影系统
│   ├── 地面平面(PlaneGeometry) + 阴影材质
│   └── GLTF模型(ShaderBall)
│       ├── 外部材质（带随机UV+溶解）
│       ├── 内部材质（仅溶解）
│       └── 标志材质
2. 着色器替换技术（核心创新）
javascript
// Three.js着色器修改机制
material.onBeforeCompile = function(shader) {
    // 1. 添加自定义Uniform变量
    shader.uniforms['disolve'] = { value: 0 };
    
    // 2. 替换标准着色器代码片段
    shader.fragmentShader = shader.fragmentShader.replace(
        '#include <map_fragment>', 
        customMapFragment
    );
};
技术原理：Three.js的着色器由多个可替换的"代码块"组成

优势：无需编写完整着色器，只需修改关键部分

3. 随机UV算法技术细节
3.1 噪声生成阶段
glsl
// 两种噪声源选择
if(useNoiseMap == 1.0)
    k = texture2D(noiseMap, 0.005*uv).x;  // 纹理噪声
else
    k = directNoise(uv);                   // 程序化噪声
3.2 虚拟纹理分区
glsl
// 将纹理空间分为8个虚拟纹理
float index = k * 8.0;           // 噪声值映射到8个区域
float ia = floor(index);         // 第一个虚拟纹理索引
float ib = ia + 1.0;             // 第二个虚拟纹理索引
3.3 偏移量生成
glsl
// 为每个虚拟纹理生成唯一UV偏移
vec2 offa = sin(vec2(3.0, 7.0) * ia);  // 使用正弦函数作为哈希
vec2 offb = sin(vec2(3.0, 7.0) * ib);
3.4 纹理采样与混合
glsl
// 使用导数确保正确的Mipmap级别
vec4 cola = textureGrad(mapper, uv + offa, dFdx(uv), dFdy(uv));
vec4 colb = textureGrad(mapper, uv + offb, dFdx(uv), dFdy(uv));

// 智能混合：考虑颜色差异的平滑过渡
return mix(cola, colb, smoothstep(0.2, 0.8, f - 0.1*sum(cola-colb)));
4. 溶解效果算法
glsl
// 核心溶解计算公式
float vv = texture2D(alphaMap, vAlphaMapUv).g;          // 采样溶解贴图
float r = disolve * (1.0 + threshold * 2.0) - threshold; // 计算溶解范围
float mixf = clamp((vv - r) * (1.0/threshold), 0.0, 1.0); // 计算透明度
diffuseColor.a = mixf;                                  // 应用透明度
💡 三、关键技术亮点
1. 高级阴影技术
VSM阴影映射：方差阴影映射，解决传统阴影痤疮问题

阴影优化：

适当的阴影贴图尺寸（1024×1024）

阴影偏移(bias)消除自阴影伪影

阴影模糊(radius)柔化边缘

2. HDR环境照明系统
真实感照明：Equirectangular HDR贴图提供基于图像的照明

双用途：

作为场景背景（天空盒）

作为环境反射源

强度控制：独立控制背景和环境反射强度

3. 性能优化策略
javascript
// 1. 按需渲染（非连续动画循环）
controls.addEventListener('change', render);
gui.onChange(render);

// 2. 适当的纹理尺寸和Mipmap
map.repeat.set(20, 20);  // 合理重复次数

// 3. 阴影质量与性能平衡
shadow.mapSize.width = shadow.mapSize.height = 1024;

// 4. 使用Draco压缩减小模型文件
loader.setDRACOLoader(new DRACOLoader());
4. 用户体验设计
响应式设计：窗口大小自适应

直观交互：轨道控制器提供自然3D导航

实时反馈：所有参数调整即时可见效果

渐进加载：纹理→环境→模型的分步加载

🚀 四、技术难点与解决方案
1. 无平铺纹理的接缝问题
难点：虚拟纹理间过渡处可能出现明显接缝

解决方案：

基于颜色差异的智能混合

使用平滑过渡函数(smoothstep)

考虑屏幕空间导数(textureGrad)

2. 多材质效果同步
难点：外部和内部材质需要同步溶解

解决方案：

统一的Uniform变量控制

通过GUI设置器同时更新两个材质

3. 着色器代码维护
难点：GLSL代码作为字符串难以调试

解决方案：

模块化代码片段(/* glsl */注释)

清晰的函数和变量命名

详细的代码注释

📊 五、应用场景与扩展性
1. 实际应用场景
游戏开发：角色死亡/消失特效

建筑可视化：建筑材料自然纹理表现

产品展示：交互式材质演示

艺术创作：动态视觉效果生成

2. 扩展可能性
更多噪声算法：Perlin噪声、Simplex噪声

动画效果：随时间变化的溶解和随机UV

多纹理混合：多个纹理层叠加随机UV

物理集成：与物理引擎结合的破碎效果

3. 性能优化方向
计算着色器：使用WebGL 2.0的计算着色器生成噪声

纹理数组：使用纹理数组代替虚拟纹理

LOD系统：根据距离调整随机UV计算精度

🎨 六、视觉效果对比
模式	纹理表现	性能消耗	适用场景
标准纹理	明显重复图案	低	简单场景、性能敏感
随机UV（噪声贴图）	自然连续	中	大多数3D场景
随机UV（程序化）	可控性强	中高	需要动态变化的场景
Suslik方法	最佳过渡	中	高质量要求 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js WebGL示例 - 随机UV纹理和溶解效果 -->
		<title>Three.js WebGL示例 - 随机UV纹理和溶解效果</title>
		<meta charset="utf-8">
		<!-- 
			视口设置：
			- width=device-width: 宽度等于设备宽度
			- user-scalable=no: 禁止用户手动缩放
			- minimum-scale=1.0: 最小缩放比例为1.0（不缩小）
			- maximum-scale=1.0: 最大缩放比例为1.0（不放大）
			确保3D场景在不同设备上保持固定比例
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 引入外部CSS样式文件 -->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>

	<body>
		<!-- 
			3D场景的主容器
			Three.js的WebGL渲染器会将画布(canvas)元素添加到此div中
			所有3D内容都将在这个容器内渲染显示
		-->
		<div id="container"></div>
		<!-- 
			页面底部信息栏
			显示项目信息和Three.js官网链接
			用于展示技术来源和项目说明
		-->
		<div id="info">
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 随机UV纹理和溶解效果演示
		</div>

		<!-- 
			导入映射(Import Map)配置
			用于在支持ES模块的浏览器中映射模块名称到实际文件路径
			这是现代JavaScript模块化开发的重要特性
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块
			type="module"表示这是一个ES6模块，支持import/export语法
			模块中的代码在严格模式下运行，有自己的作用域
		-->
		<script type="module">

			// ==================== 模块导入部分 ====================
			// 导入Three.js核心库的所有功能并命名为THREE
			// THREE现在包含Three.js的所有核心类和方法
			import * as THREE from 'three';

			// 从Three.js附加组件中导入特定功能模块
			// OrbitControls: 轨道控制器，允许用户用鼠标/触摸屏旋转、平移、缩放相机
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			// GLTFLoader: GLTF/GLB格式的3D模型加载器，支持加载带纹理、动画的3D模型
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			// HDRLoader: 高动态范围图像加载器，用于加载HDR环境贴图
			// HDR贴图提供更真实的环境光照和反射效果
			import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
			// DRACOLoader: Draco压缩格式解码器，用于解压缩Google的Draco压缩格式的3D模型
			// 可以显著减小3D模型文件大小，加快网络传输
			import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';

			// 导入lil-gui库，这是一个轻量级的GUI控制面板库
			// 用于创建实时调整参数的交互式控制面板
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// ==================== 全局变量声明 ====================
			// 这些变量将在多个函数中使用，所以声明在模块作用域中
			let camera;        // 相机对象，定义观察3D场景的视角
			let scene;         // 场景对象，包含所有3D对象、灯光、相机
			let renderer;      // 渲染器对象，负责将3D场景渲染到2D画布
			let dirLight;      // 平行光对象，模拟太阳光
			let ground;        // 地面网格对象，作为阴影接收面
			let gui;           // GUI控制面板对象
			let material;      // 外部材质对象（ShaderBall的外表面材质）
			let materialIn;    // 内部材质对象（ShaderBall的内表面材质）
			let uniforms;      // 外部材质的自定义着色器uniform变量集合
			let uniformsIn;    // 内部材质的自定义着色器uniform变量集合

			// ==================== 初始化并开始渲染 ====================
			// 调用初始化函数设置所有3D元素
			init();
			// 调用渲染函数进行第一次渲染
			render();

			// ==================== 初始化函数 ====================
			/**
			 * init() - 初始化Three.js场景的主要函数
			 * 这个函数负责：
			 * 1. 创建场景、相机、渲染器
			 * 2. 设置灯光和阴影
			 * 3. 创建地面平面
			 * 4. 加载纹理贴图
			 * 5. 加载HDR环境贴图
			 * 6. 加载3D模型
			 * 7. 设置轨道控制器
			 * 8. 绑定窗口大小调整事件
			 */
			function init() {

				// 获取HTML中的容器元素，Three.js将在此元素内创建画布
				const container = document.getElementById( 'container' );

				// ========== 创建透视相机 ==========
				/**
				 * THREE.PerspectiveCamera - 透视相机
				 * 模拟人眼视角，有近大远小的透视效果
				 * 参数详解：
				 * @param {number} 45 - 视野角度(Field of View, FOV)，单位是度
				 *                     45度是常用的自然视角
				 * @param {number} window.innerWidth / window.innerHeight - 宽高比
				 *                     根据浏览器窗口大小动态计算，避免图像拉伸
				 * @param {number} 0.1 - 近裁剪面距离，相机看不到此距离内的物体
				 *                     避免近距离物体渲染问题
				 * @param {number} 20 - 远裁剪面距离，相机看不到此距离外的物体
				 *                     优化渲染性能
				 */
				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 0.1, 20 );
				// 设置相机在3D空间中的位置 (x, y, z)
				// x: -0.8 (向左偏移), y: 0.6 (向上偏移), z: 1.5 (向后偏移)
				camera.position.set( -0.8, 0.6, 1.5 );

				// ========== 创建场景 ==========
				/**
				 * THREE.Scene - 3D场景
				 * 所有3D对象、灯光、相机的容器
				 * 类似于一个虚拟的3D世界
				 */
				scene = new THREE.Scene();

				// ========== 创建WebGL渲染器 ==========
				/**
				 * THREE.WebGLRenderer - WebGL渲染器
				 * 使用WebGL API在HTML canvas上渲染3D图形
				 * 配置选项：
				 * @param {Object} { antialias: true } - 开启抗锯齿
				 *                     平滑边缘，消除锯齿状像素边缘
				 */
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				// 设置设备像素比，适配高DPI显示器（如Retina屏）
				// 使渲染分辨率匹配屏幕物理分辨率，避免模糊
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器的输出画布大小为浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 设置色调映射(Tone Mapping)算法
				// ACESFilmicToneMapping：电影级色调映射，提供更好的高光处理和色彩表现
				renderer.toneMapping = THREE.ACESFilmicToneMapping;
				// 设置色调映射的曝光度，控制整体亮度
				// 0.7是中等偏暗的曝光，适合HDR场景
				renderer.toneMappingExposure = 0.7;
				// 启用阴影映射，允许物体投射和接收阴影
				renderer.shadowMap.enabled = true;
				// 设置阴影贴图类型为VSM（Variance Shadow Mapping）
				// VSM阴影提供更柔和的阴影边缘，减少阴影痤疮问题
				renderer.shadowMap.type = THREE.VSMShadowMap;
				// 将渲染器的DOM元素（canvas画布）添加到页面容器中
				// 现在可以在页面上看到3D场景了
				container.appendChild( renderer.domElement );

				// ========== 创建平行光 ==========
				/**
				 * THREE.DirectionalLight - 平行光
				 * 模拟太阳光，所有光线方向平行
				 * 参数详解：
				 * @param {number} 0xFFFFFF - 光的颜色，白色光
				 * @param {number} 3 - 光的强度，3是较强的亮度
				 */
				dirLight = new THREE.DirectionalLight( 0xFFFFFF, 3 );
				// 设置光源位置 (x, y, z)
				// 位置影响阴影方向和物体受光面
				dirLight.position.set( -0.5, 1, 0.8 );
				// 启用阴影投射，该光源可以产生阴影
				dirLight.castShadow = true;
				// 将光源添加到场景中
				scene.add( dirLight );
				
				// ========== 配置阴影 ==========
				// 获取光源的阴影属性对象
				const shadow = dirLight.shadow;
				// 设置阴影贴图的尺寸（宽度和高度）
				// 1024x1024像素，尺寸越大阴影质量越高，性能消耗越大
				shadow.mapSize.width = shadow.mapSize.height = 1024;
				// 设置阴影模糊半径，值越大阴影边缘越模糊
				// 16提供适度的模糊效果
				shadow.radius = 16;
				// 设置阴影偏移，解决阴影痤疮问题（阴影出现在不该出现的地方）
				// 负值将阴影稍微拉离物体表面
				shadow.bias = -0.0005;
				
				// ========== 配置阴影相机 ==========
				/**
				 * 平行光使用正交相机来渲染阴影贴图
				 * 阴影相机定义了从光源视角看到的区域
				 */
				const shadowCam = shadow.camera, s = 2;
				// 设置阴影相机的近裁剪面
				shadowCam.near = 0.5;
				// 设置阴影相机的远裁剪面
				shadowCam.far = 3;
				// 设置阴影相机的边界：右边界和上边界为2个单位
				shadowCam.right = shadowCam.top = s;
				// 设置阴影相机的边界：左边界和下边界为-2个单位
				// 这样阴影相机看到的是一个4x4单位的正方形区域
				shadowCam.left = shadowCam.bottom = -s;
				
				// 阴影调试代码（已注释掉）
				// 如果取消注释，会显示阴影相机的视锥体，用于调试阴影范围
				// scene.add( new THREE.CameraHelper(shadowCam) );

				// ========== 创建地面平面 ==========
				/**
				 * 地面作为阴影接收面，增强3D场景的真实感
				 */
				// 创建平面几何体，宽度2个单位，高度2个单位
				const plane = new THREE.PlaneGeometry( 2, 2 );
				// 将平面绕X轴旋转-90度（-π/2）
				// 默认平面是垂直的，旋转后变成水平面
				plane.rotateX( -Math.PI * 0.5 );
				// 创建网格对象，使用阴影材质
				// THREE.ShadowMaterial：只显示阴影的特殊材质
				// opacity: 0.5 - 半透明阴影，可以看到地面下的背景
				ground = new THREE.Mesh( plane, new THREE.ShadowMaterial( { opacity: 0.5 } ) );
				// 启用地面接收阴影
				ground.receiveShadow = true;
				// 设置地面位置：z轴-0.5，将地面稍微向后移动
				ground.position.z = -0.5;
				// 将地面添加到场景
				scene.add( ground );

				// ========== 加载纹理贴图 ==========
				/**
				 * 加载三种纹理贴图用于不同的视觉效果
				 */
				
				// 1. 主纹理贴图 - 玉石纹理
				const map = new THREE.TextureLoader().load( 'textures/jade.jpg' );
				// 设置颜色空间为sRGB，确保颜色显示正确
				// sRGB是标准的显示器色彩空间
				map.colorSpace = THREE.SRGBColorSpace;
				// 设置纹理在U和V方向上的包裹方式为重复
				// 当纹理坐标超过[0,1]范围时，纹理会重复而不是拉伸
				map.wrapS = map.wrapT = THREE.RepeatWrapping;
				// 设置纹理重复次数，U和V方向各重复20次
				// 这样即使在大表面上也不会看到明显的纹理拉伸
				map.repeat.set( 20, 20 );
				// 不翻转Y轴，有些纹理文件需要翻转，这里保持原样
				map.flipY = false;

				// 2. 溶解贴图 - 用于溶解效果的黑白纹理
				// 白色区域保持不透明，黑色区域完全透明，灰色区域半透明
				const disolveMap = new THREE.TextureLoader().load( 'textures/shaderball_ds.jpg' );
				disolveMap.flipY = false;

				// 3. 噪声贴图 - 用于随机UV效果的噪声纹理
				// 提供随机值来偏移纹理坐标
				const noise = new THREE.TextureLoader().load( 'textures/noise.png' );

				// ========== 加载HDR环境贴图 ==========
				/**
				 * HDR贴图提供高质量的环境照明和反射
				 * 比普通纹理包含更宽的亮度范围
				 */
				new HDRLoader()
					// 设置HDR文件所在的目录路径
					.setPath( 'textures/equirectangular/' )
					// 加载指定的HDR文件
					.load( 'lobe.hdr', function ( texture ) {
						
						// 设置纹理映射方式为等距柱状投影
						// 这种映射方式适合全景环境贴图
						texture.mapping = THREE.EquirectangularReflectionMapping;
						
						// ========== 配置场景环境 ==========
						// 设置场景背景为HDR贴图，可以看到天空盒
						scene.background = texture;
						// 设置场景环境贴图，影响物体的环境反射
						scene.environment = texture;
						// 设置背景模糊度，0.5表示中等模糊
						scene.backgroundBlurriness = 0.5;
						// 设置背景强度，1.0表示原始亮度
						scene.backgroundIntensity = 1.0;
						// 设置环境光强度，1.5表示比原始亮度稍亮
						// 增强物体受环境光影响的程度
						scene.environmentIntensity = 1.5;
						
						// 环境设置完成后进行第一次渲染
						render();
						
						// ========== 加载GLTF 3D模型 ==========
						/**
						 * GLTF是标准的3D模型格式，支持网格、材质、动画等
						 */
						// 创建GLTF加载器并设置模型文件路径
						const loader = new GLTFLoader().setPath( 'models/gltf/' );
						// 设置DRACO解码器路径，用于解压缩Draco格式的模型
						loader.setDRACOLoader( new DRACOLoader().setDecoderPath( 'jsm/libs/draco/gltf/' ) );
						// 加载GLB文件（二进制格式的GLTF）
						loader.load( 'ShaderBall2.glb', function ( gltf ) {
							
							// 获取模型的根场景对象，取第一个子对象
							const shaderBall = gltf.scene.children[ 0 ];
							
							/**
							 * 模型结构说明：
							 * shaderBall是一个包含3个子对象的组(Group)：
							 * 1. base - 外部表面（主要显示部分）
							 * 2. inside - 内部表面（溶解时可见）
							 * 3. logo - 标志（如果有的话）
							 * 
							 * 注意：模型中已经包含了环境光遮蔽(AO)贴图
							 * AO贴图模拟物体表面接触处的阴影，增强立体感
							 */
							
							// 遍历模型的所有子对象，设置它们的阴影属性和渲染顺序
							let i = shaderBall.children.length, n = 0;
							// 倒序遍历所有子对象
							while ( i-- ) {
								// 设置每个子对象可以接收阴影
								shaderBall.children[ i ].receiveShadow = true;
								// 设置每个子对象可以投射阴影
								shaderBall.children[ i ].castShadow = true;
								// 设置渲染顺序，确保正确的渲染层级
								// 数值越大越后渲染（显示在最前面）
								shaderBall.children[ i ].renderOrder = n++;
							}
							
							// ========== 设置外部材质 ==========
							// 获取第一个子对象（外部表面）的材质
							material = shaderBall.children[ 0 ].material;
							// 设置材质的漫反射贴图为玉石纹理
							material.map = map;
							// 设置材质的透明度贴图为溶解贴图
							// alphaMap控制每个像素的透明度
							material.alphaMap = disolveMap;
							// 启用材质透明度，允许alphaMap生效
							material.transparent = true;
							
							// ========== 设置内部材质 ==========
							// 获取第二个子对象（内部表面）的材质
							materialIn = shaderBall.children[ 1 ].material;
							// 内部材质也使用相同的溶解贴图
							materialIn.alphaMap = disolveMap;
							// 启用内部材质的透明度
							materialIn.transparent = true;
							
							// ========== 自定义外部材质着色器 ==========
							/**
							 * onBeforeCompile是一个Three.js材质特有的回调函数
							 * 在着色器编译之前被调用，允许我们修改默认的着色器代码
							 * 这是实现自定义着色器效果的关键技术
							 */
							material.onBeforeCompile = function ( shader ) {
								
								// ========== 添加自定义Uniform变量 ==========
								/**
								 * Uniform是着色器中的全局变量，在渲染过程中保持不变
								 * 可以在JavaScript中设置，在GLSL着色器中使用
								 */
								// disolve: 溶解程度控制，0为完全显示，1为完全溶解
								shader.uniforms[ 'disolve' ] = { value: 0 };
								// threshold: 溶解阈值，控制溶解边缘的锐利程度
								shader.uniforms[ 'threshold' ] = { value: 0.2 };
								// noiseMap: 噪声贴图，用于随机UV效果
								shader.uniforms[ 'noiseMap' ] = { value: noise };
								// enableRandom: 是否启用随机UV效果，1启用，0禁用
								shader.uniforms[ 'enableRandom' ] = { value: 1 };
								// useNoiseMap: 是否使用噪声贴图（而不是程序化噪声）
								shader.uniforms[ 'useNoiseMap' ] = { value: 1 };
								// useSuslikMethod: 是否使用Suslik的随机UV算法
								shader.uniforms[ 'useSuslikMethod' ] = { value: 0 };
								// debugNoise: 是否进入噪声调试模式
								shader.uniforms[ 'debugNoise' ] = { value: 0 };
								
								// ========== 替换着色器代码片段 ==========
								/**
								 * Three.js的着色器使用模块化设计，包含许多可替换的代码块
								 * 通过替换这些代码块，我们可以自定义渲染效果
								 */
								
								// 1. 在裁剪平面解析器代码后添加随机UV函数的定义
								shader.fragmentShader = shader.fragmentShader.replace( 
									'#include <clipping_planes_pars_fragment>', 
									'#include <clipping_planes_pars_fragment>' + randomUV 
								);
								
								// 2. 替换标准的纹理采样代码为自定义的随机UV采样代码
								shader.fragmentShader = shader.fragmentShader.replace( 
									'#include <map_fragment>', 
									map_fragment 
								);
								
								// 3. 替换透明度贴图的变量声明代码
								shader.fragmentShader = shader.fragmentShader.replace( 
									'#include <alphamap_pars_fragment>', 
									alphamap_pars_fragment 
								);
								
								// 4. 替换透明度贴图的处理代码
								shader.fragmentShader = shader.fragmentShader.replace( 
									'#include <alphamap_fragment>', 
									alphamap_fragment 
								);
								
								// 保存着色器的uniforms引用，以便后续通过GUI控制
								uniforms = shader.uniforms;
							};
							
							// ========== 自定义内部材质着色器 ==========
							/**
							 * 内部材质只添加溶解效果，不添加随机UV效果
							 * 这样在溶解过程中，内部保持规则的纹理
							 */
							materialIn.onBeforeCompile = function ( shader ) {
								// 添加溶解相关的uniform变量
								shader.uniforms[ 'disolve' ] = { value: 0 };
								shader.uniforms[ 'threshold' ] = { value: 0.2 };
								
								// 只替换溶解效果相关的代码片段
								shader.fragmentShader = shader.fragmentShader.replace( 
									'#include <alphamap_pars_fragment>', 
									alphamap_pars_fragment 
								);
								shader.fragmentShader = shader.fragmentShader.replace( 
									'#include <alphamap_fragment>', 
									alphamap_fragment 
								);
								
								// 保存内部材质的uniforms引用
								uniformsIn = shader.uniforms;
							};
							
							// 将加载的模型添加到场景中
							scene.add( shaderBall );
							// 模型添加后重新渲染场景
							render();
							// 创建GUI控制面板
							createGUI();
						} );
					} );

				// ========== 创建轨道控制器 ==========
				/**
				 * OrbitControls允许用户通过鼠标交互控制相机
				 * 左键拖拽：旋转视角
				 * 右键拖拽：平移视角
				 * 滚轮：缩放视角
				 */
				const controls = new OrbitControls( camera, renderer.domElement );
				// 添加变化事件监听器，当用户操作控制器时重新渲染
				// 如果没有动画循环，这个监听器是必要的
				controls.addEventListener( 'change', render );
				// 设置相机与目标点的最小距离，防止相机穿过物体
				controls.minDistance = 0.3;
				// 设置相机与目标点的最大距离，防止离得太远
				controls.maxDistance = 10;
				// 设置控制器的目标点，相机将围绕此点旋转
				controls.target.set( 0, 0.4, 0 );
				// 更新控制器状态
				controls.update();

				// ========== 窗口大小调整事件监听 ==========
				/**
				 * 当浏览器窗口大小改变时，调整相机和渲染器
				 * 保持3D场景的正确比例和填充
				 */
				window.addEventListener( 'resize', onWindowResize );
			}

			// ==================== 创建GUI控制面板函数 ====================
			/**
			 * createGUI() - 创建交互式控制面板
			 * 使用lil-gui库创建可以实时调整参数的界面
			 * 每个参数变化都会触发重新渲染
			 */
			function createGUI() {
				
				// ========== 创建设置对象 ==========
				/**
				 * 使用getter和setter创建响应式对象
				 * 当GUI控件值改变时，会自动调用setter函数
				 * 在setter中更新uniform变量并重新渲染
				 */
				const setting = {
					
					// ----- 是否启用随机UV效果 -----
					get 'Enabled'() {
						// getter：返回当前是否启用随机UV
						// uniforms.enableRandom.value是0或1，转换为布尔值
						return uniforms.enableRandom.value ? true : false;
					},
					set 'Enabled'( v ) {
						// setter：设置是否启用随机UV
						// v是布尔值，转换为1或0赋值给uniform
						uniforms.enableRandom.value = v ? 1 : 0; 
						render();  // 更新渲染
					},

					// ----- 是否使用噪声贴图 -----
					get 'UseNoiseMap'() {
						return uniforms.useNoiseMap.value ? true : false;
					},
					set 'UseNoiseMap'( v ) {
						uniforms.useNoiseMap.value = v ? 1 : 0; 
						render();
					},

					// ----- 是否使用Suslik方法 -----
					/**
					 * Suslik方法是一种改进的随机UV算法
					 * 提供更自然的纹理混合过渡
					 */
					get 'SuslikMethod'() {
						return uniforms.useSuslikMethod.value ? true : false;
					},
					set 'SuslikMethod'( v ) {
						uniforms.useSuslikMethod.value = v ? 1 : 0; 
						render();
					},

					// ----- 是否调试噪声 -----
					/**
					 * 调试模式下，用固定颜色代替纹理
					 * 红色表示第一个虚拟纹理，蓝色表示第二个
					 * 用于可视化随机UV算法的工作方式
					 */
					get 'DebugNoise'() {
						return uniforms.debugNoise.value ? true : false;
					},
					set 'DebugNoise'( v ) {
						uniforms.debugNoise.value = v ? 1 : 0; 
						render();
					},

					// ----- 溶解程度控制 -----
					get 'disolve'() {
						return uniforms.disolve.value;
					},
					set 'disolve'( v ) {
						// 同时更新外部材质和内部材质的溶解程度
						uniforms.disolve.value = v; 
						uniformsIn.disolve.value = v;
						// 根据溶解程度调整地面透明度
						// 溶解程度越高，地面越透明，增强整体效果
						ground.material.opacity = ( 1 - v ) * 0.5;
						render();
					},

					// ----- 溶解阈值控制 -----
					get 'threshold'() {
						return uniforms.threshold.value;
					},
					set 'threshold'( v ) {
						// 同时更新外部材质和内部材质的溶解阈值
						uniforms.threshold.value = v; 
						uniformsIn.threshold.value = v;
						render();
					}
				};

				// ========== 创建GUI实例并添加控制器 ==========
				/**
				 * GUI控制器类型说明：
				 * - add(对象, 属性名): 自动检测属性类型创建合适控件
				 * - add(对象, 属性名, 最小值, 最大值, 步长): 创建数值滑块
				 */
				gui = new GUI();
				
				// 添加材质粗糙度控制器
				// 粗糙度影响材质表面的微观凹凸程度
				// 0: 完全光滑（镜面），1: 完全粗糙（漫反射）
				gui.add( material, 'roughness', 0, 1, 0.01 ).onChange( render );
				
				// 添加材质金属度控制器
				// 金属度影响材质是否像金属
				// 0: 非金属（塑料、陶瓷），1: 金属（金、银、铜）
				gui.add( material, 'metalness', 0, 1, 0.01 ).onChange( render );
				
				// 添加溶解程度控制器
				// 控制物体从完整到完全溶解的过程
				gui.add( setting, 'disolve', 0, 1, 0.01 ).onChange( render );
				
				// 添加溶解阈值控制器
				// 控制溶解边缘的锐利/模糊程度
				gui.add( setting, 'threshold', 0, 1, 0.01 ).onChange( render );
				
				// 添加启用随机UV效果的开关
				gui.add( setting, 'Enabled' );
				
				// 添加使用噪声贴图的开关
				gui.add( setting, 'UseNoiseMap' );
				
				// 添加使用Suslik方法的开关
				gui.add( setting, 'SuslikMethod' );
				
				// 添加调试噪声的开关
				gui.add( setting, 'DebugNoise' );
			}

			// ==================== 窗口大小调整处理函数 ====================
			/**
			 * onWindowResize() - 响应浏览器窗口大小变化
			 * 保持3D场景的正确比例和填充整个窗口
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机的投影矩阵
				// 必须调用此方法使宽高比变化生效
				camera.updateProjectionMatrix();
				// 更新渲染器的尺寸为新的窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 重新渲染场景
				render();
			}

			// ==================== 渲染函数 ====================
			/**
			 * render() - 渲染3D场景
			 * 将场景从相机视角渲染到画布上
			 * 这是Three.js中最核心的渲染调用
			 */
			function render() {
				// renderer.render(场景, 相机)
				// 使用指定的相机渲染整个场景
				renderer.render( scene, camera );
			}

			// ==================== GLSL着色器代码片段 ====================
			/**
			 * 以下是用GLSL（OpenGL着色语言）编写的自定义着色器代码
			 * GLSL在GPU上运行，用于处理每个像素的颜色计算
			 * 这些代码片段通过字符串替换插入到Three.js的标准着色器中
			 */

			// ========== 随机UV效果的GLSL代码 ==========
			/**
			 * 这段代码实现了"无平铺纹理"技术
			 * 核心思想：通过噪声生成随机UV偏移，避免重复纹理的明显接缝
			 * 
			 * 技术原理：
			 * 1. 使用噪声值将纹理空间划分为多个区域
			 * 2. 每个区域使用不同的UV偏移量
			 * 3. 在区域边界平滑过渡，避免明显接缝
			 */
			const randomUV = /* glsl */ `

			// ========== Uniform变量声明 ==========
			// Uniform是从JavaScript传递到着色器的只读全局变量
			uniform sampler2D noiseMap;          // 噪声贴图纹理采样器
			uniform float enableRandom;          // 是否启用随机效果（1或0）
			uniform float useNoiseMap;           // 是否使用噪声贴图（1或0）
			uniform float debugNoise;            // 调试模式开关（1或0）
			uniform float useSuslikMethod;       // 是否使用Suslik方法（1或0）

			// ========== 直接噪声函数（程序化噪声） ==========
			/**
			 * directNoise() - 生成2D程序化噪声
			 * 优点：不需要纹理，完全由数学计算生成
			 * 缺点：计算量比纹理采样大
			 * 
			 * 算法：值噪声(Value Noise)
			 * 1. 在整数格点上生成随机值
			 * 2. 在格点之间进行双线性插值
			 * 3. 使用平滑函数改善插值效果
			 */
			float directNoise(vec2 p){
			    vec2 ip = floor(p);               // 获取整数部分，确定格点位置
			    vec2 u = fract(p);                // 获取小数部分，用于格点间插值
			    u = u*u*(3.0-2.0*u);              // 3次平滑插值函数，得到更平滑的过渡
			    
			    // 双线性插值：先在x方向插值，再在y方向插值
			    float res = mix(
			        mix(rand(ip),rand(ip+vec2(1.0,0.0)),u.x),  // 底部两个点的x方向插值
			        mix(rand(ip+vec2(0.0,1.0)),rand(ip+vec2(1.0,1.0)),u.x),  // 顶部两个点的x方向插值
			        u.y  // y方向插值
			    );
			    return res*res;                   // 平方增加对比度，使噪声更明显
			}

			// ========== 辅助函数：计算vec4各分量之和 ==========
			/**
			 * sum() - 计算RGB三个颜色通道的和
			 * 用于评估两个颜色之间的差异
			 * 在纹理混合时考虑颜色差异，实现更自然的过渡
			 */
			float sum( vec4 v ) { return v.x+v.y+v.z; }

			// ========== 主函数：无平铺纹理采样 ==========
			/**
			 * textureNoTile() - 核心的无平铺纹理采样函数
			 * 
			 * 参数：
			 * @param sampler2D mapper - 要采样的纹理
			 * @param vec2 uv - 原始纹理坐标
			 * 
			 * 返回值：
			 * @return vec4 - 采样得到的颜色
			 * 
			 * 算法步骤：
			 * 1. 生成噪声值作为随机因子
			 * 2. 根据噪声值选择两个"虚拟纹理"
			 * 3. 为每个虚拟纹理计算不同的UV偏移
			 * 4. 采样两个虚拟纹理
			 * 5. 根据噪声的小数部分和颜色差异进行平滑混合
			 */
			vec4 textureNoTile( sampler2D mapper, in vec2 uv ){
			    
			    // ========== 步骤1：生成噪声值 ==========
			    float k = 0.0;  // 噪声值，范围[0,1]
			    if( useNoiseMap == 1.0 ) 
			    	// 使用噪声贴图：采样噪声纹理，缩放系数0.005使噪声变化缓慢
			    	k = texture2D( noiseMap, 0.005*uv ).x;  // 取红色通道作为噪声值
			    else 
			    	// 使用程序化噪声：直接计算噪声
			    	k = directNoise( uv );
			    
			    // ========== 步骤2：计算虚拟纹理索引 ==========
			    // 将噪声值映射到8个虚拟纹理（0-7）
			    float index = k*8.0;
			    // 获取索引的小数部分，用于两个虚拟纹理之间的插值
			    float f = fract( index );
			    float ia = 0.0;  // 第一个虚拟纹理的索引
			    float ib = 0.0;  // 第二个虚拟纹理的索引
			    
			    // ========== 步骤3：根据算法选择索引计算方式 ==========
			    if( useSuslikMethod == 1.0 ){
			    	// Suslik方法：使用四舍五入和向下取整
			    	ia = floor(index+0.5);  // 四舍五入
			    	ib = floor(index);      // 向下取整
			    	// 调整插值因子，使过渡更集中在中间
			    	f = min(f, 1.0-f)*2.0;
			    } else {
			    	// 标准方法：使用向下取整和加1
			    	ia = floor( index );    // 向下取整
			    	ib = ia + 1.0;          // 下一个索引
			    }
			    
			    // ========== 步骤4：为虚拟纹理生成UV偏移 ==========
			    // 使用正弦函数生成伪随机偏移
			    // sin(vec2(3.0,7.0)*ia)：不同的索引产生不同的偏移向量
			    // 3.0和7.0是质数，避免周期性重复
			    vec2 offa = sin(vec2(3.0,7.0)*ia);
			    vec2 offb = sin(vec2(3.0,7.0)*ib);
			    // 注意：这里可以使用更复杂的哈希函数，但正弦函数已经足够
			    
			    // ========== 步骤5：计算Mipmap所需的导数 ==========
			    /**
			     * dFdx和dFdy是GLSL内置函数，计算片段着色器中变量的屏幕空间导数
			     * 用于正确的Mipmap层级选择，避免纹理闪烁（摩尔纹）
			     */
			    vec2 dx = dFdx(uv);  // uv在屏幕x方向的变化率
			    vec2 dy = dFdy(uv);  // uv在屏幕y方向的变化率
			    
			    // ========== 步骤6：采样两个虚拟纹理 ==========
			    /**
			     * textureGrad()是带导数参数的纹理采样函数
			     * 比普通的texture2D()函数更精确，特别是在透视变形大的情况下
			     */
			    vec4 cola = textureGrad( mapper, uv + offa, dx, dy );
			    vec4 colb = textureGrad( mapper, uv + offb, dx, dy );
			    
			    // ========== 步骤7：调试模式特殊处理 ==========
			    if( debugNoise == 1.0 ){
			    	// 调试模式：用固定颜色代替实际纹理
			    	// 红色表示第一个虚拟纹理的采样区域
			    	cola = vec4( 0.1,0.0,0.0,1.0 );
			    	// 蓝色表示第二个虚拟纹理的采样区域
			    	colb = vec4( 0.0,0.0,1.0,1.0 );
			    	// 这样可以直观看到噪声如何划分纹理空间
			    }
			    
			    // ========== 步骤8：混合两个虚拟纹理 ==========
			    /**
			     * 混合因子考虑两个因素：
			     * 1. f：基于噪声小数部分的线性插值因子
			     * 2. 0.1*sum(cola-colb)：两个颜色的差异
			     * 
			     * 颜色差异调整：如果两个颜色差别大，提前开始混合
			     * 这样可以避免在高对比度边缘出现明显的接缝
			     * 
			     * smoothstep(0.2,0.8,...)：将混合因子限制在0.2-0.8之间
			     * 并在边界处平滑过渡，避免硬边缘
			     */
			    return mix( cola, colb, smoothstep(0.2,0.8,f-0.1*sum(cola-colb)) );
			}`;

			// ========== 纹理采样片段替换代码 ==========
			/**
			 * 这段代码替换Three.js标准的纹理采样逻辑
			 * #ifdef USE_MAP：条件编译，只有在使用纹理贴图时才包含此代码
			 */
			const map_fragment = /* glsl */ `
			#ifdef USE_MAP
				// 根据是否启用随机效果选择不同的纹理采样方式
				if( enableRandom == 1.0 ) 
					// 启用随机UV：使用自定义的无平铺纹理采样函数
					diffuseColor *= textureNoTile( map, vMapUv );
				else 
					// 禁用随机UV：使用Three.js标准的纹理采样函数
					diffuseColor *= texture2D( map, vMapUv );
			#endif
			`;

			// ========== 透明度贴图参数声明 ==========
			/**
			 * 定义溶解效果所需的uniform变量
			 * 这些变量将通过JavaScript传递到着色器
			 */
			const alphamap_pars_fragment = /* glsl */ `
			#ifdef USE_ALPHAMAP
				uniform sampler2D alphaMap;      // 透明度贴图（溶解贴图）
				uniform float disolve;           // 溶解程度（0.0-1.0）
				uniform float threshold;         // 溶解阈值（0.0-1.0）
			#endif
			`;

			// ========== 透明度贴图处理片段 ==========
			/**
			 * 溶解效果的核心算法
			 * 根据溶解贴图的值、溶解程度和阈值计算最终透明度
			 * 
			 * 算法原理：
			 * 1. 从溶解贴图采样一个值（vv）
			 * 2. 根据溶解程度(disolve)和阈值(threshold)计算溶解范围(r)
			 * 3. 判断vv是否在溶解范围内，计算混合因子(mixf)
			 * 4. 将混合因子赋给最终透明度
			 */
			const alphamap_fragment = /* glsl */ `
			#ifdef USE_ALPHAMAP
			    // 步骤1：采样溶解贴图，取绿色通道作为溶解值
			    // 绿色通道通常用于透明度信息
			    float vv = texture2D( alphaMap, vAlphaMapUv ).g;
			    
			    // 步骤2：计算溶解范围
			    // disolve * (1.0 + threshold * 2.0)：将溶解程度映射到扩展的范围
			    // - threshold：减去阈值，实现溶解区域的偏移
			    // 这样当disolve=0.5时，溶解区域在中间
			    float r = disolve * (1.0 + threshold * 2.0) - threshold;
			    
			    // 步骤3：计算混合因子（透明度）
			    // (vv - r)：计算溶解值与溶解范围的相对位置
			    // *(1.0/threshold)：归一化到[0,1]范围
			    // clamp(...)：限制在0.0到1.0之间
			    // 结果：在溶解范围内的值逐渐从1过渡到0
			    float mixf = clamp((vv - r)*(1.0/threshold), 0.0, 1.0);
			    
			    // 步骤4：应用最终透明度
			    // diffuseColor.a是Three.js材质的透明度通道
				diffuseColor.a = mixf;
			#endif
			`;

		</script>

	</body>
</html>