<!-- Three.js WebXR图层技术演示 - 功能详解
🎯 核心功能概述
这是一个基于Three.js的WebXR综合演示应用，展示了如何在虚拟现实环境中集成多种类型的内容呈现。应用包含一个主VR场景，其中嵌入了三个独立的XR图层，每个图层展示不同类型的内容和交互方式。

🏗️ 系统架构
text
主VR场景（房间环境）
├── 过山车图层（圆柱投影）
├── 马动画图层（平面投影）
└── GUI控制面板图层（平面投影）
🎪 三大核心功能模块
1. 主场景 - 物理模拟房间
环境：6×6×6米的线框立方体房间

物理系统：200个彩色小球的重力和碰撞模拟

交互：通过VR控制器可以发射小球

光照：环境光+定向光的真实光照系统

2. 过山车图层 - 沉浸式体验
展示方式：圆柱形投影，提供环绕式观看体验

核心内容：

复杂的参数化过山车轨道

随轨道运动的第一人称视角相机

完整的环境（地面、树木、天空、游乐设施）

动态阴影和光照效果

交互：可以用控制器"拿起"整个过山车场景

3. 马动画图层 - 3D模型展示
展示方式：平面四边形，类似"画中画"

核心内容：

从GLTF文件加载的马模型

骨骼动画系统（行走/奔跑动画）

动态相机环绕拍摄

专业的三点布光系统

交互：点击可以隐藏/显示马模型

4. GUI图层 - 交互式控制面板
展示方式：平面四边形，类似浮动面板

核心内容：

使用dat.GUI创建的参数控制界面

HTMLMesh技术将2D HTML转换为3D可交互对象

完整的鼠标事件转发系统

交互：可以在VR中直接操作滑块和按钮

🔧 主要技术亮点
🎮 WebXR高级特性
XR图层系统：

createQuadLayer()：创建平面投影图层

createCylinderLayer()：创建圆柱投影图层

每个图层独立渲染，性能优化

控制器集成：

完整的6DoF控制器支持

控制器模型自动匹配（Oculus、Vive等）

射线交互系统

挤压和选择两种交互模式

⚛️ 物理引擎模拟
碰撞检测系统：

球体与AABB边界碰撞

球体与球体之间的碰撞

动量守恒和能量损失模拟

运动模拟：

基于时间的积分运动

重力加速度（9.8 m/s²）

空气阻力模拟

🎨 图形技术
曲线动画系统：

javascript
// 参数化三维曲线
x = sin(3t) * cos(4t) * 100
y = sin(10t)*2 + cos(17t)*2 + 5
z = sin(t) * sin(4t) * 100
自定义几何体：

RollerCoasterGeometry：专门优化的轨道几何

TreesGeometry：程序化生成的树木

SkyGeometry：天空穹顶

材质系统：

MeshLambertMaterial：漫反射材质（小球）

MeshPhongMaterial：高光材质（轨道）

MeshBasicMaterial：无光照材质（GUI）

🔄 动画系统
过山车运动：

基于曲线参数的平滑运动

切线方向自动计算

坡度影响速度的动态系统

GLTF动画：

AnimationMixer动画混合器

骨骼动画播放控制

时间同步和插值

🖱️ 交互系统
事件转发机制：

javascript
// VR控制器事件 → 传统鼠标事件
dispatchEvent({ 
  type: 'mousedown', 
  data: { x: uv.x, y: 1 - uv.y }
})
射线检测：

控制器射线与世界坐标转换

UV坐标计算和映射

图层拾取和拖拽

🚀 性能优化
渲染优化：

WebGPU后端支持

多视图渲染（Multiview）

图层独立更新

内存管理：

几何体复用（小球共用同一几何）

纹理共享

对象池模式（小球循环使用）

🎮 交互体验流程
VR用户操作流程：
进入场景：点击VR按钮进入虚拟现实模式

观察环境：看到房间、三个图层和飘浮的小球

控制器交互：

选择按钮：点击图层进行交互（隐藏马、拾取过山车、操作GUI）

挤压按钮：按住发射小球

控制器指向：指向GUI图层操作控制面板

移动体验：在房间内自由移动，从不同角度观看各个图层

非VR用户操作流程：
鼠标控制：使用鼠标旋转视角

键盘控制：WASD移动，空格跳跃

📊 技术栈总结
技术领域	使用技术	目的
渲染引擎	Three.js + WebGPU	高性能3D渲染
VR框架	WebXR API	虚拟现实支持
物理模拟	自定义物理引擎	碰撞和运动
模型格式	GLTF 2.0	3D模型加载
动画系统	Three.js Animation	骨骼和关键帧动画
UI框架	dat.GUI + HTMLMesh	VR中的2D界面
数学计算	向量/矩阵运算	3D变换和投影 -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js WebXR图层演示 -->
		<title>Three.js WebXR - XR图层技术演示</title>
		<!-- 字符编码设置：UTF-8支持中文 -->
		<meta charset="utf-8">
		<!-- 视口设置：适配移动设备，禁止用户缩放 -->
		<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
		<!-- 引入CSS样式表 -->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
	<body>
		<!-- 信息显示区域：展示项目信息和链接 -->
		<div id="info">
			<!-- 链接到Three.js官方网站 -->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> WebXR虚拟现实 - XR图层技术演示<br>
			<small>包含过山车场景、马模型动画和交互式GUI</small>
		</div>

		<!-- 导入映射配置：定义模块路径别名，解决模块导入路径问题 -->
		<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模块 -->
		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js核心模块（WebGPU版本）
			// WebGPU是新一代图形API，相比WebGL有更好的性能
			import * as THREE from 'three/webgpu';

			// 导入几何体模块：BoxLineGeometry用于创建线框立方体
			import { BoxLineGeometry } from 'three/addons/geometries/BoxLineGeometry.js';
			
			// 导入WebXR相关模块
			import { VRButton } from 'three/addons/webxr/VRButton.js';  // 创建VR进入按钮
			import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';  // 控制器模型工厂
			
			// 导入GLTF加载器：用于加载GLTF格式的3D模型
			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
			
			// 导入交互组件：InteractiveGroup用于管理可交互对象
			import { InteractiveGroup } from 'three/addons/interactive/InteractiveGroup.js';
			
			// 导入过山车相关几何体：专门为过山车场景设计的几何体
			import {
				RollerCoasterGeometry,        // 过山车轨道几何体
				RollerCoasterShadowGeometry,  // 过山车阴影几何体
				RollerCoasterLiftersGeometry, // 支撑结构几何体
				TreesGeometry,                // 树木几何体
				SkyGeometry                   // 天空几何体
			} from 'three/addons/misc/RollerCoaster.js';
			
			// 导入HTML网格渲染器：将HTML元素转换为3D网格对象
			import { HTMLMesh } from 'three/addons/interactive/HTMLMesh.js';
			
			// 导入GUI库：创建用户界面控件
			import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

			// ==================== 全局变量声明区域 ====================
			
			// 主场景相关变量
			let camera, scene, renderer;           // 主场景的相机、场景、渲染器
			
			// XR控制器相关变量
			let controller1, controller2;          // 两个XR控制器（逻辑控制器）
			let controllerGrip1, controllerGrip2;  // 控制器的握把模型（视觉模型）
			
			// 房间（边界）对象
			let room;  // 用于限定物理模拟区域的线框立方体
			
			// 物理模拟相关变量
			let count = 0;                          // 用于轮询房间中的物体（小球）
			const radius = 0.08;                    // 小球的半径（单位：米）
			let normal = new THREE.Vector3();       // 用于碰撞检测的法向量
			const relativeVelocity = new THREE.Vector3();  // 用于计算碰撞的相对速度
			
			// 时间相关变量
			const clock = new THREE.Clock();       // Three.js时钟对象，用于时间计算
			
			// 过山车场景相关变量
			const funfairs = [];                   // 游乐设施数组（旋转的圆柱体）
			const train = new THREE.Object3D();    // 过山车列车对象
			const rcdelta = clock.getDelta() * 0.8; // 过山车模拟的时间增量（减速因子0.8）
			const PI2 = Math.PI * 2;               // 2π常量，用于角度计算
			let rccamera = null;                   // 过山车场景的相机（第一人称视角）
			let rcscene = null;                    // 过山车场景（独立于主场景）
			
			// 矩阵和射线检测相关
			const tempMatrix = new THREE.Matrix4(); // 临时矩阵，用于坐标变换
			let raycaster = null;                   // 射线检测器，用于控制器交互
			
			// ==================== 过山车轨道曲线定义 ====================
			// 使用闭包创建曲线对象，避免污染全局命名空间
			const curve = ( function () {
				// 内部使用的临时向量
				const vector = new THREE.Vector3();
				const vector2 = new THREE.Vector3();

				return {
					// 获取曲线上参数t对应的点位置
					// t ∈ [0,1]，通过参数方程定义复杂的三维曲线
					getPointAt: function ( t ) {
						t = t * PI2;  // 将[0,1]映射到[0,2π]，实现完整循环
						
						// 三维参数方程：通过三角函数组合创建复杂的空间曲线
						// x = sin(3t) * cos(4t) * 50 * 2
						// y = sin(10t)*2 + cos(17t)*2 + 5 + 0.3
						// z = sin(t) * sin(4t) * 50 * 2
						const x = Math.sin( t * 3 ) * Math.cos( t * 4 ) * 50;
						const y = Math.sin( t * 10 ) * 2 + Math.cos( t * 17 ) * 2 + 5;
						const z = Math.sin( t ) * Math.sin( t * 4 ) * 50;

						// 返回向量并放大2倍
						return vector.set( x, y, z ).multiplyScalar( 2 );
					},

					// 获取曲线上参数t对应的切线方向（导数）
					getTangentAt: function ( t ) {
						const delta = 0.0001;  // 微小增量，用于数值微分计算
						const t1 = Math.max( 0, t - delta );  // 前一点参数
						const t2 = Math.min( 1, t + delta );  // 后一点参数

						// 计算切线方向：通过两点差商的极限近似
						// 切线 = (P(t+Δt) - P(t-Δt)) / (2Δt)
						return vector2.copy( this.getPointAt( t2 ) )
							.sub( this.getPointAt( t1 ) ).normalize();  // 归一化得到单位向量
					}
				};
			} )();

			// ==================== 马动画相关变量 ====================
			let horseCamera = null;         // 马场景的相机（透视相机）
			let horseScene = null;          // 马场景（独立于主场景）
			let horseMixer = null;          // 动画混合器，用于控制模型动画
			let horseTheta = 0;             // 马相机的旋转角度（弧度）
			let horseMesh = null;           // 马的网格模型（从GLTF加载）
			const horseRadius = 600;        // 马相机绕行半径（单位：米）

			// ==================== GUI相关变量 ====================
			let guiScene = null;            // GUI场景（正交投影）
			let guiCamera = null;           // GUI相机（正交相机，用于2D界面）
			let guiGroup = null;            // 交互组，包含可交互的GUI元素

			// ==================== XR图层相关变量 ====================
			// XR图层是WebXR的重要特性，允许将不同的3D内容渲染到不同的纹理层
			let rollercoasterLayer = null;  // 过山车图层（圆柱图层）
			let horseLayer = null;          // 马动画图层（四边形图层）
			let guiLayer = null;            // GUI图层（四边形图层）

			// ==================== GUI参数配置 ====================
			// 这些参数用于控制GUI中的滑块，目前仅作展示用途
			const parameters = {
				radius: 0.6,             // 半径参数
				tube: 0.2,               // 管状参数
				tubularSegments: 150,    // 管状分段数
				radialSegments: 20,      // 径向分段数
				p: 2,                    // 数学参数p（用于几何形状）
				q: 3,                    // 数学参数q（用于几何形状）
				thickness: 0.5           // 厚度参数
			};

			// ==================== 初始化函数调用 ====================
			init();  // 启动应用初始化

			// ==================== 辅助函数定义 ====================
			
			/**
			 * 获取控制器射线与场景物体的交点
			 * @param {THREE.Object3D} controller - XR控制器对象
			 * @returns {Array} 交点数组，包含所有相交的物体和交点信息
			 */
			function getIntersections( controller ) {
				// 从控制器世界矩阵中提取旋转部分到临时矩阵
				tempMatrix.identity().extractRotation( controller.matrixWorld );

				// 设置射线起点：控制器的世界坐标位置
				raycaster.ray.origin.setFromMatrixPosition( controller.matrixWorld );
				
				// 设置射线方向：控制器前方（Z轴负方向），考虑控制器旋转
				raycaster.ray.direction.set( 0, 0, - 1 ).applyMatrix4( tempMatrix );

				// 执行射线检测：检测与场景中所有子物体的交点
				return raycaster.intersectObjects( scene.children, false );
			}

			// ==================== 主初始化函数 ====================
			/**
			 * 初始化整个Three.js应用
			 * 包括：场景、相机、渲染器、控制器、XR图层等所有组件
			 */
			function init() {
				// ---------- 1. 创建主场景 ----------
				scene = new THREE.Scene();
				scene.background = new THREE.Color( 0x505050 );  // 设置场景背景色为中灰色
				
				// 创建射线检测器实例
				raycaster = new THREE.Raycaster();

				// ---------- 2. 创建主相机 ----------
				// 使用透视相机模拟人眼视角
				camera = new THREE.PerspectiveCamera( 
					50,                                 // 视野角度（FOV）
					window.innerWidth / window.innerHeight, // 宽高比
					0.1,                                // 近裁剪面
					10                                  // 远裁剪面
				);
				camera.position.set( 0, 1.6, 3 );  // 设置相机位置：X=0, Y=1.6（人眼高度）, Z=3

				// ---------- 3. 创建房间（物理边界） ----------
				// 使用BoxLineGeometry创建6x6x6米的线框立方体
				room = new THREE.LineSegments(
					// 参数：宽度、高度、深度、宽度分段、高度分段、深度分段
					new BoxLineGeometry( 6, 6, 6, 10, 10, 10 ),
					new THREE.LineBasicMaterial( { color: 0x808080 } )  // 灰色线框材质
				);
				room.geometry.translate( 0, 3, 0 );  // 将几何体上移3米，使房间底部在Y=0处
				scene.add( room );

				// ---------- 4. 添加光照 ----------
				// 半球光：模拟天空和地面的环境光照
				scene.add( new THREE.HemisphereLight( 0x606060, 0x404040 ) );
				
				// 平行光：模拟太阳光，产生阴影和明暗对比
				const light = new THREE.DirectionalLight( 0xffffff );
				light.position.set( 1, 1, 1 ).normalize();  // 设置方向并归一化
				scene.add( light );

				// ---------- 5. 创建物理小球 ----------
				// 使用二十面体几何体创建近似球形
				const geometry = new THREE.IcosahedronGeometry( radius, 3 );  // 参数：半径，细分级别

				// 创建200个随机颜色和位置的小球
				for ( let i = 0; i < 200; i ++ ) {
					// 创建网格对象：几何体 + Lambert材质（漫反射）
					const object = new THREE.Mesh( 
						geometry, 
						new THREE.MeshLambertMaterial( { 
							color: Math.random() * 0xffffff  // 随机颜色
						} ) 
					);

					// 设置随机位置在房间内
					object.position.x = Math.random() * 4 - 2;  // X: [-2, 2]
					object.position.y = Math.random() * 4;      // Y: [0, 4]
					object.position.z = Math.random() * 4 - 2;  // Z: [-2, 2]

					// 为每个小球存储初始速度（用户数据）
					object.userData.velocity = new THREE.Vector3();
					object.userData.velocity.x = Math.random() * 0.01 - 0.005;  // X速度：[-0.005, 0.005]
					object.userData.velocity.y = Math.random() * 0.01 - 0.005;  // Y速度：[-0.005, 0.005]
					object.userData.velocity.z = Math.random() * 0.01 - 0.005;  // Z速度：[-0.005, 0.005]

					room.add( object );  // 将小球添加到房间中
				}

				// ---------- 6. 创建WebGPU渲染器 ----------
				renderer = new THREE.WebGPURenderer( { 
					antialias: true,                  // 启用抗锯齿，平滑边缘
					forceWebGL: true,                 // 如果WebGPU不可用，强制回退到WebGL
					outputBufferType: THREE.UnsignedByteType,  // 输出缓冲区类型：无符号字节
					multiview: true                   // 启用多视图，VR中为每只眼睛单独渲染
				} );
				
				// 设置渲染器属性
				renderer.setPixelRatio( window.devicePixelRatio );  // 考虑设备像素比
				renderer.setSize( window.innerWidth, window.innerHeight );  // 设置渲染尺寸
				renderer.setAnimationLoop( render );  // 设置动画循环回调函数
				renderer.xr.enabled = true;  // 启用WebXR支持
				
				// 将渲染器的Canvas元素添加到页面
				document.body.appendChild( renderer.domElement );

				// ---------- 7. 创建VR按钮 ----------
				// VRButton会自动检测设备VR能力并创建合适的按钮
				document.body.appendChild( VRButton.createButton( renderer ) );

				// ---------- 8. 定义控制器事件处理函数 ----------
				
				/**
				 * 挤压开始事件处理
				 * 当用户按下控制器上的挤压按钮时触发
				 */
				function onSqueezeStart( ) {
					this.userData.isSelecting = true;  // 标记控制器为选择状态
				}

				/**
				 * 挤压结束事件处理
				 * 当用户释放控制器上的挤压按钮时触发
				 */
				function onSqueezeEnd() {
					this.userData.isSelecting = false;  // 取消选择状态
				}

				/**
				 * 选择开始事件处理
				 * 当用户按下控制器上的选择按钮时触发
				 * @param {Event} event - 事件对象
				 */
				function onSelectStart( event ) {
					const controller = event.target;  // 获取触发事件的控制器
					const intersections = getIntersections( controller );  // 获取射线交点
					let hadSelection = false;  // 标记是否处理了选择

					// 遍历所有交点，处理与不同图层的交互
					for ( let x = 0; x < intersections.length; x ++ ) {
						// 情况1：与马图层交互 - 点击隐藏
						if ( intersections[ x ].object == horseLayer ) {
							horseLayer.visible = false;  // 隐藏马图层
							hadSelection = true;  // 标记已处理选择
						}

						// 情况2：与过山车图层交互 - 附加到控制器
						if ( intersections[ x ].object == rollercoasterLayer ) {
							// 将过山车图层附加到控制器，实现拾取效果
							controller.attach( rollercoasterLayer );
							hadSelection = true;  // 标记已处理选择
						}

						// 情况3：与GUI图层交互 - 转发鼠标事件
						if ( intersections[ x ].object == guiLayer ) {
							const uv = intersections[ x ].uv;  // 获取UV坐标（纹理坐标）
							// 将VR控制器事件转换为GUI能理解的鼠标事件
							guiGroup.children[ 0 ].dispatchEvent( { 
								type: 'mousedown',           // 事件类型：鼠标按下
								data: { 
									x: uv.x,                 // X坐标（归一化到[0,1]）
									y: 1 - uv.y              // Y坐标（反转，因为UV和屏幕Y轴方向相反）
								}, 
								target: guiGroup             // 事件目标
							} );
							hadSelection = true;  // 标记已处理选择
						}
					}

					// 如果没有与特定图层交互，则设置为选择模式（用于发射小球）
					this.userData.isSelecting = hadSelection === false;
				}

				/**
				 * 选择结束事件处理
				 * 当用户释放控制器上的选择按钮时触发
				 */
				function onSelectEnd( ) {
					// 恢复马图层的可见性
					horseLayer.visible = true;
					
					// 将过山车图层重新附加到场景（放下）
					scene.attach( rollercoasterLayer );
					
					// 发送鼠标抬起事件到GUI
					guiGroup.children[ 0 ].dispatchEvent( { 
						type: 'mouseup',     // 事件类型：鼠标抬起
						data: { x: 0, y: 0 }, // 坐标归零
						target: guiGroup      // 事件目标
					} );
					
					// 取消选择状态
					this.userData.isSelecting = false;
				}

				// ---------- 9. 设置控制器1 ----------
				controller1 = renderer.xr.getController( 0 );  // 获取第一个XR控制器
				
				// 添加事件监听器
				controller1.addEventListener( 'selectstart', onSelectStart );    // 选择开始
				controller1.addEventListener( 'selectend', onSelectEnd );        // 选择结束
				controller1.addEventListener( 'squeezestart', onSqueezeStart );  // 挤压开始
				controller1.addEventListener( 'squeezeend', onSqueezeEnd );      // 挤压结束
				
				// 控制器连接事件：当控制器成功连接时
				controller1.addEventListener( 'connected', function ( event ) {
					this.add( buildController( event.data ) );  // 添加控制器视觉表示
				} );
				
				// 控制器断开事件：当控制器断开连接时
				controller1.addEventListener( 'disconnected', function () {
					this.remove( this.children[ 0 ] );  // 移除控制器视觉表示
				} );
				
				scene.add( controller1 );  // 将控制器添加到场景

				// ---------- 10. 设置控制器2（与控制器1类似） ----------
				controller2 = renderer.xr.getController( 1 );  // 获取第二个XR控制器
				
				// 添加相同的事件监听器
				controller2.addEventListener( 'selectstart', onSelectStart );
				controller2.addEventListener( 'selectend', onSelectEnd );
				controller2.addEventListener( 'squeezestart', onSqueezeStart );
				controller2.addEventListener( 'squeezeend', onSqueezeEnd );
				controller2.addEventListener( 'connected', function ( event ) {
					this.add( buildController( event.data ) );
				} );
				controller2.addEventListener( 'disconnected', function () {
					this.remove( this.children[ 0 ] );
				} );
				
				scene.add( controller2 );

				// ---------- 11. 创建控制器模型工厂 ----------
				// XRControllerModelFactory会自动获取与用户设备匹配的控制器3D模型
				const controllerModelFactory = new XRControllerModelFactory();

				// 设置控制器1的握把模型（视觉部分）
				controllerGrip1 = renderer.xr.getControllerGrip( 0 );
				controllerGrip1.add( controllerModelFactory.createControllerModel( controllerGrip1 ) );
				scene.add( controllerGrip1 );

				// 设置控制器2的握把模型（视觉部分）
				controllerGrip2 = renderer.xr.getControllerGrip( 1 );
				controllerGrip2.add( controllerModelFactory.createControllerModel( controllerGrip2 ) );
				scene.add( controllerGrip2 );

				// ---------- 12. 窗口大小调整事件 ----------
				window.addEventListener( 'resize', onWindowResize );

				// ---------- 13. 设置过山车图层 ----------
				// createCylinderLayer创建圆柱形图层，内容显示在圆柱内表面
				rollercoasterLayer = renderer.xr.createCylinderLayer( 
					1,                          // 圆柱高度（米）
					Math.PI / 2,                // 弧度角度（90度）
					2,                          // 圆柱半径（米）
					new THREE.Vector3( 0, 1.5, - 0.5 ),  // 图层位置（世界坐标）
					new THREE.Quaternion(),      // 图层旋转（无旋转）
					1500,                       // 纹理宽度（像素）
					1000,                       // 纹理高度（像素）
					renderRollercoaster         // 渲染回调函数
				);
				scene.add( rollercoasterLayer );

				// ---------- 14. 初始化过山车场景 ----------
				rcscene = new THREE.Scene();
				rcscene.background = new THREE.Color( 0xf0f0ff );  // 浅蓝色背景

				// 添加过山车场景的半球光
				const rclight = new THREE.HemisphereLight( 0xfff0f0, 0x606066 );
				rclight.position.set( 1, 1, 1 );
				rcscene.add( rclight );

				rcscene.add( train );  // 将列车对象添加到过山车场景

				// 创建过山车场景的相机（第一人称视角）
				rccamera = new THREE.PerspectiveCamera( 50, 1, 0.1, 500 );
				train.add( rccamera );  // 将相机附加到列车上，跟随列车移动

				// ---------- 15. 创建过山车环境 ----------
				
				// 15.1 创建地面几何
				let rcgeometry = new THREE.PlaneGeometry( 500, 500, 15, 15 );
				rcgeometry.rotateX( - Math.PI / 2 );  // 旋转为水平面（X轴旋转-90度）

				// 随机化地面顶点高度，创建起伏地形
				const positions = rcgeometry.attributes.position.array;
				const vertex = new THREE.Vector3();

				for ( let i = 0; i < positions.length; i += 3 ) {
					vertex.fromArray( positions, i );  // 从数组读取顶点坐标

					// 添加随机偏移，使地面不规则
					vertex.x += Math.random() * 10 - 5;  // X方向偏移[-5,5]
					vertex.z += Math.random() * 10 - 5;  // Z方向偏移[-5,5]

					// 根据与场景中心的距离计算高度
					const distance = ( vertex.distanceTo( scene.position ) / 5 ) - 25;
					vertex.y = Math.random() * Math.max( 0, distance );  // 越远越高

					vertex.toArray( positions, i );  // 写回修改后的坐标
				}

				rcgeometry.computeVertexNormals();  // 重新计算法向量（用于光照）

				// 创建地面材质和网格
				let rcmaterial = new THREE.MeshLambertMaterial( {
					color: 0x407000  // 绿色地面
				} );

				let rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcscene.add( rcmesh );

				// 15.2 添加树木几何
				rcgeometry = new TreesGeometry( rcmesh );  // 基于地面生成树木
				rcmaterial = new THREE.MeshBasicMaterial( {
					side: THREE.DoubleSide,    // 双面渲染
					vertexColors: true         // 使用顶点颜色（TreesGeometry包含颜色数据）
				} );
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcscene.add( rcmesh );

				// 15.3 添加天空几何
				rcgeometry = new SkyGeometry();  // 天空穹顶
				rcmaterial = new THREE.MeshBasicMaterial( { color: 0xffffff } );  // 白色天空
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcscene.add( rcmesh );

				// 15.4 创建过山车轨道
				rcgeometry = new RollerCoasterGeometry( curve, 1500 );  // 基于曲线生成轨道
				rcmaterial = new THREE.MeshPhongMaterial( {
					vertexColors: true  // 使用顶点颜色（轨道不同部分可能有不同颜色）
				} );
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcscene.add( rcmesh );

				// 15.5 创建过山车支撑结构
				rcgeometry = new RollerCoasterLiftersGeometry( curve, 100 );  // 支撑柱
				rcmaterial = new THREE.MeshPhongMaterial();  // Phong材质（高光反射）
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcmesh.position.y = 0.1;  // 稍微抬高，避免与地面穿插
				rcscene.add( rcmesh );

				// 15.6 创建过山车阴影
				rcgeometry = new RollerCoasterShadowGeometry( curve, 500 );  // 投影到地面
				rcmaterial = new THREE.MeshBasicMaterial( {
					color: 0x305000,     // 深绿色阴影
					depthWrite: false,   // 禁用深度写入（阴影不需要写入深度缓冲）
					transparent: true    // 启用透明（阴影半透明）
				} );
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcmesh.position.y = 0.1;  // 贴近地面
				rcscene.add( rcmesh );

				// 15.7 添加游乐设施（装饰性圆柱体）
				// 第一个游乐设施：红色圆柱体
				rcgeometry = new THREE.CylinderGeometry( 10, 10, 5, 15 );  // 参数：顶部半径、底部半径、高度、分段数
				rcmaterial = new THREE.MeshLambertMaterial( {
					color: 0xff8080  // 红色
				} );
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcmesh.position.set( - 80, 10, - 70 );  // 设置位置
				rcmesh.rotation.x = Math.PI / 2;  // 绕X轴旋转90度（水平放置）
				rcscene.add( rcmesh );
				funfairs.push( rcmesh );  // 添加到游乐设施数组，用于后续动画

				// 第二个游乐设施：蓝色圆锥台
				rcgeometry = new THREE.CylinderGeometry( 5, 6, 4, 10 );  // 顶部半径5，底部半径6，形成锥台
				rcmaterial = new THREE.MeshLambertMaterial( {
					color: 0x8080ff  // 蓝色
				} );
				rcmesh = new THREE.Mesh( rcgeometry, rcmaterial );
				rcmesh.position.set( 50, 2, 30 );
				rcscene.add( rcmesh );
				funfairs.push( rcmesh );

				// ---------- 16. 设置马动画图层 ----------
				// createQuadLayer创建四边形图层，内容显示在矩形平面上
				horseLayer = renderer.xr.createQuadLayer( 
					1,                          // 图层宽度（米）
					1,                          // 图层高度（米）
					new THREE.Vector3( - 1.5, 1.5, - 1.5 ),  // 图层位置（左上方）
					new THREE.Quaternion(),      // 图层旋转
					800,                         // 纹理宽度（像素）
					800,                         // 纹理高度（像素）
					renderQuad                   // 渲染回调函数
				);
				scene.add( horseLayer );

				// 设置马图层的几何体为圆形（视觉装饰）
				horseLayer.geometry = new THREE.CircleGeometry( .5, 64 );  // 半径0.5米，64个分段

				// 初始化马场景相机
				horseCamera = new THREE.PerspectiveCamera( 50, 1, 1, 10000 );
				horseCamera.position.y = 300;  // 设置相机高度为300米（鸟瞰视角）

				// 初始化马场景
				horseScene = new THREE.Scene();
				horseScene.background = new THREE.Color( 0xf0f0f0 );  // 浅灰色背景

				// 添加马场景的灯光
				// 主光源：冷色调蓝色光
				const light1 = new THREE.DirectionalLight( 0xefefff, 1.5 );
				light1.position.set( 1, 1, 1 ).normalize();
				horseScene.add( light1 );

				// 补光：暖色调红色光
				const light2 = new THREE.DirectionalLight( 0xffefef, 1.5 );
				light2.position.set( - 1, - 1, - 1 ).normalize();
				horseScene.add( light2 );

				// 加载马的GLTF模型
				const loader = new GLTFLoader();
				loader.load( 'models/gltf/Horse.glb', function ( gltf ) {
					// 模型加载成功回调
					horseMesh = gltf.scene.children[ 0 ];  // 获取模型中的第一个网格
					horseMesh.scale.set( 1.5, 1.5, 1.5 );  // 放大1.5倍
					horseScene.add( horseMesh );

					// 创建动画混合器并播放动画
					horseMixer = new THREE.AnimationMixer( horseMesh );
					// 获取第一个动画剪辑，设置持续时间为1秒并播放
					horseMixer.clipAction( gltf.animations[ 0 ] ).setDuration( 1 ).play();
				} );

				// ---------- 17. GUI相关函数（占位） ----------
				// 这些函数在GUI参数变化时被调用，当前为空实现
				function onChange() { 
					// 当GUI参数变化时的处理函数（可在此添加参数更新逻辑）
				}
				
				function onThicknessChange() { 
					// 厚度参数变化的特殊处理函数
				}

				// ---------- 18. 设置GUI场景 ----------
				guiScene = new THREE.Scene();
				guiScene.background = new THREE.Color( 0x0 );  // 黑色背景

				// 使用正交相机渲染2D GUI（无透视效果）
				guiCamera = new THREE.OrthographicCamera( - 1, 1, 1, - 1, 0, 1 );
				guiScene.add( guiCamera );

				// 创建dat.GUI实例
				const gui = new GUI( { width: 300 } );
				
				// 添加各种参数控制器到GUI
				gui.add( parameters, 'radius', 0.0, 1.0 ).onChange( onChange );  // 半径滑块
				gui.add( parameters, 'tube', 0.0, 1.0 ).onChange( onChange );    // 管状参数滑块
				gui.add( parameters, 'tubularSegments', 10, 150, 1 ).onChange( onChange );  // 分段数滑块
				gui.add( parameters, 'radialSegments', 2, 20, 1 ).onChange( onChange );     // 径向分段滑块
				gui.add( parameters, 'p', 1, 10, 1 ).onChange( onChange );       // 参数p滑块
				gui.add( parameters, 'q', 0, 10, 1 ).onChange( onChange );       // 参数q滑块
				gui.add( parameters, 'thickness', 0, 1 ).onChange( onThicknessChange );  // 厚度滑块
				
				gui.domElement.style.visibility = 'hidden';  // 隐藏原始GUI DOM元素（只显示3D版本）

				// 创建交互组，用于处理GUI的交互事件
				guiGroup = new InteractiveGroup();
				guiScene.add( guiGroup );

				// 将GUI的DOM元素转换为3D网格
				const mesh = new HTMLMesh( gui.domElement );
				guiGroup.add( mesh );

				// 计算GUI场景的边界框，用于调整相机
				const bbox = new THREE.Box3().setFromObject( guiScene );

				// ---------- 19. 创建GUI图层 ----------
				guiLayer = renderer.xr.createQuadLayer( 
					1.2,                        // 图层宽度1.2米
					.8,                         // 图层高度0.8米
					new THREE.Vector3( 1.5, 1.5, - 1.5 ),  // 图层位置（右上方）
					new THREE.Quaternion(),      // 图层旋转
					1280,                       // 纹理宽度（像素）
					800,                        // 纹理高度（像素）
					renderGui                   // 渲染回调函数
				);
				scene.add( guiLayer );

				// 根据边界框调整正交相机的投影参数
				guiCamera.left = bbox.min.x;    // 左边界
				guiCamera.right = bbox.max.x;   // 右边界
				guiCamera.top = bbox.max.y;     // 上边界
				guiCamera.bottom = bbox.min.y;  // 下边界
				guiCamera.updateProjectionMatrix();  // 更新相机投影矩阵
			}

			// ==================== 图层渲染回调函数 ====================
			
			/**
			 * 渲染GUI场景的回调函数
			 * 在GUI图层需要更新时被调用
			 */
			function renderGui() {
				// 使用正交相机渲染GUI场景（2D界面）
				renderer.render( guiScene, guiCamera );
			}

			/**
			 * 渲染马动画场景的回调函数
			 * 在马图层需要更新时被调用
			 */
			function renderQuad() {
				// 更新马相机位置：围绕中心点旋转
				horseTheta += 0.1;  // 每次增加0.1弧度

				// 计算相机在圆周上的位置
				horseCamera.position.x = horseRadius * Math.sin( THREE.MathUtils.degToRad( horseTheta ) );
				horseCamera.position.z = horseRadius * Math.cos( THREE.MathUtils.degToRad( horseTheta ) );

				// 相机始终看向场景中心点(0, 150, 0)
				horseCamera.lookAt( 0, 150, 0 );

				// 更新马动画
				if ( horseMixer ) {
					const time = Date.now();  // 获取当前时间
					// 更新动画混合器：计算时间差并转换为秒
					horseMixer.update( ( time - prevTime ) * 0.001 );
					prevTime = time;  // 保存当前时间用于下一帧计算
				}

				// 渲染马场景
				renderer.render( horseScene, horseCamera );
			}

			// ==================== 过山车动画相关变量 ====================
			const rcposition = new THREE.Vector3();  // 列车当前位置
			const tangent = new THREE.Vector3();     // 轨道切线方向
			const lookAt = new THREE.Vector3();      // 列车朝向目标点

			let rcvelocity = 0;  // 过山车当前速度
			let progress = 0;    // 轨道进度（0到1之间）

			let prevTime = performance.now();  // 记录上一帧的时间（用于动画混合器）

			/**
			 * 渲染过山车场景的回调函数
			 * 在过山车图层需要更新时被调用
			 */
			function renderRollercoaster() {
				const time = performance.now();  // 获取高精度时间戳
				
				// 旋转游乐设施：随时间缓慢旋转
				for ( let i = 0; i < funfairs.length; i ++ ) {
					// 每个游乐设施绕Y轴旋转，速度与时间相关
					funfairs[ i ].rotation.y = time * 0.0004;
				}

				// 更新过山车位置
				progress += rcvelocity;  // 根据速度更新进度
				progress = progress % 1;  // 确保进度在[0,1)范围内循环

				// 获取当前进度对应的轨道位置
				rcposition.copy( curve.getPointAt( progress ) );
				rcposition.y += 0.3;  // 将列车稍微抬高，避免与轨道穿插

				// 更新列车位置
				train.position.copy( rcposition );

				// 获取当前点的切线方向
				tangent.copy( curve.getTangentAt( progress ) );

				// 根据轨道坡度调整速度：上坡减速，下坡加速
				// 切线方向的Y分量表示坡度（上坡为负，下坡为正）
				rcvelocity -= tangent.y * 0.0000001 * rcdelta;
				
				// 限制速度在合理范围内
				rcvelocity = Math.max( 0.00004, Math.min( 0.0002, rcvelocity ) );

				// 设置列车朝向：看向切线反方向的前方点
				train.lookAt( lookAt.copy( rcposition ).sub( tangent ) );

				// 渲染过山车场景
				renderer.render( rcscene, rccamera );
			}

			// ==================== 控制器视觉构建函数 ====================
			/**
			 * 根据控制器的目标射线模式构建不同的视觉表示
			 * @param {Object} data - 控制器数据，包含targetRayMode等信息
			 * @returns {THREE.Object3D} 控制器视觉对象
			 */
			function buildController( data ) {
				let geometry, material;

				switch ( data.targetRayMode ) {
					case 'tracked-pointer':  // 跟踪指针模式（如Oculus Touch、Vive控制器）
						// 创建射线几何：从原点到(0,0,-1)的线段
						geometry = new THREE.BufferGeometry();
						geometry.setAttribute( 'position', new THREE.Float32BufferAttribute( 
							[ 0, 0, 0, 0, 0, - 1 ],  // 两个点：起点和终点
							3  // 每个点3个分量（x,y,z）
						) );
						geometry.setAttribute( 'color', new THREE.Float32BufferAttribute( 
							[ 0.5, 0.5, 0.5, 0, 0, 0 ],  // 起点灰色，终点黑色
							3  // 每个颜色3个分量（r,g,b）
						) );

						// 使用线基本材质，启用顶点颜色和加法混合
						material = new THREE.LineBasicMaterial( { 
							vertexColors: true,       // 使用顶点颜色
							blending: THREE.AdditiveBlending  // 加法混合（发光效果）
						} );

						return new THREE.Line( geometry, material );

					case 'gaze':  // 凝视模式（如Cardboard、Daydream）
						// 创建圆环几何：内径0.02，外径0.04，32个分段
						geometry = new THREE.RingGeometry( 0.02, 0.04, 32 ).translate( 0, 0, - 1 );
						// 使用基本材质，半透明
						material = new THREE.MeshBasicMaterial( { 
							opacity: 0.5,      // 50%透明度
							transparent: true  // 启用透明
						} );
						return new THREE.Mesh( geometry, material );

					// 注意：未处理其他模式，如'screen'等
				}
			}

			// ==================== 窗口大小调整处理 ====================
			/**
			 * 窗口大小调整事件处理函数
			 * 当浏览器窗口大小改变时调用
			 */
			function onWindowResize() {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				camera.updateProjectionMatrix();  // 更新相机投影矩阵

				// 更新渲染器大小
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			// ==================== 控制器交互处理 ====================
			/**
			 * 处理控制器的交互逻辑
			 * @param {THREE.Object3D} controller - 要处理的控制器对象
			 */
			function handleController( controller ) {
				// 处理挤压选择：发射小球
				if ( controller.userData.isSelecting ) {
					// 获取房间中的一个小球（循环使用）
					const object = room.children[ count ++ ];

					// 设置小球位置为控制器位置
					object.position.copy( controller.position );
					
					// 设置随机初始速度
					object.userData.velocity.x = ( Math.random() - 0.5 ) * 3;  // X方向：[-1.5, 1.5]
					object.userData.velocity.y = ( Math.random() - 0.5 ) * 3;  // Y方向：[-1.5, 1.5]
					object.userData.velocity.z = ( Math.random() - 9 );        // Z方向：向前发射
					
					// 应用控制器的旋转到速度向量
					object.userData.velocity.applyQuaternion( controller.quaternion );

					// 循环计数：如果超出范围，回到第一个小球
					if ( count === room.children.length ) count = 0;
				}

				// 处理GUI交互：转发鼠标移动事件
				const intersections = getIntersections( controller );
				for ( let x = 0; x < intersections.length; x ++ ) {
					if ( intersections[ x ].object == guiLayer ) {
						const uv = intersections[ x ].uv;  // 获取UV坐标
						// 将控制器的交互转换为GUI的鼠标移动事件
						guiGroup.children[ 0 ].dispatchEvent( { 
							type: 'mousemove',   // 事件类型：鼠标移动
							data: { 
								x: uv.x,         // X坐标
								y: 1 - uv.y      // Y坐标反转
							}, 
							target: guiGroup     // 事件目标
						} );
					}
				}
			}

			// ==================== 主渲染循环函数 ====================
			/**
			 * 每一帧调用的主渲染函数
			 * 这是Three.js动画循环的核心
			 */
			function render() {
				// 首先渲染所有XR图层
				// 这个方法会依次调用各个图层的渲染回调函数
				renderer.xr.renderLayers( );

				// 处理两个控制器的交互
				handleController( controller1 );
				handleController( controller2 );

				// 旋转马图层：产生动态效果
				horseLayer.rotation.y -= 0.02;

				// ========== 物理模拟：更新小球位置和碰撞检测 ==========
				const delta = clock.getDelta() * 0.8;  // 获取时间增量并减速
				const range = 3 - radius;  // 房间边界范围（考虑小球半径）

				// 遍历房间中的所有小球
				for ( let i = 0; i < room.children.length; i ++ ) {
					const object = room.children[ i ];

					// 更新位置：基于速度和时间的积分
					object.position.x += object.userData.velocity.x * delta;
					object.position.y += object.userData.velocity.y * delta;
					object.position.z += object.userData.velocity.z * delta;

					// ---------- X轴边界碰撞检测 ----------
					if ( object.position.x < - range || object.position.x > range ) {
						// 将位置限制在边界内
						object.position.x = THREE.MathUtils.clamp( object.position.x, - range, range );
						// 反转X方向速度（完全弹性碰撞）
						object.userData.velocity.x = - object.userData.velocity.x;
					}

					// ---------- Y轴边界碰撞检测 ----------
					if ( object.position.y < radius || object.position.y > 6 ) {
						// 确保小球不低于地面（考虑半径）
						object.position.y = Math.max( object.position.y, radius );

						// 碰撞后速度衰减（非完全弹性碰撞）
						object.userData.velocity.x *= 0.98;  // X方向衰减2%
						object.userData.velocity.y = - object.userData.velocity.y * 0.8;  // Y方向反转并衰减20%
						object.userData.velocity.z *= 0.98;  // Z方向衰减2%
					}

					// ---------- Z轴边界碰撞检测 ----------
					if ( object.position.z < - range || object.position.z > range ) {
						object.position.z = THREE.MathUtils.clamp( object.position.z, - range, range );
						object.userData.velocity.z = - object.userData.velocity.z;
					}

					// ---------- 小球之间的碰撞检测 ----------
					// 只检测当前小球之后的小球，避免重复检测
					for ( let j = i + 1; j < room.children.length; j ++ ) {
						const object2 = room.children[ j ];

						// 计算从object2指向object的向量
						normal.copy( object.position ).sub( object2.position );

						// 计算两球心距离
						const distance = normal.length();

						// 如果距离小于两球半径之和，发生碰撞
						if ( distance < 2 * radius ) {
							// 计算排斥向量：使两球刚好接触
							normal.multiplyScalar( 0.5 * distance - radius );

							// 调整两球位置：互相推开
							object.position.sub( normal );  // object向normal反方向移动
							object2.position.add( normal ); // object2向normal方向移动

							// 归一化法向量（碰撞方向）
							normal.normalize();

							// 计算相对速度：object相对于object2的速度
							relativeVelocity.copy( object.userData.velocity ).sub( object2.userData.velocity );

							// 计算沿法线方向的速度分量
							normal = normal.multiplyScalar( relativeVelocity.dot( normal ) );

							// 交换沿法线方向的速度分量（一维弹性碰撞公式）
							object.userData.velocity.sub( normal );
							object2.userData.velocity.add( normal );
						}
					}

					// 应用重力：每秒9.8米/秒²的加速度
					object.userData.velocity.y -= 9.8 * delta;
				}

				// 最后渲染主场景
				renderer.render( scene, camera );
			}

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