<!-- Three.js VR传送功能代码详解
一、核心功能概述
这是一个基于Three.js + WebXR的虚拟现实传送演示应用，实现了以下核心功能：

1. VR场景构建
创建了一个6×6×6米的虚拟房间（线框立方体）

设置了环境光和定向光系统，模拟真实光照

定义了可传送的地板区域

2. 传送机制实现
射线瞄准：用户使用VR控制器指向地板位置

位置预览：实时显示圆形标记指示传送目标点

传送执行：释放控制器按钮后瞬间移动到目标位置

防眩晕设计：使用瞬间传送而非连续移动，减少VR不适感

3. 完整的VR交互系统
支持单人或双VR控制器操作

控制器可视化（匹配实际设备外观）

控制器射线可视化（指示瞄准方向）

二、主要技术点详解
1. WebXR API集成
javascript
// 关键技术：
renderer.xr.enabled = true;  // 启用WebXR
VRButton.createButton(renderer);  // 自动创建VR进入按钮
baseReferenceSpace = renderer.xr.getReferenceSpace();  // 获取XR坐标参考系
作用：

提供标准的VR会话管理

自动处理VR设备兼容性

管理头部追踪和控制器输入

2. 传送算法实现
javascript
// 传送核心算法：
const offsetPosition = { 
    x: -INTERSECTION.x, 
    y: -INTERSECTION.y, 
    z: -INTERSECTION.z, 
    w: 1 
};
const teleportSpaceOffset = baseReferenceSpace.getOffsetReferenceSpace(transform);
renderer.xr.setReferenceSpace(teleportSpaceOffset);
技术原理：

不是移动相机，而是移动整个参考空间

计算当前位置到目标位置的负向量偏移

通过修改XR参考空间实现"世界移动，用户不动"的错觉

3. 射线检测系统
javascript
// 射线检测流程：
tempMatrix.extractRotation(controller.matrixWorld);  // 1. 提取控制器旋转
raycaster.ray.origin.setFromMatrixPosition(controller.matrixWorld);  // 2. 设置射线起点
raycaster.ray.direction.set(0, 0, -1).applyMatrix4(tempMatrix);  // 3. 设置射线方向
const intersects = raycaster.intersectObjects([floor]);  // 4. 检测交点
关键技术：

从控制器变换矩阵提取精确的位置和朝向

使用THREE.Raycaster进行高效的3D碰撞检测

只检测与地板平面的交点，提高性能

4. 控制器管理系统
javascript
// 控制器架构：
controller1 = renderer.xr.getController(0);  // 逻辑控制器（处理输入）
controllerGrip1 = renderer.xr.getControllerGrip(0);  // 视觉控制器（显示模型）

// 自动加载匹配的3D模型
const model = controllerModelFactory.createControllerModel(controllerGrip1);
分层设计：

逻辑层：处理按钮事件、选择状态

视觉层：显示与实际设备匹配的3D模型

事件层：统一的selectstart/selectend事件处理

5. 性能优化技术
javascript
// 关键优化点：
renderer.setAnimationLoop(animate);  // 使用VR优化的动画循环
geometry.setAttribute('position', buffer);  // 使用BufferGeometry提高性能
marker.visible = INTERSECTION !== undefined;  // 条件渲染标记
三、系统架构
1. 初始化阶段
text
初始化流程：
1. 创建基础3D场景（场景图、相机、灯光）
2. 设置WebXR渲染器和VR按钮
3. 创建房间、地板、传送标记等场景对象
4. 设置控制器系统和事件监听
5. 启动动画循环
2. 每帧更新循环
text
动画循环流程：
1. 重置交点状态
2. 检测各控制器选择状态
3. 执行射线检测（如正在选择）
4. 更新传送标记位置和可见性
5. 渲染场景（VR模式下渲染两次：左眼/右眼）
3. 事件处理流程
text
传送执行流程：
用户按下选择按钮 → 开始射线检测 → 显示传送标记
用户释放选择按钮 → 计算偏移向量 → 更新参考空间 → 完成传送
四、关键技术特色
1. 无眩晕移动方案
瞬间传送：避免连续移动引起的晕动症

位置预览：传送前显示目标位置，增强空间认知

视觉反馈：明显的传送标记，提供操作确认

2. 跨设备兼容性
支持6DOF控制器（Oculus Touch、Vive控制器）

支持3DOF凝视控制（Cardboard、Daydream）

自动适配不同控制器的可视化模型

3. 模块化设计
场景管理：独立的房间、地板、标记对象

控制器抽象：统一的事件处理接口

渲染分离：逻辑更新与渲染解耦 -->


<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- 页面标题：Three.js VR传送演示 -->
		<title>Three.js VR - 传送功能演示</title>
		<!-- 字符编码设置为UTF-8，支持多语言字符 -->
		<meta charset="utf-8">
		<!-- 
			视口设置：
			width=device-width: 宽度设置为设备宽度
			initial-scale=1.0: 初始缩放比例为1倍
			user-scalable=no: 禁止用户手动缩放页面
			这是移动端Web开发的标准配置
		-->
		<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>

		<!-- 
			信息展示区域，显示页面相关信息和链接
			id="info": 用于CSS样式和JavaScript操作
		-->
		<div id="info">
			<!-- 
				Three.js官方网站链接：
				target="_blank": 在新标签页打开链接
				rel="noopener": 安全设置，防止新页面通过window.opener访问原页面
			-->
			<a href="https://threejs.org" target="_blank" rel="noopener">Three.js</a> VR - 传送功能演示
			<br>
			<small>使用VR控制器指向地板并选择来传送到该位置</small>
		</div>

		<!-- 
			导入映射表(Import Map):
			这是ES6模块系统的一部分，用于定义模块的导入路径
			允许我们使用简短的模块名称而不是完整的URL路径
		-->
		<script type="importmap">
			{
				"imports": {
					"three": "../build/three.module.js",
					"three/addons/": "./jsm/"
				}
			}
		</script>

		<!-- 
			主JavaScript模块：
			type="module": 表示这是一个ES6模块，支持模块化导入导出
			模块中的代码在严格模式下运行，有自己的作用域
		-->
		<script type="module">

			// ==================== 模块导入区域 ====================
			// 导入Three.js核心库的所有功能，并使用THREE作为命名空间
			import * as THREE from 'three';

			// 从Three.js附加组件中导入特定模块
			// BoxLineGeometry: 用于创建由线条组成的立方体几何体，常用于VR房间的表示
			import { BoxLineGeometry } from 'three/addons/geometries/BoxLineGeometry.js';
			// VRButton: 用于创建一键进入VR模式的按钮组件
			import { VRButton } from 'three/addons/webxr/VRButton.js';
			// XRControllerModelFactory: 用于创建与VR控制器匹配的3D模型
			import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';

			// ==================== 全局变量声明 ====================
			// 核心Three.js对象
			let camera;      // 相机：定义观察3D场景的视角
			let scene;       // 场景：所有3D对象的容器
			let raycaster;   // 射线投射器：用于检测3D空间中的相交点
			let renderer;    // 渲染器：将3D场景渲染到2D画布上
			
			// VR控制器对象
			let controller1, controller2;          // 控制器对象：处理输入事件和逻辑
			let controllerGrip1, controllerGrip2;  // 控制器握柄：显示控制器的3D模型

			// 场景对象和XR相关
			let room;                // 房间：线框立方体，表示VR环境边界
			let marker;              // 标记：圆形标记，指示传送的目标位置
			let floor;               // 地板：平面，作为可以传送的区域
			let baseReferenceSpace;  // 基础参考空间：XR中的坐标系统基准

			// 交互相关
			let INTERSECTION;        // 存储当前射线与地板的交点坐标，用于传送定位
			const tempMatrix = new THREE.Matrix4();  // 临时矩阵：用于各种3D变换计算

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

			/**
			 * 初始化函数 - 应用程序的入口点
			 * 负责创建和配置所有Three.js对象、设置VR环境、绑定事件处理器
			 * 这个函数只在页面加载时执行一次
			 */
			function init() {

				// ==================== 场景设置 ====================
				// 创建场景对象，所有3D对象都将添加到这个场景中
				scene = new THREE.Scene();
				// 设置场景背景颜色为灰色（十六进制颜色值0x505050）
				scene.background = new THREE.Color( 0x505050 );

				// ==================== 相机设置 ====================
				// 创建透视相机，模拟人眼的视角
				// 参数说明：
				// 50: 视野角度(Field of View)，单位度，较大的值会产生鱼眼效果
				// window.innerWidth / window.innerHeight: 宽高比，根据浏览器窗口计算
				// 0.1: 近裁剪面，距离相机多近的对象开始渲染
				// 10: 远裁剪面，距离相机多远的对象停止渲染
				camera = new THREE.PerspectiveCamera( 
					50, 
					window.innerWidth / window.innerHeight, 
					0.1, 
					10 
				);
				// 设置相机初始位置：x=0, y=1（相当于人眼高度）, z=3（向前3个单位）
				camera.position.set( 0, 1, 3 );

				// ==================== 创建房间（线框立方体） ====================
				// 使用BoxLineGeometry创建房间的线框表示
				// 参数说明：宽6x高6x深6，每边分割为10段，然后向上平移3个单位使房间中心在地面以上
				room = new THREE.LineSegments(
					new BoxLineGeometry( 6, 6, 6, 10, 10, 10 ).translate( 0, 3, 0 ),
					new THREE.LineBasicMaterial( { color: 0xbcbcbc } )  // 线框材质，浅灰色
				);
				scene.add( room );

				// ==================== 灯光设置 ====================
				// 添加半球光：模拟天空和地面的环境光
				// 参数说明：天空颜色(0xa5a5a5)，地面颜色(0x898989)，光照强度(3)
				scene.add( new THREE.HemisphereLight( 0xa5a5a5, 0x898989, 3 ) );

				// 添加方向光：模拟太阳等定向光源
				const light = new THREE.DirectionalLight( 0xffffff, 3 );  // 白色光，强度3
				light.position.set( 1, 1, 1 ).normalize();  // 设置光源方向并归一化向量
				scene.add( light );

				// ==================== 创建传送标记 ====================
				// 传送标记是一个圆形网格，用于指示用户可以传送到的位置
				marker = new THREE.Mesh(
					// 圆形几何体：半径0.25，32段细分，绕X轴旋转-90度使其水平
					new THREE.CircleGeometry( 0.25, 32 ).rotateX( - Math.PI / 2 ),
					new THREE.MeshBasicMaterial( { color: 0xbcbcbc } )  // 基础材质，浅灰色
				);
				scene.add( marker );

				// ==================== 创建地板 ====================
				// 地板是一个半透明的平面，表示用户可以传送的区域
				floor = new THREE.Mesh(
					// 平面几何体：宽4.8x深4.8，各边分割为2段，绕X轴旋转-90度使其水平
					new THREE.PlaneGeometry( 4.8, 4.8, 2, 2 ).rotateX( - Math.PI / 2 ),
					// 基础材质：浅灰色，半透明（透明度0.25）
					new THREE.MeshBasicMaterial( { 
						color: 0xbcbcbc, 
						transparent: true, 
						opacity: 0.25 
					} )
				);
				scene.add( floor );

				// ==================== 创建射线投射器 ====================
				// 射线投射器用于检测从控制器发出的射线与3D对象的交点
				raycaster = new THREE.Raycaster();

				// ==================== 渲染器设置 ====================
				// 创建WebGL渲染器，用于将3D场景绘制到HTML canvas元素上
				// antialias: true 启用抗锯齿，使边缘更平滑
				renderer = new THREE.WebGLRenderer( { antialias: true } );
				// 设置设备像素比，确保在高DPI设备上清晰显示
				renderer.setPixelRatio( window.devicePixelRatio );
				// 设置渲染器尺寸为浏览器窗口大小
				renderer.setSize( window.innerWidth, window.innerHeight );
				// 设置动画循环函数，每帧调用animate函数
				renderer.setAnimationLoop( animate );

				// ==================== WebXR设置 ====================
				// 监听XR会话开始事件，当用户进入VR模式时触发
				renderer.xr.addEventListener( 'sessionstart', () => {
					// 获取基础参考空间，这是XR坐标系的原点
					baseReferenceSpace = renderer.xr.getReferenceSpace();
				} );
				// 启用WebXR功能
				renderer.xr.enabled = true;

				// 将渲染器的canvas元素添加到页面body中
				document.body.appendChild( renderer.domElement );
				// 创建并添加VR按钮，用户点击此按钮可以进入VR模式
				document.body.appendChild( VRButton.createButton( renderer ) );

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

				/**
				 * 选择结束事件处理函数
				 * 当用户释放控制器上的选择按钮时触发
				 * 这里实现了传送的核心逻辑
				 */
				function onSelectEnd() {
					// 清除选择状态标志
					this.userData.isSelecting = false;

					// 检查是否有有效的交点（即控制器指向地板上的某个位置）
					if ( INTERSECTION ) {
						// ==================== 传送计算逻辑 ====================
						// 1. 创建偏移位置：从交点位置反向偏移
						//    这是为了将用户从当前位置"移动"到目标位置
						//    w=1 表示这是一个位置向量（齐次坐标）
						const offsetPosition = { 
							x: - INTERSECTION.x, 
							y: - INTERSECTION.y, 
							z: - INTERSECTION.z, 
							w: 1 
						};
						
						// 2. 创建无旋转的偏移四元数（保持当前朝向）
						const offsetRotation = new THREE.Quaternion();
						
						// 3. 创建XR刚体变换对象
						//    这个变换表示从当前位置到目标位置的位移
						const transform = new XRRigidTransform( offsetPosition, offsetRotation );
						
						// 4. 获取偏移后的参考空间
						//    getOffsetReferenceSpace创建一个新的参考空间，该空间相对于基础空间应用了指定变换
						const teleportSpaceOffset = baseReferenceSpace.getOffsetReferenceSpace( transform );
						
						// 5. 设置新的参考空间，实现传送效果
						//    实际上并没有移动相机，而是改变了整个坐标系统的参考点
						renderer.xr.setReferenceSpace( teleportSpaceOffset );
					}
				}

				// ==================== 第一个控制器设置 ====================
				// 获取第一个XR控制器（通常是左手控制器或唯一控制器）
				controller1 = renderer.xr.getController( 0 );
				// 绑定选择开始事件
				controller1.addEventListener( 'selectstart', onSelectStart );
				// 绑定选择结束事件
				controller1.addEventListener( 'selectend', onSelectEnd );
				// 绑定控制器连接事件（当控制器被检测到时触发）
				controller1.addEventListener( 'connected', function ( event ) {
					// event.data包含控制器信息（如类型、目标射线模式等）
					// buildController根据控制器类型创建可视化表示
					this.add( buildController( event.data ) );
				} );
				// 绑定控制器断开连接事件
				controller1.addEventListener( 'disconnected', function () {
					// 移除控制器的可视化表示
					this.remove( this.children[ 0 ] );
				} );
				// 将控制器添加到场景中
				scene.add( controller1 );

				// ==================== 第二个控制器设置 ====================
				// 获取第二个XR控制器（通常是右手控制器）
				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 );

				// ==================== 控制器3D模型创建 ====================
				// XRControllerModelFactory会自动检测用户使用的VR设备
				// 并加载匹配的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, false );
			}

			/**
			 * 构建控制器可视化表示
			 * 根据控制器的类型创建不同的视觉反馈
			 * 
			 * @param {Object} data - 控制器数据对象，包含控制器的配置信息
			 * @returns {THREE.Object3D} 控制器的可视化3D对象
			 */
			function buildController( data ) {
				let geometry, material;  // 几何体和材质变量

				// 根据控制器的目标射线模式创建不同的可视化效果
				switch ( data.targetRayMode ) {
					// 'tracked-pointer': 普通6DOF VR控制器（如Oculus Touch、Vive控制器）
					case 'tracked-pointer':
						// 创建射线几何体：一条从控制器向前延伸的线段
						geometry = new THREE.BufferGeometry();
						// 设置顶点位置：起点(0,0,0)，终点(0,0,-1)（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 );

					// 'gaze': 凝视控制器（如Cardboard、Daydream）
					// 用户通过头部移动来控制光标
					case 'gaze':
						// 创建圆环几何体：内径0.02，外径0.04，32段细分
						// 向前平移1个单位，使其在用户面前可见
						geometry = new THREE.RingGeometry( 0.02, 0.04, 32 ).translate( 0, 0, - 1 );
						// 创建基础材质：半透明，透明度0.5
						material = new THREE.MeshBasicMaterial( { 
							opacity: 0.5,        // 半透明
							transparent: true    // 启用透明度
						} );
						// 返回圆环网格对象
						return new THREE.Mesh( geometry, material );
				}
			}

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

				// 更新渲染器的尺寸以匹配窗口新尺寸
				renderer.setSize( window.innerWidth, window.innerHeight );
			}

			/**
			 * 动画循环函数 - 每帧调用
			 * 这是Three.js应用的核心循环，负责更新场景状态和渲染
			 * 在VR模式下，每只眼睛每帧都会调用此函数
			 */
			function animate() {
				// 重置交点变量，准备新一帧的交点检测
				INTERSECTION = undefined;

				// ==================== 第一个控制器交点检测 ====================
				// 检查第一个控制器是否正在选择（用户按住了选择按钮）
				if ( controller1.userData.isSelecting === true ) {
					// 1. 从控制器的世界变换矩阵中提取旋转部分
					//    extractRotation方法提取矩阵的旋转分量到tempMatrix
					tempMatrix.identity().extractRotation( controller1.matrixWorld );

					// 2. 设置射线起点为控制器在世界空间中的位置
					//    setFromMatrixPosition从矩阵中提取位置信息
					raycaster.ray.origin.setFromMatrixPosition( controller1.matrixWorld );
					
					// 3. 设置射线方向为控制器前方（Z轴负方向）
					//    应用控制器的旋转矩阵，使方向与控制器朝向一致
					raycaster.ray.direction.set( 0, 0, - 1 ).applyMatrix4( tempMatrix );

					// 4. 检测射线与地板的交点
					//    intersectObjects返回射线与指定对象数组的所有交点
					const intersects = raycaster.intersectObjects( [ floor ] );

					// 5. 如果检测到交点，存储第一个交点的位置
					if ( intersects.length > 0 ) {
						INTERSECTION = intersects[ 0 ].point;  // point属性是交点在世界坐标中的位置
					}

				// ==================== 第二个控制器交点检测 ====================
				// 逻辑与第一个控制器相同，但使用第二个控制器的数据
				} else if ( controller2.userData.isSelecting === true ) {
					tempMatrix.identity().extractRotation( controller2.matrixWorld );

					raycaster.ray.origin.setFromMatrixPosition( controller2.matrixWorld );
					raycaster.ray.direction.set( 0, 0, - 1 ).applyMatrix4( tempMatrix );

					const intersects = raycaster.intersectObjects( [ floor ] );

					if ( intersects.length > 0 ) {
						INTERSECTION = intersects[ 0 ].point;
					}
				}

				// ==================== 更新传送标记 ====================
				// 如果检测到有效交点，更新标记位置到交点处
				if ( INTERSECTION ) {
					// copy方法将交点的坐标复制到标记的位置
					marker.position.copy( INTERSECTION );
				}

				// 设置标记的可见性：有交点时显示，无交点时隐藏
				marker.visible = INTERSECTION !== undefined;

				// ==================== 渲染场景 ====================
				// 这是动画循环的最后一步，将更新后的3D场景渲染到屏幕上
				// 在VR模式下，renderer会自动为每只眼睛渲染两次
				renderer.render( scene, camera );
			}

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