<!-- 代码功能概述
这是一个基于Three.js的WebXR球体射击游戏，允许用户在虚拟现实（VR）环境中使用控制器发射具有物理效果的球体。球体会在虚拟房间内反弹、碰撞，创造出逼真的物理交互体验。

核心功能模块
WebXR沉浸式体验

支持VR头盔和控制器

双控制器操作（左右手独立）

自动加载匹配设备的3D控制器模型

物理球体射击系统

按下控制器触发键发射球体

随机速度和方向的球体发射

800个球体实例循环使用

物理仿真环境

四面墙壁和地板的碰撞边界

球体之间的物理碰撞

重力、反弹系数等物理参数

两种交互模式

VR模式：使用控制器射线瞄准发射

桌面模式：使用鼠标轨道控制器浏览场景

主要技术点详解
1. Three.js核心架构
javascript
// 经典Three.js三大件
let scene = new THREE.Scene();      // 3D场景容器
let camera = new THREE.PerspectiveCamera(...); // 透视相机
let renderer = new THREE.WebGLRenderer(...);   // WebGL渲染器
场景图(Scene Graph)：层级化组织3D对象

透视投影：模拟人眼视角，支持近大远小

WebGL 2.0渲染：硬件加速的3D图形渲染

2. WebXR集成技术
javascript
renderer.xr.enabled = true; // 启用WebXR支持
XRButton.createButton(renderer, {...}); // 创建XR会话按钮
WebXR Device API：标准化VR/AR API

控制器输入处理：selectstart/selectend事件

姿态追踪：控制器位置和旋转的实时更新

3. 实例化渲染(Instanced Rendering)
javascript
spheres = new THREE.InstancedMesh(geometry, material, 800);
spheres.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
性能优化：800个球体只使用一个绘制调用

动态更新：每帧更新实例的变换矩阵

内存高效：共享几何体和材质数据

4. Rapier物理引擎集成
javascript
physics = await RapierPhysics(); // 异步加载物理引擎
physics.addScene(scene); // 自动扫描场景中的物理对象
刚体物理：静态物体（mass=0）和动态物体（mass>0）

碰撞检测：连续的碰撞检测避免穿透

约束求解：物理约束的数值求解

5. 控制器视觉表示系统
javascript
// 两种控制器模式
case 'tracked-pointer': // VR控制器射线
case 'gaze': // 头戴式凝视光标
自适应控制器模型：自动匹配用户设备

视觉反馈：射线/光标显示交互状态

握把方向：正确的手部姿势模拟

6. 物理发射算法
javascript
// 随机速度计算
velocity.x = (Math.random() - 0.5) * 2;
velocity.y = (Math.random() - 0.5) * 2;
velocity.z = (Math.random() - 9);
velocity.applyQuaternion(controller.quaternion); // 应用控制器方向
随机性：增加游戏性和视觉效果

方向继承：继承控制器的旋转方向

循环缓冲区：循环使用800个球体实例

7. 场景构建技术
javascript
// 房间线框 - 视觉参考
new BoxLineGeometry(6, 6, 6, 10, 10, 10);
// 物理碰撞体 - 不可见但参与物理计算
new THREE.MeshNormalMaterial({ visible: false });
分离视觉与物理：独立的视觉对象和碰撞体

模块化场景：墙壁、地板作为独立对象

灯光系统：半球光+方向光的组合照明

8. 动画和渲染循环
javascript
// WebXR优化的动画循环
renderer.setAnimationLoop(animate);
// 传统的requestAnimationFrame在WebXR中不适用
技术架构图
text
┌─────────────────────────────────────────────────┐
│               HTML5页面容器                      │
├─────────────────────────────────────────────────┤
│  Three.js渲染引擎        WebXR API              │
│      │                       │                  │
│      ├─ 场景图管理           ├─ 会话管理        │
│      ├─ 材质系统             ├─ 输入处理        │
│      ├─ 几何体系统           ├─ 姿态追踪        │
│      └─ 相机系统             └─ 控制器模型      │
├─────────────────────────────────────────────────┤
│           Rapier物理引擎                         │
│      ├─ 刚体动力学                              │
│      ├─ 碰撞检测                                │
│      ├─ 约束求解                                │
│      └─ 空间分区                                │
├─────────────────────────────────────────────────┤
│            WebGL 2.0渲染                         │
│      ├─ 实例化绘制                              │
│      ├─ 着色器编译                              │
│      └─ 帧缓冲区管理                            │
└─────────────────────────────────────────────────┘
性能优化策略
GPU优化

实例化渲染减少Draw Call

共享材质和几何体

静态批处理

CPU优化

对象池复用球体实例

事件委托减少事件监听器

向量和矩阵对象复用

内存优化

BufferGeometry减少内存占用

按需加载物理引擎

纹理和材质的智能管理

兼容性考虑
浏览器支持

支持Chrome、Firefox、Edge的WebXR

降级到非XR的轨道控制器模式

渐进增强的设计理念

设备适配

自动检测VR设备能力

适配不同控制器类型

响应式布局支持各种屏幕 -->


<!DOCTYPE html>
<!-- HTML5文档声明，语言设置为英文 -->
<html lang="en">
	<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：禁止用户手动缩放页面
			这些设置确保页面在移动设备上正确显示
		-->
		<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>
		<!-- 
			信息显示区域：
			- 显示Three.js官方链接和当前应用描述
			- id="info" 用于CSS样式定位
		-->
		<div id="info">
			<!-- 
				外部链接到Three.js官网：
				- target="_blank"：在新标签页打开链接
				- rel="noopener"：安全设置，防止新页面访问原页面的window对象
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> 
			WebXR - 球体射击模拟器
		</div>

		<!-- 
			导入映射(Import Map)：
			- 现代JavaScript模块系统特性
			- 定义模块路径别名，简化import语句
			- 浏览器原生支持，无需构建工具
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			- type="module"：声明为ES6模块
			- 支持import/export语法
			- 在模块作用域中运行，避免全局污染
		-->
		<script type="module">
			// ============================================
			// 模块导入部分
			// ============================================
			
			// 导入Three.js核心库的所有功能
			// THREE是Three.js的主要命名空间对象
			import * as THREE from 'three';

			// 从three.js附加组件中导入特定模块
			// BoxLineGeometry：用于创建线框立方体房间的几何体
			import { BoxLineGeometry } from 'three/addons/geometries/BoxLineGeometry.js';
			// XRButton：用于创建WebXR会话入口按钮的组件
			import { XRButton } from 'three/addons/webxr/XRButton.js';
			// XRControllerModelFactory：用于创建与设备匹配的3D控制器模型的工厂
			import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
			// RapierPhysics：高性能物理引擎的Three.js集成
			import { RapierPhysics } from 'three/addons/physics/RapierPhysics.js';
			// OrbitControls：非XR模式下的相机轨道控制器
			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

			// ============================================
			// 全局变量声明部分
			// ============================================
			
			// Three.js核心对象
			let camera;     // 相机：定义观察场景的视角
			let scene;      // 场景：包含所有3D对象的容器
			let renderer;   // 渲染器：负责将3D场景绘制到2D画布上

			// WebXR控制器对象
			let controller1;    // 第一个XR控制器（通常是左手）
			let controller2;    // 第二个XR控制器（通常是右手）
			
			// 控制器握把对象（用于附加3D模型）
			let controllerGrip1;  // 第一个控制器的握把
			let controllerGrip2;  // 第二个控制器的握把

			// 场景对象引用
			let room;       // 房间线框对象
			let spheres;    // 球体实例化网格对象（包含所有球体）
			let physics;    // 物理引擎实例

			// 临时向量对象（用于计算球体发射速度）
			// 避免在每帧动画中创建新对象，提高性能
			const velocity = new THREE.Vector3();

			// 球体计数器
			// 用于跟踪当前应该发射哪个球体（循环使用800个球体实例）
			let count = 0;

			// ============================================
			// 初始化调用
			// ============================================
			
			// 第一步：初始化Three.js场景和WebXR设置
			init();
			
			// 第二步：异步初始化物理引擎
			// await等待物理引擎加载完成后再继续执行
			await initPhysics();

			// ============================================
			// 函数定义部分
			// ============================================
			
			/**
			 * 主初始化函数
			 * 负责创建Three.js核心对象、设置场景、灯光、渲染器
			 * 配置WebXR控制器和事件监听器
			 */
			function init() {
				// 创建Three.js场景对象
				// 场景是所有3D对象的根容器
				scene = new THREE.Scene();
				// 设置场景背景颜色为深灰色（十六进制颜色码）
				scene.background = new THREE.Color(0x505050);

				// 创建透视相机（Perspective Camera）
				// 参数说明：
				// 1. 视野角度（FOV）：50度，类似人眼视野
				// 2. 宽高比：根据窗口大小动态计算
				// 3. 近裁剪面：0.1，距离相机0.1单位以内的物体不显示
				// 4. 远裁剪面：50，距离相机50单位以外的物体不显示
				camera = new THREE.PerspectiveCamera(
					50, 
					window.innerWidth / window.innerHeight, 
					0.1, 
					50
				);
				// 设置相机初始位置（x, y, z坐标）
				// y=1.6模拟人眼站立时的平均高度（单位：米）
				camera.position.set(0, 1.6, 3);

				// 创建房间线框（视觉参考）
				// BoxLineGeometry参数：
				// 宽6单位，高6单位，深6单位
				// 宽度分段10，高度分段10，深度分段10（决定线框密度）
				room = new THREE.LineSegments(
					new BoxLineGeometry(6, 6, 6, 10, 10, 10),
					new THREE.LineBasicMaterial({ color: 0x808080 }) // 灰色线框材质
				);
				// 将房间几何体向上移动3个单位
				// 使房间中心位于y=3处（房间高度6，这样地板在y=0）
				room.geometry.translate(0, 3, 0);
				// 将房间添加到场景中
				scene.add(room);

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

				// 添加方向光（模拟主要光源，如太阳）
				const light = new THREE.DirectionalLight(0xffffff, 3);
				// 设置光源方向向量并归一化（长度为1）
				light.position.set(1, 1, 1).normalize();
				scene.add(light);

				// 创建WebGL渲染器
				// antialias: true 开启抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer({ antialias: true });
				// 设置设备像素比，适配高DPI屏幕（如Retina显示屏）
				renderer.setPixelRatio(window.devicePixelRatio);
				// 设置渲染器尺寸为整个窗口大小
				renderer.setSize(window.innerWidth, window.innerHeight);
				// 设置动画循环回调函数（替代传统的requestAnimationFrame）
				renderer.setAnimationLoop(animate);
				// 启用WebXR支持
				renderer.xr.enabled = true;
				// 将渲染器的canvas元素添加到HTML文档的body中
				document.body.appendChild(renderer.domElement);

				// 创建轨道控制器（用于非XR模式下的相机控制）
				// 允许用户用鼠标拖拽、缩放来查看场景
				const controls = new OrbitControls(camera, renderer.domElement);
				controls.maxDistance = 10;  // 最大缩放距离
				controls.target.y = 1.6;    // 控制目标点的高度（与相机高度一致）
				controls.update();           // 更新控制器状态

				// 创建并添加WebXR入口按钮
				// 用户点击此按钮可进入VR/AR模式
				document.body.appendChild(XRButton.createButton(renderer, {
					// 请求深度感知特性（如果设备支持）
					'optionalFeatures': ['depth-sensing'],
					// 深度感知配置
					'depthSensing': {
						// 优先使用GPU优化的深度数据
						'usagePreference': ['gpu-optimized'],
						// 数据格式偏好（空数组表示无特殊偏好）
						'dataFormatPreference': []
					}
				}));

				// ============================================
				// 控制器事件处理函数
				// ============================================
				
				/**
				 * 选择开始事件处理函数
				 * 当用户按下控制器选择按钮时触发
				 * this指向触发事件的控制器对象
				 */
				function onSelectStart() {
					// 在控制器的userData对象中存储选择状态
					// userData是Three.js对象提供的自定义数据存储区
					this.userData.isSelecting = true;
				}

				/**
				 * 选择结束事件处理函数
				 * 当用户释放控制器选择按钮时触发
				 */
				function onSelectEnd() {
					this.userData.isSelecting = false;
				}

				// ============================================
				// 第一个控制器设置（索引0）
				// ============================================
				
				// 获取第一个WebXR控制器
				controller1 = renderer.xr.getController(0);
				// 绑定选择开始事件
				controller1.addEventListener('selectstart', onSelectStart);
				// 绑定选择结束事件
				controller1.addEventListener('selectend', onSelectEnd);
				// 绑定控制器连接事件
				controller1.addEventListener('connected', function (event) {
					// event.data包含控制器信息
					// 根据控制器类型创建视觉表示并添加到控制器
					this.add(buildController(event.data));
				});
				// 绑定控制器断开连接事件
				controller1.addEventListener('disconnected', function () {
					// 移除控制器的视觉表示（第一个子元素）
					this.remove(this.children[0]);
				});
				// 将控制器添加到场景中
				scene.add(controller1);

				// ============================================
				// 第二个控制器设置（索引1）
				// ============================================
				
				// 获取第二个WebXR控制器
				controller2 = renderer.xr.getController(1);
				// 绑定相同的事件处理函数
				controller2.addEventListener('selectstart', onSelectStart);
				controller2.addEventListener('selectend', onSelectEnd);
				controller2.addEventListener('connected', function (event) {
					this.add(buildController(event.data));
				});
				controller2.addEventListener('disconnected', function () {
					this.remove(this.children[0]);
				});
				scene.add(controller2);

				// ============================================
				// 控制器模型加载
				// ============================================
				
				// 创建XR控制器模型工厂
				// 自动加载与用户设备匹配的3D控制器模型
				const controllerModelFactory = new XRControllerModelFactory();

				// 获取第一个控制器的握把对象
				// 握把是控制器模型的父对象，确保正确方向
				controllerGrip1 = renderer.xr.getControllerGrip(0);
				// 创建控制器模型并添加到握把
				controllerGrip1.add(controllerModelFactory.createControllerModel(controllerGrip1));
				// 将握把添加到场景
				scene.add(controllerGrip1);

				// 第二个控制器握把设置（同上）
				controllerGrip2 = renderer.xr.getControllerGrip(1);
				controllerGrip2.add(controllerModelFactory.createControllerModel(controllerGrip2));
				scene.add(controllerGrip2);

				// ============================================
				// 窗口事件监听
				// ============================================
				
				// 监听窗口大小变化事件
				// 当用户调整浏览器窗口大小时触发
				window.addEventListener('resize', onWindowResize);
			}

			/**
			 * 根据控制器类型构建视觉表示
			 * @param {Object} data - 控制器数据对象，包含targetRayMode等信息
			 * @returns {THREE.Object3D} 控制器的视觉表示对象
			 */
			function buildController(data) {
				// 声明几何体和材质变量
				let geometry, material;

				// 根据控制器的目标射线模式创建不同的视觉表示
				switch (data.targetRayMode) {
					case 'tracked-pointer':
						// 追踪指针模式（如VR控制器、手柄）
						// 创建一条射线来表示控制器的指向
						geometry = new THREE.BufferGeometry();
						// 设置顶点位置：起点(0,0,0)和终点(0,0,-1)
						// 6个数值代表两个点的x,y,z坐标
						geometry.setAttribute('position', new THREE.Float32BufferAttribute([0, 0, 0, 0, 0, -1], 3));
						// 设置顶点颜色：起点灰色(0.5,0.5,0.5)和终点黑色(0,0,0)
						geometry.setAttribute('color', new THREE.Float32BufferAttribute([0.5, 0.5, 0.5, 0, 0, 0], 3));
						// 创建线材质，启用顶点颜色和加法混合
						material = new THREE.LineBasicMaterial({
							vertexColors: true,
							blending: THREE.AdditiveBlending  // 加法混合使线条更亮
						});
						// 返回线对象
						return new THREE.Line(geometry, material);

					case 'gaze':
						// 凝视模式（如Cardboard、Daydream等基于头瞄的设备）
						// 创建一个圆环来表示凝视点
						geometry = new THREE.RingGeometry(0.02, 0.04, 32);
						// 将圆环移动到z=-1的位置（相机前方）
						geometry.translate(0, 0, -1);
						// 创建基础材质，半透明
						material = new THREE.MeshBasicMaterial({
							opacity: 0.5,
							transparent: true
						});
						// 返回圆环网格对象
						return new THREE.Mesh(geometry, material);
					// 注意：没有default case，理论上应该始终匹配上述模式之一
				}
			}

			/**
			 * 窗口大小调整事件处理函数
			 * 确保渲染尺寸和相机比例与窗口大小匹配
			 */
			function onWindowResize() {
				// 更新相机宽高比
				camera.aspect = window.innerWidth / window.innerHeight;
				// 更新相机投影矩阵（必须调用此方法使更改生效）
				camera.updateProjectionMatrix();
				// 更新渲染器尺寸
				renderer.setSize(window.innerWidth, window.innerHeight);
			}

			/**
			 * 初始化物理引擎（异步函数）
			 * 创建物理场景、刚体、碰撞体
			 */
			async function initPhysics() {
				// 异步加载Rapier物理引擎
				// await暂停函数执行，直到Promise完成
				physics = await RapierPhysics();

				// ============================================
				// 创建静态碰撞体（地板和墙壁）
				// 这些物体质量设为0，不会受重力影响
				// ============================================
				
				{
					// 创建立方体几何体（用于地板和墙壁）
					const geometry = new THREE.BoxGeometry(6, 2, 6);
					// 创建不可见材质（物理碰撞体不需要可见）
					const material = new THREE.MeshNormalMaterial({ visible: false });

					// 创建地板
					const floor = new THREE.Mesh(geometry, material);
					floor.position.y = -1;  // 地板在y=-1位置
					// 在userData中存储物理属性
					// mass: 0 表示静态物体（无限质量）
					floor.userData.physics = { mass: 0 };
					scene.add(floor);

					// 创建正X方向墙壁（右侧墙壁）
					const wallPX = new THREE.Mesh(geometry, material);
					wallPX.position.set(4, 3, 0);      // 位置：x=4, y=3, z=0
					wallPX.rotation.z = Math.PI / 2;  // 绕Z轴旋转90度
					wallPX.userData.physics = { mass: 0 };
					scene.add(wallPX);

					// 创建负X方向墙壁（左侧墙壁）
					const wallNX = new THREE.Mesh(geometry, material);
					wallNX.position.set(-4, 3, 0);     // 位置：x=-4, y=3, z=0
					wallNX.rotation.z = Math.PI / 2;  // 绕Z轴旋转90度
					wallNX.userData.physics = { mass: 0 };
					scene.add(wallNX);

					// 创建正Z方向墙壁（后侧墙壁）
					const wallPZ = new THREE.Mesh(geometry, material);
					wallPZ.position.set(0, 3, 4);      // 位置：x=0, y=3, z=4
					wallPZ.rotation.x = Math.PI / 2;  // 绕X轴旋转90度
					wallPZ.userData.physics = { mass: 0 };
					scene.add(wallPZ);

					// 创建负Z方向墙壁（前侧墙壁）
					const wallNZ = new THREE.Mesh(geometry, material);
					wallNZ.position.set(0, 3, -4);     // 位置：x=0, y=3, z=-4
					wallNZ.rotation.x = Math.PI / 2;  // 绕X轴旋转90度
					wallNZ.userData.physics = { mass: 0 };
					scene.add(wallNZ);
				}

				// ============================================
				// 创建球体实例化网格
				// 使用InstancedMesh高效渲染大量相同几何体
				// ============================================
				
				// 创建二十面体几何体（近似球体）
				// 参数：半径0.08，细分级别3
				const geometry = new THREE.IcosahedronGeometry(0.08, 3);
				// 创建Lambert材质（受光照影响，性能较好）
				const material = new THREE.MeshLambertMaterial();
				
				// 创建实例化网格：800个实例，共享相同的几何体和材质
				spheres = new THREE.InstancedMesh(geometry, material, 800);
				// 设置实例矩阵为动态绘制（频繁更新）
				spheres.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
				// 设置物理属性：质量1（动态物体），恢复系数1.1（有弹性）
				spheres.userData.physics = { mass: 1, restitution: 1.1 };
				// 添加到场景
				scene.add(spheres);

				// 临时变量：用于设置每个实例的位置和颜色
				const matrix = new THREE.Matrix4();  // 4x4变换矩阵
				const color = new THREE.Color();     // 颜色对象

				// 初始化所有球体实例的位置和颜色
				for (let i = 0; i < spheres.count; i++) {
					// 生成随机位置
					// x: -2 到 2 之间
					// y: 0 到 4 之间
					// z: -2 到 2 之间
					const x = Math.random() * 4 - 2;
					const y = Math.random() * 4;
					const z = Math.random() * 4 - 2;

					// 创建位置变换矩阵
					matrix.setPosition(x, y, z);
					// 为第i个实例设置变换矩阵
					spheres.setMatrixAt(i, matrix);
					
					// 生成随机颜色
					// 0xffffff * Math.random() 生成随机的RGB颜色
					spheres.setColorAt(i, color.setHex(0xffffff * Math.random()));
				}

				// ============================================
				// 将整个场景添加到物理引擎
				// ============================================
				
				// 自动扫描场景中所有带有userData.physics的对象
				// 根据mass属性创建对应的静态或动态刚体
				physics.addScene(scene);
			}

			/**
			 * 处理控制器输入，发射球体
			 * @param {THREE.Group} controller - 控制器对象
			 */
			function handleController(controller) {
				// 检查控制器是否正在选择（触发键按下）
				if (controller.userData.isSelecting) {
					// 将当前球体（索引为count）移动到控制器位置
					physics.setMeshPosition(spheres, controller.position, count);

					// 计算随机发射速度
					// x方向：-1到1之间的随机值
					velocity.x = (Math.random() - 0.5) * 2;
					// y方向：-1到1之间的随机值
					velocity.y = (Math.random() - 0.5) * 2;
					// z方向：-9到-8之间的随机值（主要向后）
					velocity.z = (Math.random() - 9);
					
					// 应用控制器的旋转方向
					// 使发射方向与控制器指向一致
					velocity.applyQuaternion(controller.quaternion);

					// 为球体设置计算得到的速度
					physics.setMeshVelocity(spheres, velocity, count);

					// 递增计数器，循环使用球体实例
					// 当达到最大实例数时重置为0
					if (++count === spheres.count) count = 0;
				}
			}

			/**
			 * 动画循环函数（每帧调用）
			 * 这是Three.js应用的核心循环
			 */
			function animate() {
				// 处理两个控制器的输入（检查是否发射球体）
				handleController(controller1);
				handleController(controller2);

				// 渲染场景
				// 将3D场景通过相机视角渲染到2D画布上
				renderer.render(scene, camera);
				
				// 注意：这里没有显式调用requestAnimationFrame
				// 因为使用了renderer.setAnimationLoop(animate)
				// WebXR模式下会自动使用正确的刷新率
			}

			// ============================================
			// 注意：
			// 代码中没有显式的错误处理机制
			// 实际生产环境中应考虑添加try-catch和错误提示
			// ============================================
			
		</script>
	</body>
</html>