【立项背景与目标】
新民大街是长春的历史文化街区,两侧集中了伪满"八大部"建筑群、地质宫和长春历史文化博物馆,是城市近代建筑最密集的一段。线下到访只能看外观:每栋楼的营建年代、设计者、功能更迭都写在文献里,走完一条街看不到这些信息;传统图文展陈又难以表达街区的空间尺度与建筑关系。本项目把整条街区做成可在浏览器和 VR 头显里第一人称漫游的三维场景,目标很明确——"走进去看建筑、进门厅看沿革",不装插件、不依赖网络,双击即可运行。
【软件功能与核心模块】
1. 街区场景:9 栋历史建筑与文化广场,1 单位 = 1 米,含道路、行道树、地形起伏与远景雾化边界。
2. 第一人称行走:WASD + 鼠标视角,走/跑/跳、飞行、Q/E 分段转身、抛物线传送;墙体、台基、台阶有碰撞,楼梯可上二层。
3. 建筑交互:准星指向建筑弹出信息卡(名称、英文名、沿革分段),再点同一栋传送到正门前。
4. 内景漫游:博物馆主馆与 7 栋建筑门厅可进入;同一空间按 1/2/3(VR 为右手侧键)切换三套历史陈设,讲同一栋楼的三个时期。
5. 展板讲解:室内展板本身就是讲解点,准星指到即高亮,点击弹出图文面板并支持中文语音朗读。
6. 自动导览:10 站路线依次传送并讲解,N 下一站、B 开始/结束、V 朗读。
7. 导航与设置:右下角小地图点击传送;菜单含地点、导览、地图、画质(帧率/分辨率)、舒适度(分段转身、暗角)、朗读开关,设置本地持久化。
8. VR 模式:HTC VIVE 手柄完整映射(左手触控板行走、右手扳机进出内景、侧握开菜单),头显内自带可翻页说明书牌与腕部速查牌。
【业务流程与功能路径】
双击 start.cmd → 本地服务起在 127.0.0.1:8099 并做健康检查 → 浏览器加载场景(带进度条)→ 点击画面锁定鼠标 → 沿街行走,走近任一建筑正门 → 进门厅 → 按 1/2/3 看三个时期的陈设 → 出门回到街区 → 按 M 打开菜单导览或直接传送 → 点页面底部按钮进入 VR,戴头显后用左手触控板走、右手扳机进门。
【整体架构与设计思路】
整条链路是「Blender 建模 → glTF 导出精简 → Three.js 运行时」,前端不打包、不用框架:ES 模块 + importmap 直接跑静态文件,由本地 Python 服务托管。
1. 资产层:街区与 8 个内景在 Blender 中建模、烘焙,导出 glb 时开启 meshopt 压缩、KHR_mesh_quantization 量化与 Basis/KTX2 贴图。外景 72.7 万三角面压到 17.2 MB;内景按栋拆成独立 glb,进出时按需加载、退出即释放。
2. 数据层:建筑轮廓、POI 文案、碰撞墙线、内景配置、展板讲解点、楼梯高度全部外置为 JSON 驱动(poi / buildings / collision / interiors / interior_info / stairs),改内容不动代码。
3. 运行时:src 下 23 个 ES 模块共 8,612 行,main.js 负责场景装配与主循环,其余按职责拆分(碰撞、小地图、导览、沙盘、内景陈设、沿革场景、云与远景、性能优化)。桌面与 VR 共用同一套交互与同一张 Canvas UI。
【我负责的模块与结果】
独立完成建模、程序与测试。量化结果:整包 56 MB / 294 个文件,双击即用;外景 762 个 mesh 按 100 米分块实例化合并,draw call 与显存占用明显下降;碰撞由模型 0.35–2 m 高度带自动抽取,381 条闭合轮廓、11,073 段墙线;内景 8 个 × 3 套陈设 = 24 套场景;展板讲解点 11 处;本地从点开到可走动约 5 秒。
【难点、坑与解法】
1. VR 双眼渲染的填充率:不新增任何全屏图层——云写进现有天穹 shader,地面云影用一块贴世界坐标的"幕布",避免去改 56 个共用材质;alphaTest 镂空树叶不投影;各向异性固定 4×。
2. 模型没有碰撞体:直接从 glb 的墙、台基、柱高度带提取轮廓生成墙线,用网格哈希加速 + 圆与线段最近点推离,大步长自动细分防穿墙;楼梯另做坡面高度与上下两层碰撞,脚高超过 1.5 m 自动切上层。
3. 内外景衔接:内景是独立 glb,进门不能有跳变——用门斗坐标 + 淡入淡出,退出时释放临时资源,避免反复进出导致显存增长。
4. 浏览器坑:Esc 退出后 1.5 秒内指针锁定必然被拒,单独写重试模块;Canvas 中文换行要逐字测量,英文技术词不能被拆开;python -m http.server 加载大 glb 会因长连接堆积僵死,改为自写短连接 + no-store + 健康检查的本地服务。