<!-- Three.js 贴花喷涂系统 - 详细功能与技术点分析
🎯 项目概述
这是一个基于WebGL的交互式3D贴花喷涂演示应用，使用Three.js框架构建。用户可以在一个3D人物头部模型表面点击喷涂自定义贴花，体验真实的贴花投影效果。

✨ 核心功能
1. 交互式贴花喷涂
点击喷涂：在模型表面任意位置点击，生成随机大小/颜色的贴花

实时预览：鼠标移动时显示交点位置和表面法线方向

贴花管理：支持清除所有贴花，重新开始喷涂

2. 可视化辅助系统
法线显示：用彩色线段可视化模型表面法线方向

交点指示：用彩色立方体显示当前鼠标指向的精确位置

性能监控：实时显示帧率(FPS)和渲染时间(MS)

3. 用户控制面板
大小控制：调节贴花的最小和最大缩放范围

旋转控制：开启/关闭贴花的随机旋转

一键清除：快速移除所有贴花

4. 3D场景控制
自由视角：鼠标拖拽旋转，滚轮缩放，右键平移

自适应窗口：自动适应浏览器窗口大小变化

高质量渲染：抗锯齿、sRGB色彩空间、多光源照明

🔧 主要技术点
1. Three.js核心架构
javascript
// 完整的三维图形管线
场景(Scene) → 相机(Camera) → 渲染器(Renderer)
    ↓
模型(Mesh) = 几何体(Geometry) + 材质(Material)
    ↓
贴花(Decal)作为子对象附加到模型
2. 贴花几何体生成技术
DecalGeometry原理
javascript
// 核心：将贴花"投影"到模型表面
new DecalGeometry(
    mesh,           // 目标模型
    position,       // 投影中心点
    orientation,    // 投影方向
    size            // 投影范围
);
表面贴合：计算模型与投影体的相交几何

多边形裁剪：生成贴合模型曲面的多边形

UV映射：保持贴图正确投影到变形后的几何体

Z-Fighting解决方案
javascript
polygonOffset: true,          // 启用多边形偏移
polygonOffsetFactor: -4,      // 偏移因子
depthWrite: false             // 禁用深度写入
防止贴花与模型表面深度冲突导致的闪烁

3. 光线投射与交互检测
坐标转换链
text
屏幕坐标(像素) → 标准化设备坐标(NDC) → 世界坐标(3D)
javascript
// 屏幕坐标转NDC（-1到1）
mouse.x = (clientX / width) * 2 - 1;
mouse.y = -(clientY / height) * 2 + 1;

// NDC转世界射线
raycaster.setFromCamera(mouse, camera);
交点计算
javascript
raycaster.intersectObject(mesh, false, intersects);
// 返回：交点坐标、面索引、法线向量等
法线变换
javascript
// 局部法线 → 世界法线
const normalMatrix = new THREE.Matrix3().getNormalMatrix(mesh.matrixWorld);
n.applyNormalMatrix(normalMatrix);
4. 材质与着色系统
Phong光照模型
环境光：均匀的基础照明

方向光x2：冷暖色调，增强立体感

高光计算：基于视线方向与法线的反射

多层纹理映射
javascript
{
    map: decalDiffuse,      // 漫反射贴图（颜色）
    normalMap: decalNormal, // 法线贴图（凹凸细节）
    specularMap: specularMap // 高光贴图（反射强度）
}
颜色空间管理
javascript
decalDiffuse.colorSpace = THREE.SRGBColorSpace;
// sRGB：符合人眼感知的非线性色彩
// Linear：线性色彩空间，用于物理计算
5. 性能优化技术
渲染顺序控制
javascript
m.renderOrder = decals.length;
// 确保新贴花显示在旧贴花之上
// 避免透明物体的渲染顺序问题
几何体重用
javascript
// 复用基础材质，只修改必要属性
const material = decalMaterial.clone();
material.color.setHex(Math.random() * 0xffffff);
高效的事件处理
javascript
// 区分点击与拖拽
let moved = false;
controls.addEventListener('change', () => moved = true);
window.addEventListener('pointerdown', () => moved = false);
6. 资源加载与管理
GLTF模型加载
javascript
const loader = new GLTFLoader();
loader.load('model.glb', (gltf) => {
    mesh = gltf.scene.children[0];
    // 异步加载，不阻塞主线程
});
纹理加载与缓存
javascript
const textureLoader = new THREE.TextureLoader();
// 自动处理重复加载、错误处理
7. 响应式设计
自适应布局
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();  // 必须调用
    renderer.setSize(window.innerWidth, window.innerHeight);
}
设备像素比适配
javascript
renderer.setPixelRatio(window.devicePixelRatio);
// Retina等高DPI屏幕显示优化
🎨 视觉效果特色
1. 真实的光照系统
双方向光（暖色+冷色）营造立体感

环境光填充阴影区域

Phong材质的高光反射效果

2. 贴花的视觉特性
透明度融合：边缘透明，自然过渡

法线细节：通过法线贴图增加表面纹理

随机变化：大小、旋转、颜色的随机组合

3. 交互反馈
实时法线可视化

鼠标位置精确指示

流畅的相机控制

📊 技术架构图
text
用户交互层
    ↓
事件处理层（点击、移动、窗口大小）
    ↓
Three.js核心层（场景、相机、渲染器）
    ├── 几何系统（DecalGeometry生成）
    ├── 材质系统（多层纹理、光照）
    ├── 光影系统（多光源、阴影）
    └── 物理系统（光线投射、碰撞检测）
    ↓
WebGL渲染层
    ↓
Canvas输出层
🔍 关键技术挑战与解决方案
挑战1：曲面贴花的精确投影
问题：在复杂曲面上投影平面贴花

解决方案：DecalGeometry的相交计算 + 多边形裁剪

挑战2：透明贴花的渲染顺序
问题：多个透明贴花叠加时渲染顺序混乱

解决方案：固定渲染顺序 + 深度测试优化

挑战3：实时交互的性能
问题：大量贴花时的性能下降

解决方案：几何体复用 + 高效的射线检测

🚀 扩展可能性
贴花库系统：多个贴花图案选择

撤销/重做功能：喷涂历史管理

贴花编辑：大小、旋转、位置的手动调整

物理模拟：贴花的重力、风力效果

多人协作：实时共享喷涂结果

导出功能：保存喷涂后的模型

📱 跨平台兼容性
桌面浏览器：Chrome、Firefox、Safari、Edge

移动设备：触摸屏适配（可扩展）

性能自适应：根据设备能力调整贴花数量和质量 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js贴花喷涂效果演示 -->
		<title>Three.js WebGL - 贴花喷涂效果演示</title>
		
		<!-- 字符编码设置为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		
		<!-- 
			视口设置：控制移动设备上的显示方式
			width=device-width: 宽度等于设备宽度
			user-scalable=no: 禁止用户手动缩放
			minimum-scale=1.0: 最小缩放比例为1.0
			maximum-scale=1.0: 最大缩放比例为1.0
		-->
		<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>

		<!-- 
			主要容器：用于承载Three.js渲染器生成的canvas元素
			id="container": 用于JavaScript中获取该DOM元素
		-->
		<div id="container"></div>
		
		<!-- 
			信息显示区域：显示项目信息和操作提示
			id="info": 用于CSS样式和JavaScript操作
		-->
		<div id="info">
			<!-- Three.js官方链接 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> - 贴花喷涂效果演示<br/>
			<!-- 操作提示 -->
			点击模型表面喷涂贴花 | 拖动鼠标旋转视角 | 滚轮缩放
		</div>

		<!-- 
			导入映射表(Import Map)：现代JavaScript模块导入配置
			作用：将模块标识符映射到实际的文件路径
			type="importmap": 指定脚本类型为导入映射表
		-->
		<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对象包含Vector3、Scene、WebGLRenderer等所有核心类
			import * as THREE from 'three';

			// 导入性能监控工具
			// Stats用于显示FPS（帧率）、MS（渲染时间）等性能指标
			import Stats from 'three/addons/libs/stats.module.js';
			
			// 导入轻量级GUI库
			// GUI用于创建参数控制面板，方便调试和交互
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// 导入轨道控制器
			// OrbitControls实现用鼠标拖拽、滚轮缩放、右键平移的相机控制
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
			
			// 导入GLTF模型加载器
			// GLTFLoader用于加载.glb/.gltf格式的3D模型文件
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// 导入贴花几何体生成器
			// DecalGeometry用于在模型表面生成贴花几何体
			import { DecalGeometry } from 'three/addons/geometries/DecalGeometry.js';

			// ==================== 全局变量声明 ====================
			
			// 获取渲染容器DOM元素的引用
			// container将作为Three.js渲染器的挂载点
			const container = document.getElementById( 'container' );

			// 核心Three.js对象变量
			let renderer;   // WebGL渲染器：负责将3D场景渲染到canvas
			let scene;      // 场景对象：包含所有3D对象（模型、灯光、相机等）
			let camera;     // 相机对象：定义观察3D场景的视角
			let stats;      // 性能统计对象：显示帧率等性能信息

			// 3D模型相关变量
			let mesh;       // 主要的3D模型网格对象：用于喷涂贴花的目标模型
			
			// 光线投射相关变量
			let raycaster;  // 光线投射器：计算鼠标点击与3D模型的交点
			let line;       // 辅助线段：可视化显示模型表面的法线方向

			// 交点信息对象：存储鼠标与模型交点的详细信息
			const intersection = {
				intersects: false,              // 布尔值：是否检测到交点
				point: new THREE.Vector3(),     // 交点坐标：3D空间中的位置（x,y,z）
				normal: new THREE.Vector3()     // 交点法线：模型表面在交点处的方向向量
			};
			
			// 鼠标标准化设备坐标
			// 范围：x从-1（左）到1（右），y从-1（下）到1（上）
			const mouse = new THREE.Vector2();
			
			// 交点结果数组：临时存储raycaster检测到的所有交点
			const intersects = [];

			// ==================== 纹理和材质初始化 ====================
			
			// 创建纹理加载器实例
			// 用于异步加载图片文件并转换为Three.js纹理对象
			const textureLoader = new THREE.TextureLoader();
			
			// 加载贴花漫反射纹理（颜色贴图）
			// 显示贴花的基本颜色和图案
			const decalDiffuse = textureLoader.load( 'textures/decal/decal-diffuse.png' );
			// 设置颜色空间为sRGB，确保颜色显示正确（更符合人眼感知）
			decalDiffuse.colorSpace = THREE.SRGBColorSpace;
			
			// 加载贴花法线纹理
			// 用于模拟表面凹凸细节，增加立体感
			const decalNormal = textureLoader.load( 'textures/decal/decal-normal.jpg' );

			// 创建贴花基础材质（Phong光照模型）
			const decalMaterial = new THREE.MeshPhongMaterial( {
				specular: 0x444444,            // 高光颜色：浅灰色，控制反射高光的颜色
				map: decalDiffuse,             // 漫反射贴图：贴花的基础颜色纹理
				normalMap: decalNormal,        // 法线贴图：增加表面细节的凹凸感
				normalScale: new THREE.Vector2( 1, 1 ),  // 法线贴图强度：x和y方向的缩放
				shininess: 30,                 // 高光亮度：值越大，高光点越小越亮
				transparent: true,             // 启用透明度：允许材质有透明部分
				depthTest: true,               // 深度测试：确保贴花被遮挡时不显示
				depthWrite: false,             // 深度写入：关闭，防止贴花影响后续渲染的深度
				polygonOffset: true,           // 多边形偏移：启用，解决z-fighting问题
				polygonOffsetFactor: - 4,      // 偏移因子：负值使贴花稍微浮在模型表面
				wireframe: false               // 线框模式：关闭，显示完整面片而非线框
			} );

			// ==================== 贴花管理系统 ====================
			
			// 贴花对象数组：存储所有已创建的贴花网格
			// 用于统一管理和批量清除贴花
			const decals = [];
			
			// 鼠标辅助对象：可视化显示鼠标指向的位置和方向
			let mouseHelper;
			
			// 贴花变换参数：存储单个贴花的位置、旋转和大小
			const position = new THREE.Vector3();      // 位置向量（x,y,z）
			const orientation = new THREE.Euler();     // 旋转欧拉角（x,y,z轴旋转）
			const size = new THREE.Vector3( 10, 10, 10 ); // 大小向量（初始10x10x10单位）

			// ==================== GUI控制参数 ====================
			
			// 用户可调节的参数对象
			// 这些参数会通过GUI面板暴露给用户
			const params = {
				minScale: 10,      // 贴花最小缩放比例（范围1-30）
				maxScale: 20,      // 贴花最大缩放比例（范围1-30）
				rotate: true,      // 布尔值：是否随机旋转贴花
				clear: function () {  // 函数：清除所有贴花
					removeDecals();
				}
			};

			// ==================== 主初始化函数 ====================
			
			// 程序入口：调用初始化函数启动应用
			init();

			/**
			 * 初始化函数
			 * 设置Three.js环境、加载资源、绑定事件监听器
			 */
			function init() {
				// 创建WebGL渲染器实例
				// antialias: true 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				
				// 设置设备像素比
				// 在高DPI屏幕（如Retina）上使用更高分辨率渲染
				renderer.setPixelRatio( window.devicePixelRatio );
				
				// 设置渲染器尺寸为窗口大小
				// 使3D场景填满整个浏览器窗口
				renderer.setSize( window.innerWidth, window.innerHeight );
				
				// 设置动画循环回调函数
				// animate函数将在每一帧被调用（通常60fps）
				renderer.setAnimationLoop( animate );
				
				// 将渲染器的canvas元素添加到容器中
				// renderer.domElement就是<canvas>元素
				container.appendChild( renderer.domElement );

				// 初始化性能监控器
				stats = new Stats();
				// 将性能监控器的DOM元素添加到容器中
				container.appendChild( stats.dom );

				// 创建3D场景
				// 场景是所有3D对象（网格、灯光、相机）的容器
				scene = new THREE.Scene();

				// 创建透视相机
				// 参数：视野角度(FOV)45度，宽高比，近裁剪面1单位，远裁剪面1000单位
				camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 1000 );
				
				// 设置相机初始位置：沿z轴向后移动120单位
				// 这样可以从正面看到场景中心
				camera.position.z = 120;

				// 初始化轨道控制器
				// 将相机和渲染器的canvas元素关联
				const controls = new OrbitControls( camera, renderer.domElement );
				
				// 设置相机最小距离：防止相机过于接近模型
				controls.minDistance = 50;
				
				// 设置相机最大距离：防止相机过于远离模型
				controls.maxDistance = 200;

				// ==================== 光照设置 ====================
				
				// 添加环境光
				// 环境光提供均匀的基础照明，没有方向性
				// 参数：光照颜色（灰色），强度1.0
				scene.add( new THREE.AmbientLight( 0x666666 ) );

				// 添加第一个方向光（暖色调）
				// 方向光模拟太阳等远距离光源，有明确的方向
				const dirLight1 = new THREE.DirectionalLight( 0xffddcc, 3 );
				dirLight1.position.set( 1, 0.75, 0.5 );  // 设置光源位置
				scene.add( dirLight1 );

				// 添加第二个方向光（冷色调）
				// 使用冷暖两种色调的光源增加场景的色彩丰富度
				const dirLight2 = new THREE.DirectionalLight( 0xccccff, 3 );
				dirLight2.position.set( - 1, 0.75, - 0.5 );  // 设置相反方向的位置
				scene.add( dirLight2 );

				// ==================== 辅助可视化 ====================
				
				// 创建用于显示法线方向的线段几何体
				// 初始包含两个点（起点和终点）
				const geometry = new THREE.BufferGeometry();
				geometry.setFromPoints( [ new THREE.Vector3(), new THREE.Vector3() ] );

				// 创建线段对象：使用基础线条材质
				line = new THREE.Line( geometry, new THREE.LineBasicMaterial() );
				scene.add( line );

				// 加载3D模型
				loadLeePerrySmith();

				// 初始化光线投射器
				// 用于计算鼠标点击与3D模型的交点
				raycaster = new THREE.Raycaster();

				// 创建鼠标辅助对象：一个小长方体
				// 用于可视化显示鼠标指向的位置和表面方向
				mouseHelper = new THREE.Mesh( 
					new THREE.BoxGeometry( 1, 1, 10 ),  // 几何体：1x1x10的长方体
					new THREE.MeshNormalMaterial()      // 材质：法线材质（根据方向显示不同颜色）
				);
				mouseHelper.visible = false;  // 默认隐藏，只有在检测到交点时显示
				scene.add( mouseHelper );

				// ==================== 窗口事件监听 ====================
				
				// 监听窗口大小变化事件
				// 当浏览器窗口改变大小时，调整渲染器和相机
				window.addEventListener( 'resize', onWindowResize );

				// 跟踪用户是否移动了相机（通过轨道控制器）
				// 用于区分"点击"和"拖拽"操作
				let moved = false;

				// 监听轨道控制器的变化事件
				// 当用户拖拽、缩放或平移相机时触发
				controls.addEventListener( 'change', function () {
					moved = true;  // 标记相机已被移动
				} );

				// 监听鼠标按下事件
				window.addEventListener( 'pointerdown', function () {
					moved = false;  // 重置移动标志，假设用户是点击而非拖拽
				} );

				// 监听鼠标释放事件
				window.addEventListener( 'pointerup', function ( event ) {
					// 如果相机没有被移动（即用户没有进行拖拽操作）
					if ( moved === false ) {
						// 检查鼠标位置与模型的交点
						checkIntersection( event.clientX, event.clientY );
						
						// 如果检测到交点，发射贴花
						if ( intersection.intersects ) shoot();
					}
				} );

				// 监听鼠标移动事件
				window.addEventListener( 'pointermove', onPointerMove );

				// 鼠标移动事件处理函数
				function onPointerMove( event ) {
					// 只处理主指针事件（防止多指触控干扰）
					if ( event.isPrimary ) {
						// 实时检测鼠标位置与模型的交点
						checkIntersection( event.clientX, event.clientY );
					}
				}

				// ==================== 交点检测函数 ====================
				
				/**
				 * 检查鼠标位置与3D模型的交点
				 * @param {number} x - 鼠标在屏幕上的X坐标（像素）
				 * @param {number} y - 鼠标在屏幕上的Y坐标（像素）
				 */
				function checkIntersection( x, y ) {
					// 如果模型尚未加载完成，直接返回
					if ( mesh === undefined ) return;

					// 将屏幕像素坐标转换为标准化设备坐标（NDC）
					// NDC范围：x从-1（左）到1（右），y从-1（下）到1（上）
					mouse.x = ( x / window.innerWidth ) * 2 - 1;
					mouse.y = - ( y / window.innerHeight ) * 2 + 1;

					// 设置光线投射器：从相机位置向鼠标方向发射射线
					raycaster.setFromCamera( mouse, camera );
					
					// 计算射线与模型的交点
					// 参数：目标模型、是否检测子对象、存储结果的数组
					raycaster.intersectObject( mesh, false, intersects );

					// 如果检测到交点
					if ( intersects.length > 0 ) {
						// 获取第一个交点（最接近相机的交点）
						const p = intersects[ 0 ].point;
						
						// 更新鼠标辅助对象的位置到交点
						mouseHelper.position.copy( p );
						
						// 存储交点坐标
						intersection.point.copy( p );

						// 计算模型的法线矩阵
						// 法线矩阵用于将模型局部空间的法线转换到世界空间
						const normalMatrix = new THREE.Matrix3().getNormalMatrix( mesh.matrixWorld );

						// 计算交点处的法线方向
						// 1. 获取交点的面法线（局部空间）
						const n = intersects[ 0 ].face.normal.clone();
						
						// 2. 应用法线矩阵，转换到世界空间
						n.applyNormalMatrix( normalMatrix );
						
						// 3. 缩放法线向量并加到交点位置，得到法线末端点
						n.multiplyScalar( 10 );
						n.add( intersects[ 0 ].point );

						// 存储法线方向
						intersection.normal.copy( intersects[ 0 ].face.normal );
						
						// 让鼠标辅助对象朝向法线方向
						// lookAt()使物体的-z轴指向目标位置
						mouseHelper.lookAt( n );

						// 更新法线显示线段
						// 线段从交点开始，沿着法线方向延伸
						const positions = line.geometry.attributes.position;
						positions.setXYZ( 0, p.x, p.y, p.z );  // 起点：交点位置
						positions.setXYZ( 1, n.x, n.y, n.z );  // 终点：法线延伸位置
						positions.needsUpdate = true;           // 标记几何体需要更新

						// 标记检测到交点
						intersection.intersects = true;

						// 清空交点数组，为下一次检测做准备
						intersects.length = 0;

					} else {
						// 没有检测到交点
						intersection.intersects = false;
					}
				}

				// ==================== GUI控制面板设置 ====================
				
				// 创建GUI实例
				const gui = new GUI();
				
				// 添加最小缩放滑块：控制贴花的最小大小
				// 参数：目标对象，属性名，最小值，最大值
				gui.add( params, 'minScale', 1, 30 );
				
				// 添加最大缩放滑块：控制贴花的最大大小
				gui.add( params, 'maxScale', 1, 30 );
				
				// 添加旋转复选框：控制是否随机旋转贴花
				gui.add( params, 'rotate' );
				
				// 添加清除按钮：点击时执行清除函数
				gui.add( params, 'clear' );
				
				// 默认打开GUI面板
				gui.open();
			}

			// ==================== 3D模型加载函数 ====================
			
			/**
			 * 加载LeePerrySmith头部模型
			 * 这是一个高质量的人头模型，常用于Three.js示例
			 */
			function loadLeePerrySmith() {
				// 加载模型的漫反射贴图（颜色贴图）
				const map = textureLoader.load( 'models/gltf/LeePerrySmith/Map-COL.jpg' );
				map.colorSpace = THREE.SRGBColorSpace;  // 设置颜色空间为sRGB
				
				// 加载高光贴图：控制表面不同区域的反射强度
				const specularMap = textureLoader.load( 'models/gltf/LeePerrySmith/Map-SPEC.jpg' );
				
				// 加载法线贴图：增加表面细节的凹凸感
				const normalMap = textureLoader.load( 'models/gltf/LeePerrySmith/Infinite-Level_02_Tangent_SmoothUV.jpg' );

				// 创建GLTF加载器实例
				const loader = new GLTFLoader();

				// 异步加载GLB模型文件
				loader.load( 
					'models/gltf/LeePerrySmith/LeePerrySmith.glb',  // 模型文件路径
					
					// 加载完成后的回调函数
					function ( gltf ) {
						// gltf.scene包含整个场景，我们取第一个子对象（头部模型）
						mesh = gltf.scene.children[ 0 ];
						
						// 为模型创建新的材质（Phong光照模型）
						mesh.material = new THREE.MeshPhongMaterial( {
							specular: 0x111111,       // 高光颜色：深灰色
							map: map,                 // 漫反射贴图
							specularMap: specularMap, // 高光贴图
							normalMap: normalMap,     // 法线贴图
							shininess: 25             // 高光亮度
						} );

						// 将模型添加到场景中
						scene.add( mesh );
						
						// 将模型放大10倍，使其在场景中更显眼
						mesh.scale.multiplyScalar( 10 );
					}
				);
			}

			// ==================== 贴花发射函数 ====================
			
			/**
			 * 在交点处发射（创建）一个新的贴花
			 * 根据当前参数随机生成贴花的大小、旋转和颜色
			 */
			function shoot() {
				// 设置贴花位置：交点坐标
				position.copy( intersection.point );
				
				// 设置贴花方向：鼠标辅助对象的旋转角度
				orientation.copy( mouseHelper.rotation );

				// 如果启用了随机旋转，绕Z轴随机旋转
				if ( params.rotate ) {
					// 生成0到2π之间的随机角度（0到360度）
					orientation.z = Math.random() * 2 * Math.PI;
				}

				// 在最小值和最大值之间随机生成贴花大小
				const scale = params.minScale + Math.random() * ( params.maxScale - params.minScale );
				size.set( scale, scale, scale );  // 设置三个轴相同的缩放值

				// 克隆贴花基础材质
				// 使用clone()而不是直接赋值，使每个贴花可以有独立属性
				const material = decalMaterial.clone();
				
				// 随机设置贴花颜色
				// 0xffffff是白色，Math.random()*0xffffff生成随机RGB颜色
				material.color.setHex( Math.random() * 0xffffff );

				// 创建贴花网格对象
				// DecalGeometry在模型表面生成几何体，使其完美贴合曲面
				const m = new THREE.Mesh( 
					new DecalGeometry( mesh, position, orientation, size ),  // 贴花几何体
					material  // 贴花材质
				);
				
				// 设置渲染顺序：按创建顺序递增
				// 确保新贴花显示在旧贴花之上
				m.renderOrder = decals.length;

				// 将新贴花添加到管理数组
				decals.push( m );

				// 将贴花附加到模型上（作为模型的子对象）
				// 这样贴花会跟随模型移动/旋转
				mesh.attach( m );
			}

			// ==================== 贴花管理函数 ====================
			
			/**
			 * 移除所有贴花
			 * 清空贴花数组并从模型中移除所有贴花对象
			 */
			function removeDecals() {
				// 遍历所有贴花对象
				decals.forEach( function ( d ) {
					// 从父对象（模型）中移除贴花
					mesh.remove( d );
				} );

				// 清空贴花数组
				decals.length = 0;
			}

			// ==================== 窗口大小变化处理 ====================
			
			/**
			 * 窗口大小变化事件处理函数
			 * 调整相机和渲染器以适应新的窗口尺寸
			 */
			function onWindowResize() {
				// 更新相机的宽高比
				// 防止场景拉伸或压缩
				camera.aspect = window.innerWidth / window.innerHeight;
				
				// 更新相机的投影矩阵
				// 必须调用此方法才能使宽高比变更生效
				camera.updateProjectionMatrix();

				// 更新渲染器大小
				// 使canvas填满整个窗口
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 动画循环函数 ====================
			
			/**
			 * 动画循环函数
			 * 每一帧被调用，负责渲染场景和更新性能统计
			 */
			function animate() {
				// 渲染场景：将3D场景绘制到canvas
				// 参数：场景对象、相机对象
				renderer.render( scene, camera );

				// 更新性能监控器显示
				// 计算并显示当前帧率等性能指标
				stats.update();
			}

		</script>

	</body>
</html>