虚拟现实技术 · 第 4 次课 · 课堂案例

用 WebXR 生成一座故宫

第 4 章 虚拟现实开发常用软件 · 网页端路线:HTML + JavaScript + Three.js + WebXR —— 不装引擎、不导模型,整座紫禁城由代码在运行时算出来

中华女子学院4 学时 · 180 分钟(理论 2 + 实验 2)授课人:孙琪翔2026-09-23 · 第 4 周数字媒体技术实验室
导

本讲导览

上次课回答"用什么软件做 VR"(Unity 路线),这一课回答"不装引擎,能不能做 VR"

这一讲换了一条技术路线:不安装引擎、不写 C#、不导入模型,只在浏览器里用 HTML + JavaScript 把一座紫禁城"算"出来,然后把它推进头显漫游。

还有一个更现实的理由:这节课的教室里有 40 个人、36 个机位,但只有 1 台 PICO Neo 3。把 180 分钟全给设备,每人也就 4.5 分钟——连戴卸和消毒都不够。所以这节课的组织方式是:人人做出 VR,人人也戴上一次;再用 4 个人替全班测出数据。设备不是"排队体验",而是一条与作业并行的传递流水线:设备一直在传,人不能一直等。

本讲产出 = 一个能在浏览器里漫游的紫禁城场景。它不依赖任何 3D 模型文件:午门、内金水桥、太和门、三大殿、东西廊庑、围墙全部由代码在运行时生成,连贴图都是画出来的——整份工程只有 2 个文件、约 660 KB,断网也能跑。

场景支持鼠标环视、WASD 行走、点击地面传送、时辰滑块与 4 个预设机位;用支持 WebXR 的浏览器打开后可点"进入 VR"。本节课的 1:50—2:26 是"全员传看"环节:按座位顺序轮着看,谁看完就让给下一位,不卡个人时间;戴上后只做两件事——环视一眼、说一句话。其余时间大家在 PC 上继续改造自己的场景。2:26—2:36 由 4 位同学做定岗深测(清晰度 / 延迟 / 舒适度 / 比例与退出),全班看投屏。

一、为什么这节课值得单独讲 WebXR

① 分发成本几乎为零

做 Unity 项目要经历"打包 → 安装 → 启动";网页端只要一个链接。同学、家人、评委的浏览器都能直接打开,不需要装任何东西,也不经过应用商店审核。

② 迭代成本极低

改一行代码、刷新页面就是一次完整迭代,不必等构建与部署。做原型验证时,这条路线的时间成本通常是引擎路线的几分之一。

③ 它把第 3、4 章缝在一起

刷新率、分辨率、定位方式这些硬件指标,在浏览器里变成了可以现场读到的数字:FPS 面板、像素比、WebXR 的参考空间。硬件不再是纸上的参数。

二、两条路线对照:Unity(上次课)与 WebXR(本讲)

对比项Unity 引擎路线WebXR 网页路线(本讲)
运行环境独立可执行程序(EXE / APK)浏览器(桌面 / 头显一体机)
开发语言C#HTML + JavaScript
场景来源导入模型资产(FBX 等)+ 编辑器摆放代码程序化生成(也可加载外部模型)
部署方式打包、安装、更新一个 URL,零安装、零更新
性能上限高,可承载复杂场景与精细美术中,受浏览器与移动 GPU 限制
硬件接入官方 SDK(PICO / Quest 等),功能最全标准 WebXR API,跨设备通用;设备专属能力较少
典型用途商业项目、复杂交互、重型应用展示与漫游、教学、快速原型、跨设备分发
本课程定位第 6 章主线(16 学时)本讲(第 4 章)的第二条路线,也是期末合集的备选形式
两条路线不是"谁替代谁"。判断标准只有一条:这个作品要不要脱离浏览器、要不要跑重美术、要不要用设备专属能力。要,就走引擎;不要,网页端往往更快更省。

三、180 分钟时间轴

时段时长环节干什么
0:00—0:088′开场约束说明(40 人 / 36 机位 / 1 台设备)· 本讲地图与产出 · 点清机位与传看顺序
0:08—0:3022′PART 1 WebXR 是什么标准与能力边界 · 安全上下文 · 头显当场做支持性检测(投屏)
0:30—0:5020′PART 2 最小可运行场景三件套 + Three.js · 30 行代码 · 进入 VR 的四步 · 实操 A
0:50—1:0010′课间教师接设备、开投屏、一次性眼罩与擦镜布就位 —— 设备上机的唯一准备窗口
1:00—1:3232′PART 3 程序化生成故宫坐标系与比例 · 中轴布局 · 三种屋顶几何 · 实操 B
1:32—1:5018′PART 4 + 6 材质光照 / 交互与退出程序化贴图 · 单平行光 · 昼夜 · 实操 C · 退出三条路 · 传看三条纪律
1:50—2:2636′★ 全员传看40 人按座位顺序轮着看,不卡个人时间:戴上 → 只转头环视 → 说一句话 → 摘下 → 换眼罩 → 传下一位
2:26—2:3610′★ 4 人定岗深测清晰度 / 延迟 / 舒适度 / 比例与退出,全班看投屏
2:36—2:5115′PART 5 性能预算帧预算 · 合批与取舍 · 读数入口 · 用真机数据回填 PC 读数
2:51—2:587′PART 7 部署与发布安全上下文三条路 · 头显打开与退出流程 · 安装为应用(PWA)
2:58—3:002′收束达标线 · 课堂作业 · 下次课预告
时间账(老师心里有数就行):按平均 40—60 秒/人估算,40 人约 30—40 分钟,窗口给 36 分钟。所以它必须与大家的 PC 作业并行,不能单独占一段让人干等;慢了多少,就靠"到点即停 + 课后补做"兜底。
超时压缩优先级:① 到点(2:26)就停,没轮到的登记后补做;② 再保 PART 3 与 PART 5;③ 可压 PART 1 的支持现状表与 PART 7 的故障速查(课后自行阅读)。

四、本讲学习目标(可观测)

目标内容怎么检验
T1说出 WebXR 的三个前提:安全上下文、浏览器支持、设备会话提问 + 测验
T2解释为什么 file:// 与局域网 http:// 测不出真实的 WebXR 支持情况提问
T3比较引擎路线与网页路线的适用边界,各举一个该走哪条路的场景讨论
T4写出一个最小 WebXR + Three.js 页面,并说明 XR 下为什么必须改用 setAnimationLoop实操 A + 巡视
T5说明程序化建模在本项目中的三条收益(体积、离线、可控)提问
T6指出本项目采用的三种屋顶形制,并说出自定义几何体需要提供哪三组数组提问
T7读出自己机器上的 FPS / DrawCalls / 三角面,并判断瓶颈在哪里记录表
T8说出"snap turn 与传送"为什么比"持续平移与连续旋转"更舒适提问
T9完成六项课堂任务(跑通最小场景 / 比例校核 / 新增构件 / 光照实验 / 性能实验 / 真机观察与分发)两轮举手验收
T10说出 VR 里退出会话的三条路径,并解释为什么"在网页上放一个普通按钮"在沉浸模式下不管用提问 + 演示

五、模块地图

一

WebXR 是什么:把 VR 放进浏览器

浏览器不再只是"看网页的软件",它可以是一台 VR 运行时

1.1 一句话定义

WebXR Device API 是由 W3C 制定的浏览器标准接口,让网页代码直接驱动头显、手柄与空间追踪能力。它取代了早期的 WebVR(只做 VR、接口零散),把 VR 与 AR 统一到同一套 API 之下。

这句话的真正含义是:做 VR 应用,不再是引擎的专利。一个 HTML 文件加上几百行 JavaScript,就能在头显里跑起来——这也是本讲要亲手验证的事。

1.2 七个必须记住的概念

概念写法 / 取值含义与用途
能力入口navigator.xr浏览器是否具备 XR 能力。它是 undefined,后面的一切都无从谈起
会话模式immersive-vr / immersive-ar / inline沉浸式 VR / 沉浸式 AR / 页面内嵌(不接管显示)
参考空间local-floor / bounded-floor / local / viewer世界原点定在哪里。local-floor 以用户脚下的地面为原点,最符合"站着的人"的直觉
输入源inputSources手柄、手势、眼动等输入设备,以及它们的姿态与按键
帧循环renderer.setAnimationLoop()进入 XR 后渲染节奏由头显接管,必须改用它
安全上下文HTTPS 或 localhostWebXR 的硬性前提,不满足时 navigator.xr 会被藏起来
会话生命周期requestSession() → session.end()进入与退出 VR;退出后要交还控制权给页面

1.3 最重要的一条工程约束:安全上下文

WebXR 只在"安全上下文"里可用:https://… 或 http://localhost(含 127.0.0.1)。
用 file:// 双击打开、或用局域网地址 http://192.168.x.x 访问时,浏览器会把 navigator.xr 直接藏起来 —— 这时你测出来"这个设备不支持 WebXR",是一个假结论。

为什么浏览器要这么做?因为 VR 会读取头显与手柄的空间姿态,属于敏感能力,标准要求它必须运行在可验证来源的页面里。这条规则没有例外,也不看你的设备有多贵。它是本讲最容易误判、也最容易浪费半天时间的一个点。

第七节会给出三条绕行路线(HTTPS 托管、端口转发、浏览器白名单)。请记住排查顺序:先问"是不是安全上下文",再问"设备支不支持"。

1.4 支持现状(2026 年 9 月)

平台 / 浏览器沉浸式 VR说明
桌面 Chrome / Edge(Windows)支持PC 接头显(含一体机串流)可进入 VR;没有头显时,可用开发者工具或模拟扩展调试 XR 流程
Meta Quest 系列浏览器支持移动端 WebXR 生态最成熟的一支
PICO 浏览器(PICO 4 / Neo 3 等)以设备实测为准与系统版本、浏览器版本强相关,同一型号不同固件可能结果不同——课前必须实测一次
Android Chrome部分支持移动 AR 能力较完整;VR 需要外接头显
iOS Safari有限 / 逐步开放以系统版本为准,不要想当然
表里的"支持"是能力层面的描述,不等于"你手上这台设备一定能进 VR"。唯一可靠的判断方法:在目标设备上打开页面,看 navigator.xr 与 isSessionSupported('immersive-vr') 的实际返回值——这也是下周设备到位后要做的第一件事。

1.5 网页端路线能做什么、做不到什么

✅ 很合适

  • 展览、漫游、导览类场景(本讲就是);
  • 课堂演示与快速原型:改一行、刷一下就能看;
  • 跨设备分发:PC 浏览器、头显浏览器、手机同一条链接;
  • 与网页生态打通:二维码、微信、课件页面直接嵌入;
  • 轻量交互:传送、抓取、面板 UI、开关与滑块。

⚠️ 代价高或不合适

  • 复杂实时全局光照、电影级写实美术(算力不够);
  • 超大场景(GB 级模型与贴图,加载时间不可接受);
  • 需要离线包、本地文件系统或设备专属能力的重型应用;
  • 对延迟与稳定性要求极高的竞技类内容;
  • 完全依赖某个厂商专属 SDK 的功能(网页端只能走标准 API)。

1.6 随堂一测(口头抢答,不计分)

  1. 我用 file:// 打开页面,按钮显示"不支持 WebXR",能得出"这台设备不支持 WebXR"的结论吗?为什么?
  2. 想让世界原点落在脚底下,应该请求哪个参考空间?
  3. 一个同事说"网页做不出 VR"。请用一句话说出他这句话哪里不准确。

1.7 本模块配套:看视频 · 动手演示 · 权威文档

类型资源怎么用
📺 视频WebXR 在 3D 引擎中的实践(W3C 中国 · 29:03)标准制定方讲的 WebXR 定位与能力边界,对应 1.1—1.2
📺 视频使用 WebXR 打造沉浸式网站体验(26:17)看"网页端 VR 能做成什么样",对应 1.5 的能力边界
📺 视频HTTPS 是什么?加密原理和证书(11:32)理解 1.3 的安全上下文:为什么浏览器要"藏起" navigator.xr
🧪 演示07 进入 VR 四步检查当场看你这台设备的真实返回值
🔗 官方示例W3C WebXR Samples · Three.js WebXR 示例集官方示例,可直接打开对照
二

技术栈与最小可运行场景

30 行代码,把一个球体放进 VR —— 先跑通骨架,再谈故宫

2.1 三件套:页面、样式、逻辑

层技术在本项目里负责什么
页面层HTML画布容器、HUD 面板、加载进度、"进入 VR"按钮
样式层CSSHUD 排版、按钮状态、提示浮层
逻辑层JavaScript建场景、算几何、画贴图、处理输入、驱动 XR 会话
3D 库Three.js(r128,UMD 版)把 WebGL 的复杂细节封装成 Scene / Mesh / Material / Light

浏览器本身已经提供了两套底层能力:WebGL(画三角形)与 WebXR(接管头显)。但直接用原生 WebGL 画一座故宫,意味着你要自己写着色器、自己算矩阵、自己管理缓冲区。Three.js 的作用就是把这些收起来,让我们把精力放在"宫殿应该长什么样",而不是"投影矩阵怎么乘"。

2.2 先说一个必须提前知道的坑:库的加载方式

<!-- ✅ 本项目采用:UMD 单文件,双击 file:// 也能加载 -->
<script src="./three.min.js"></script>

// ❌ ES Module 版:在 file:// 下会被浏览器的同源策略拦下
import * as THREE from 'three';

本项目用的是 Three.js r128 的 UMD 构建(单文件 603 KB),用普通 <script src> 引入。两者的区别直接影响调试体验:UMD 能在 file:// 下加载,ES Module 不能——这是"双击就能预览"和"必须先开服务器"的分界线。

但要再说一次:file:// 只能预览画面,进不了 VR。进 VR 仍然需要安全上下文。

2.3 七类核心对象

对象作用在本项目里对应什么
Scene场景根节点,所有物体的容器整座紫禁城
PerspectiveCamera观察者(投影方式与视锥)你的眼睛;进入 VR 后姿态由头显驱动
WebGLRenderer每帧把场景画出来输出到画布或头显的双眼视图
Mesh可渲染物体 = 几何体 + 材质一根柱子、一片瓦顶、一块台基
Group物体的分组容器一座单体建筑(太和殿、午门……)
Light光照1 盏平行光 + 1 盏半球光
Raycaster射线拾取,判断"指着谁"点击地面 / 扳机传送的落点判定

2.4 渲染循环:两行代码的差别

// 普通网页动画:浏览器按刷新率回调
requestAnimationFrame(tick);

// 进入 VR 之后:渲染节奏交给头显,必须改用这一行
renderer.setAnimationLoop(tick);
在 XR 会话里继续用 requestAnimationFrame,典型症状是戴上头显就黑屏或卡住:头显的合成器要求每个 XR 帧都提交画面,而这个节奏由 setAnimationLoop 保证。Three.js 会自动为左右眼各渲染一次,并把结果交给头显合成器。

2.5 最小可运行场景(完整 30 行)

<!DOCTYPE html>
<html><head><meta charset="utf-8"><style>body{margin:0;overflow:hidden}#vr{position:fixed;left:12px;bottom:12px}</style></head>
<body>
<button id="vr">进入 VR</button>
<script src="./three.min.js"></script>
<script>
  // 1) 三个基本对象
  var scene = new THREE.Scene();
  scene.background = new THREE.Color(0x9ec9f0);
  var camera = new THREE.PerspectiveCamera(70, innerWidth/innerHeight, 0.1, 2000);
  camera.position.set(0, 1.6, 4);            // 1.6 m ≈ 人眼高度
  var renderer = new THREE.WebGLRenderer({antialias:true});
  renderer.setSize(innerWidth, innerHeight);
  renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5));
  document.body.appendChild(renderer.domElement);

  // 2) 一盏灯 + 一个物体
  scene.add(new THREE.HemisphereLight(0xbcd8f0, 0x6b5a44, 0.9));
  var ball = new THREE.Mesh(
    new THREE.SphereGeometry(0.6, 32, 24),
    new THREE.MeshStandardMaterial({color:0xb22222})
  );
  ball.position.y = 1.2;
  scene.add(ball);

  // 3) 让渲染器接管帧循环(XR 必需)
  renderer.xr.enabled = true;
  renderer.setAnimationLoop(function(){
    ball.rotation.y += 0.01;
    renderer.render(scene, camera);
  });

  // 4) 进入 VR
  var btn = document.getElementById('vr');
  if(!navigator.xr){ btn.disabled = true; btn.textContent = '当前浏览器不支持 WebXR'; }
  else navigator.xr.isSessionSupported('immersive-vr').then(function(ok){
    if(!ok){ btn.disabled = true; btn.textContent = '本设备不支持沉浸式 VR'; return; }
    btn.onclick = function(){
      navigator.xr.requestSession('immersive-vr', {optionalFeatures:['local-floor']})
        .then(function(s){ renderer.xr.setSession(s); })
        .catch(function(e){ btn.textContent = '启动失败:' + e.message; });
    };
  });
</script>
</body></html>

2.6 逐行拆解:每一行代码到底管什么

把上面 30 行拆成 8 个细节,每个细节都给一个"关掉它会发生什么"的例子。配套演示:01 号演示 · 最小场景逐行讲解——点右侧任意一行代码,就能把那一行打开或关掉,亲眼看见它的作用。

细节代码关掉它会发生什么(这就是它的作用)
① 场景底色scene.background = new THREE.Color(...)背景变黑,但物体还在——说明"黑屏"不等于"没渲染"
② 相机new THREE.PerspectiveCamera(70, w/h, 0.1, 2000)整块画面消失。这是"看不见东西"的第一嫌疑
③ 相机位置camera.position.set(0, 1.6, 4)改成 (0, 0.2, 1) 就从地上贴着看——位置决定构图
④ 像素比setPixelRatio(min(dpr, 1.5))去掉上限,高分屏更清晰但更吃性能——清晰度换帧率的开关
⑤ 光照HemisphereLight + DirectionalLight标准材质全黑。99% 的"我的模型是黑的"都是这条
⑥ 物体new THREE.Mesh(Geometry, Material)场景里少一个东西。几何体管形状,材质管外观
⑦ 位置与单位ball.position.y = 1.21 单位 = 1 米:1.2 m 约是胸口高度,1.6 m 约是人眼高度
⑧ 渲染循环renderer.setAnimationLoop(fn)画面冻住。XR 下用 requestAnimationFrame 会黑屏

细节 A · 相机:为什么"第一件事永远先查相机"

新手最常见的报错是"我建了物体却什么都看不见"。按下面顺序查,基本一次命中:

// 排查三连(本项目在 ?debug=1 下也能这样查)
console.log(camera.position);              // ① 相机在哪:是不是在物体里面/后面
console.log(camera.rotation);              // ② 相机朝哪:有没有 lookAt 目标
console.log(camera.near, camera.far);      // ③ 近/远裁剪面:near 太大,近处物体直接被剪掉

// 最典型的错误:只写位置,不写朝向
camera.position.set(0, 1.6, 4);            // 相机在 z=4 看着 −z 方向(three.js 默认朝 −z)
camera.lookAt(0, 1.2, 0);                  // 想让相机看目标,必须显式 lookAt

动手看:02 号演示 · 坐标系与相机——四个滑块分别是相机 X/Y/Z 与视野 FOV,把高度调到 1.7 就是"站着看",调到 0.6 就是"蹲下看",FOV 拉到 100° 就能看到明显的边缘拉伸。

细节 B · 光照与材质:为什么"我的模型是黑的"

// 对比:同一种红色,两种材质
new THREE.MeshBasicMaterial({color:0xb22222})   // 不受光:永远是这个颜色,适合画 UI、标线
new THREE.MeshStandardMaterial({color:0xb22222}) // 受光:没灯就是全黑(VR 场景用这个)

scene.add(new THREE.HemisphereLight(0xbcd8f0, 0x6b5a44, 0.9));  // 天光补色,避免背光面死黑
var sun = new THREE.DirectionalLight(0xffffff, 1.2);            // 主光(太阳),负责明暗与投影
sun.position.set(4, 6, 3); scene.add(sun);

动手看:03 号演示 · 光照与材质——四个球并排对比"基础材质 / 平行光 / 半球光 / 两盏灯+阴影",把两盏灯都拖到 0,就能复现"全黑"的现象。

细节 C · 单位与比例:1 单位 = 1 米

这条看起来是常识,但它决定了整个工程能不能讲得通:紫禁城的每一个尺寸都是"米",所以"太和殿 35.4 m"这样的历史资料可以直接抄进代码,后面才能做比例校核。

反例:如果按"厘米"建模,人高就会写成 170,相机高度写成 165,光照距离、阴影范围、移动速度全部要放大 100 倍——最后必然出现"人比台阶还高""走出去三步就到了另一个城市"这类问题。先定单位,再动手。

细节 D · 帧循环:为什么一定要乘 deltaTime

// ❌ 帧率相关:60 fps 的机器比 30 fps 的机器快一倍
ball.rotation.y += 0.01;

// ✅ 帧率无关:每秒转固定角度,跟机器性能无关
var dt = Math.min(clock.getDelta(), 0.1);         // 每帧耗时(秒),并夹住上限防跳帧
ball.rotation.y += (90 * Math.PI/180) * dt;       // 每秒转 90°

// 进入 XR 后还必须换掉循环方式
renderer.setAnimationLoop(animate);   // ✅ 头显刷新节奏接管
// requestAnimationFrame(animate);    // ❌ 戴上头显就黑屏/卡住

动手看:04 号演示 · 帧循环与 deltaTime——把"模拟设备帧率"拖到 15 fps,左边的方块明显变慢、右边几乎不变。这就是"手感不对/晕"的技术原因。

2.7 进入 VR 的四步(配 07 号演示)

  1. 检测能力:navigator.xr 是否存在(不存在 = 浏览器或安全上下文不满足);
  2. 检测会话模式:navigator.xr.isSessionSupported('immersive-vr');
  3. 请求会话:navigator.xr.requestSession('immersive-vr', {optionalFeatures:[...]});
  4. 交给渲染器:renderer.xr.setSession(session)。
optionalFeatures 与 requiredFeatures 的区别很关键:写进 requiredFeatures 的能力如果设备不支持,会话会直接失败;写进 optionalFeatures,设备有就用、没有就降级。本项目请求的是 local-floor(地面原点)、bounded-floor(安全边界)、hand-tracking(手势),全部写成可选——这样即使头显没有手势追踪,场景照样能进。

动手看:07 号演示 · 进入 VR 的四步检查——页面上把每一步的实际返回值都打出来(协议、navigator.xr、isSessionSupported、按钮状态),这一步失败了该查什么,页面上直接写着。

2.8 随堂实操 A(约 10 分钟)

  1. 把上面的最小场景存成 hello-webxr.html,与 three.min.js 放在同一目录;
  2. 双击打开(file://)——画面应该能出来,但按钮会显示"不支持 WebXR"。先亲眼看到这个"假结论";
  3. 把 SphereGeometry 的半径从 0.6 改成 1.5,把材质颜色改成自己喜欢的颜色,刷新;
  4. 按 F12 打开控制台,确认没有红色报错。
这一步的目的不是"做出东西",而是亲手确认两件事:① WebXR 的可用性受安全上下文控制;② 改一行代码、刷一下页面就是一次完整迭代——网页端路线快在哪里,你自己感受得到。

2.9 本模块配套:看视频 · 动手演示

类型资源说明
🧪 演示01 最小场景逐行讲解点一行代码 = 开关一个细节(本站演示,离线可用)
🧪 演示02 坐标系与相机滑块调相机位置与 FOV,体会"1 单位 = 1 米"
🧪 演示03 光照与材质四个球对比四种光照方案,复现"模型全黑"
🧪 演示04 帧循环与 deltaTime模拟 15 fps 低性能设备,看两种写法差多少
🧪 演示07 进入 VR 四步检查把"进不去 VR"的排查顺序做成可交互页面
📺 视频快速上手 Three.js —— 浏览器中的 3D 渲染引擎(11:30)与本模块 2.1—2.5 完全对应,最适合课前看
📺 视频什么是渲染管线?如何绘制 3D 物体?(9:20)讲清"三角形是怎么变成屏幕像素的",回答"为什么这一切叫 WebGL"
📺 视频three.js 添加坐标轴、光源和阴影效果(15:29)与 2.6 细节 A/B 对应:坐标轴、光源、阴影
🔗 文档Three.js 官方文档 · MDN:WebXR Device API(中文)查 API 用,比看视频快
三

程序化生成故宫:几何

没有一砖一瓦的模型文件,宫殿是"算"出来的

3.1 为什么选择"用代码建模"

方案体积网络依赖可控性适合本讲吗
下载现成模型(素材库 / AI 生成)几十 MB ~ GB需要下载受精度与授权限制不适合:课堂网络不可控,版权也不清楚
建模软件自制(Blender)中等需要分发高不适合本次课:40 人在一节课里做不完
程序化生成(本讲)约 660 KB零请求,断网可用每个尺寸都是一个可调变量✓ 采用

程序化建模还有一个隐藏收益:它是"可解释"的。模型文件里的一根柱子是几万个顶点坐标;而程序里的一根柱子是 addPillar(x, z, y0, h, r)——想让它高一点,改一个数就行,还能顺便讲清"高多少算合理"。

3.2 先把坐标系定死

单位先定,比例才不会乱。建模最常见的灾难不是"面太多",而是"不知道自己用的是厘米还是米"——最后做出来的人比柱子高,或者柱子比宫殿还粗。

3.3 中轴布局:从午门到保和殿

建筑中心坐标(z)建模要点尺寸校核
午门+150凹字形城台(三座门洞)+ 重檐庑殿正楼 + 两翼廊屋 + 两座攒尖角亭城台顶 11 m ✓
内金水河 · 五桥+112河道 + 汉白玉栏杆 + 5 座石拱桥(中央主桥最宽)主桥宽 7.4 m
太和门+78单层台基 + 九间门殿 + 重檐歇山顶(含山花)屋脊 ≈ 20 m
太和殿−55三层须弥座(2.4 / 2.8 / 3.5 m)+ 三层望柱栏板 + 32 根红柱 + 青绿彩绘额枋 + 两圈斗拱 + 重檐庑殿 + 正脊鸱吻 + 月台鎏金铜缸总高 35.4 m(实测 35.05 m)✓
中和殿−98方形台基 + 单檐四角攒尖 + 鎏金宝顶约 19 m
保和殿−140台基 + 重檐(下庑殿 / 上歇山带山花)约 29.5 m
东西廊庑x = ±62185 m 连檐走廊红墙 + 窗棂 + 单向坡灰瓦顶 + 檐下红灯笼纵深贯通全院
体仁阁 / 弘义阁x = ±52两重檐楼阁(灰瓦)——
四周围墙x = ±88 / z = ±1766.5 m 红墙 + 黄琉璃墙帽6.5 m ✓
比例校核是这一步的隐藏训练。比如太和殿,把"三层台基 + 屋身 + 重檐屋顶"逐段加起来,程序里算出的总高是 35.4 m,查证的历史数据是 35.05 m——误差 1%,说明坐标、单位与分段还原是站得住的。这类校核会原样出现在你的课堂作业里。

3.4 中式屋顶:三种形制,三段自定义几何

Three.js 提供了立方体、球、圆柱等基础几何体,但没有"庑殿顶"。中式屋顶必须自己写:给出顶点、法线、UV三组数组,组装成 BufferGeometry。

形制用在哪几何特征代码入口
庑殿顶(四阿顶)午门正楼、太和殿四坡:前后为梯形、左右为三角形,五条脊(正脊 + 四条垂脊)hipGeo() / addHipRoof()
歇山顶太和门、保和殿上层上半为两坡,下半四面坡,两端带山花gableGeo() / addGableRoof()
四角攒尖顶中和殿、午门角亭四坡汇于一点,顶部加鎏金宝顶addPyramidRoof()
// 庑殿顶的骨架:手写顶点 / 法线 / UV(节选,已简化)
function hipGeo(w, d, h, spine){
  var hw = w/2, hd = d/2, s = Math.max(0.5, spine)/2;
  var pos = [], uvs = [], nors = [];
  var slopeF = Math.sqrt(h*h + hd*hd);          // 前后坡的斜长 → 用于 UV 纵向比例
  var slopeS = Math.sqrt(h*h + (hw-s)*(hw-s));  // 侧坡

  function quad(a, b, c, dd, nrm, uvArr){       // 一个面:3 或 4 个顶点
    var ids = [a, b, c]; if(dd) ids.push(a, c, dd);   // 四边形 → 两个三角形
    ...
  }

  var A = [-s, h, 0], B = [s, h, 0];            // 正脊两端
  var F1 = [ hw, 0,  hd], F2 = [-hw, 0,  hd];   // 南侧檐口
  var Bk1 = [-hw, 0, -hd], Bk2 = [ hw, 0, -hd]; // 北侧檐口

  var nf = [0,  hd,  h], nb = [0,  hd, -h];     // 前后坡法线(手算)
  var nl = [-h, hw-s, 0], nr = [ h, hw-s, 0];   // 左右坡法线
  ...
  var g = new THREE.BufferGeometry();
  g.setAttribute('position', new THREE.Float32BufferAttribute(pos, 3));
  g.setAttribute('normal',   new THREE.Float32BufferAttribute(nors, 3));
  g.setAttribute('uv',       new THREE.Float32BufferAttribute(uvs, 2));
  return g;
}

注意 quad() 里的 ids.push(a, c, dd):四边形要拆成两个三角形。前后坡是梯形(不是三角形),必须给 6 个顶点、6 组 UV 才能铺满——这是本项目最早踩到的坑之一(详见 3.6)。

3.5 让建筑"站得住"的四类构件

构件做法本项目数量级
台基与须弥座逐层用 Box 叠上去,层高就是历史尺寸太和殿三层:2.4 / 2.8 / 3.5 m
望柱与栏板沿台基边缘等距排布,间距约 1.9 m 生成一组望柱 966 根、栏板 930 块
柱网与斗拱立柱按开间分布;檐下沿长度生成"斗拱线"红柱 146 根、斗拱 356 组
匾额、灯笼、窗棂贴图 + 简单几何体(Box / Sphere)灯笼 35 盏 × 两庑

这里有一处关键的工程判断:这些构件单看都很简单,数量却上千。如果一根柱子一个 Mesh,光是提交次数就会拖垮帧率。解决方式是实例化合批(InstancedMesh),详见 PART 5。

3.6 三个一定会踩的坑

  1. 梯形屋面不是三角形。庑殿顶的前后坡是梯形,需要 6 个顶点、6 组 UV;只按 3 个顶点写,屋面会缺一大块。
  2. 法线要自己算。手写几何体不会自动获得正确法线;法线错了,屋顶会"一块亮一块黑",看起来像贴图坏了,其实是光照方向错了。
  3. UV 要按实际尺寸。贴图的重复次数应随构件的米数计算(repeat.set(宽/6, 高/4) 这类写法)。否则同一张瓦片贴图,在小屋上被拉长、在大殿上被压扁,砖缝大小对不上。

还有一个更"隐蔽"的坑写在 PART 6:把局部坐标当成世界坐标用。当物体带父容器(Group)时,它的坐标是局部的,合批前必须先换算到世界坐标,否则上千根柱子会整体错位。

3.7 随堂实操 B(约 15 分钟)

  1. 打开场景源码,找到太和殿的屋顶高度参数,把它改成原来的 ±20%,刷新页面,观察形制变化;改回原值;
  2. 把中轴上一座建筑整体沿 z 轴移动 20 m,检查它与地面、台基的关系有没有错位;
  3. 回答:你刚才改动的到底是哪一个变量?它影响的是几何、材质,还是位置?
第 3 问是本讲的"分水岭":能说清"我改的是什么",才说明你真的看懂了这段代码,而不是在碰运气调数字。

3.8 本模块配套:看视频 · 动手演示

类型资源怎么用
🧪 演示05 程序化几何与贴图拖滑块改面阔/进深/层高/正脊,屋顶实时重建,并显示顶点数与 DrawCall
📺 视频用 three.js 制作你的第一个 3D 地图(12:04)另一条"用代码生成几何"的思路,对照故宫的做法
📺 视频低模 UV 该给多大才合适?UV 像素原理(19:05)解释 3.6 第三条坑:为什么 UV 要按实际尺寸设置
📺 视频Blender 几何节点程序化建模(10:15)对照组:不用代码、用节点也能程序化生成,理解两种路线的差别
四

材质、贴图与光照

一张贴图都不下载:所有纹理都是运行时画出来的

4.1 为什么不用一张图片贴图

本项目的贴图不是图片文件,而是运行时用 Canvas 2D 画出来、再交给 GPU 的 CanvasTexture。四个好处:

代价也很直接:程序化贴图做不到照片级写实。它擅长表现"重复的、有规律的"表面——瓦、砖、墙、栏杆,正好是古建筑的主体。

4.2 八种程序化贴图

贴图画法要点用在哪些构件
黄琉璃瓦逐行错缝排布 + 顶部高光带三大殿、午门正楼的屋顶
灰瓦低饱和青灰 + 颗粒噪点东西廊庑、两翼楼阁
朱红墙底色 + 竖向色差(模拟雨水冲刷)宫墙、立柱、门扇
汉白玉浅色底 + 云纹噪点台基、栏杆、石桥
金砖地面方格分块 + 亮度扰动广场铺装
青绿彩绘条带 + 云纹额枋、梁枋
冰裂纹窗棂网格线门窗、廊庑墙面
匾额文字 + 描边 + 底色各殿门楣、广场导览牌

4.3 材质复用:把纹理 clone 出来改重复次数

// 生纹理一次,改 repeat 复用;用 key 缓存,避免重复创建材质
var matCache = {};
function wallMat(w, h){
  var key = 'w' + (w|0) + '_' + (h|0);
  if(matCache[key]) return matCache[key];
  var t = tex.wallR.clone();                 // 克隆纹理,各自设置平铺次数
  t.needsUpdate = true;
  t.repeat.set(Math.max(1, w/6), Math.max(1, h/4));
  return (matCache[key] = new THREE.MeshStandardMaterial({map:t, roughness:0.9}));
}
为什么必须缓存?材质对象在渲染时对应着色器程序与提交批次。同样的墙面每出现一次就新建一个材质,会让 Draw Call 成倍膨胀——这正是 PART 5 要处理的问题。记住一条经验:能复用的材质就复用,能让纹理 repeat 解决的就别新建材质。

4.4 光照:两盏灯打完全场

阴影用一张 2048 的 PCFSoft 阴影贴图,正交阴影相机按中轴范围裁剪,并设置 bias / normalBias 抑制摩尔纹。

阴影范围是一个必须做的取舍。阴影贴图的分辨率被摊在整个阴影相机范围内:范围开得越大,单个像素覆盖的地面越大,阴影就越糊、越抖。开得太小,远处的建筑又投不出影子。所以正确做法是让阴影相机只包住视野中必须投影的部分(本项目取中轴一带约 ±210 m × 140~190 m),而不是无脑盖住全场。

4.5 雾、天空与昼夜

把"时间"做成一个可以滑动的变量,是这类场景性价比最高的一招:几行插值代码,换来一整套"晨昏四季"的可讲内容,而且几乎不增加渲染负担。

4.6 随堂实操 C(约 10 分钟)

  1. 把 HUD 上的"时辰"滑块从 5:00 拉到 21:00,记录三个时刻(清晨 / 正午 / 黄昏后)的画面差异:色温、影子长度与方向、灯火;
  2. 指出哪些变化属于光照参数(光源强度、颜色、阴影),哪些属于材质参数(自发光、反射率);
  3. 把画面停在 21:00,回答:为什么夜间灯笼没有让帧率明显下降?

4.7 本模块配套:看视频 · 动手演示

类型资源怎么用
🧪 演示03 光照与材质四个球对比四种方案;两盏灯拖到 0 复现"全黑"
🧪 演示05 程序化几何与贴图切"程序化瓦片 ⇄ 纯色",看同一几何体的两种外观
📺 视频使用 Canvas 完成基本绘图(12:26)程序化贴图的前置技能:Canvas 2D 画图(本项目的瓦/砖/墙都靠它)
📺 视频PBR 材质贴图最全详解(35:49)选看:粗糙度/金属度/法线这些参数到底在干什么
五

性能预算:为什么它能跑在移动头显上

这一节把第 3 课的硬件指标,变成浏览器里可以读到的数字

5.1 先算一笔帧预算

头显刷新率 72 Hz 意味着每帧只有约 13.9 ms(1000 ÷ 72)。这 13.9 ms 里要同时完成:CPU 逻辑与物理、Draw Call 提交、GPU 渲染、以及双眼画面的合成。移动头显用的是移动芯片级 GPU,没有独立显卡,也不能靠风扇长时间压散热。

把这句话和上节课的硬件内容连起来看:刷新率不是一个抽象的规格数字,它是一份必须按时交卷的时间预算。超了就掉帧,掉帧就眩晕——这是第 2 章讲过的 Motion-to-Photon 延迟在工程上的真实来源。

5.2 本课程的资产预算(承接第 3 次课)

项目参考预算为什么是这条线
单个物体面数≤ 5 万三角面单个物体过大,视锥剔除就失去意义
全场景面数≤ 50 万三角面移动 GPU 的顶点与光栅化压力上限
单张贴图≤ 2K显存与带宽;本项目实际只用 ≤ 256×256

5.3 本项目的读数记录

指标项目记录说明
Draw Calls43 — 114随视锥内物体数量变化;这是本项目最关键的读数
三角面约 3.8 万远低于 50 万预算,说明"减面"不是本项目的瓶颈
纹理运行时生成,零下载全部由 Canvas 绘制,单张 ≤ 256×256
光源2 盏1 平行光(投影)+ 1 半球光,无实时点光源
像素比min(devicePixelRatio, 1.5)限制填充率——高分屏上这是最直接的省算力开关
这些数字只作量级参考,不要当成常数背。HUD 面板显示的是你这一刻、这个视角的读数:转头、走近、把时辰调到夜晚,数值都会变。课堂上请记录你自己机器上的一次真实读数,并写清是在哪个机位、哪个时辰取的——这比抄一个"标准答案"有价值得多。

5.4 六条优化手段

手段具体做法收益
实例化合批
InstancedMesh
望柱 966、栏板 930、红柱 146、斗拱 356、灯笼 70 —— 每类只用一个 draw call把上千次提交压成几次,本项收益最大的一条
低面数几何立柱用 10 边圆柱(openEnded)、斗拱用 24 顶点盒体、自定义屋顶 12—18 顶点三角面数量级下降
阴影只给该给的物体望柱、栏板、斗拱关闭 castShadow直接缩小阴影 pass 的绘制量
限制像素比setPixelRatio(min(dpr, 1.5))减少填充像素,对移动 GPU 效果明显
雾 + 天空球220—780 m 淡出允许更近的渲染距离,远景不必精细
昼夜不重建只写 uniform 与自发光强度避免运行时的卡顿尖峰

5.5 怎么量:三个读数入口

  1. 页面内置面板:本项目 HUD 直接显示 FPS、DrawCalls、三角面、纹理数——课堂上先用它;
  2. 代码读数:renderer.info.render.calls、renderer.info.render.triangles、renderer.info.memory.textures;
  3. 开发者工具:Chrome DevTools 的 Performance 与 Rendering 面板,看帧时间构成(脚本 / 渲染 / 合成)。
// 把性能读数显示在页面上(本项目 HUD 的做法)
var info = renderer.info.render;
el.innerHTML = 'FPS <b>' + fps + '</b> | DrawCalls <b>' + info.calls +
               '</b> | 三角面 <b>' + (info.triangles/1000).toFixed(0) + 'k</b>' +
               ' | 纹理 <b>' + renderer.info.memory.textures + '</b>';
结论一句话:在 VR 里,Draw Call 往往比三角面更致命。每一个物体一次提交都有固定开销,几百次提交就能吃掉整个帧预算——所以你才会看到"明明只有 3 万面,却卡得不行"的情况。优化的第一顺位永远是减少提交次数,其次才是减面、砍纹理、降分辨率。

5.6 课堂追问

  1. 为什么"合批"要排在"减面"前面?请用帧预算里的时间构成解释。
  2. 如果把 966 根望柱的 castShadow 全部打开,最可能先出问题的是哪一项读数?
  3. 这个场景原封不动搬到一台三年前的手机上打开,不做任何优化,你觉得会先卡在哪一步?

5.7 本模块配套:看视频 · 动手演示

类型资源怎么用
🧪 演示06 性能对比:独立 Mesh 与 InstancedMesh本讲最值得动手的一个演示:把数量拖到 3000,对比 DrawCall
📺 视频合批渲染 & SpriteBatch 原理(26:31)解释"为什么合批能省时间"的底层机制
📺 视频GPU Instancing:降低 DrawCall(12:02)Unity 视角讲同一个概念,概念是通用的
六

交互与输入:一套场景,两套控制

同一份代码,既要能在机房里用鼠标键盘跑,也要能在头显里用手柄跑

6.1 总览:PC 与 VR 的输入映射

场景输入行为
PC 预览
(备课 / 投屏 / 无头显时)
鼠标拖拽环视(俯仰限幅 ±77°,避免翻转)
W / A / S / D 或方向键沿视线方向行走,Shift 加速(6 → 14 m/s)
单击地面射线命中可落脚面 → 显示落点环 → 松开执行传送
HUD 面板时辰滑块(5:00—21:00)、暂停昼夜、4 个预设机位
VR
(头显 + 手柄)
头部自然环视(由头显姿态直接驱动)
扳机按住 → 手柄发出橙色射线、地面显示绿色落点环;松开 → 传送到该点
左摇杆按头朝向平滑行走(约 4.2 m/s)
右摇杆左右Snap turn,每次 30°,350 ms 冷却
控制面板低头看身前下方的控制面板 → 扳机点「退出 VR」→ 退出会话(见 6.5)
长按握把 2 秒任意一只手柄按住握把 → 兜底退出,不用瞄准、不用找菜单
为什么 PC 端也值得认真做?因为本课程的大部分开发与演示都在 PC 上完成:备课、投屏、课堂讲解、以及设备不可用时(比如本周),PC 端就是唯一能让学生亲手操作的入口。

6.2 可落脚面的设计

传送不是"想传哪传哪"。本项目把所有允许落脚的表面登记进一个集合,射线只对这个集合求交:

玩家的活动范围再整体夹紧在围墙之内(wallX / southZ / northZ 三个上限),避免"一脚踏空到场景外",也避免穿墙。

6.3 舒适度:为什么是"传送 + 分步转身"

为什么用传送,而不是连续行走

VR 里"人没动、画面在动"最容易引发不适:前庭系统感觉没动,视觉系统却报告在加速。瞬移把连续的加减速打断,是当前最稳的移动方案。本项目 VR 里保留的平滑行走也刻意压到 4.2 m/s,并只在"沿头朝向"这一个方向上生效。

为什么是 30° 一档,还要 350 ms 冷却

连续旋转同样容易晕。Snap turn 把转动切成 30° 一档,一档一档转;350 ms 冷却是为了防止摇杆轻微漂移被识别成连续输入,导致画面一直转个不停——这类"小概率但高频"的手感问题,靠参数调,不靠运气。

6.4 一个必须绕开的坑:不要在 VR 里每帧写相机姿态

// ❌ 错误:进入 XR 后,相机姿态由头显每帧写入,你写它 = 两边互相覆盖
camera.rotation.y += 30 * Math.PI / 180;

// ✅ 正确:旋转"玩家"这一层父节点,相机保持由头显驱动
player.rotation.y += 30 * Math.PI / 180;
症状很有欺骗性:画面抖动、视点漂移、转向失灵,甚至戴上头显后画面"粘"在脸上。原因是你和头显在抢同一个属性。正确做法是把玩家做成一个 Group(rig),所有转身、位移都作用在 rig 上;相机作为它的子节点,只负责"被头显驱动"。

6.5 退出 VR:三条路,一条都不能省

这是本讲最容易被忽略、但在课堂上最容易出事的一环:学生进去以后出不来。网页端 VR 的退出入口由浏览器提供,页面无权代替;但页面必须给出用户自己找得到的出口。

方式操作定位
控制面板按钮低头看身前下方的控制面板 → 扳机射线指向「退出 VR」→ 按下扳机主路径:看得见、摸得着
长按握把 2 秒任意一只手柄按住握把(squeeze)2 秒兜底路径:不用瞄准、不用找菜单
系统键按头显系统键 → 选「退出 VR」官方出口:规范强制浏览器提供,永远可用;位置随固件版本变化

进入 VR 后的前 9 秒,控制面板会先被举到眼前——不是为了好看,而是让第一次戴上头显的人在教师还没来得及讲之前就知道怎么退出去。9 秒后它平滑落到视线下方(前方 0.95 m、高 0.66 m、倾斜 52°),低头可见、不挡景观。

面板 = 挂在玩家 rig 上的普通物体,「退出 VR」按钮是它的一个子网格
  · 每帧用射线判定是否命中按钮;命中时只点亮按钮,不摆传送标记
  · 松开扳机:命中按钮 → exitVR() → session.end();否则 → 传送
  · 另有兜底:updateVRInput() 中检测握把(buttons[1])长按 2 秒
  · 退出失败时提示"请按系统键退出",避免把人困在里面
一条值得记住的设计经验:凡是"只有一条退出路径"的沉浸式应用,在真实课堂上迟早会出问题——因为那条路径依赖"用户知道它在哪"。设计时要反着问自己:如果用户什么提示都没看见、什么菜单都找不到,他还能不能出来?
在网页里放一个普通按钮是没用的:沉浸模式下页面 DOM 一般不渲染到头显里(DOM Overlay 主要面向 immersive-ar)。想给用户一个看得见的按钮,就必须把它做成场景里的 3D 物体。这一条要在下周设备实测时一并确认。

6.6 课堂追问

  1. 右摇杆转向为什么要加 350 ms 冷却?不加会发生什么?
  2. 如果把活动范围放开到围墙之外,会出现哪两类问题(一类是体验,一类是性能)?
  3. PC 端与 VR 端的代码,哪一部分是共用的?哪一部分必须分开写?
  4. 为什么"握把长按退出"必须存在,即使已经有控制面板按钮和系统键?

6.7 本模块配套:看视频

类型资源怎么用
📺 视频《半条命:Alyx》移动方式官方深入解读(中字)(10:33)顶级 VR 大作为什么同时保留"传送"和"平滑移动"——正对应 6.3 的舒适度设计
📺 视频XR 眼镜戴久了头晕?晕动症的成因与缓解(13:54)选看:把"为什么会晕"讲到生理层面,解释为什么传送与 snap turn 更稳
七

部署与发布:怎么让头显打开它

工程做完只是"能跑",能发出去才叫"能用"

7.1 安全上下文的三条路

方式做法适用限制
① HTTPS 托管
(推荐)
把 .html 与 three.min.js 放进任意 HTTPS 空间(本课程网站就是一份),得到一个短链接课堂演示、课后分享、给同学和家人看需要一个能放静态文件的空间
② 本地服务 + 端口转发在电脑上跑 python -m http.server 8080,头显通过 USB 端口转发访问 http://127.0.0.1:8080开发调试(改一次看一次)需要数据线、驱动与端口转发配置
③ 局域网 HTTP + 白名单浏览器打开 chrome://flags/#unsafely-treat-insecure-origin-as-secure,填入 http://192.168.x.x:端口,设为 Enabled 后重启浏览器应急(没有公网空间时)该开关随浏览器与固件版本变化,不一定存在;只适合临时使用
再强调一次:双击 file:// 打开,永远进不了 VR——它能看画面,但那只是"预览",不是"运行"。判断方式很简单:如果按钮显示"当前浏览器不支持 WebXR",先查安全上下文,再查设备。

为什么"必须放到网络上"——四种打开方式对照

打开方式是安全上下文吗能进 VR 吗课堂能不能用
file:// 双击本地文件否不能(只能看画面,navigator.xr 被隐藏)只能用来检查"画面渲染对不对"
http://192.168.x.x(局域网)否默认不能(除非给浏览器加白名单 flag)应急,依赖固件版本,不推荐
http://127.0.0.1(本机服务 / USB 转发)是能开发调试用;头显要通过 USB 端口转发
https://…(放到网站上)是能课堂首选:一个链接,全班都能开

把这件事讲透,只需要一句话:VR 会读取你头部的空间姿态,属于敏感能力,所以浏览器规定它只能运行在"可验证来源"的页面上。这条规则不看设备贵不贵,也不看你是不是在做教学演示——file:// 就是不行。

# 本机临时起一个"算安全"的服务(开发/调试用)
python -m http.server 8080
# 电脑访问 http://127.0.0.1:8080/你的页面.html  → 可以进 VR
# 头显访问:USB 连接后做端口转发,或把它放到 https 上
& 'D:\VRLab\Android\platform-tools\adb.exe' reverse tcp:8080 tcp:8080   # 头显侧的 8080 指向电脑

# 课堂最省事的做法:直接用它已经发布好的 https 地址
https://www.qixiangsun.com.cn/assets/vr-2026/webxr/gugong_webxr.html
所以"部署"这一步不是形式主义:不放到网络上,前面所有工作都只能在电脑上看,进不了头显。而一旦放上去,顺带还得到了三件事:① 一个可以发给任何人的链接;② 可以"安装为应用"(PWA);③ 装了之后断网也能打开。

7.2 在头显上打开场景:六步

  1. 确认两个文件在同一目录:主程序 .html 与 three.min.js(改名、移动都会导致加载失败);
  2. 用方式①或②把它变成安全上下文;
  3. 在头显浏览器地址栏输入链接;
  4. 先看 HUD 上的统计面板有没有读数(FPS / DrawCalls)——有读数说明渲染正常,没有读数说明脚本报错了;
  5. 点"进入 VR",戴好头显、确认手柄已连接,先原地环视一圈再尝试移动。
  6. 退出:按 6.5 的三条路任选一条。第一次必须由教师完整走一遍并计时,再交给学生。

7.3 退出 VR 与「安装为应用」

退出 VR 的三条路

  • 控制面板:低头 → 扳机点「退出 VR」(进入后前 9 秒面板会主动举到眼前);
  • 长按握把 2 秒:不用瞄准的兜底通道;
  • 系统键:浏览器提供的官方出口,永远可用。

退出后页面自动回到 PC 漫游状态,并在下方弹出「已退出 VR」提示,可直接再次进入。

安装为应用(PWA)

  • 页面右上角「安装为应用」按钮:Chrome / Edge 会弹原生安装框;其他浏览器按其菜单手动「添加到主屏幕 / 桌面」;
  • 装好后全屏启动(没有地址栏),首次访问之后断网也能打开;
  • 做不到"打开就自动进 VR":规范要求进入 VR 必须由用户手势触发,仍要点一次「进入 VR」;
  • 一体机浏览器对 PWA 安装的支持程度不一,属于需要实测的项目。
实现上就是三样东西:manifest.webmanifest(应用名 / 图标 / 全屏启动)、sw.js(Service Worker:首次访问后离线可用)、一套图标。前提仍然是安全上下文——file:// 下 Service Worker 不会注册,"安装"与"离线"都不会生效。
为什么值得做这一步:装成应用之后,学生那边的情况变成"桌面上多了一个紫禁城图标",而不是"要去群里翻一个链接"。占用的还是同一个网址,成本只有三个文件。

7.4 故障速查

现象最可能的原因处理
按钮显示"当前浏览器不支持 WebXR"不在安全上下文,或浏览器没有 WebXR换 HTTPS / localhost;确认浏览器版本
isSessionSupported 返回 false当前设备不支持沉浸式 VR 会话换浏览器或换设备;先在 PC 端把内容做完
会话启动失败,出现错误信息把设备不支持的能力写进了 requiredFeatures改成 optionalFeatures
进入 VR 后画面抖动 / 漂移代码在每帧改写相机姿态改为旋转玩家 rig(见 6.4)
进入 VR 后找不到怎么退出控制面板在视线下方,没低头看;或系统键菜单不熟长按手柄握把 2 秒即可退出(见 6.5)
点「安装为应用」没弹出安装框该浏览器不支持自动安装,或已处于全屏应用模式按页面提示,在浏览器菜单里手动「添加到主屏幕 / 桌面」
页面空白three.min.js 路径错误或不在同目录;脚本报错开控制台看 404 与报错信息
画面很糊、明显掉帧像素比过高 / 阴影范围过大 / Draw Call 过多限制 setPixelRatio、收小阴影相机、做合批
画面看得见,但物体位置错乱把局部坐标当世界坐标使用(父容器没换算)合批或复制前先换算到世界坐标

7.5 本地最小服务

# 方式一:Python 自带(机房电脑一般都有)
python -m http.server 8080
然后浏览器打开 http://127.0.0.1:8080/主程序.html

# 方式二:Node 环境
npx serve -l 8080
课堂上的实用做法:本课程网站已经放了这份场景的可直接打开版本(见本页顶部按钮),它本身就运行在 HTTPS 上——等于顺手解决了安全上下文这个前提。把它发给同学、发给家人,一个链接就够。

7.6 本模块配套:看视频 · 动手演示

类型资源怎么用
🧪 演示07 进入 VR 四步检查把本机是 file:// / 局域网 http / https 三种情况都跑一遍,对着表格填
📺 视频增进 Web App 体验:充分利用 PWA 及其能力(Google 中国 · 12:10)官方讲 PWA:为什么"网页能变成应用"、能得到什么
📺 视频你管这破玩意叫 HTTPS?(7:57)轻松看懂 HTTPS 与证书,理解"必须放到网络上"的由来
🔗 工具model-viewer 在线编辑器把任意 .glb 拖进去就能看、能导出一段网页代码——做作品集封面很好用

7.6 一台设备怎么让 40 个人都戴上:全员传看 + 定岗深测(1:50—2:36)

教室里只有 1 台 PICO Neo 3。把时间全给它,每人也就 4.5 分钟——连戴卸和消毒都不够。所以这个环节分两段:先让全班每个人亲手戴上一次(覆盖面),再由 4 个人把数据测准(质量)。

阶段时间谁上机目标
全员传看1:50—2:26(36′)全班 40 人,按座位顺序轮着看(不卡个人时间)每个人都亲手看见一次;每人留一句话
定岗深测2:26—2:36(10′)4 人,每人 2 分钟测数据、走完整交互与退出
时间账(老师心里有数就行):按平均 40—60 秒/人估算,40 人约 30—40 分钟,窗口给 36 分钟;不卡个人时间,谁看完就让给下一位,到点即停。而且它必须与大家的 PC 作业并行——设备在传,其他人在做作业,不能单独占一段让人干等。轮着看只能"看一眼",不能完整"玩"(传送、摇杆、退出),完整体验留给下面 4 位定岗的同学:这就是取舍。

传看三条纪律(1:50 之前讲完,并写上黑板)

  1. 只转头环视,不碰扳机、不碰摇杆——一碰就会传送,后面的人看到的画面就变了,40 个人的观察立刻不可比;
  2. 坐着看,不站起来;
  3. 任何不适立刻摘下,不要硬撑。

每人只说一句话(三选一):"清楚 / 有点糊,远处屋脊我看到的是一句话描述" | "转头跟得上 / 有拖影" | "有点晕 / 不晕"。40 个人 × 一句话,就是 40 个数据点——教师现场把它们变成板书统计。

现场谁做什么

角色职责
学生管理员 ①擦拭镜片、换一次性眼罩、在相邻两人之间递送设备(不走动过道)
学生管理员 ②维持传递秩序、提醒下一位准备(不记时、不打勾——按座位顺序传,看座位就知道传到哪)
教师站在传递区旁边讲评:每人对下一句话,立刻接成知识点(清晰度 → PPD;拖影 → 帧率与延迟;晕 → 舒适度设计)
其余同学继续做课堂作业 T1 / T2,并填观察卡——不是干等

容易翻车的三件事

项目处理
卫生一次性眼罩一人一片(3 秒换好);每 10 人擦一次镜片;由学生管理员执行,不占教师时间
戴眼镜允许戴着试,但提醒"先摘眼镜戴头显、确认不顶镜片";顶着不舒服就直接摘镜体验(画面会糊,如实记录)
发热与电量连续 40 分钟会热、会掉电:能边充边用就接充电宝;明显烫手就暂停 1 分钟

定岗深测:4 个人把数据测准

人选规则当场公布(作业先完成者 4 位),每人 2 分钟,全班看投屏。每人只测一件事:

岗只测这一件事记录
① 清晰度远处屋脊、斗拱是否看得清(和 PC 上比)1—5 分 + 一句话
② 延迟快速左右转头,画面跟不跟得上有 / 无拖影
③ 舒适度扳机传送一次 + 摇杆走两步眩晕 0—3 级
④ 比例与退出台基相对自己身高有多高;再按三条退出路径各走一遍退出用时(秒)+ 用了哪条路

班级结论表(板书,全班一起填)

到点即停:2:26 一到立刻停止传看,没轮到的同学登记后课后补做。不要为了"让所有人都戴上"挤掉后面的性能与部署环节——那两块同样要考。
#检查项结果
1是否安全上下文(协议是 https: 吗)
2navigator.xr 是否存在
3isSessionSupported('immersive-vr') 的返回值
4"进入 VR"按钮能不能点
5退出用了哪条路、几秒
这一步不是形式主义:WebXR 的可用性取决于设备系统版本与浏览器版本,同一型号不同固件都可能结果不同。前四项决定这条路线能不能走,第五项决定课堂上敢不敢把设备交给学生——所以要在全班面前把结论测出来,而不是写完再说。
设备出问题时的三级降级:① 页面打不开 → 换手机热点,或打开已安装的应用图标(PWA 离线可用);② 能进但退不出来 → 长按握把 2 秒 → 系统键 → 长按电源强制重启;③ 投屏失败 → 改用 USB 镜像,再不行改为"教师口述 + 学生看自己 PC 上的同一页面"。设备可以坏,课不能停。
给教师的一行操作:场景地址后加上 ?debug=1 会挂出一个调试钩子 window.__gugong(不写这个参数时完全不影响正式使用)。在头显浏览器控制台里用 __gugong.isPresenting() 可以确认是否真的进入了会话;想在 PC 端先看控制面板长什么样,用 __gugong.showPanel() 把它调出来。
实

课堂实操与成果验收

六项课堂任务(逐项有操作步骤与验收点,不卡时间、做完为止)+ 三张规定截图 + 两轮举手验收 + 一张记录表

一、这一节的作业总要求(先看这一段)

本讲用到的演示都在一个入口里:演示目录(7 个教学演示 + 1 个课堂小例子)。 演示文件名统一用英文(例如 demo01-minimal-scene.html)——中文文件名在部分机房电脑上会乱码或打不开,所以中文标题写在页面里,文件名一律用英文。
其中 「WebXR 实验馆」是一个完整的小应用(高尔夫 + 射击),做任务 2、任务 3 时可以先打开它照着改——它就是"把这一课的东西拼起来"的样子。
所有任务课内完成,本课程不布置课后任务。
你要交的 5 样东西:① 你改过的最小场景(能跑);② 改造后的故宫场景(至少两处改动);③ 3 张规定截图(见第三节,命名要规范);④ 课堂记录表(数据真实、可复现);⑤ 真机观察卡(戴过或看过都要填)。
验收方式:两轮举手验收 + 同桌互检 + 教师抽验 8 台。抽验只看 20 秒:页面能不能跑、改动能不能看出来、数据是不是编的。
三条硬性规矩:① 改动必须有依据——改了尺寸,就要写清依据来自哪里(不准写"我觉得好看");② 数据必须真实——HUD 读数会随视角变化,如实记录比抄一个"标准答案"得分高;③ 截图必须能看清读数——看不清读数的截图直接退回重截。

二、先熟悉场景(3 分钟,人人必做)

  1. 打开本课程网站的紫禁城 WebXR 场景(顶部按钮那个链接);
  2. 按住鼠标拖拽环视;用 W A S D 行走,按住 Shift 加速;
  3. 单击地面,看到绿色落点环后再松开鼠标,完成一次传送;
  4. 依次点 4 个预设机位:广场远眺 / 月台近景 / 午门仰视 / 全景俯瞰,感受"同一个场景换个机位就是另一张图";
  5. 最后按 F12 打开控制台看一眼:有红色报错吗?(这是我们查问题的第一动作)

三、六项课堂任务(逐项都有操作步骤与验收点)

任务 1 · 跑通最小场景并改一处(参考 10 分钟,不卡时间)

做什么:把 2.5 节的 30 行代码存成 hello-webxr.html,与 three.min.js 放在同一目录,然后改一处参数。

  1. 新建文件夹 学号-姓名,把两个文件放进去(必须同目录);
  2. 双击打开 hello-webxr.html,记下按钮显示的是"进入 VR"还是"当前浏览器不支持 WebXR";
  3. 把球体半径从 0.6 改成 1.5,颜色改成你喜欢的色值,保存后刷新;
  4. 按 F12 确认控制台没有红色报错。
验收点(必须三条全中):① 画面里能看到一个球,且大小/颜色是你改过的;② 控制台无红字;③ 你能说出"按钮为什么显示不支持"——因为 file:// 不是安全上下文。
常见错误:文件不在同一目录(报 404);双击后改了文件却没刷新(浏览器缓存);把半径写在材质里(改错对象)。

任务 2 · 比例校核:改一处真实尺寸(参考 20 分钟,不卡时间)

做什么:打开故宫场景源码,找一处尺寸,查证它的真实数值,把代码改成真实值,并写下依据。

  1. 选一处构件:台基高度 / 台阶层数 / 柱子高度 / 围墙高度 / 屋顶高度,任选一处;
  2. 查一个可引用的来源(故宫官方资料、建筑史教材、可靠科普站),记下数值与出处;
  3. 在代码里找到对应变量,把数值改掉(不要直接写数字,先在注释里写清依据);
  4. 刷新页面,截一张"改动后"的图,与改动前对比;
  5. 在记录表写下:改动项 → 改前值 → 改后值 → 依据来源。
验收点:① 改动肉眼可见;② 依据写清了来源(不是"我觉得");③ 能回答"这个改动属于几何、材质还是位置?"
参考量级:太和殿总高约 35 m,三层台基 2.4 / 2.8 / 3.5 m,午门城台约 11 m,围墙约 6.5 m。
常见错误:改的数值被别处覆盖(同一个尺寸在代码里出现多次);改了但忘了记改前值;把"屋顶高度"和"建筑总高"混为一谈。

任务 3 · 新增一组构件(参考 12 分钟,不卡时间)

做什么:在场景里加入一组原来没有的东西,并用一句话说清它怎么做的。

  1. 从这五样里选一样:灯笼 / 望柱 / 栏板 / 甬道 / 导览牌(也可以做一面照壁);
  2. 用现成的工具函数或 BoxGeometry / CylinderGeometry 把它加进去(位置要和周围对齐);
  3. 给它一个材质(纯色也行,能解释就行);
  4. 刷新看效果,确认没有穿模、没有悬空、比例正常。
验收点:① 新构件在场景里看得见、位置合理;② 能说出用了什么几何体、什么材质、放在哪个坐标;③ 没有引入报错。
常见错误:坐标用错单位(写成厘米,飞到天上);只复制了代码没加到场景里(忘 scene.add);加了但没有父容器,位置对不上。

任务 4 · 光照实验:三个时辰(参考 8 分钟,不卡时间)

做什么:把"时辰"滑块从 5:00 拉到 21:00,记录三个时刻的画面差异。

  1. 分别在 5:00 / 15:00 / 21:00 各截一张图(同一个机位,用"广场远眺");
  2. 记录每个时刻的:色温(暖/冷)、影子长度与方向、灯火有无;
  3. 回答:哪些变化属于光照参数,哪些属于材质参数;21:00 时灯笼为什么没让帧率明显下降。
验收点:三行记录填满;能区分"光照参数 vs 材质参数";能说出"夜间灯火只改材质自发光,不新增光源"。

任务 5 · 性能实验:合批到底省了什么(参考 10 分钟,不卡时间)

做什么:用 06 号演示做一次对照实验,抄下 4 个数字。

  1. 把"物体数量"拖到 3000,模式选独立 Mesh,等半秒,记下 DrawCall 与 三角面;
  2. 切到 InstancedMesh 合批,同样记下这两个数字;
  3. 把两组数字填进记录表,并回答一个问题:为什么合批后三角面反而变多了?
  4. 再打开故宫场景,抄一次 HUD 上的 DrawCall / 三角面 / FPS,作为"真实项目"的对照。
验收点:① 4 个数字都记下;② 能答出"合批后整体只做一次视锥剔除,远处实例也被一起提交,所以三角面升高";③ 能说出结论:Draw Call 比三角面更致命。
实测参考:3000 个物体时,独立 Mesh 约 930 次 DrawCall、三角面 18.6k;合批后 2 次 DrawCall、三角面 60.0k。

任务 6 · 真机观察与分发(随传看环节完成,下课前补完)

  1. 传看时:轮到你戴 → 只转头环视 → 说一句话 → 摘下传下一位;没轮到也要看投屏,把看到的不同写进观察卡;
  2. 看/听完 4 位定岗同学的数据后,把四岗数据抄进观察卡;
  3. 把场景链接发给自己(微信文件传输助手 / 邮件),并当场确认能打开;
  4. 点一次右上角「安装为应用」:弹安装框就装,没弹就在浏览器菜单里手动"添加到主屏幕 / 桌面";
  5. 记录结果:装成功 / 不支持手动添加 / 没找到入口,如实写。
验收点:① 观察卡有内容(不是空白);② 手机或邮箱里确实收到了链接;③ 安装结果如实记录——"我这边不支持"也是有效答案。

四、三张规定截图与提交规范

编号截什么必须能看清对应任务
截图 1你的最小场景全屏你改过的球体 + 页面没有任何报错任务 1
截图 2故宫场景"改动前 / 改动后"对比(同一机位)改动的那一处看得出来任务 2 / 3
截图 3合批实验:两种模式各一张右边面板上的 DrawCall 数字(这是关键证据)任务 4

五、两轮举手验收(40 人怎么在课内验完)

轮次什么时候收验什么怎么验
第 1 轮任务 1—2 大体做完时(一般在 PART 3 讲完前后)任务 1 + 任务 2完成的举手 → 同桌互检(按下面 3 条互查)→ 在记录表签字
第 2 轮任务 3—5 大体做完时(一般在性能那一节结束前后)任务 3 + 4 + 5完成的举手 → 教师抽验 8 台(每台约 20 秒)→ 未过的登记课后补
不卡时间:上面写的"什么时候收"只是时机参考,实际以完成情况为准——教师看现场节奏决定什么时候喊这两轮。任务本身也不设截止时间,做完为止;确实做不完的,登记后课后到实验室补做。

同桌互检三条(互相查,查完签字):① 你的页面能打开且没有红字报错吗?② 改动看得见吗?③ 记录表里的数字和 HUD 上的一致吗?

教师抽验看什么(20 秒一台):① 页面能跑;② 改动痕迹可见(不是原版);③ 记录表的数据与 HUD 对得上。抽验不是抽查作业量,而是抽查"数据是不是编的"。

加分项 · 30 秒现场演示

完成全部任务的同学可自愿申请现场演示(约 3—5 人),照着这三句话讲:

  1. "我改了什么:把 XX 从 X 米改成 Y 米,依据是 XX 资料。"
  2. "改动前后有什么不同:这是同一机位的两张图,差别在……"
  3. "我的性能读数:DrawCall X、三角面 Y、FPS Z;我认为瓶颈在……"
三句话里最关键的是第三句。**能读出数字、并说出瓶颈在哪里**,说明你已经从"会做"走到"会判断"——这是这门课真正要考的能力。

六、课堂记录表(每人填写,两轮验收都要看这张表)

记录项我的记录说明
浏览器与版本说明"在什么环境里测的"
是否安全上下文是 HTTPS / localhost,还是 file:// 或局域网 http
FPS / DrawCalls / 三角面抄 HUD 面板的实时读数
5:00 的画面特征色温、影子长度与方向
15:00 的画面特征同上
21:00 的画面特征同上,并注明灯火变化
我改的一处参数改前值 → 改后值 → 可见的变化
我戴上时的一句话清楚 / 有点糊、有无拖影、晕不晕,任选一项如实记录
真机对比(看投屏填)清晰度 / 转头延迟 / 移动舒适度 / 人体比例,各写一句"和 PC 上有什么不同"
合批实验 · 独立 Mesh(3000 个)DrawCall = ____ 三角面 = ____
合批实验 · InstancedMesh(3000 个)DrawCall = ____ 三角面 = ____;为什么三角面反而更多?
改动依据(来源)写明来自故宫官方资料 / 教材 / 可靠科普站(不准写"我觉得")
安装为应用的结果装成功 / 不支持手动添加 / 没找到入口(如实写)
同桌互检签字同桌姓名:__________(互检三条例全过才签)

七、达标线(必过四条 + 加分三条)

必过(四条,缺一条即未达标)

  1. 场景在浏览器里正常渲染,HUD 有实时读数;
  2. 至少两处改动(一处比例校核 + 一处新增构件),且改动有依据、记录表能对上;
  3. 能说出 WebXR 的三个前提,并说明为什么 file:// 测不出真实结论;
  4. 能说出退出 VR 的三条路,并说明为什么"在网页上放一个普通按钮"在沉浸模式下不管用。

加分(三条,任选一条即可申请现场演示)

  1. 能解释合批的代价:不只说"DrawCall 变小",还能说清"为什么三角面反而变多";
  2. 能指出至少两处"程序化生成"的证据(自定义屋顶几何、Canvas 生成的贴图、实例化合批的栏杆);
  3. 能把链接安装成应用,并说清"为什么装成应用也做不到打开即进 VR"。
三条全过 = 本讲的课堂实操部分完成。第 3 条是本讲的"核心考点":它考的不是记性,而是你有没有真的踩过那个坑。

八、更多例子:课堂小例子 · 免费 3D 库与在线示例

8.0 课堂小例子 · WebXR 实验馆(高尔夫 + 射击)

下面这个例子是把前面几个演示拼起来的一个完整小应用:一个菜单 + 两个能进头显的体验(挥杆打高尔夫、射线打靶),带得分、退出按钮和性能读数面板。建议先点开玩两分钟,再回来看它的代码——你会发现它用到的每一块,你都已经在本课里见过。

它在演示什么对应本课哪一节你可以照着改什么
一个场景 + 两个体验分组(Group 切换显隐)PART 2 最小可运行场景再加第三个体验,比如"投篮"
全部几何体由代码生成:球、旗杆、树、靶子、房间PART 3 程序化生成把树换成别的形状,或改球的半径
一盏半球光 + 一盏平行光;用 emissive 做发光靶子PART 4 光照与材质改平行光方向,看影子与明暗变化
左下角实时显示 FPS / DrawCall / 三角面 / 纹理PART 5 性能预算把靶子数量从 5 改成 50,看读数怎么变
桌面用鼠标、VR 用手柄射线;两条退出通道PART 6 交互与退出改击球蓄力速度、或改退出按钮的位置
Three.js 放在本地,不依赖任何 CDNPART 7 部署与发布把它放进自己的网站目录一起上传
这个例子和你收到的原文件有什么区别:原文件用 CDN 加载 Three.js(cdn.jsdelivr.net),机房网络一慢就会永远卡在"正在加载 Three.js…";现在已经改成本地库 + 本地控制器库,断网也能打开,并补了 WebGL 兜底提示、VR 内退出按钮、长按握把退出、性能读数与快捷键。

一个故宫不够看。下面这些全部是免费的,链接都已逐个核验可打开(2026-09-22)。建议每个至少点开一次,看别人怎么做,比只看故宫一个例子更快建立判断力。

8.1 免费 3D 库 / 引擎(都能在浏览器里跑)

库 / 引擎特点适合拿来做什么
Three.js最主流的 WebGL 库,示例几百个,中文资料最多本课程选用;写代码控制一切
A-Frame用 HTML 标签写 VR(<a-box>),不用写渲染代码半天做出一个能进头显的场景;适合第一次接触 VR 的人
Babylon.js功能比 three.js 更"开箱即用",自带在线 Playground(改完即看)想快速试一个玩法;企业级项目
PlayCanvas完整的网页版编辑器,像"网页里的 Unity"不想写太多代码、想用编辑器搭场景
<model-viewer>一行 HTML 标签就能展示 3D 模型,Google 出品给网页/电商/课程加一个可旋转的 3D 模型
TresJSVue 风格的 Three.js 封装前端同学做课程网站里的 3D 展台
Needle Engine把 Unity 工程直接导出成网页已有 Unity 项目,想一键上网页
Zdog极简伪 3D(没有真正的透视),画风可爱做图标、插画式 3D,几乎不占性能

8.2 在线示例(点开就能看,最适合"照着改")

示例站里面有什么
W3C WebXR Samples标准组织给的官方示例,最权威;可用来对照"你的设备到底支持哪一项能力"
Three.js WebXR 示例集官方示例里所有 WebXR 相关的(手柄、传送、绘画、体积雾…),点开即运行
A-Frame 示例几十个"打开就进 VR"的小场景,代码量极小,适合当模板
Babylon Playground在线改代码即时预览,示例按功能分类
Khronos glTF 官方样例模型标准的 3D 格式测试模型(含材质、骨骼动画),用来测试"我的加载器对不对"

8.3 免费模型 / 贴图资源(注意看授权)

站点内容授权
Poly HavenHDRI 环境图、PBR 材质、模型CC0(可商用、免署名)
ambientCG上千套 PBR 材质与贴图CC0
Kenney低模游戏素材包(角色、道具、场景)CC0
Quaternius低模建筑、角色、自然素材CC0
Sketchfab海量模型,可按"可下载 + CC 授权"筛选逐件看授权(CC BY 需署名)
Mixamo角色骨骼动画(走路、挥手等)免费(需注册);用于教学演示
两条使用纪律:① 下载素材前先看授权,课堂上必须养成习惯——CC0 随便用,CC BY 要署名,标"非商用"的不能进商业作品;② 外部站点会变(有的需要科学上网、有的会关站),所以本课程的课堂演示都用自建页面,外链只作为扩展阅读。
怎么用这些例子做自己的场景(三步):① 先在示例站里找一个最接近你想法的,打开、改一个数字、刷新;② 把它的核心几行抄进自己的页面,跑通;③ 再回头改比例、换素材、加交互。不要从空白文件开始写——那是效率最低的路。
作

课堂作业 · 六项任务 + 一项加分(与上一节表格对应)

全部课内完成,不卡时间、做完为止;逐项的操作步骤、验收点与常见错误见上面《课堂实操与成果验收》

一、基本信息

作业名称网页端沉浸场景改造:从看懂到改懂
完成形式个人独立完成 · 课内完成 · 随课验收
时间安排随 PART 3—6 边讲边做,合计约 20 分钟
提交内容改造后的源码或截图 + 课堂记录表 + 一段 100 字以内的说明
与期末关系计入本学期课堂案例合集;网页端形式可作为期末大作业的呈现方式之一

二、任务清单

编号任务要求难度
任务 1
必做
跑通最小场景把 30 行最小场景跑起来、改一处参数、控制台无报错,并说清"为什么按钮显示不支持"★
任务 2
必做
比例校核选一处构件(台基、屋顶、柱子、围墙皆可),查证一个真实尺寸,把代码中的数值改为该尺寸,并写明依据来源与改动前后的差异★★
任务 3
必做
新增一组构件在中轴、月台或廊庑处新增一组构件(灯笼 / 望柱 / 栏板 / 甬道 / 照壁 / 导览牌),说明用了什么几何体、什么材质、如何定位★★
任务 4
必做
光照实验记录 5:00 / 15:00 / 21:00 三个时刻的色温、影子与灯火,并区分"光照参数"与"材质参数"★
任务 5
必做
性能实验与判断用 06 号演示做一次"独立 Mesh ⇄ InstancedMesh"对照实验,记录两组 DrawCall 与三角面,并解释为什么合批后三角面反而变多★★★
任务 6
必做
真机观察与分发填写观察卡(戴过或看过都写),把场景链接发给自己并确认能打开,尝试"安装为应用"并如实记录结果★
加分30 秒现场演示按"我改了什么 / 前后有什么不同 / 我的性能读数"三句话讲清自己的改动★★★
关于"查证真实尺寸":可以查故宫官方资料、建筑史教材或可靠科普来源。关键不是数字本身,而是你写清楚了它从哪来——这就是工程上"可追溯"的习惯,也是评分里"理解"一项的主要依据。
七项任务全部在课内完成,时间怎么分配看下面这张表;逐项的操作步骤、验收点与常见错误写在上面「课堂实操与成果验收」一节,两处内容一致,任选一处照着做即可。
任务123456加分
建议顺序①②③④⑤⑥⑦
提交物截图 01截图 02 + 记录表截图 02 + 记录表记录表截图 03 + 记录表观察卡 + 链接现场演示
验收轮次第 1 轮(做完 ①② 后举手 + 同桌互检)第 2 轮(做完 ③④⑤ 后举手 + 教师抽验 8 台)看观察卡自愿申请

三、评分量规

维度权重看什么
完成度40%场景能跑起来,改造效果肉眼可见,没有引入报错
规范20%尺寸写成变量而不是散落的数字;命名清晰;有注释说明"改了什么"
理解20%能说清几何、材质、性能三件事的因果关系(例如"为什么这个改动会增加 Draw Call")
记录20%记录表完整、数据真实、别人能照着复现

四、常见错误(提前避坑)

  • 改了但没记改前的值——回不去,也没法说明"变化了多少";
  • 把尺寸写成魔法数字——同一份代码里出现 5 个 3.5,没人知道哪个是台基高度;
  • 只截图不记数据——"看着挺好"不是工程记录;
  • 控制台有红色报错却当没看见——很多"画面看起来还行"的场景,其实已经在报错;
  • 把性能数据抄成理想值——读数本来就随视角变化,如实记录反而更容易拿分。

五、想做得更好(自选加分方向)

查

一页速查 · 达标线 · 下次课预告

把这一页抄在笔记本上,本讲的骨架就齐了

一、六句话速查

主题要记住的
WebXR 三前提安全上下文(HTTPS / localhost)· 浏览器支持 · 设备会话支持
最小技术栈HTML + JavaScript + Three.js + renderer.xr
两条渲染循环普通页面用 requestAnimationFrame;XR 用 setAnimationLoop
程序化建模三步定坐标系与单位 → 定比例(可校核)→ 写几何(顶点 / 法线 / UV)
性能优先级Draw Call > 填充率 > 三角面
最容易犯的两个错在非安全上下文里判断"不支持 WebXR";在 VR 里每帧写相机姿态
退出与分发退出的三条路:控制面板按钮 / 长按握把 2 秒 / 系统键;分发:装成应用(PWA)= 一个图标 + 全屏 + 离线

二、本讲达标线

  1. 场景能在浏览器中正常渲染并显示性能读数;
  2. 能指出至少两处程序化生成的证据;
  3. 能说清 WebXR 的三个前提与 file:// 的假结论;
  4. 能说出退出 VR 的三条路,并知道"安装为应用"能带来什么、不能带来什么;
  5. 完成六项课堂任务的必做部分,三张规定截图与记录表齐全。

三、下次课预告(2026-09-30)

附

附录 · 上次课(09-16)内容存档

引擎路线:《虚拟现实开发常用软件》与 Unity 课堂案例 01 的完整课堂内容

上一次课走的是引擎路线(Unity):软件生态与工具选型、资产导入的五道关、编辑环境核对、XR 环境配置、模型与第一个 C# 脚本、模拟器 → 头显双轨验证。这一节把完整内容整段存档,复习时可以对照着看。本讲(09-23)走的是网页端路线,两条路线共用同一章的知识框架。

展开查看完整存档(6 个内容板块 + 课堂演示中心 + 演示设计 + 视频资料)
导

本讲导览

上次课回答“硬件能做什么”,这次课回答“用什么软件把它做出来”

这节课以第 4 章“虚拟现实开发常用软件”为骨架,把上一课(第 3 次课)讲过的硬件关键指标作为“软件设置的依据”贯穿全课。课堂产出不是“听懂”,而是一台机器上一个能跑起来的 VR 场景。

本课产出 = 期末大作业的第 1 个课堂案例(课堂案例 01)。本学期采用“12 次课 = 8 个课堂案例”的模型:8 个课堂案例从本课开始逐个积累,第 12 次课(12-02)整理成合集整体演示,期末大作业(40%)即该合集。

今天要走完的四步

① 核对版本与插件  →  ② 配置 XR  →  ③ 导入模型 + 写脚本  →  ④ 用 PICO 看一眼
    12 分钟              30 分钟         25 分钟                25 分钟

本讲学习目标(可观测)

目标内容怎么检验
T1说出 VR/AR 开发的四类工具(建模 / 引擎 / 资产 / 验证)各管什么,每类举 2 例提问 + 生态地图
T2解释本课程为何选 Unity 而非 Unreal;Blender 与 3ds Max 的定位差异投票 + 讨论
T3说明模型从建模软件到 VR 场景的五道关,指出三个常见错误管线页 + 测验
T4查到自己机位上的 Unity 版本号并记录任务卡填写
T5配置 XR 环境:XR Plugin + Interaction Toolkit + XR Origin + Device Simulator逐台巡视
T6导入一个模型并修正比例场景截图
T7写出并运行第一个 C# 脚本,让物体动起来课堂验收
T8说出上节课的硬件指标(PPD / 刷新率 / 定位方式)在 Unity 里对应哪个设置测验
T9完成课堂案例 01 的验收验收清单

180 分钟时间轴

时段时长环节主要动作
0:00–0:088'开场本学期模型与今日产出:讲清“期末 = 8 个课堂案例的合集”,今天的产出是第 1 个课堂案例
0:08–0:2012'4.1 软件生态地图四类工具分工;资产模型的“轻重”直接决定设备能否跑满 90Hz
0:20–0:3111'4.2 建模与引擎选型Blender vs 3ds Max、Unity vs Unreal;引擎选择与“生成设备”的关系
0:31–0:4211'4.3 资产从哪来三条来路 + 导入五道关;面数过高 → 掉帧 → 眩晕
0:42–0:5311'4.4 编程入门与机房环境C# 最小认知(GameObject / Component / Start-Update);本机已装好什么、版本怎么查
0:53–1:0310'课间教师巡查机房:插件是否齐全、能否新建项目
1:03–1:1512'实验 A · 核对版本 + 认界面Help → About Unity 查版本号;Package Manager 查插件;认六个面板
1:15–1:4530'实验 B · XR 环境配置 ★XR Plugin Management → Interaction Toolkit → XR Origin → Device Simulator
1:45–2:1025'实验 C · 模型 + 第一个脚本 ★导入 FBX、修比例、写最小脚本让物体转起来
2:10–2:3525'双轨验证 ★8 组轮换戴 PICO 看“自己做的场景”,对比模拟器与真机差异
2:35–2:5015'收束课堂案例 01 逐项验收、记录本机版本、预告下次课

模块地图

一

软件生态与工具选型

4.1 四类工具各管一段 · 4.2 建模与引擎怎么选

1.1 四类工具:一类工具只干一件事

类别它负责什么典型工具本课程会用到
建模造出物体的形状Blender、3ds Max、MayaBlender(看一眼界面 + 导出一个 FBX)
引擎把内容组织成可运行的应用Unity、Unreal EngineUnity 6(全程)
资产提供现成的模型、贴图、动画、音效Sketchfab、Poly Haven、Mixamo、AI 生成工具素材库 + AI 生成
验证检查“在真机上到底行不行”XR Device Simulator(PC 模拟)、头显真机模拟器为主 + 头显验证
“一类工具只干一件事”是本课的第一条原则:建模软件不做交互逻辑,引擎不做精细建模,资产库不负责优化。知道边界,才知道遇到问题该找哪一环。

1.2 建模软件:Blender 与 3ds Max

Blender(免费 · 开源)

免费、跨平台、更新快,建模/雕刻/渲染/动画一体;社区教程极多,适合个人开发与课程作业。本课程用它做“建模—导出 FBX”的最小闭环。

3ds Max / Maya(行业标准 · 商业授权)

在建筑可视化、影视与游戏公司中使用广泛,插件生态成熟、团队协作流程完善;代价是授权成本与学习曲线。

1.3 引擎:Unity 与 Unreal 怎么选

维度Unity 6(本课程选择)Unreal Engine
上手成本较低,C# 语法友好,教学资料多较高,C++ 与蓝图双轨
XR 支持OpenXR + XR Interaction Toolkit,跨 PICO / Quest / Vive内置 XR 框架,偏向高保真与主机级画面
画面保真够用,移动端一体机表现稳定更强,但更吃 GPU
一体机性能移动端优化路径成熟对头显算力要求更高
为什么本课程选 Unity:C# 上手快、XR Interaction Toolkit 提供现成交互组件、OpenXR 一次配置可跨品牌设备,且对移动端一体机(PICO 4 Ultra)的性能优化路径更成熟。Unreal 更强的是画面上限,但“画面更好”往往意味着更高的 GPU 开销——这正是上次课讲的生成设备的现实意义。
硬件接口 ①②:① 资产产出的模型有多“重”(面数、贴图),直接决定设备能不能跑满 90Hz;② 引擎越追求画面,越吃 GPU——生成设备(也就是“算力在哪”)不是抽象概念,它决定了你能选哪条技术路线。
二

资产从哪来:一个模型到 VR 的五道关

4.3 三条来路 + 五道关 + 三个最常翻车的坑

2.1 三条来路

素材库(最快)

Sketchfab 模型库、Poly Haven 贴图与 HDRI、Mixamo 角色动画。适合快速搭场景,注意授权与命名规范。

自己建(最可控)

用 Blender 从零建模,尺寸、拓扑、UV 自己说了算。代价是时间——课程里只在必要的小物件上使用。

AI 生成(最新)

Meshy、Hunyuan3D、TRELLIS 等文/图生 3D,适合快速原型。但要检查拓扑、UV、比例与版权,通常需要二次修整。

2.2 五道关:模型从建模软件到 VR 场景

① 建模  →  ② 减面  →  ③ 导出 FBX  →  ④ 导入设置  →  ⑤ 在场景里验证
            控制面数      禁中文路径      单位与缩放 ↑         戴上头显看
                                         最常翻车的一关
关卡要做什么没做好会怎样
① 建模按真实比例建模,统一单位进 Unity 后比例不对
② 减面控制在合理面数(一体机尤其敏感)掉帧、发热、眩晕
③ 导出 FBX路径与文件名不含中文导入失败、材质丢失
④ 导入设置检查 Scale / 轴向 / 材质模型躺倒、悬空、变成粉色
⑤ 验证先在模拟器看,再戴头显看“在 PC 上明明没问题”

2.3 最常见的三个坑

  1. 缩放不对:模型小到看不见、或大到撑爆场景 → 改 Transform → Scale(常用 1 或 0.01);
  2. 贴图变粉红:材质丢失或路径含中文 → 重新指定材质,并把素材放到纯英文路径;
  3. 轴向搞错:模型躺倒或漂在空中 → Blender 默认 Z 轴向上,Unity 是 Y 轴向上,需要旋转或导出时校正。
硬件接口 ③:面数过高 → 掉帧 → 眩晕。这不是“画面问题”,而是接上了上次课的刷新率与 Motion-to-Photon 延迟:延迟一旦超标,人就会不适,再好的内容也救不回来。
三

实验 A · 环境核对与界面认知

12 分钟 · 不安装,只核对:确认版本与插件齐全就能开工

本次课不安装、不下载 Unity——机房已部署好 Unity 及整套 XR 环境。你要做的是把版本与插件核对清楚,然后直接开工。

A1 查 Unity 版本号(今天的第一个任务)

路径打开 Unity → 顶部菜单 Help → About Unity,弹窗里能看到完整版本号,例如 6000.0.83f1
要做的把这个版本号抄到任务卡上(教师会收齐全班版本号,用于排查工程兼容问题)
为什么第一件事就查版本:Unity 只能升级工程,不能降级。如果现在记录的版本低于你以后使用的版本,工程就可能打不开——这是真实工程里最常见的坑之一。

A2 确认项目里装了哪些包

  • 路径:Window → Package Manager → 左上角下拉框选 In Project;
  • 要找的包:XR Plugin Management、XR Interaction Toolkit;
  • 顺带看:列表中若有 Input System,说明输入系统已就绪;
  • 若缺包:下拉框切到 Unity Registry 搜索安装;若机房不能联网,用教师提供的 .unitypackage 本地导入(Assets → Import Package → Custom Package)。

A3 打开或新建项目

  • 打开已有:Unity Hub → 项目 → 点机房提供的模板项目;
  • 若需新建:Hub → 新建项目 → 模板选 3D (Built-In Render Pipeline);
  • 工程命名用英文(如 VRCase01),工程路径必须是纯英文。

A4 认识六个面板(必记)

面板位置作用一句话记忆
Hierarchy 层级左侧列出场景里所有物体场景里“有什么”
Scene 场景中央编辑视角,搭建场景你工作的地方
Game 游戏中央运行时真实画面(相机视角)玩家“看到什么”
Inspector 检视右侧选中物体的组件与属性选中什么改什么
Project 项目底部工程里所有资源文件素材“存在哪”
Console 控制台底部报错、警告、调试输出出问题先看这里

自测三个问题:运行时报错先看哪个面板?哪个面板显示“玩家实际看到的画面”?哪个面板列出场景里“有什么物体”?

A5 保存场景

File → Save(Ctrl+S)。场景文件是 Assets/ 下的 .unity 文件,养成随时保存的习惯。

硬件接口 ④:稍后要加的 XR Origin,就是上次课讲的 Inside-Out 定位在软件里的落点——硬件负责“知道自己在哪”,软件负责“把位置用起来”。
四

实验 B · XR 环境配置 ★

30 分钟 · 把普通 3D 项目变成 VR 项目的一步,后面 9 次课的地基

#操作路径说明 / 注意事项
B1启用 OpenXREdit → Project Settings → XR Plug-in Management在 Windows 标签页勾选 OpenXR;OpenXR 是跨设备开放标准,一次配置可支持 PICO / Vive / Quest。若提示需重启编辑器,按提示重启后继续
B2确认 XR Interaction ToolkitPackage Manager → In Project它提供抓取、射线、传送、UI 交互等现成交互组件;清单里若出现 Samples,展开能看到 Starter Assets 与 XR Device Simulator 就说明示例包已就绪
B3添加 XR Origin (VR)Hierarchy 空白处右键 → XR → XR Origin (VR)它替代普通相机,负责跟随头显位置与朝向。必须禁用或删除场景里原有的 Main Camera,否则两个相机打架、画面异常
B4添加 XR Device SimulatorProject → Assets/Samples/XR Interaction Toolkit/<版本>/XR Device Simulator → 把预制体拖进 Hierarchy用键盘 + 鼠标模拟头显转头与手柄操作。本课程“PC 开发为主、头显验证为辅”,这个组件就是“PC 上开发”的支柱
B5Play 验证点击顶部 ▶ Play期望结果:Game 视图里视角能随 WASD 与鼠标转动而移动

XR Device Simulator 常用模拟按键(默认)

按键作用
W / A / S / D模拟头显前后左右移动
按住鼠标右键拖动模拟转头
Tab(按住)切换左右手
G(按住)模拟手柄握持(Grip)
鼠标左键模拟手柄触发(Trigger)
按键以你机器上模拟器预制体显示的提示为准(版本不同可能略有差异)。按了没反应?先用鼠标点一下 Game 视图,让焦点落在游戏窗口里。
B 环节的思考题:XR Origin 解决的是上次课讲的哪个硬件问题?——提示:和“头显怎么知道自己在哪”有关,也就是跟踪定位。
五

实验 C · 导入模型与第一个脚本 ★

25 分钟 · 让场景里真的有东西,而且它会动

C1 导入 FBX 模型

  • Project 面板右键 → Create → Folder,先建一个 Models 文件夹;
  • 把教师提供的 .fbx(或 .obj)拖进 Assets/Models;
  • 选中模型,Inspector 里会出现 Model / Rig / Materials 三个标签页。
本次课不依赖联网下载模型,统一使用教师提供的模型文件。

C2 放进场景并修正比例

检查项怎么做
比例是否合理与场景里的 Cube / Plane 对比;不对就改 Transform → Scale(1 或 0.01)
位置是否合适调整 Transform → Position 的 Y 值(Unity 是 Y 轴向上)
材质是否正常若呈粉红色,说明材质丢失或贴图路径含中文,需重新指定

C3 写出第一个脚本

Project 面板空白处右键 → Create → C# Script,命名为 SpinObject——首字母大写、不能有中文、不能有空格。

using UnityEngine;

public class SpinObject : MonoBehaviour
{
    public float speed = 60f;   // 每秒旋转的角度

    // Start 在物体第一次被激活时调用一次
    void Start()
    {
        Debug.Log("SpinObject 启动了");
    }

    // Update 每帧调用一次(适合做持续运动)
    void Update()
    {
        transform.Rotate(0f, speed * Time.deltaTime, 0f);
    }
}

挂载与运行

  1. 选中场景里的模型(或任意物体);
  2. 把 SpinObject 从 Project 面板拖到 Inspector 下方空白处;
  3. 点 ▶ Play,物体开始旋转;
  4. Play 状态下可以在 Inspector 里实时改 Speed,看转速变化(试试从 60 改成 600)。

读代码要点(对应 4.3 开发语言)

概念在这个脚本里的体现
GameObject你挂脚本的那个物体
ComponentSpinObject 本身就是挂在物体上的一个组件
MonoBehaviourUnity 所有脚本的基类,必须继承
Start()只执行一次,适合初始化
Update()每帧执行,适合持续动作
Time.deltaTime让转动速度与帧率无关——快慢机器上转得一样
Time.deltaTime 是本课最值得记住的细节:没有它,高刷新率的机器上物体会转得更快。这和上次课讲的帧率、延迟是同一件事的两面。
六

双轨验证:模拟器 → HTC Vive 真机 ★

25 分钟 · 同一个场景,在 PC 与头显里各看一遍

你已经在 PC 上用 Device Simulator 跑通了场景。现在戴上 HTC Vive 看一个真实运行的 VR 场景,体会软件设置与硬件体验之间的差距——这就是本课程“双轨流程”的核心。

本实验室的头显是 HTC Vive ×5:有线 + 基站方案,头显固定在 5 个机位上、搬不动,所以这一环节看的是教师演示的场景,不是每位同学自己的工程(后续课次设备流程熟练后,再安排"带自己工程上机")。

组织形式

  • 5 组轮换,5 套 HTC Vive 同时开放,按机位号分 1—5 组,每组 8 人;
  • 每人约 3 分钟(只看一眼,不是完整体验);
  • 未轮到的组:继续完善自己的场景,或帮旁边同学排错。

戴上头显做三个动作

  • 看:画面清不清晰?和 PC 上的 Game 视图比,差别在哪?
  • 转:快速转头——画面跟得上吗?有没有拖影或延迟?
  • 走:瞬移一步,感受移动时的舒适度。

记录对比(课堂任务卡填写)

对比项PC 模拟器HTC Vive 真机
画面清晰度
转头时的延迟感
眩晕 / 不适感
思考题:同一个场景,为什么在 PC 上看着没问题,戴到头显里可能出现不适?提示——回想上次课的 PPD、刷新率、Motion-to-Photon 延迟。
板书收束句:硬件决定上限,软件决定你能不能碰到这个上限。
演

课堂演示中心

7 个演示 · 浏览器直接打开 · 全部离线可用、无外部依赖

本节课的主线演示是 07 软件生态与管线决策台,它的五个标签分别对应 4.1—4.4 的讲授环节与收束。01—06 为硬件主题,属于上一课(第 3 次课):其中 07 的标签②「硬件 ↔ 软件对照」正好用来回指上次课学过的参数。

演

课堂演示设计 · 基于本机实装环境

Unity 6000.6.0f1 + XR Interaction Toolkit 3.6.0 · 7 个演示,每个 3—6 分钟

下面 7 个演示全部基于这台机器上今天实际装好的版本设计,不是通用教程。每个演示都遵循同一个结构:先说是哪一步 → 现场做 → 让学生看到现象 → 当场读出数字。演示用的工程是 D:\UnityProjects\VRCase01,场景 Case01.unity。

一、实装环境核对表(演示前先念一遍)

组件本机版本在哪看演示时要学生注意什么
Unity 编辑器6000.6.0f1Help → About UnityUnity 只能升不能降:如果你的版本比机房高,机房的工程就打不开。这是第一件要记下来的事
Input System1.20.0Package Manager → In Project手柄按键、模拟器按键、后续所有交互都走它
XR Interaction Toolkit3.6.0Package Manager → In Project抓取、射线、传送、UI 交互的现成组件都在这个包里
XR Plug-in Management4.7.0Package Manager → In Project"一次配置、跨设备"的开关就在它的设置页里
OpenXR1.18.0Package Manager → In Project真正接管头显的运行时;这一个勾错了,Play 之后视角一定不动
XRI 样例包3.6.0(Starter Assets / XR Device Simulator)Assets/Samples/XR Interaction Toolkit/3.6.0关键认知:模拟器不是第三方插件,是官方包自带的样例
PICO Streaming Service(PC 端)已装开始菜单接一体机时才用;接 HTC Vive 走 SteamVR,不需要它
为什么把"核对版本"排成第一个演示:这不是客套。教师机与机房机版本可能不同,而版本不一致是唯一一种"后面所有步骤都白做"的故障。先用 3 分钟把它排除掉,后面 150 分钟才安全。

二、7 个课堂演示(U1—U7)

U1 · 3 分钟
版本与包核对
目标:全班机器版本一致,每人知道自己这台是什么环境。
操作:Help → About Unity 读版本号 → Package Manager → In Project 读四个包版本 → 填任务卡。
应看到:编辑器 6000.6.0f1;Input System 1.20.0 / XRI 3.6.0 / XR Management 4.7.0 / OpenXR 1.18.0。
翻车点:装成"团结引擎(Tuanjie)"或 2022 LTS,工程直接打不开。
U2 · 6 分钟
OpenXR 一次性配置
目标:让"一次配置支持 Vive / PICO / Quest"这句话变成看得见的东西。
操作:Project Settings → XR Plug-in Management → Windows 标签勾 OpenXR → 展开 OpenXR 看 Interaction Profile 列表 → 按提示重启编辑器。
应看到:HTC Vive Controller、PICO、Oculus Touch 等配置项并排在同一张表里。
对应知识点:上次课的 Outside-In 基站定位,落到软件里就是 XR Origin 读取的姿态数据。
U3 · 6 分钟
XR Origin + Device Simulator:看 / 转 / 走 / 抓
目标:没有头显也能把 6DoF 演完整。
操作:Hierarchy 右键 → XR → XR Origin (VR);删掉旧的 Main Camera;把 XR Device Simulator 预制体拖进 Hierarchy;Play 后用 WASD 移动、按住鼠标右键转头、Tab 切左右手、G 握持、鼠标左键触发。
应看到:Game 视图里有虚拟手柄;走动时物体之间出现视差——这就是 6DoF 的价值。
翻车点:按键没反应 → 先用鼠标点一下 Game 视图;画面异常 → 旧主相机没删。
U4 · 5 分钟
射线交互与反馈:Hover / Select / 变色
目标:把"交互 = 事件 + 反馈"这句话讲实。
操作:给立方体挂 XRSimpleInteractable + InteractButton 脚本;Play 后用射线指上去、按下、移开。
应看到:灰色 → 悬停变黄(hoverEntered)→ 按下变绿(selectEntered)→ 移开复位。
对应知识点:输入设备那一节的"手柄是怎么被看见的",在软件里变成"事件是怎么被触发的"。
U5 · 6 分钟
第一个脚本:Start / Update / Time.deltaTime
目标:讲清"初始化一次"和"每帧一次"的区别,以及转速为什么要乘 deltaTime。
操作:把 SpinObject 拖到物体上 → Play(默认 60 度/秒)→ 在 Inspector 把 speed 改成 180 → 再 Play 对比 → 看 Console。
应看到:转速随参数变化;Console 里 Start 的日志只出现一次。
对应知识点:如果不乘 deltaTime,高刷新率的机器上物体会转得更快——这就是"帧率"这个硬件指标在代码里的落点。
U6 · 6 分钟
自检与性能读数:F1 与 F2
目标:把"验收"从手感变成数字,把"面数 → 掉帧 → 眩晕"这条链落地。
操作:Play 后 SceneSelfCheck 自动跑五项检查,按 F1 可重查;按 F2 开性能浮层读 FPS / Triangles / Draw Calls;把场景里的树复制成 10 棵,再看这三个数。
应看到:缺项被直接点名;三角面与 Draw Call 上升、帧率下降。
翻车点:个别机器取不到计数器、显示 n/a,属正常,不影响场景运行。
U7 · 5 分钟
模型导入与比例:从建模软件到场景
目标:把"资产导入五道关"里最容易翻车的一段摊开讲。
操作:导入 _woodhouse.fbx 与 Palm.fbx → 检查 Scale Factor 与单位 → 放进场景,和 XR Origin 比高矮 → 材质变粉红时重新指定贴图。
应看到:尺寸正常(人能从门口走过去);粉红材质修好后显示正常。
翻车点:素材路径含中文或空格;贴图丢失(材质的引用关系断了);坐标轴不一致导致模型躺倒(Blender 是 Z 轴向上、Unity 是 Y 轴向上)。

三、演示与课堂时间轴的对应

时段演示为什么放在这个点
0:08–0:53 讲授只做 U1(版本与包)它同时是"实验 A"的起点,提前做掉,实验段就不慌
1:03–1:15 实验 AU1 全班跟做每人都记下自己的版本号,这是后面所有排障的依据
1:15–1:45 实验 B ★U2 + U3地基环节:XR 环境不通,后面全都做不了
1:45–2:10 实验 C ★U4 + U5 + U7先让场景里有东西(U7),再让它动(U5),再让它可交互(U4)
2:10–2:35 双轨验证U6 前半段 + 真机PC 上先读三个数,戴头显时才有对照
2:35–2:50 收束U6 后半段(复制物体再看数字)用它把"优化"第一次讲成可量化的动作

四、演示翻车的三级降级方案

级别触发条件降级做法
一级Package Manager 连不上网、包装不上用提前导出的 XR 相关 .unitypackage 离线安装;U2 改为"看已装好的工程"
二级头显连不上 / SteamVR 找不到设备全部走 Device Simulator,真机环节改为教师机投屏演示,学生只做记录
三级Unity 崩溃或工程打不开用教师机的录屏与截图按原顺序讲完流程,学生改为填写"故障记录表"(也算一次完整练习)
视

视频资料 · 第 4 次课配套

27 条 B 站视频 · 逐条核验标题、时长与发布日期 · 按学习顺序分组

怎么用:本课视频不能替代动手。建议顺序是"课上跟做 → 卡住了看对应的那一条 → 想深入再看完整系列"。第五组(Pico Neo3 开发系列)与实验室设备直接对应,是最值得课后刷的一条线。播放量、点赞数为 2026-09-15 核验值。

一、引擎认识与安装(对应 4.1 工具选型与实验 A)

知识点视频时长数据怎么看
Unity 6 正确安装别再把团结引擎当 Unity 了!Unity 6 正确下载安装教程(嗜睡的猫咪)18:0013.7 万播放 / 1733 赞本课首推:直接回答"我装的是不是 Unity"——团结引擎是国产分支,工程不通用
Hub 与编辑器安装最简单的手把手保姆级 Unity 入门教程:下载和安装(喵布里)13:248.5 万播放 / 1603 赞课后在自己电脑上补装时用;注意版本要选 LTS 并与机房保持同一大版本
引擎选型:Unity vs UnrealUnity 和 UE 引擎应该选哪个?深入浅出的对比介绍(枫2)12:103.2 万播放 / 1139 赞对应 4.1"一类工具只干一件事":为什么本课选 Unity 而不是 Unreal
Unreal 的门槛在哪深度解析,为什么 Unreal 比 Unity 难?(倾海海海海)12:137.8 万播放 / 1750 赞反方视角:承认 Unreal 的画面上限,再解释"上限高 ≠ 课堂合适"

二、编辑器界面与环境核对(对应实验 A)

知识点视频时长数据怎么看
编辑器全貌(必看)Unity 10 分钟快速入门(Ross-Ning)11:4778.1 万播放 / 2.6 万赞本课首推:11 分钟走完 Hierarchy / Scene / Game / Inspector / Project / Console 六个面板,正好对上实验 A4
界面布置与自定义Unity 新手入门:编辑器界面布置(上月球去写甲骨文)6:372.0 万播放 / 264 赞面板被拖乱了怎么办——多人共用机房机器时人人都会遇到

三、XR 环境配置与交互(对应实验 B)

知识点视频时长数据怎么看
OpenXR 环境配置【Unity VR 开发入门】OpenXR:头盔手柄的环境配置(VR-Sowilo)9:447966 播放 / 114 赞本课首推:把"勾了 OpenXR 之后到底发生了什么"讲得比多数教程清楚
OpenXR + XRI 完整配置Unity VR 开发教程:OpenXR + XR Interaction Toolkit 安装和配置(Teacher_Liu)18:113356 播放 / 36 赞课后再看一遍,把 B 环节的每一步对齐到视频里
XRI 快速配置交互快速配置交互:移动、抓取、UI 交互(XR Interaction Toolkit)(SpatialXR社区)18:441.8 万播放 / 1094 赞本课首推:想在下节课做出"能抓、能传送"的场景,看这一条
XR Device Simulator(官方)Unity 设备模拟器(Device Simulator)教程(Unity 官方)3:521.3 万播放 / 295 赞4 分钟讲完全部模拟按键;官方出品,界面与 3.6.0 最接近
XR 模拟器实操Unity XR 模拟器 XR Device Simulator 使用教程(Cool灬浩)4:436369 播放 / 103 赞补充"按键没反应"这类现场问题,和本页故障速查表配合看
XR Origin 设置Unity 开发 Pico VR 项目基础:导入并设置 XR Origin(老徐看VR)3:111850 播放 / 12 赞补一个"XR Origin 到底替代了相机的什么功能"的直观解释
XR Origin 基本设置XR Origin 基本设置(划破长空那一鸣)2:43773 播放 / 3 赞短平快;播放量很低,但这一步确实没有更好的中文资料
SteamVR 与 OpenXR 的关系使用 OpenXR 代替 SteamVR 以获得更好的 VR 体验(JuiceforeaL_)2:522.4 万播放 / 399 赞回答"为什么现在推荐 OpenXR,而不是直接挂 SteamVR 插件"
SteamVR 报错排查串流时 SteamVR 报错检测不到头盔,怎么解决(赤峰飞人乔尔特)18:018.3 万播放 / 569 赞真机环节最可能撞上的故障,先看症状再对号入座

四、模型、脚本与性能(对应实验 C 与性能读数)

知识点视频时长数据怎么看
模型导入注意事项Blender 模型导入到 Unity 的相关设置以及注意点(愿为磐石守一人)7:064.7 万播放 / 704 赞本课首推:比例、单位、坐标轴、材质四条一次讲全,正好对上 U7
导入 FBX(最短路径)两分钟教会你如何在 Unity 中导入 FBX 的 3D 模型(YuZou邹宇)1:562.2 万播放 / 152 赞课堂只放这 2 分钟,其余留给课后
材质丢失(粉红)修复导入 Unity 的 FBX 丢失了处理方式(经常会遇到)(poorgun慢)5:251.9 万播放 / 127 赞把"模型变粉红"从一个意外变成一个可解释、可修复的常见现象
脚本生命周期零基础学习 C# 在 Unity 中的使用:脚本生命周期(M_Studio)10:352.8 万播放 / 1369 赞本课首推:Start / Update 各调用几次、顺序如何,看这一条就够了
从组件到脚本【Unity 游戏开发入门 01】从组件 Component 到 C# 脚本(IGBeginner01)4:043.5 万播放 / 972 赞补"脚本就是一个自定义组件"这个概念,讲清挂载方式为什么是拖拽
Profiler 性能分析简单易懂的 Unity 性能优化:Profiler 使用技巧实例解说(游戏石匠Super)10:417883 播放 / 325 赞本课首推:和 F2 浮层配合,把"掉帧"定位到具体环节
Draw Call 优化几个小动作让帧数立刻提升:Unity 性能优化之 Draw Calls(AliveCat)4:241.2 万播放 / 446 赞回答 U6 里的问题:帧率低时先看三角面还是先看 Draw Call

五、与实验室设备直接对应的开发线(推荐课后刷)

知识点视频时长数据怎么看
Pico Neo3 开发(1)Hello WorldPico VR Neo3 开发入门教程(1)——Hello World(怜子卿如水)6:313.7 万播放 / 567 赞与实验室备用机同型号,也是目前唯一一条完整的中文设备对应教程线
Pico Neo3 开发(2)传送与移动Pico VR Neo3 开发入门教程(2)——射线传送,移动(怜子卿如水)8:191.9 万播放 / 192 赞射线传送是后面"密室逃脱"演示案例的必备交互
Pico Neo3 开发(4)开关门Pico VR Neo3 开发入门教程(4)——握把手,开关门(怜子卿如水)10:078705 播放 / 90 赞抓取 + 旋转约束的典型做法,可直接迁移到期末案例
Pico Neo3 开发(7)射线事件Pico VR Neo3 开发入门教程(7)——射线悬停和点击事件的回调(怜子卿如水)9:027332 播放 / 110 赞接上 U4 的 Hover / Select,看它在完整项目里怎么用
Unity + SteamVR(Vive)Unity + SteamVR VR 教程(HTC Vive 设备)(镜欲染)10:144832 播放 / 97 赞本实验室头显是 HTC Vive:这条讲的是 Vive 那条老路,和 OpenXR 方案对照看
内容缺口(如实说明):① Unity 6(6000.x)的中文教程还很少,绝大多数优质视频仍是 2021—2022 版界面,菜单路径会有差异,以本课操作手册与现场界面为准;② XR Origin、XR Device Simulator 的中文专门讲解播放量普遍很低(几百到几千),说明这块确实缺资料,上表已是能找到的最好选择;③ 没有找到"VR 项目性能优化"的中文系统课,只能用通用 Profiler 与 Draw Call 视频替代。