<!-- WebXR 手部交互 VR 应用 - 功能描述与技术点分析
🎯 应用功能概述
这是一个基于 WebXR 和 Three.js 的虚拟现实手部交互演示应用，允许用户在 VR 环境中使用自然的手势与 3D 对象进行交互。

核心功能特性
🔍 手部追踪交互

完全免控制器，使用摄像头进行手部追踪

实时渲染逼真的手部3D模型

支持双手独立操作

👆 手势识别与交互

指点手势：从指尖发射射线检测对象

捏合手势：用于拖拽对象和点击按钮

悬停反馈：对象被指向时会有视觉反馈

🔄 对象交互系统

拖拽系统：捏合手势拖拽3D立方体

按钮系统：点击UI按钮触发功能

物理反馈：交互时的缩放动画

📱 用户界面

浮动菜单：跟随相机位置的UI面板

重置功能：随机化所有立方体位置和属性

退出功能：优雅退出VR会话

🎮 场景管理

20个可交互的彩色立方体

带有阴影的地面平面

自适应灯光系统

🛠️ 主要技术点详解
1. Three.js 3D渲染引擎
渲染核心
javascript
// WebGL渲染器配置
renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.xr.enabled = true;  // 启用WebXR支持
renderer.setAnimationLoop(animate);  // VR模式下的动画循环
场景构建
相机系统：透视相机（50°视野，0.1-10单位范围）

光照系统：

半球光（环境照明）

方向光（主光源，带阴影）

几何体：立方体、平面、文本几何体

2. WebXR API 集成
会话管理
javascript
const sessionInit = {
  requiredFeatures: ['hand-tracking']  // 必需的手部追踪功能
};
document.body.appendChild(VRButton.createButton(renderer, sessionInit));
手部模型系统
javascript
// Oculus手部模型
hand1.add(new OculusHandModel(hand1));
// 手部指针模型（用于射线交互）
const handPointer1 = new OculusHandPointerModel(hand1, controller1);
3. ECSY 实体组件系统架构
架构优势
关注点分离：数据（组件）与逻辑（系统）分离

性能优化：基于组件的查询提高执行效率

可扩展性：易于添加新的组件和系统

核心组件设计
text
├── Object3D（关联Three.js对象）
├── Button（按钮状态和回调）
├── Draggable（拖拽属性和状态）
├── OffsetFromCamera（相对相机位置）
└── 标签组件（Intersectable、Randomizable等）
系统协作流程


4. 交互检测系统
射线碰撞检测
javascript
// HandRaySystem中的核心检测逻辑
const intersections = hp.intersectObject(object, false);
if (intersections && intersections.length > 0) {
    // 找到最近的碰撞点
    distance = intersections[0].distance;
    intersectingEntity = entity;
}
状态机管理
按钮状态机：none → hovered → pressed → none

拖拽状态机：detached → hovered → to-be-attached → attached → to-be-detached → detached

5. 手部交互逻辑
捏合手势检测
javascript
if (hp.isPinched()) {
    // 捏合状态处理
    if (!hp.isAttached() && draggable.state != 'attached') {
        draggable.state = 'to-be-attached';
        draggable.attachedPointer = hp;
        hp.setAttached(true);
    }
}
对象附着/分离机制
javascript
// 附着到手指
draggable.attachedPointer.children[0].attach(object);

// 分离回原始位置
draggable.originalParent.attach(object);
6. 性能优化技术
渲染优化
阴影优化：4096×4096阴影贴图分辨率

抗锯齿：WebGL渲染器开启抗锯齿

相机更新：手动控制相机更新时机

逻辑优化
按需执行：系统只在需要时执行逻辑

精确查询：每个系统只查询相关组件

状态缓存：避免重复计算

7. 响应式设计
窗口适应
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix();
    renderer.setSize(window.innerWidth, window.innerHeight);
}
XR会话管理
会话开始：显示手部模型，校准UI位置

会话结束：清理资源，显示退出提示

异常处理：超时和错误处理

8. 视觉反馈系统
交互反馈
悬停反馈：对象放大10%

按钮反馈：按下时放大并执行动作

拖拽反馈：跟随手部移动

UI反馈
文本提示：操作指引和状态提示

颜色编码：重置（蓝色）、退出（红色）

位置提示：菜单跟随头部位置

🚀 技术栈总结
技术类别	具体技术	作用
3D渲染	Three.js v0.13x+	3D场景渲染和对象管理
VR/AR	WebXR API	虚拟现实支持和手部追踪
架构模式	ECSY	实体-组件-系统架构
交互检测	射线碰撞算法	手部与对象交互检测
状态管理	有限状态机	按钮和拖拽状态管理
UI系统	3D文本和平面	虚拟现实用户界面
💡 应用亮点
全手部追踪：无需任何物理控制器

自然交互：捏合、指向等自然手势

模块化架构：ECSY提供清晰的代码结构

跨平台：支持所有现代浏览器和VR设备

开源生态：基于成熟的Three.js生态 -->


<!DOCTYPE html>
<html lang="zh-CN">

<head>
	<!-- 页面标题：three.js WebXR 手部输入示例 - 点选和拖拽交互 -->
	<title>three.js WebXR 手部输入示例 - 点选和拖拽交互</title>
	<!-- 字符编码设置为UTF-8，支持中文字符 -->
	<meta charset="utf-8">
	<!-- 
		视口设置：
		width=device-width - 宽度等于设备宽度
		initial-scale=1.0 - 初始缩放比例为1
		user-scalable=no - 禁止用户手动缩放（更适合VR/AR应用）
	-->
	<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> 
		VR - 手部输入 - 点选和拖拽交互<br />
		<!-- 描述性文本 -->
		<small>使用WebXR手部追踪技术，通过手势进行3D对象交互</small>
	</div>

	<!-- 
		模块导入映射（Import Map）：
		现代JavaScript模块导入配置，定义模块路径别名
		让浏览器知道如何解析import语句中的模块路径
	-->
	<script type="importmap">
		{
			"imports": {
				"three": "../build/three.module.js",
				"three/addons/": "./jsm/"
			}
		}
	</script>

	<!-- 
		主JavaScript模块：
		type="module"表示这是一个ES6模块，支持模块化导入
		代码按功能分为多个部分，详细注释如下
	-->
	<script type="module">

		// ========== 模块导入区域 ==========
		// 导入three.js核心库和所有功能
		import * as THREE from 'three';
		
		// 导入WebXR相关组件
		// VR按钮组件：创建进入VR模式的按钮
		import { VRButton } from 'three/addons/webxr/VRButton.js';
		// XR控制器模型工厂：创建控制器的3D模型
		import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
		// Oculus手部模型：显示手部的3D模型
		import { OculusHandModel } from 'three/addons/webxr/OculusHandModel.js';
		// Oculus手部指针模型：手部的交互指针（用于射线检测）
		import { OculusHandPointerModel } from 'three/addons/webxr/OculusHandPointerModel.js';
		// 文本创建工具：在3D场景中创建2D文本
		import { createText } from 'three/addons/webxr/Text2D.js';

		// 导入ECSY实体组件系统库
		// ECSY是一种实体-组件-系统架构，用于游戏开发
		// World: 实体世界容器
		// System: 系统基类
		// Component: 组件基类
		// TagComponent: 标签组件（只有标签，没有数据）
		// Types: 数据类型定义
		import { World, System, Component, TagComponent, Types } from 'three/addons/libs/ecsy.module.js';

		// ========== ECSY组件定义区域 ==========
		// 组件是实体的数据容器，不包含逻辑

		/**
		 * Object3D组件：
		 * 用于将Three.js的3D对象与ECSY实体关联起来
		 * 这是连接Three.js渲染系统和ECSY逻辑系统的桥梁
		 */
		class Object3D extends Component { 
			// 组件包含一个object属性，存储Three.js对象引用
		}
		// 定义组件的模式（schema），描述组件的数据结构
		Object3D.schema = {
			// object字段类型为Ref（引用类型），指向Three.js的Object3D对象
			object: { type: Types.Ref }
		};

		/**
		 * Button组件：
		 * 定义按钮的交互状态和回调函数
		 * 用于创建可交互的UI按钮
		 */
		class Button extends Component { }
		Button.schema = {
			// 当前状态：表示按钮在当前帧的状态
			// 可能的值：'none'(无交互), 'hovered'(悬停), 'pressed'(按下)
			currState: { 
				type: Types.String,  // 字符串类型
				default: 'none'      // 默认值为'none'
			},
			// 上一帧状态：用于检测状态变化（如从悬停变为按下）
			prevState: { 
				type: Types.String, 
				default: 'none' 
			},
			// 动作回调函数：当按钮被按下时执行的函数
			action: { 
				type: Types.Ref,           // 引用类型，存储函数引用
				default: () => { }         // 默认是空函数
			}
		};

		/**
		 * Draggable组件：
		 * 定义可拖拽对象的属性和状态
		 * 允许3D对象被手部指针拖拽移动
		 */
		class Draggable extends Component { }
		Draggable.schema = {
			// 拖拽状态：表示对象当前的拖拽状态
			// 可能的值：
			// 'detached' - 未附着（自由状态）
			// 'hovered' - 被手部指针悬停
			// 'to-be-attached' - 将要附着到手部指针
			// 'attached' - 已附着到手部指针（正在拖拽）
			// 'to-be-detached' - 将要分离手部指针
			state: { 
				type: Types.String, 
				default: 'none' 
			},
			// 原始父对象：拖拽前对象所属的父级
			// 用于释放对象时将其放回原来的位置层级
			originalParent: { 
				type: Types.Ref, 
				default: null 
			},
			// 附着的指针：当前附着的是哪个手部指针
			// 一个对象一次只能被一只手拖拽
			attachedPointer: { 
				type: Types.Ref, 
				default: null 
			}
		};

		/**
		 * OffsetFromCamera组件：
		 * 定义对象相对于相机的位置偏移
		 * 用于创建跟随相机移动的UI元素（如菜单面板）
		 */
		class OffsetFromCamera extends Component { }
		OffsetFromCamera.schema = {
			// X轴偏移量：相对于相机的水平位置
			x: { 
				type: Types.Number, 
				default: 0 
			},
			// Y轴偏移量：相对于相机的垂直位置
			y: { 
				type: Types.Number, 
				default: 0 
			},
			// Z轴偏移量：相对于相机的深度位置
			z: { 
				type: Types.Number, 
				default: 0 
			},
		};

		// ========== 标签组件定义区域 ==========
		// 标签组件只有标签没有数据，用于标记实体的类型
		// 便于系统查询特定类型的实体

		/**
		 * Intersectable标签组件：
		 * 标记实体为"可交互的"，可以被手部射线检测到
		 * 所有需要交互的对象（按钮、可拖拽物体）都需要此标签
		 */
		class Intersectable extends TagComponent { }

		/**
		 * HandsInstructionText标签组件：
		 * 标记实体为"手部操作说明文本"
		 * 用于控制操作说明文本的显示/隐藏逻辑
		 */
		class HandsInstructionText extends TagComponent { }

		/**
		 * NeedCalibration标签组件：
		 * 标记实体为"需要校准"
		 * 用于需要根据相机位置进行初始位置校准的物体
		 */
		class NeedCalibration extends TagComponent { }

		/**
		 * Randomizable标签组件：
		 * 标记实体为"可随机化"
		 * 表示该实体的属性（位置、旋转、颜色等）可以被随机设置
		 */
		class Randomizable extends TagComponent { }

		// ========== ECSY系统定义区域 ==========
		// 系统包含业务逻辑，处理具有特定组件组合的实体

		/**
		 * ButtonSystem系统：
		 * 处理所有按钮实体的状态更新和视觉反馈
		 * 每帧执行，根据按钮状态更新按钮外观，并触发按钮点击事件
		 */
		class ButtonSystem extends System {

			/**
			 * 系统执行方法：每帧被调用
			 * @param {number} delta - 距离上一帧的时间差（秒）
			 * @param {number} time - 从开始到现在的总时间（秒）
			 */
			execute( /*delta, time*/ ) {
				// 查询所有包含Button组件的实体
				// results是一个包含所有匹配实体的数组
				this.queries.buttons.results.forEach( entity => {
					// 获取按钮组件的可变引用（可以修改组件数据）
					const button = entity.getMutableComponent( Button );
					// 获取关联的Three.js网格对象
					const buttonMesh = entity.getComponent( Object3D ).object;
					
					// 根据按钮当前状态更新视觉反馈
					if ( button.currState == 'none' ) {
						// 无交互状态：恢复正常大小
						buttonMesh.scale.set( 1, 1, 1 );
					} else {
						// 悬停或按下状态：稍微放大（1.1倍），提供视觉反馈
						buttonMesh.scale.set( 1.1, 1.1, 1.1 );
					}

					// 检测按钮按下事件
					// 条件：当前状态是'pressed'，但上一帧状态不是'pressed'
					// 这确保点击事件只在状态从非按下变为按下时触发一次
					if ( button.currState == 'pressed' && button.prevState != 'pressed' ) {
						// 执行按钮关联的动作回调函数
						button.action();
					}

					// 状态转移：为下一帧做准备
					// 将当前状态保存为上一帧状态
					button.prevState = button.currState;
					// 重置当前状态为'none'
					// 注意：HandRaySystem会在下一帧根据手部交互重新设置currState
					button.currState = 'none';

				} );
			}
		}

		// 定义系统需要查询的组件
		// 系统只会处理包含这些组件的实体
		ButtonSystem.queries = {
			// 查询名为"buttons"的实体组
			buttons: {
				// 这些实体必须包含Button组件
				components: [ Button ]
			}
		};

		/**
		 * DraggableSystem系统：
		 * 处理所有可拖拽实体的状态逻辑
		 * 管理拖拽的附着和分离过程
		 */
		class DraggableSystem extends System {

			execute( /*delta, time*/ ) {
				// 查询所有包含Draggable组件的实体
				this.queries.draggable.results.forEach( entity => {
					// 获取可拖拽组件的可变引用
					const draggable = entity.getMutableComponent( Draggable );
					// 获取关联的Three.js对象
					const object = entity.getComponent( Object3D ).object;
					
					// 如果是第一次执行，记录原始父对象
					// 这是为了释放对象时能放回原来的位置
					if ( draggable.originalParent == null ) {
						draggable.originalParent = object.parent;
					}

					// 根据拖拽状态执行相应操作
					switch ( draggable.state ) {
						// 状态：将要附着
						// HandRaySystem检测到捏合手势后设置此状态
						case 'to-be-attached':
							// 将对象附着到手部指针的第一个子对象上
							// draggable.attachedPointer是手部指针对象
							draggable.attachedPointer.children[ 0 ].attach( object );
							// 状态变为已附着
							draggable.state = 'attached';
							break;
							
						// 状态：将要分离
						// HandRaySystem检测到松开手势后设置此状态
						case 'to-be-detached':
							// 将对象放回原始父对象下
							draggable.originalParent.attach( object );
							// 状态变为未附着
							draggable.state = 'detached';
							break;
							
						// 其他状态：保持正常大小
						default:
							object.scale.set( 1, 1, 1 );
					}
				} );
			}
		}

		DraggableSystem.queries = {
			draggable: {
				components: [ Draggable ]
			}
		};

		/**
		 * HandRaySystem系统：
		 * 处理手部射线与可交互对象的碰撞检测
		 * 这是最核心的交互系统，负责检测手部与3D对象的交互
		 */
		class HandRaySystem extends System {

			/**
			 * 系统初始化方法
			 * @param {Object} attributes - 初始化参数
			 * @param {Array} attributes.handPointers - 手部指针模型数组
			 */
			init( attributes ) {
				// 保存传入的手部指针引用
				this.handPointers = attributes.handPointers;
			}

			execute( /*delta, time*/ ) {
				// 遍历每个手部指针（左右手）
				this.handPointers.forEach( hp => {
					// 初始化变量
					let distance = null;           // 最近的碰撞距离
					let intersectingEntity = null; // 最近的碰撞实体
					
					// 查询所有可交互实体（有Intersectable标签的实体）
					this.queries.intersectable.results.forEach( entity => {
						// 获取实体的Three.js对象
						const object = entity.getComponent( Object3D ).object;
						// 使用手部指针的射线检测与对象的碰撞
						// intersectObject方法返回射线与对象的交点数组
						// 第二个参数false表示不递归检测子对象
						const intersections = hp.intersectObject( object, false );
						
						// 如果有碰撞交点
						if ( intersections && intersections.length > 0 ) {
							// 找到最近的碰撞对象（距离最小的）
							// 这是为了处理多个对象重叠的情况
							if ( distance == null || intersections[ 0 ].distance < distance ) {
								distance = intersections[ 0 ].distance;
								intersectingEntity = entity;
							}
						}
					} );
					
					// 如果有碰撞发生
					if ( distance ) {
						// 设置手部指针的光标位置到碰撞点
						hp.setCursor( distance );
						
						// 处理按钮交互
						if ( intersectingEntity.hasComponent( Button ) ) {
							const button = intersectingEntity.getMutableComponent( Button );
							
							// 如果手部处于捏合状态（食指和拇指捏在一起）
							if ( hp.isPinched() ) {
								// 设置按钮状态为按下
								button.currState = 'pressed';
							} 
							// 如果手部没有捏合，并且按钮当前不是按下状态
							else if ( button.currState != 'pressed' ) {
								// 设置按钮状态为悬停
								button.currState = 'hovered';
							}
							// 注意：如果按钮当前是按下状态，而手部已经松开
							// 这个状态会在ButtonSystem中被重置为'none'
						}

						// 处理可拖拽对象交互
						if ( intersectingEntity.hasComponent( Draggable ) ) {
							const draggable = intersectingEntity.getMutableComponent( Draggable );
							const object = intersectingEntity.getComponent( Object3D ).object;
							
							// 悬停时放大对象，提供视觉反馈
							object.scale.set( 1.1, 1.1, 1.1 );
							
							// 检查手部捏合状态
							if ( hp.isPinched() ) {
								// 手部捏合：尝试开始拖拽
								// 条件：手部指针当前没有附着对象，且对象不是已附着状态
								if ( ! hp.isAttached() && draggable.state != 'attached' ) {
									// 设置对象状态为将要附着
									draggable.state = 'to-be-attached';
									// 记录附着的手部指针
									draggable.attachedPointer = hp;
									// 标记手部指针为已附着状态
									hp.setAttached( true );
								}
							} else {
								// 手部松开：尝试结束拖拽
								// 条件：手部指针当前附着对象，且对象是已附着状态
								if ( hp.isAttached() && draggable.state == 'attached' ) {
									// 调试信息
									console.log( 'hello' );
									// 设置对象状态为将要分离
									draggable.state = 'to-be-detached';
									// 清除附着的手部指针引用
									draggable.attachedPointer = null;
									// 标记手部指针为未附着状态
									hp.setAttached( false );
								}
							}
						}
					} else {
						// 没有碰撞：设置手部指针的光标到默认距离（1.5单位）
						hp.setCursor( 1.5 );
					}
				} );
			}
		}

		HandRaySystem.queries = {
			intersectable: {
				components: [ Intersectable ]
			}
		};

		/**
		 * InstructionSystem系统：
		 * 控制操作说明文本的显示和隐藏
		 * 当用户戴上头显时显示，取下时隐藏
		 */
		class InstructionSystem extends System {

			init( attributes ) {
				// 保存控制器引用（用于检测是否戴上头显）
				this.controllers = attributes.controllers;
			}

			execute( /*delta, time*/ ) {
				// 检查是否有控制器可见
				// 控制器可见通常意味着用户戴上了VR头显
				let visible = false;
				this.controllers.forEach( controller => {
					if ( controller.visible ) {
						visible = true;
					}
				} );

				// 设置所有操作说明文本的可见性与控制器一致
				this.queries.instructionTexts.results.forEach( entity => {
					const object = entity.getComponent( Object3D ).object;
					object.visible = visible;
				} );
			}
		}

		InstructionSystem.queries = {
			instructionTexts: {
				components: [ HandsInstructionText ]
			}
		};

		/**
		 * CalibrationSystem系统：
		 * 校准系统，将标记为需要校准的对象定位到相机相对位置
		 * 主要用于UI元素，使其跟随相机移动
		 */
		class CalibrationSystem extends System {

			init( attributes ) {
				// 保存相机和渲染器引用
				this.camera = attributes.camera;
				this.renderer = attributes.renderer;
			}

			execute( /*delta, time*/ ) {
				// 查询所有需要校准的实体
				this.queries.needCalibration.results.forEach( entity => {
					// 只有在XR会话已建立时进行校准
					// 因为需要获取XR相机的位置
					if ( this.renderer.xr.getSession() ) {
						// 获取位置偏移量组件
						const offset = entity.getComponent( OffsetFromCamera );
						// 获取Three.js对象
						const object = entity.getComponent( Object3D ).object;
						// 获取当前XR相机（与用户头部位置一致）
						const xrCamera = this.renderer.xr.getCamera();
						
						// 计算对象的世界位置：相机位置 + 偏移量
						object.position.x = xrCamera.position.x + offset.x;
						object.position.y = xrCamera.position.y + offset.y;
						object.position.z = xrCamera.position.z + offset.z;
						
						// 校准完成，移除需要校准的标签
						// 这样下次系统执行时就不会再处理这个实体
						entity.removeComponent( NeedCalibration );
					}
				} );
			}
		}

		CalibrationSystem.queries = {
			needCalibration: {
				components: [ NeedCalibration ]
			}
		};

		/**
		 * RandomizerSystem系统：
		 * 随机化系统，为标记为可随机化的实体设置随机属性
		 * 用于初始化和重置场景中的物体
		 */
		class RandomizerSystem extends System {

			init( /*attributes*/ ) {
				// 初始化时需要随机化
				this.needRandomizing = true;
			}

			execute( /*delta, time*/ ) {
				// 如果不需要随机化，直接返回
				if ( ! this.needRandomizing ) {
					return;
				}

				// 查询所有可随机化的实体
				this.queries.randomizable.results.forEach( entity => {
					const object = entity.getComponent( Object3D ).object;

					// 随机设置颜色：0xFFFFFF是白色，Math.random()*0xFFFFFF得到随机颜色
					object.material.color.setHex( Math.random() * 0xffffff );

					// 随机设置位置：
					// X和Z轴：-1到1之间
					// Y轴：0到2之间（地面上方）
					object.position.x = Math.random() * 2 - 1;
					object.position.y = Math.random() * 2;
					object.position.z = Math.random() * 2 - 1;

					// 随机设置旋转：每个轴0到2π弧度（0到360度）
					object.rotation.x = Math.random() * 2 * Math.PI;
					object.rotation.y = Math.random() * 2 * Math.PI;
					object.rotation.z = Math.random() * 2 * Math.PI;

					// 随机设置缩放：0.5到1.5倍
					object.scale.x = Math.random() + 0.5;
					object.scale.y = Math.random() + 0.5;
					object.scale.z = Math.random() + 0.5;
					
					// 只执行一次随机化，然后设置标志为false
					// 重置按钮会重新设置为true
					this.needRandomizing = false;
				} );
			}
		}

		RandomizerSystem.queries = {
			randomizable: {
				components: [ Randomizable ]
			}
		};

		// ========== 全局变量和主程序 ==========

		// 创建ECS世界，这是所有实体和系统的容器
		const world = new World();
		
		// 创建Three.js时钟，用于获取时间信息
		const clock = new THREE.Clock();
		
		// 声明全局变量（在init函数中初始化）
		let camera, scene, renderer;

		// 调用初始化函数
		init();

		/**
		 * 创建按钮网格对象的辅助函数
		 * @param {number} x - X轴尺寸
		 * @param {number} y - Y轴尺寸
		 * @param {number} z - Z轴尺寸（对于按钮通常是薄片）
		 * @param {number} color - 按钮颜色（十六进制）
		 * @returns {THREE.Mesh} 按钮网格对象
		 */
		function makeButtonMesh( x, y, z, color ) {
			// 创建立方体几何体
			const geometry = new THREE.BoxGeometry( x, y, z );
			// 创建Phong材质（有光泽感）
			const material = new THREE.MeshPhongMaterial( { color: color } );
			// 创建网格对象
			const buttonMesh = new THREE.Mesh( geometry, material );
			return buttonMesh;
		}

		/**
		 * 主初始化函数
		 * 设置Three.js场景、渲染器、XR环境、ECS实体和系统
		 */
		function init() {
			// 创建容器div并添加到body
			const container = document.createElement( 'div' );
			document.body.appendChild( container );

			// 创建Three.js场景
			scene = new THREE.Scene();
			// 设置场景背景色为深灰色
			scene.background = new THREE.Color( 0x444444 );

			// 创建透视相机
			// 参数：视野角度50度，宽高比，近裁剪面0.1，远裁剪面10
			camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.1, 10 );
			// 设置相机初始位置（大约是人眼高度）
			// X=0（中心），Y=1.2（大约站立时的眼睛高度），Z=0.3（稍微向前）
			camera.position.set( 0, 1.2, 0.3 );

			// 添加半球光（模拟天空和地面的环境光）
			// 参数：天空颜色，地面颜色，光照强度
			scene.add( new THREE.HemisphereLight( 0xcccccc, 0x999999, 3 ) );

			// 添加方向光（模拟太阳光）
			const light = new THREE.DirectionalLight( 0xffffff, 3 );
			light.position.set( 0, 6, 0 );  // 从上方照射
			light.castShadow = true;        // 启用阴影投射
			
			// 配置阴影相机范围（决定阴影显示的区域）
			light.shadow.camera.top = 2;
			light.shadow.camera.bottom = -2;
			light.shadow.camera.right = 2;
			light.shadow.camera.left = -2;
			
			// 设置阴影贴图分辨率（越高阴影越清晰，性能消耗越大）
			light.shadow.mapSize.set( 4096, 4096 );
			scene.add( light );

			// 创建WebGL渲染器
			renderer = new THREE.WebGLRenderer( { antialias: true } );  // 开启抗锯齿
			renderer.setPixelRatio( window.devicePixelRatio );  // 适配设备像素比
			renderer.setSize( window.innerWidth, window.innerHeight );  // 设置渲染尺寸
			renderer.setAnimationLoop( animate );  // 设置动画循环回调函数
			renderer.shadowMap.enabled = true;     // 启用阴影映射
			renderer.xr.enabled = true;            // 启用WebXR支持
			renderer.xr.cameraAutoUpdate = false;  // 关闭自动更新相机（由ECSY系统控制）

			// 将渲染器的canvas元素添加到容器中
			container.appendChild( renderer.domElement );

			// 配置XR会话初始化参数
			// requiredFeatures指定需要的手部追踪功能
			const sessionInit = {
				requiredFeatures: [ 'hand-tracking' ]  // 必需：手部追踪
			};

			// 创建VR按钮并添加到页面
			// 用户点击此按钮可以进入VR模式
			document.body.appendChild( VRButton.createButton( renderer, sessionInit ) );

			// ========== 创建XR控制器和手部模型 ==========

			// 获取左手控制器（索引0）
			const controller1 = renderer.xr.getController( 0 );
			scene.add( controller1 );

			// 获取右手控制器（索引1）
			const controller2 = renderer.xr.getController( 1 );
			scene.add( controller2 );

			// 创建控制器模型工厂
			const controllerModelFactory = new XRControllerModelFactory();

			// 设置左手（控制器0）
			// 控制器握把：手柄的视觉表现
			const controllerGrip1 = renderer.xr.getControllerGrip( 0 );
			// 为握把添加控制器模型
			controllerGrip1.add( controllerModelFactory.createControllerModel( controllerGrip1 ) );
			scene.add( controllerGrip1 );

			// 左手的手部模型
			const hand1 = renderer.xr.getHand( 0 );
			// 添加Oculus手部模型（显示手的外观）
			hand1.add( new OculusHandModel( hand1 ) );
			// 创建手部指针模型（用于交互的射线）
			const handPointer1 = new OculusHandPointerModel( hand1, controller1 );
			hand1.add( handPointer1 );
			scene.add( hand1 );

			// 设置右手（控制器1） - 与左手对称
			const controllerGrip2 = renderer.xr.getControllerGrip( 1 );
			controllerGrip2.add( controllerModelFactory.createControllerModel( controllerGrip2 ) );
			scene.add( controllerGrip2 );

			const hand2 = renderer.xr.getHand( 1 );
			hand2.add( new OculusHandModel( hand2 ) );
			const handPointer2 = new OculusHandPointerModel( hand2, controller2 );
			hand2.add( handPointer2 );
			scene.add( hand2 );

			// ========== 创建场景中的3D对象 ==========

			// 创建地板
			const floorGeometry = new THREE.PlaneGeometry( 4, 4 );  // 4x4的平面
			const floorMaterial = new THREE.MeshPhongMaterial( { color: 0x222222 } );  // 深灰色
			const floor = new THREE.Mesh( floorGeometry, floorMaterial );
			floor.rotation.x = - Math.PI / 2;  // 旋转90度，使其水平
			floor.receiveShadow = true;        // 接收阴影
			scene.add( floor );

			// 创建菜单面板（透明背景，用于放置按钮）
			const menuGeometry = new THREE.PlaneGeometry( 0.24, 0.5 );  // 较小尺寸的面板
			const menuMaterial = new THREE.MeshPhongMaterial( {
				opacity: 0,       // 完全透明
				transparent: true, // 启用透明度
			} );
			const menuMesh = new THREE.Mesh( menuGeometry, menuMaterial );
			// 设置菜单位置：相机右前方
			menuMesh.position.set( 0.4, 1, -1 );
			// 轻微旋转，面向用户
			menuMesh.rotation.y = - Math.PI / 12;
			scene.add( menuMesh );

			// 创建"重置"按钮
			const resetButton = makeButtonMesh( 0.2, 0.1, 0.01, 0x355c7d );  // 蓝色按钮
			const resetButtonText = createText( '重置', 0.06 );  // 创建文本"重置"，字号0.06
			resetButton.add( resetButtonText );
			// 将文本稍微向前移动，避免与按钮表面重叠
			resetButtonText.position.set( 0, 0, 0.0051 );
			// 在菜单面板中的位置（相对位置）
			resetButton.position.set( 0, -0.06, 0 );
			menuMesh.add( resetButton );

			// 创建"退出"按钮（红色）
			const exitButton = makeButtonMesh( 0.2, 0.1, 0.01, 0xff0000 );
			const exitButtonText = createText( '退出', 0.06 );
			exitButton.add( exitButtonText );
			exitButtonText.position.set( 0, 0, 0.0051 );
			// 放在重置按钮下方
			exitButton.position.set( 0, -0.18, 0 );
			menuMesh.add( exitButton );

			// 创建操作说明文本
			const instructionText = createText( '这是一个WebXR手部交互演示，请用手部进行探索。', 0.04 );
			instructionText.position.set( 0, 1.6, -0.6 );  // 放在用户前方稍高位置
			scene.add( instructionText );

			// 创建退出提示文本（默认隐藏）
			const exitText = createText( '正在退出会话...', 0.04 );
			exitText.position.set( 0, 1.5, -0.6 );
			exitText.visible = false;  // 初始不可见
			scene.add( exitText );

			// ========== 注册ECS组件和系统 ==========

			// 注册所有组件到ECS世界
			world
				.registerComponent( Object3D )
				.registerComponent( Button )
				.registerComponent( Intersectable )
				.registerComponent( HandsInstructionText )
				.registerComponent( OffsetFromCamera )
				.registerComponent( NeedCalibration )
				.registerComponent( Randomizable )
				.registerComponent( Draggable );

			// 注册系统并传递必要参数
			// 注意：系统的执行顺序与注册顺序一致
			world
				// 1. 随机化系统：先随机化物体位置
				.registerSystem( RandomizerSystem )
				// 2. 指令系统：控制文本显示
				.registerSystem( InstructionSystem, { controllers: [ controllerGrip1, controllerGrip2 ] } )
				// 3. 校准系统：校准UI位置到相机
				.registerSystem( CalibrationSystem, { renderer: renderer, camera: camera } )
				// 4. 按钮系统：处理按钮状态
				.registerSystem( ButtonSystem )
				// 5. 拖拽系统：处理拖拽逻辑
				.registerSystem( DraggableSystem )
				// 6. 手部射线系统：处理手部交互（最后执行，因为它设置按钮状态）
				.registerSystem( HandRaySystem, { handPointers: [ handPointer1, handPointer2 ] } );

			// ========== 创建ECS实体 ==========

			// 创建20个可拖拽的立方体
			for ( let i = 0; i < 20; i ++ ) {
				// 创建立方体几何体
				const object = new THREE.Mesh( 
					new THREE.BoxGeometry( 0.15, 0.15, 0.15 ),  // 0.15x0.15x0.15的立方体
					new THREE.MeshLambertMaterial( { color: 0xffffff } )  // 白色Lambert材质
				);
				scene.add( object );

				// 创建对应实体
				const entity = world.createEntity();
				entity.addComponent( Intersectable );      // 可交互
				entity.addComponent( Randomizable );       // 可随机化
				entity.addComponent( Object3D, { object: object } );  // 关联3D对象
				entity.addComponent( Draggable );          // 可拖拽
			}

			// 创建菜单实体
			const menuEntity = world.createEntity();
			menuEntity.addComponent( Intersectable );  // 可交互（用于射线检测）
			menuEntity.addComponent( OffsetFromCamera, { x: 0.4, y: 0, z: -1 } );  // 相对于相机的偏移
			menuEntity.addComponent( NeedCalibration );  // 需要根据相机位置校准
			menuEntity.addComponent( Object3D, { object: menuMesh } );

			// 创建"重置"按钮实体
			const rbEntity = world.createEntity();
			rbEntity.addComponent( Intersectable );
			rbEntity.addComponent( Object3D, { object: resetButton } );
			
			// 定义重置按钮的动作回调函数
			const rbAction = function () {
				// 设置随机化系统的标志为true，触发重新随机化
				world.getSystem( RandomizerSystem ).needRandomizing = true;
			};
			
			rbEntity.addComponent( Button, { action: rbAction } );

			// 创建"退出"按钮实体
			const ebEntity = world.createEntity();
			ebEntity.addComponent( Intersectable );
			ebEntity.addComponent( Object3D, { object: exitButton } );
			
			// 定义退出按钮的动作回调函数
			const ebAction = function () {
				// 显示退出提示文本
				exitText.visible = true;
				
				// 2秒后执行
				setTimeout( function () {
					// 隐藏退出提示文本
					exitText.visible = false; 
					// 结束当前的XR会话
					renderer.xr.getSession().end();
				}, 2000 );
			};
			
			ebEntity.addComponent( Button, { action: ebAction } );

			// 创建操作说明文本实体
			const itEntity = world.createEntity();
			itEntity.addComponent( HandsInstructionText );  // 标记为操作说明文本
			itEntity.addComponent( Object3D, { object: instructionText } );

			// 添加窗口大小变化事件监听器
			window.addEventListener( 'resize', onWindowResize );
		}

		/**
		 * 窗口大小变化处理函数
		 * 当浏览器窗口大小变化时，调整相机和渲染器
		 */
		function onWindowResize() {
			// 更新相机的宽高比
			camera.aspect = window.innerWidth / window.innerHeight;
			// 更新相机投影矩阵（必须调用）
			camera.updateProjectionMatrix();
			// 更新渲染器尺寸
			renderer.setSize( window.innerWidth, window.innerHeight );
		}

		/**
		 * 动画循环函数
		 * 每帧自动调用，驱动整个应用的更新和渲染
		 */
		function animate() {
			// 获取时间增量（距离上一帧的时间，秒）
			const delta = clock.getDelta();
			// 获取经过的总时间（秒）
			const elapsedTime = clock.elapsedTime;
			
			// 更新XR相机（将XR设备的位置/旋转应用到相机）
			renderer.xr.updateCamera( camera );
			
			// 执行所有ECS系统，传递时间参数
			world.execute( delta, elapsedTime );
			
			// 渲染场景
			renderer.render( scene, camera );
		}

	</script>
</body>

</html>