<!-- Three.js VR 交互沙盒 - 代码功能与技术点详解
一、总体功能概述
这是一个基于 WebXR 技术 的 三维虚拟现实交互演示环境，将传统 Web 技术与现代 VR 技术相结合，展示了以下核心功能：

核心展示内容：
玻璃质感的环面扭结物体 - 具有物理属性的透明 3D 模型

动态反射镜面 - 实时反射场景内容的镜子效果

三维交互界面 - 将传统 2D GUI 面板转换为 3D 空间中的交互对象

完整 VR 控制器支持 - 可在 VR 环境中使用手柄进行交互

实时性能监控 - 在 3D 空间中显示渲染性能数据

二、主要技术架构
1. Three.js 核心框架
场景管理 (THREE.Scene) - 所有 3D 对象的容器

透视相机 (THREE.PerspectiveCamera) - 模拟人眼视角的 3D 相机

WebGL 渲染器 (THREE.WebGLRenderer) - 硬件加速的 3D 渲染引擎

动画循环 (setAnimationLoop) - 60fps 的渲染更新机制

2. WebXR 虚拟现实集成
VR 模式切换 (VRButton) - 标准化的 VR 进入/退出按钮

控制器抽象 (XRController) - 统一的 VR 手柄输入处理

手柄模型 (XRControllerModelFactory) - 自动加载与设备匹配的 3D 手柄模型

射线交互 - 可视化手柄指向的交互射线

3. 高级渲染技术
A. 基于物理的渲染 (PBR)
javascript
new THREE.MeshPhysicalMaterial({
    transmission: 1.0,    // 完全透明（玻璃效果）
    roughness: 0,         // 完美光滑表面
    metalness: 0.25,      // 轻微金属质感
    thickness: 0.5,       // 物理厚度（影响折射）
    side: THREE.DoubleSide // 双面渲染
})
B. HDR 环境光照
文件格式：.hdr 高动态范围图像

映射方式：EquirectangularReflectionMapping

双重用途：同时作为场景背景和环境反射贴图

光照效果：提供真实的环境反射和全局光照

C. 实时反射技术 (Reflector)
技术原理：渲染到纹理 (Render to Texture)

实现方式：将场景从镜面视角渲染到纹理，再应用到反射面

性能优化：可调整纹理分辨率平衡质量与性能

4. 交互系统架构
A. HTML 与 3D 融合 (HTMLMesh)
javascript
// 将 DOM 元素转换为 3D 网格
const mesh = new HTMLMesh(gui.domElement);
mesh.position.set(-0.75, 1.5, -0.5);
mesh.rotation.y = Math.PI / 4;
mesh.scale.setScalar(2);
B. 统一交互事件处理 (InteractiveGroup)
多输入支持：鼠标、触摸、VR 控制器统一处理

事件冒泡：类似 DOM 的事件传播机制

射线检测：基于 3D 空间的精确命中检测

5. 动态参数系统
A. 实时几何体更新
javascript
function onChange() {
    torus.geometry.dispose(); // 释放旧几何体内存
    torus.geometry = new THREE.TorusKnotGeometry(...Object.values(parameters));
}
B. GUI 控制面板 (lil-gui)
参数范围：为每个参数定义最小/最大值

实时反馈：参数变化立即反映在 3D 模型上

内存管理：正确释放 WebGL 资源防止内存泄漏

三、关键技术实现细节
1. 环面扭结几何体 (TorusKnotGeometry)
数学参数：p 和 q 控制复杂的拓扑结构

细分级别：tubularSegments 和 radialSegments 控制网格密度

动态重建：参数变化时重新生成几何体

2. 动画系统
javascript
function animate() {
    const time = performance.now() * 0.0002;
    torus.rotation.x = time * 0.4; // X 轴慢速旋转
    torus.rotation.y = time;       // Y 轴持续旋转
    // 渲染和性能更新...
}
3. 性能监控集成 (Stats.js)
3D 空间显示：将性能面板作为纹理显示在场景中

纹理更新：手动更新 Canvas 纹理反映实时数据

样式定制：调整显示尺寸和位置

4. 响应式设计
javascript
function onWindowResize() {
    camera.aspect = window.innerWidth / window.innerHeight;
    camera.updateProjectionMatrix(); // 更新相机矩阵
    renderer.setSize(window.innerWidth, window.innerHeight);
}
四、系统架构特点
1. 模块化设计
ES6 模块：使用现代 JavaScript 模块系统

Import Maps：浏览器原生模块别名管理

职责分离：初始化、动画、事件处理逻辑分离

2. 内存管理
显式释放：geometry.dispose() 释放 WebGL 资源

纹理管理：HDR 纹理复用为环境和背景

对象池：可扩展为对象池模式管理频繁创建的对象

3. 跨平台兼容
桌面/移动端：响应式布局适应不同屏幕

VR/非 VR 模式：同一代码支持两种体验

输入设备：统一处理多种输入方式

五、可扩展性设计
1. 易于添加新功能
新 3D 对象：遵循现有的添加模式

新交互方式：基于 InteractiveGroup 扩展

新视觉效果：集成 Three.js 后期处理

2. 性能优化空间
LOD 系统：根据距离调整细节级别

实例化渲染：批量渲染相同物体

遮挡剔除：优化复杂场景渲染

3. VR 功能扩展
手部追踪：集成手部姿态识别

空间锚点：持久化虚拟物体位置

多人协作：添加网络同步功能 -->


<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <!-- 页面基础设置 -->
    <title>Three.js VR 三维交互沙盒环境</title>
    <meta charset="utf-8">
    <!-- 移动端适配，禁止用户缩放，确保在VR设备上的良好体验 -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
    <link type="text/css" rel="stylesheet" href="main.css">
</head>
<body>
    <!-- 页面信息展示区域 -->
    <div id="info">
        <h1>Three.js VR 交互沙盒</h1>
        <p>这是一个基于WebXR技术的虚拟现实交互演示环境</p>
        <p><strong>技术栈</strong>：Three.js + WebXR + WebGL 2.0</p>
        <p class="note">注意：需要支持WebXR的浏览器和VR设备以获得完整体验</p>
    </div>

    <!-- Import Maps - 模块导入映射，用于浏览器原生模块导入 -->
    <!-- 这是一种现代JavaScript模块管理技术，允许我们为模块指定别名 -->
    <script type="importmap">
        {
            "imports": {
                "three": "../build/three.module.js",
                "three/addons/": "./jsm/"
            }
        }
    </script>

    <!-- 主应用程序代码 -->
    <script type="module">
        // 导入 Three.js 核心模块
        // Three.js是一个强大的3D图形库，用于创建和显示3D计算机图形
        import * as THREE from 'three';

        // 导入 Three.js 附加组件
        // HDRLoader：用于加载高动态范围图像，提供更真实的光照效果
        import { HDRLoader } from 'three/addons/loaders/HDRLoader.js';
        // Reflector：创建反射面对象的组件，用于实现镜面反射效果
        import { Reflector } from 'three/addons/objects/Reflector.js';
        // VRButton：创建VR模式切换按钮的组件，符合WebXR标准
        import { VRButton } from 'three/addons/webxr/VRButton.js';

        // 导入交互相关组件
        // HTMLMesh：将HTML DOM元素转换为Three.js网格对象的组件
        import { HTMLMesh } from 'three/addons/interactive/HTMLMesh.js';
        // InteractiveGroup：创建交互式对象组的组件，统一处理交互事件
        import { InteractiveGroup } from 'three/addons/interactive/InteractiveGroup.js';
        // XRControllerModelFactory：创建XR控制器3D模型的工厂类
        import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';

        // 导入第三方库
        // GUI：轻量级图形用户界面库，用于创建参数控制面板
        import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
        // Stats：性能监控库，用于显示帧率、渲染时间等性能指标
        import Stats from 'three/addons/libs/stats.module.js';

        // 全局变量声明
        let camera, scene, renderer;   // 相机、场景、渲染器 - Three.js三大核心对象
        let reflector;                  // 反射面对象引用，用于后续操作和更新
        let stats, statsMesh;           // stats性能统计对象及其在3D场景中的网格表示

        // 参数对象 - 用于调整环面扭结几何体的参数
        // 这些参数可以通过GUI面板实时调整，实现交互式参数调节
        const parameters = {
            radius: 0.6,               // 环面主要半径：控制整个环面的大小
            tube: 0.2,                 // 管状半径：控制环面管的粗细
            tubularSegments: 150,      // 管状段数：沿管状方向的细分程度，值越高表面越光滑
            radialSegments: 20,        // 径向段数：环绕管状方向的细分程度
            p: 2,                      // 环面扭结参数p：数学参数，影响环绕大环的次数
            q: 3,                      // 环面扭结参数q：数学参数，影响环绕小环的次数
            thickness: 0.5             // 材质厚度：用于物理材质，控制玻璃效果的厚度
        };

        // 程序入口：调用初始化函数
        init();

        /**
         * 主初始化函数 - 应用程序的启动入口
         * 负责创建所有3D对象、设置场景、配置渲染器并建立交互系统
         * 这个函数按照逻辑顺序执行，确保各个组件的正确初始化和依赖关系
         */
        function init() {
            // ==================== 1. 创建基础场景 ====================
            // Scene对象是所有3D对象的容器，管理对象层次结构和场景属性
            scene = new THREE.Scene();

            // ==================== 2. 加载HDR环境贴图 ====================
            // HDR贴图提供高质量的环境光照和反射信息
            new HDRLoader()  // 创建HDR加载器实例
                .setPath('textures/equirectangular/')  // 设置纹理文件的相对路径
                .load('moonless_golf_1k.hdr', function (texture) {
                    // 设置纹理映射方式为等距柱状投影
                    // 这种映射方式常用于环境贴图，将2D图像映射到球面
                    texture.mapping = THREE.EquirectangularReflectionMapping;

                    // 设置场景背景：直接作为场景的背景图像
                    scene.background = texture;
                    // 设置环境贴图：为所有PBR材质提供环境反射信息
                    scene.environment = texture;
                    
                    // 注意：HDR贴图加载是异步的，加载完成后才会设置到场景中
                });

            // ==================== 3. 创建透视相机 ====================
            // PerspectiveCamera模拟人眼视角，创建3D透视效果
            camera = new THREE.PerspectiveCamera(
                50,                                 // 视场角(FOV)：50度，控制视野宽度
                window.innerWidth / window.innerHeight, // 宽高比：根据窗口尺寸动态计算
                0.1,                                // 近裁剪面：距离相机0.1单位以内的物体不显示
                10                                  // 远裁剪面：距离相机10单位以外的物体不显示
            );
            // 设置相机位置：X=0(中心)，Y=1.6(近似人眼高度)，Z=1.5(距离原点1.5单位)
            camera.position.set(0, 1.6, 1.5);

            // ==================== 4. 创建环面扭结几何体 ====================
            // TorusKnotGeometry创建数学上的环面扭结形状，参数从parameters对象获取
            const torusGeometry = new THREE.TorusKnotGeometry(...Object.values(parameters));
            
            // MeshPhysicalMaterial是物理基础渲染材质，模拟真实世界的光学属性
            const torusMaterial = new THREE.MeshPhysicalMaterial({
                transmission: 1.0,    // 透射率：1.0表示完全透明，模拟玻璃材质
                roughness: 0,         // 粗糙度：0表示完全光滑，产生清晰的反射和折射
                metalness: 0.25,      // 金属度：0.25表示略带金属质感
                thickness: 0.5,       // 厚度：控制折射效果的强度，模拟玻璃厚度
                side: THREE.DoubleSide // 双面渲染：材质两面都可见，适合透明物体
            });
            
            // 创建网格对象：结合几何体和材质，成为可渲染的3D对象
            const torus = new THREE.Mesh(torusGeometry, torusMaterial);
            torus.name = 'torus';                    // 设置对象名称，便于后续通过名称查找
            torus.position.y = 1.5;                  // 设置Y轴位置：抬升到视线水平
            torus.position.z = -2;                   // 设置Z轴位置：向屏幕内移动2单位
            scene.add(torus);                        // 将环面扭结添加到场景中

            // ==================== 5. 创建圆柱体平台 ====================
            // CylinderGeometry创建圆柱体几何体：顶部半径1，底部半径1，高度0.1，侧面细分50段
            const cylinderGeometry = new THREE.CylinderGeometry(1, 1, 0.1, 50);
            const cylinderMaterial = new THREE.MeshStandardMaterial(); // 标准材质
            const cylinder = new THREE.Mesh(cylinderGeometry, cylinderMaterial);
            cylinder.position.z = -2;                // 与环面扭结在相同深度
            scene.add(cylinder);

            // ==================== 6. 创建反射面（镜子效果） ====================
            // Reflector使用渲染到纹理技术实现实时反射效果
            reflector = new Reflector(
                new THREE.PlaneGeometry(2, 2),  // 平面几何体：2x2单位的正方形
                {
                    textureWidth: window.innerWidth,    // 反射纹理宽度：与屏幕同宽
                    textureHeight: window.innerHeight   // 反射纹理高度：与屏幕同高
                }
            );
            // 设置反射面的位置和旋转
            reflector.position.x = 1;               // X轴位置：场景右侧
            reflector.position.y = 1.5;             // Y轴位置：与环面高度相同
            reflector.position.z = -3;              // Z轴位置：在环面后面
            reflector.rotation.y = -Math.PI / 4;    // 旋转角度：-45度，面向场景中心
            scene.add(reflector);                   // 将反射面添加到场景

            // ==================== 7. 为反射面添加边框 ====================
            // 创建边框几何体：比反射面稍大，厚度0.1
            const frameGeometry = new THREE.BoxGeometry(2.1, 2.1, 0.1);
            const frameMaterial = new THREE.MeshPhongMaterial(); // Phong材质，支持镜面高光
            const frame = new THREE.Mesh(frameGeometry, frameMaterial);
            frame.position.z = -0.07;               // 将边框放在反射面稍前方
            reflector.add(frame);                   // 将边框添加为反射面的子对象，跟随反射面移动

            // ==================== 8. 创建WebGL渲染器 ====================
            // WebGLRenderer是Three.js的核心渲染器，使用WebGL API进行硬件加速渲染
            renderer = new THREE.WebGLRenderer({ 
                antialias: true  // 开启抗锯齿：平滑几何体边缘的锯齿
            });
            renderer.autoClear = false;             // 手动控制缓冲区清除：允许多次渲染
            renderer.setPixelRatio(window.devicePixelRatio); // 设置设备像素比：适应高DPI屏幕
            renderer.setSize(window.innerWidth, window.innerHeight); // 设置渲染尺寸：全屏
            renderer.setAnimationLoop(animate);     // 设置动画循环函数：每帧调用animate函数
            renderer.xr.enabled = true;             // 启用WebXR支持：开启VR/AR功能
            renderer.toneMapping = THREE.ACESFilmicToneMapping; // 设置色调映射算法：电影级色彩
            renderer.toneMappingExposure = 1;       // 设置曝光值：1为标准曝光
            document.body.appendChild(renderer.domElement); // 将渲染器的canvas元素添加到DOM

            // ==================== 9. 创建VR模式切换按钮 ====================
            // VRButton.createButton创建符合WebXR标准的VR进入/退出按钮
            document.body.appendChild(VRButton.createButton(renderer));

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

            // ==================== 11. 创建XR控制器射线指示器 ====================
            // 创建一条线段几何体，表示VR控制器的指向射线
            const geometry = new THREE.BufferGeometry();
            geometry.setFromPoints([
                new THREE.Vector3(0, 0, 0),      // 起点：控制器位置
                new THREE.Vector3(0, 0, -5)      // 终点：向前延伸5单位
            ]);

            // 创建第一个XR控制器（通常为右手）
            const controller1 = renderer.xr.getController(0);
            controller1.add(new THREE.Line(geometry)); // 将射线添加到控制器
            scene.add(controller1);                    // 将控制器添加到场景

            // 创建第二个XR控制器（通常为左手）
            const controller2 = renderer.xr.getController(1);
            controller2.add(new THREE.Line(geometry));
            scene.add(controller2);

            // ==================== 12. 创建XR控制器手柄3D模型 ====================
            // XRControllerModelFactory根据XR API提供的信息创建相应控制器的3D模型
            const controllerModelFactory = new XRControllerModelFactory();

            // 创建第一个控制器的手柄模型
            const controllerGrip1 = renderer.xr.getControllerGrip(0);
            controllerGrip1.add(controllerModelFactory.createControllerModel(controllerGrip1));
            scene.add(controllerGrip1);

            // 创建第二个控制器的手柄模型
            const controllerGrip2 = renderer.xr.getControllerGrip(1);
            controllerGrip2.add(controllerModelFactory.createControllerModel(controllerGrip2));
            scene.add(controllerGrip2);

            // ==================== 13. 创建GUI参数控制面板 ====================
            /**
             * 几何体参数变化处理函数
             * 当几何体参数改变时，重新创建环面扭结几何体
             */
            function onChange() {
                torus.geometry.dispose(); // 释放旧几何体的GPU内存，防止内存泄漏
                // 使用新参数重新创建几何体
                torus.geometry = new THREE.TorusKnotGeometry(...Object.values(parameters));
            }

            /**
             * 材质厚度参数变化处理函数
             * 当厚度参数改变时，直接更新材质属性（无需重建几何体）
             */
            function onThicknessChange() {
                torus.material.thickness = parameters.thickness;
            }

            // 创建GUI实例，设置面板宽度为300像素
            const gui = new GUI({ width: 300 });
            
            // 添加各项参数控制滑块，并绑定变化事件处理函数
            gui.add(parameters, 'radius', 0.0, 1.0).name('主半径').onChange(onChange);
            gui.add(parameters, 'tube', 0.0, 1.0).name('管状半径').onChange(onChange);
            gui.add(parameters, 'tubularSegments', 10, 150, 1).name('管状段数').onChange(onChange);
            gui.add(parameters, 'radialSegments', 2, 20, 1).name('径向段数').onChange(onChange);
            gui.add(parameters, 'p', 1, 10, 1).name('环绕参数P').onChange(onChange);
            gui.add(parameters, 'q', 0, 10, 1).name('环绕参数Q').onChange(onChange);
            gui.add(parameters, 'thickness', 0, 1).name('材质厚度').onChange(onThicknessChange);
            
            // 初始隐藏原始GUI的DOM元素，将在3D场景中以HTMLMesh形式显示
            gui.domElement.style.visibility = 'hidden';

            // ==================== 14. 创建交互组并设置事件监听 ====================
            // InteractiveGroup是一个特殊的组，可以统一管理子对象的交互事件
            const group = new InteractiveGroup();
            
            // 为交互组添加事件监听：
            group.listenToPointerEvents(renderer, camera);  // 监听鼠标和触摸事件
            group.listenToXRControllerEvents(controller1);  // 监听第一个XR控制器事件
            group.listenToXRControllerEvents(controller2);  // 监听第二个XR控制器事件
            
            scene.add(group); // 将交互组添加到场景

            // ==================== 15. 将GUI转换为HTMLMesh并添加到3D场景 ====================
            // HTMLMesh将DOM元素渲染为Three.js的纹理材质网格对象
            const mesh = new HTMLMesh(gui.domElement);
            mesh.position.x = -0.75;      // X轴位置：场景左侧
            mesh.position.y = 1.5;        // Y轴位置：与环面高度相同
            mesh.position.z = -0.5;       // Z轴位置：靠近相机
            mesh.rotation.y = Math.PI / 4; // 旋转角度：45度，面向相机
            mesh.scale.setScalar(2);      // 缩放：放大2倍，便于阅读和交互
            group.add(mesh);              // 将GUI网格添加到交互组

            // ==================== 16. 添加性能监控器（Stats.js） ====================
            // Stats.js创建性能监控面板，显示帧率、渲染时间等性能指标
            stats = new Stats();
            // 设置面板尺寸
            stats.dom.style.width = '80px';
            stats.dom.style.height = '48px';
            // 可选：设置面板样式，使其在3D场景中更清晰
            stats.dom.style.backgroundColor = 'rgba(0, 0, 0, 0.7)';
            stats.dom.style.color = '#00ff00';
            document.body.appendChild(stats.dom); // 将Stats面板添加到DOM

            // 将Stats面板转换为HTMLMesh并添加到3D场景
            statsMesh = new HTMLMesh(stats.dom);
            statsMesh.position.x = -0.75;      // X轴位置：与GUI面板对齐
            statsMesh.position.y = 2;          // Y轴位置：在GUI面板上方
            statsMesh.position.z = -0.6;       // Z轴位置：稍靠后
            statsMesh.rotation.y = Math.PI / 4; // 旋转角度：45度，与GUI面板一致
            statsMesh.scale.setScalar(2.5);    // 缩放：放大2.5倍
            group.add(statsMesh);              // 将Stats网格添加到交互组
            
            // ==================== 初始化完成 ====================
            // 此时所有3D对象已创建，场景已设置，渲染器已配置
            // 动画循环将开始运行，每帧调用animate函数
        }

        /**
         * 窗口大小变化处理函数
         * 响应浏览器窗口大小变化，调整相机和渲染器设置
         * 确保3D场景正确适应新的窗口尺寸
         */
        function onWindowResize() {
            // 更新相机宽高比：使用新的窗口宽高比
            camera.aspect = window.innerWidth / window.innerHeight;
            // 更新相机投影矩阵：必须调用此方法使宽高比更改生效
            camera.updateProjectionMatrix();

            // 更新渲染器尺寸：调整canvas元素的大小和渲染缓冲区
            renderer.setSize(window.innerWidth, window.innerHeight);
            
            // 注意：如果需要，这里还可以更新反射面的纹理尺寸
            // 但当前实现中反射面纹理尺寸在初始化时已固定
        }

        /**
         * 动画循环函数 - 每帧调用
         * 这是Three.js应用程序的核心循环，驱动所有动画和交互更新
         * 在VR模式下，这个函数由WebXR API调用；在普通模式下，由requestAnimationFrame调用
         */
        function animate() {
            // 1. 计算基于时间的动画参数
            // performance.now()返回页面加载以来的毫秒数，精度更高
            // 乘以0.0002将毫秒转换为秒，并放慢动画速度
            const time = performance.now() * 0.0002;
            
            // 通过名称获取环面扭结对象
            const torus = scene.getObjectByName('torus');
            
            // 2. 更新环面扭结的旋转动画
            // X轴旋转：较慢的速度，time * 0.4
            torus.rotation.x = time * 0.4;
            // Y轴旋转：正常速度，time
            torus.rotation.y = time;
            // 注意：这里可以添加更多动画效果，如缩放、位置变化等

            // 3. 渲染场景
            // 这是最关键的步骤：将3D场景通过相机视角渲染到2D画布
            renderer.render(scene, camera);

            // 4. 更新性能统计信息
            // Stats.js会更新帧率、帧时间等性能指标的显示
            stats.update();

            // 5. 更新HTMLMesh的纹理
            // 由于Stats.js使用canvas绘制性能图表，而canvas不会自动触发DOM更新
            // 因此需要手动更新HTMLMesh的纹理，确保3D场景中的性能面板显示最新数据
            statsMesh.material.map.update();
            
            // 注意：如果GUI面板也有动态内容，可能也需要类似更新
            // 但当前GUI是静态的，只有用户交互时才会变化，由Three.js自动处理
        }
        
        // ==================== 额外说明 ====================
        // 关于内存管理：
        // 1. 在onChange函数中，我们调用了torus.geometry.dispose()
        //    这是Three.js中重要的内存管理实践，防止WebGL内存泄漏
        // 2. 同样，如果材质也需要替换，应该调用torus.material.dispose()
        
        // 关于性能优化：
        // 1. 当前环面扭结的细分程度较高(tubularSegments: 150)
        //    在性能较低的设备上可能需要减少此值
        // 2. 反射面使用了全屏尺寸的纹理，消耗较多显存
        //    可以通过减小textureWidth/textureHeight来优化
        
        // 关于扩展性：
        // 1. 可以添加更多3D对象到场景中
        // 2. 可以实现更复杂的交互逻辑
        // 3. 可以添加后期处理效果（如泛光、景深等）
        // 4. 可以支持更多XR功能（如手部追踪、锚点等）
    </script>
</body>
</html>