<!-- WebXR手部追踪VR交互演示 - 功能与技术详解
🎯 项目功能概述
这是一个基于WebXR标准的虚拟现实手部交互演示应用，允许用户通过VR设备（如Oculus Quest）使用真实手部动作与3D虚拟环境进行自然交互。

🌟 核心功能模块
1. VR场景与3D环境
沉浸式虚拟空间：创建了完整的3D环境，包含地板、灯光、阴影系统

视觉焦点对象：一个持续旋转的圆环结（Torus Knot）作为主要观察对象

环境光照：使用半球光模拟环境光照，定向光模拟主光源并支持阴影

2. 手部追踪交互系统
自然手势识别：通过WebXR手部追踪API获取用户手部姿势

虚拟手部模型：显示逼真的Oculus手部模型，匹配用户真实手势

射线交互机制：从手部发射虚拟射线进行远距离选择和交互

3. 交互式UI面板
浮动菜单系统：跟随用户视野的透明面板，包含4个功能按钮

橙色按钮：将圆环结颜色改为橙色

粉色按钮：将圆环结颜色改为粉色

重置按钮：恢复圆环结的原始白色

退出按钮：退出VR会话，返回普通视图

视觉反馈：悬停时按钮放大，点击时有状态变化

4. 状态提示系统
操作指引：进入VR模式时显示手部交互说明

退出确认：点击退出按钮后显示2秒倒计时提示

实时反馈：所有交互操作都有即时的视觉响应

5. 会话管理
一键进入VR：通过标准化VR按钮启动WebXR会话

安全退出：提供明确的退出流程和确认提示

会话状态管理：正确处理VR会话的启动、运行和结束

🔧 主要技术点详解
1. WebXR API集成
javascript
// WebXR会话配置
const sessionInit = {
    requiredFeatures: ['hand-tracking']  // 必须支持手部追踪
};

// 创建VR会话按钮
document.body.appendChild(VRButton.createButton(renderer, sessionInit));
技术要点：

手部追踪：使用hand-tracking特性请求，支持无控制器交互

设备抽象：统一处理不同VR设备的输入差异

会话管理：完整的生命周期管理（请求、进入、退出）

2. ECS（实体-组件-系统）架构
组件层（数据存储）
javascript
// 组件示例：只存储数据，无逻辑
class Button extends Component {
    static schema = {
        currState: { type: Types.String, default: 'none' },  // 当前状态
        prevState: { type: Types.String, default: 'none' },  // 前一状态
        action: { type: Types.Ref, default: () => {} }       // 回调函数
    };
}
系统层（逻辑处理）
javascript
// 系统示例：处理特定组件的逻辑
class ButtonSystem extends System {
    execute(delta) {
        // 遍历所有Button组件实体
        this.queries.buttons.results.forEach(entity => {
            const button = entity.getMutableComponent(Button);
            // 状态机逻辑、视觉反馈、事件触发
        });
    }
}
技术优势：

关注点分离：数据与逻辑完全分离

高效查询：系统自动过滤相关实体

可扩展性：轻松添加新组件和系统

性能优化：避免不必要的遍历和检查

3. Three.js 3D渲染管道
场景图管理
javascript
// 层次化场景结构
scene
├── Camera (相机)
├── HemisphereLight (环境光)
├── DirectionalLight (主光源)
├── Floor (地板)
├── TorusKnot (圆环结)
├── MenuPanel (菜单面板)
└── HandModels (手部模型)
材质与着色器
javascript
// PBR材质配置
const tkMaterial = new THREE.MeshPhongMaterial({ 
    color: 0xffffff,
    metalness: 0.8  // 金属质感
});
阴影系统
javascript
// 高质量阴影配置
light.shadow.mapSize.set(4096, 4096);  // 阴影贴图分辨率
light.shadow.camera.top = 2;           // 阴影相机范围
4. 手部交互检测算法
射线投射机制
javascript
// 手部射线与物体的交点检测
const intersections = handPointer.intersectObject(object, false);
if (intersections && intersections.length > 0) {
    const distance = intersections[0].distance;
    // 找到最近交点
}
手势状态机
javascript
// 按钮状态管理
if (handPointer.isPinched()) {
    button.currState = 'pressed';      // 捏合手势 = 按下
} else if (button.currState != 'pressed') {
    button.currState = 'hovered';      // 指向 = 悬停
}
5. UI跟随相机系统
相对位置计算
javascript
// 将UI定位到相机相对位置
object.position.x = xrCamera.position.x + offset.x;
object.position.y = xrCamera.position.y + offset.y;
object.position.z = xrCamera.position.z + offset.z;
工作原理：

标记需要跟随相机的实体（NeedCalibration组件）

在VR会话开始时计算绝对位置

保持相对偏移，确保UI始终在舒适观看距离

6. 动画与时间管理
帧率无关动画
javascript
// 使用时间增量确保动画速度一致
object.rotation.x += 0.4 * delta;  // 每秒旋转0.4弧度
object.rotation.y += 0.4 * delta;
Three.js动画循环
javascript
// WebXR优化的动画循环
renderer.setAnimationLoop(animate);
function animate() {
    const delta = clock.getDelta();       // 获取时间增量
    renderer.xr.updateCamera(camera);     // 更新XR相机
    world.execute(delta, elapsedTime);    // 执行ECS系统
    renderer.render(scene, camera);       // 渲染场景
}
🏗️ 系统架构设计
模块依赖关系
text
main.js (入口)
├── Three.js Core (3D渲染)
│   ├── Scene Graph (场景管理)
│   ├── WebGL Renderer (图形绘制)
│   └── Camera System (视角控制)
├── WebXR Module (VR交互)
│   ├── Hand Tracking (手部追踪)
│   ├── Session Management (会话管理)
│   └── Controller Models (控制器模型)
├── ECS Framework (架构核心)
│   ├── Component Definitions (组件定义)
│   ├── System Implementations (系统实现)
│   └── World Management (世界管理)
└── UI & Interaction (用户交互)
    ├── Ray Casting (射线检测)
    ├── Button System (按钮交互)
    └── Visual Feedback (视觉反馈)
数据流动
用户输入 → WebXR API → 手部姿态数据

姿态数据 → 手部模型更新 → 射线计算

射线检测 → 交点计算 → 按钮状态更新

状态变化 → ECS系统处理 → 视觉反馈

场景更新 → Three.js渲染 → 显示器输出

⚡ 性能优化策略
1. 渲染优化
阴影贴图复用：4096x4096高分辨率阴影，避免动态生成

几何体实例化：按钮使用相同的几何体实例

材质共享：相似物体共享材质对象

2. 计算优化
按需更新：ECS系统只处理相关实体

空间分区：射线检测使用Three.js的内置优化

状态缓存：避免每帧重新计算不变的数据

3. 内存管理
资源池化：重复使用几何体和材质

及时释放：VR会话结束时清理临时资源

渐进加载：按需创建3D模型 -->


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

<head>
    <!-- 页面标题：Three.js VR 手部交互 - 指向点击 -->
    <title>Three.js VR 手部交互 - 指向点击演示</title>
    <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">
        <a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> VR - 手部输入 - 指向点击演示<br />
        说明：这是一个WebXR手部追踪演示。请使用VR设备进入，通过手势进行交互。<br />
        操作：用手指指向按钮可进行悬停查看，捏合手指可点击按钮。
    </div>

    <!-- 模块导入映射：定义JavaScript模块的导入路径和别名 -->
    <!-- 这使得浏览器能够正确解析ES6模块导入语句 -->
    <script type="importmap">
        {
            "imports": {
                "three": "../build/three.module.js",
                "three/addons/": "./jsm/"
            }
        }
    </script>

    <script type="module">
        // ======================================================================
        // 模块导入部分
        // ======================================================================
        // 导入Three.js核心库的所有功能
        import * as THREE from 'three';
        
        // 导入WebXR相关模块：
        // VRButton: 创建进入VR模式的按钮
        import { VRButton } from 'three/addons/webxr/VRButton.js';
        // XRControllerModelFactory: 创建XR控制器模型
        import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
        // OculusHandModel: Oculus手部模型
        import { OculusHandModel } from 'three/addons/webxr/OculusHandModel.js';
        // OculusHandPointerModel: 手部指针模型，用于射线检测
        import { OculusHandPointerModel } from 'three/addons/webxr/OculusHandPointerModel.js';
        // createText: 创建3D文本的辅助函数
        import { createText } from 'three/addons/webxr/Text2D.js';
        
        // 导入ECS（实体-组件-系统）架构库：
        // ECS是一种游戏开发架构模式，将数据（组件）、行为（系统）和实体分离
        // World: ECS世界，管理所有实体、组件和系统
        // System: 系统基类，处理具有特定组件的实体
        // Component: 组件基类，存储实体数据
        // TagComponent: 标签组件基类，用于标记实体
        // Types: 类型定义，用于组件属性类型检查
        import { World, System, Component, TagComponent, Types } from 'three/addons/libs/ecsy.module.js';

        /*
        ======================================================================
        ECS 组件定义部分
        组件是实体的数据容器，只存储数据，不包含逻辑
        ======================================================================
        */

        /**
         * Object3D组件
         * 作用：将Three.js的3D对象与ECS实体关联
         * 原理：每个需要渲染的3D物体都需要这个组件
         */
        class Object3D extends Component { }
        // 定义组件的数据结构
        Object3D.schema = {
            // object属性：引用类型的Three.js对象
            // Types.Ref表示这是一个引用类型，指向内存中的对象
            object: { type: Types.Ref }
        };

        /**
         * Button组件
         * 作用：定义按钮的行为和状态
         * 包含：当前状态、前一状态和点击时的回调函数
         */
        class Button extends Component { }
        Button.schema = {
            // currState: 当前状态，有三种可能值：
            // 'none': 无交互状态（默认）
            // 'hovered': 鼠标/手部悬停在按钮上
            // 'pressed': 按钮被按下
            currState: { type: Types.String, default: 'none' },
            // prevState: 前一帧的状态，用于检测状态变化
            prevState: { type: Types.String, default: 'none' },
            // action: 点击按钮时执行的回调函数
            // 使用箭头函数作为默认值，确保类型安全
            action: { type: Types.Ref, default: () => { } }
        };

        /**
         * Intersectable标签组件
         * 作用：标记可以被射线检测的实体
         * 说明：这是一个标签组件，不包含数据，只用于标记
         * 使用场景：按钮、可交互物体等
         */
        class Intersectable extends TagComponent { }

        /**
         * Rotating标签组件
         * 作用：标记需要自动旋转的实体
         * 使用场景：需要展示旋转动画的物体
         */
        class Rotating extends TagComponent { }

        /**
         * HandsInstructionText标签组件
         * 作用：标记手部交互说明文本
         * 使用场景：当用户进入VR模式时显示操作指引
         */
        class HandsInstructionText extends TagComponent { }

        /**
         * OffsetFromCamera组件
         * 作用：定义实体相对于相机的位置偏移
         * 使用场景：UI元素需要跟随相机移动时
         */
        class OffsetFromCamera extends Component { }
        OffsetFromCamera.schema = {
            // x, y, z: 相对于相机位置的偏移量
            x: { type: Types.Number, default: 0 },
            y: { type: Types.Number, default: 0 },
            z: { type: Types.Number, default: 0 },
        };

        /**
         * NeedCalibration标签组件
         * 作用：标记需要根据相机位置进行校准的实体
         * 说明：在WebXR会话开始时，这些实体会根据相机位置重新定位
         */
        class NeedCalibration extends TagComponent { }

        /*
        ======================================================================
        ECS 系统定义部分
        系统处理具有特定组件的实体，包含游戏逻辑
        ======================================================================
        */

        /**
         * ButtonSystem: 按钮系统
         * 职责：
         * 1. 更新所有按钮的视觉状态（缩放效果）
         * 2. 检测按钮点击事件并执行相应动作
         * 3. 管理按钮状态的状态机转换
         */
        class ButtonSystem extends System {
            /**
             * execute方法：每帧执行，处理按钮逻辑
             * @param {number} delta - 上一帧到当前帧的时间差（秒）
             * @param {number} time - 从程序开始经过的总时间（秒）
             */
            execute( /* delta, time */ ) {
                // 遍历所有包含Button组件的实体
                // queries.buttons.results是ECS框架提供的查询结果
                this.queries.buttons.results.forEach( entity => {
                    // 获取可变的Button组件引用（需要修改其状态）
                    const button = entity.getMutableComponent( Button );
                    // 获取与实体关联的Three.js对象
                    const buttonMesh = entity.getComponent( Object3D ).object;
                    
                    // 根据按钮状态更新视觉表现
                    if ( button.currState == 'none' ) {
                        // 无交互状态：恢复正常大小
                        buttonMesh.scale.set( 1, 1, 1 );
                    } else {
                        // 悬停或按下状态：放大10%以提供视觉反馈
                        buttonMesh.scale.set( 1.1, 1.1, 1.1 );
                    }

                    // 检测按钮点击事件（状态从非按下变为按下）
                    // 这种检测方式确保每次按下只触发一次动作
                    if ( button.currState == 'pressed' && button.prevState != 'pressed' ) {
                        // 执行按钮关联的回调函数
                        button.action();
                    }

                    // 状态管理：保存当前状态到前一状态，并重置当前状态
                    // 当前状态将由HandRaySystem在下一帧根据交互情况重新设置
                    button.prevState = button.currState;
                    button.currState = 'none'; // 清空当前状态，等待下一帧更新
                } );
            }
        }
        // 定义系统查询：系统需要处理的组件组合
        ButtonSystem.queries = {
            buttons: {
                components: [ Button ] // 查询所有包含Button组件的实体
            }
        };

        /**
         * HandRaySystem: 手部射线系统
         * 职责：
         * 1. 检测手部射线与可交互物体的交点
         * 2. 更新手部指针光标位置
         * 3. 根据交互情况更新按钮状态
         */
        class HandRaySystem extends System {
            /**
             * init方法：系统初始化时调用
             * @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; // 相交的实体
                    
                    // 遍历所有可交互物体，检测射线交点
                    this.queries.intersectable.results.forEach( entity => {
                        const object = entity.getComponent( Object3D ).object;
                        // 检测射线与物体的交点
                        // 第二个参数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';
                            }
                        }
                    } else {
                        // 没有交点：设置光标到默认距离（1.5单位）
                        hp.setCursor( 1.5 );
                    }
                } );
            }
        }
        HandRaySystem.queries = {
            intersectable: {
                components: [ Intersectable ] // 查询所有可交互实体
            }
        };

        /**
         * RotatingSystem: 旋转系统
         * 职责：使标记为Rotating的实体持续旋转
         */
        class RotatingSystem extends System {
            /**
             * execute方法：每帧更新旋转
             * @param {number} delta - 时间增量，确保旋转速度与帧率无关
             */
            execute( delta/*, time*/ ) {
                this.queries.rotatingObjects.results.forEach( entity => {
                    const object = entity.getComponent( Object3D ).object;
                    // 绕X轴和Y轴旋转，速度系数为0.4弧度/秒
                    object.rotation.x += 0.4 * delta;
                    object.rotation.y += 0.4 * delta;
                } );
            }
        }
        RotatingSystem.queries = {
            rotatingObjects: {
                components: [ Rotating ] // 查询所有需要旋转的实体
            }
        };

        /**
         * InstructionSystem: 说明系统
         * 职责：控制手部交互说明文本的显示和隐藏
         * 逻辑：当控制器可见时显示说明，否则隐藏
         */
        class InstructionSystem extends System {
            init( attributes ) {
                // 保存控制器模型的引用
                this.controllers = attributes.controllers;
            }

            execute( /* delta, time */ ) {
                let visible = false;
                // 检查是否有控制器可见（表示已进入VR模式）
                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 => {
                    // 只有在WebXR会话激活时才进行校准
                    if ( this.renderer.xr.getSession() ) {
                        const offset = entity.getComponent( OffsetFromCamera );
                        const object = entity.getComponent( Object3D ).object;
                        // 获取XR相机（WebXR会话中的相机）
                        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 ] // 查询所有需要校准的实体
            }
        };

        /*
        ======================================================================
        主程序部分：全局变量和主函数
        ======================================================================
        */

        // 创建ECS世界实例：管理所有实体、组件和系统
        const world = new World();
        // 创建Three.js时钟：用于计算时间差，实现帧率无关的动画
        const clock = new THREE.Clock();
        // 全局变量声明：将在init函数中初始化
        let camera, scene, renderer;

        // 调用初始化函数，启动程序
        init();

        /**
         * 创建按钮网格的辅助函数
         * 作用：快速创建标准化的按钮3D对象
         * @param {number} x - X轴尺寸（宽度）
         * @param {number} y - Y轴尺寸（高度）
         * @param {number} z - Z轴尺寸（厚度）
         * @param {number} color - 颜色值（十六进制，如0xff0000表示红色）
         * @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 );
            // 启用阴影：按钮可以投射阴影
            buttonMesh.castShadow = true;
            // 按钮可以接收其他物体投射的阴影
            buttonMesh.receiveShadow = true;
            return buttonMesh;
        }

        /**
         * 初始化函数
         * 作用：设置整个Three.js场景的所有元素
         * 包括：场景、相机、渲染器、灯光、控制器、3D物体、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 );

            // ==================== 相机设置 ====================
            // 创建透视相机：
            // 参数1: 视野角度(FOV) - 50度
            // 参数2: 宽高比 - 根据窗口大小计算
            // 参数3: 近裁剪面 - 0.1单位
            // 参数4: 远裁剪面 - 10单位
            camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.1, 10 );
            // 设置相机初始位置：(x, y, z)
            // y=1.2模拟人眼高度，z=0.3稍微向前偏移
            camera.position.set( 0, 1.2, 0.3 );

            // ==================== 灯光设置 ====================
            // 添加半球光：模拟天空和地面的环境光
            // 参数1: 天空颜色，参数2: 地面颜色，参数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; // 启用阴影投射
            // 设置阴影相机范围：创建一个2x2x?的视锥体
            light.shadow.camera.top = 2;
            light.shadow.camera.bottom = -2;
            light.shadow.camera.right = 2;
            light.shadow.camera.left = -2;
            // 设置阴影贴图分辨率：4096x4096，值越高阴影越清晰
            light.shadow.mapSize.set( 4096, 4096 );
            scene.add( light );

            // ==================== 渲染器设置 ====================
            // 创建WebGL渲染器，开启抗锯齿
            renderer = new THREE.WebGLRenderer( { antialias: true } );
            // 设置设备像素比，适应高DPI屏幕
            renderer.setPixelRatio( window.devicePixelRatio );
            // 设置渲染器大小为窗口大小
            renderer.setSize( window.innerWidth, window.innerHeight );
            // 设置动画循环回调函数（替代传统的requestAnimationFrame）
            renderer.setAnimationLoop( animate );
            // 启用阴影映射
            renderer.shadowMap.enabled = true;
            // 启用WebXR支持
            renderer.xr.enabled = true;
            // 禁用相机自动更新，我们将手动更新XR相机
            renderer.xr.cameraAutoUpdate = false;

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

            // ==================== WebXR配置 ====================
            // 配置WebXR会话初始化参数
            const sessionInit = {
                // 要求手部追踪功能（必须支持）
                requiredFeatures: [ 'hand-tracking' ]
            };

            // 创建VR按钮并添加到页面
            // VR按钮会处理进入/退出VR模式的逻辑
            document.body.appendChild( VRButton.createButton( renderer, sessionInit ) );

            // ==================== 控制器设置 ====================
            // 获取两个XR控制器（左右手）
            const controller1 = renderer.xr.getController( 0 );
            scene.add( controller1 );

            const controller2 = renderer.xr.getController( 1 );
            scene.add( controller2 );

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

            // ----- 左手设置 -----
            // 获取左手控制器握把（用于显示控制器模型）
            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 );

            // ----- 右手设置 -----
            // 获取右手控制器握把
            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 );

            // ==================== 创建场景物体 ====================

            // ----- 地板 -----
            // 创建4x4的地板平面
            const floorGeometry = new THREE.PlaneGeometry( 4, 4 );
            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 ); // 0.24宽，0.5高
            const menuMaterial = new THREE.MeshPhongMaterial( {
                opacity: 0, // 完全透明
                transparent: true, // 启用透明度
            } );
            const menuMesh = new THREE.Mesh( menuGeometry, menuMaterial );
            // 设置菜单位置：相机右侧0.4单位，高度1单位，向前1单位
            menuMesh.position.set( 0.4, 1, -1 );
            // 轻微旋转，面向用户
            menuMesh.rotation.y = - Math.PI / 12;
            scene.add( menuMesh );

            // ----- 橙色按钮 -----
            // 功能：将圆环结变为橙色
            const orangeButton = makeButtonMesh( 0.2, 0.1, 0.01, 0xffd3b5 );
            // 在菜单面板中的位置：上方第一个
            orangeButton.position.set( 0, 0.18, 0 );
            menuMesh.add( orangeButton );

            // ----- 粉色按钮 -----
            // 功能：将圆环结变为粉色
            const pinkButton = makeButtonMesh( 0.2, 0.1, 0.01, 0xe84a5f );
            pinkButton.position.set( 0, 0.06, 0 );
            menuMesh.add( pinkButton );

            // ----- 重置按钮 -----
            // 功能：恢复圆环结的原始颜色
            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 );

            // ----- 退出按钮 -----
            // 功能：退出VR会话
            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 tkGeometry = new THREE.TorusKnotGeometry( 0.5, 0.2, 200, 32 );
            const tkMaterial = new THREE.MeshPhongMaterial( { color: 0xffffff } );
            tkMaterial.metalness = 0.8; // 金属质感
            const torusKnot = new THREE.Mesh( tkGeometry, tkMaterial );
            torusKnot.position.set( 0, 1, -5 ); // 放置在场景中央靠后位置
            scene.add( torusKnot );

            // ----- 手部交互说明文本 -----
            const instructionText = createText( '这是WebXR手部追踪演示，请用手部进行交互探索。', 0.04 );
            instructionText.position.set( 0, 1.6, -0.6 ); // 放置在用户视线前方
            scene.add( instructionText );

            // ----- 退出提示文本 -----
            const exitText = createText( '正在退出VR会话...', 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( Rotating )
                .registerComponent( HandsInstructionText )
                .registerComponent( OffsetFromCamera )
                .registerComponent( NeedCalibration );

            // 注册所有系统，并传入必要的参数
            world
                // 旋转系统：处理物体旋转
                .registerSystem( RotatingSystem )
                // 说明系统：传入控制器引用，用于检测VR模式
                .registerSystem( InstructionSystem, { controllers: [ controllerGrip1, controllerGrip2 ] } )
                // 校准系统：传入渲染器和相机引用
                .registerSystem( CalibrationSystem, { renderer: renderer, camera: camera } )
                // 按钮系统：处理按钮交互
                .registerSystem( ButtonSystem )
                // 手部射线系统：传入手部指针模型引用
                .registerSystem( HandRaySystem, { handPointers: [ handPointer1, handPointer2 ] } );

            // ==================== 创建ECS实体 ====================
            // 实体是组件的数据容器，通过组合组件定义对象的行为

            // ----- 菜单实体 -----
            // 菜单面板需要跟随相机，且可被射线检测
            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 } ); // 关联3D对象

            // ----- 橙色按钮实体 -----
            const obEntity = world.createEntity();
            obEntity.addComponent( Intersectable );
            obEntity.addComponent( Object3D, { object: orangeButton } );
            // 定义按钮动作：改变圆环结颜色为橙色
            const obAction = function () {
                torusKnot.material.color.setHex( 0xffd3b5 );
            };
            obEntity.addComponent( Button, { action: obAction } );

            // ----- 粉色按钮实体 -----
            const pbEntity = world.createEntity();
            pbEntity.addComponent( Intersectable );
            pbEntity.addComponent( Object3D, { object: pinkButton } );
            const pbAction = function () {
                torusKnot.material.color.setHex( 0xe84a5f ); // 粉色
            };
            pbEntity.addComponent( Button, { action: pbAction } );

            // ----- 重置按钮实体 -----
            const rbEntity = world.createEntity();
            rbEntity.addComponent( Intersectable );
            rbEntity.addComponent( Object3D, { object: resetButton } );
            const rbAction = function () {
                torusKnot.material.color.setHex( 0xffffff ); // 恢复白色
            };
            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; // 隐藏提示
                    renderer.xr.getSession().end(); // 结束WebXR会话
                }, 2000 );
            };
            ebEntity.addComponent( Button, { action: ebAction } );

            // ----- 圆环结实体 -----
            const tkEntity = world.createEntity();
            tkEntity.addComponent( Rotating ); // 标记为需要旋转
            tkEntity.addComponent( Object3D, { object: torusKnot } );

            // ----- 说明文本实体 -----
            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 );
        }

        /**
         * 动画循环函数
         * 作用：每帧调用，更新场景状态并渲染
         * 注意：这是通过renderer.setAnimationLoop设置的，不是传统的requestAnimationFrame
         */
        function animate() {
            // 获取时间增量：上一帧到当前帧的时间差（秒）
            // 使用时间增量可以确保动画速度与帧率无关
            const delta = clock.getDelta();
            // 获取经过的总时间（秒）
            const elapsedTime = clock.elapsedTime;
            
            // 更新XR相机：将WebXR设备的位姿信息同步到Three.js相机
            renderer.xr.updateCamera( camera );
            
            // 执行ECS世界更新：所有系统会按注册顺序执行
            // 参数1: 时间增量，参数2: 总经过时间
            world.execute( delta, elapsedTime );
            
            // 渲染场景：将3D场景绘制到canvas上
            renderer.render( scene, camera );
        }

    </script>
</body>

</html>