OCC 星球漫游 · 系统架构

把整个项目拆开看：谁负责什么、谁调用谁、哪些数据是权威的、哪些约定一旦违反就会出静默事故。 这份文档是代码现状的映射（不是设想），与 README.md 的分工是：README 讲"怎么跑起来"，本篇讲"它是怎么搭起来的"。

核对基线：2026-10-15 21:34（工作区代码）。凡涉及"行数 / 数量"的结论都取自当次实测。

0. 一句话

Three.js 0.184 前端（纯 ES Module，无打包器）+ Node/Express/ws 服务端，同端口提供作品、文档站与 WebSocket； 所有玩法状态在Server-authoritative，客户端只做预测与表现；两颗星球（苗圃 / 焦土）共用同一份确定性地形与资源数学。

1. 三层结构

共享层是这个项目最关键的一处架构决定：地形、矿脉、植被掉落三张表都不是"各写一遍"，而是一份代码两处跑。 任何改动都要意识到它同时影响前后端。

2. 双星球体系

两颗星球不是两个场景，而是同一个 seed 的两种参数（server/world-config.js）：

要点：

• 同 seed 私有分片：家园星不额外生成地形，只是按 private 标记隔离会话。省掉一整套地形分片逻辑。
• 网格边长必然略有差异（10.30 vs 10.21）：两星球段数不同但都要保持 2:1，所以用建造格做尺度统一时留了余量。
• 前端投影：world.js 的 applyWorldToConfig() 把 cfg.worlds[id].{radius,lonSegments,latSegments} 摊平到 cfg.planet.*，植被数量按 floraRate × 面积比 缩放（家园星约为战场的 12%）。
• 切换 = 整页重载，不是运行时 dispose。world.js 头部注明了原因：两颗星球不能同时驻留显存（光植被就 10.2 万实例），而方案自己接受"切换几秒可接受"。过渡由 #warp 遮罩盖住。

3. 前端模块地图（52 + 3 个）

3.1 入口与配置

3.2 地形与渲染

3.3 特效与表现

3.4 玩家与战斗

3.5 玩法系统

3.6 音频

三条防炸机制（缺一条就会在 50 台 NPC + Boss 齐射时爆音）：

3D 定位按球面弧长（locate()）：距离 = 方向夹角 × 当前星球半径。 🔴 不能拿世界坐标相减 —— 两颗星球都是「单位方向 × 半径」，同样的坐标差在 R520 / R820 上是完全不同的实际距离。声像用切平面投影的左右分量。

三条设计约束（都是为了不重演 2026-10-15 的"整局冻住"）：

1. 任何调用都不许抛错 —— 未解锁 / 索引没到 / 文件 404 / 浏览器缺 API，一律静默降级；主循环里的调用处再包一层 safe('audio', …)。
2. 不进首屏 —— initAudio() 只建 AudioContext，拉索引与预载 P0 都等首次用户手势（浏览器自动播放策略本来就要求）。预载只挑 kb ≤ 90 的非循环条目，约 700KB。
3. 循环源要排队 —— 环境音在 boot 末尾就 loopStart('amb')，那时索引还没到；loopStart 遇到「索引未就绪」会进 deferredLoops，索引到达后统一重放。不排队的话环境音永远不起（实测踩过：loops: []，作品进得去但没氛围）。

音效名 = 成品文件名去扩展名（ui_click / sfx_mecha_step_l / amb_home_loop）， 路径映射来自 public/assets/audio/_index.json（由 tools/audio/postprocess.py 生成 —— 新生成音效后跑一次后处理就会自动出现）。

• 调试出口：__OCC__.audio.{ready, mix, play, setBus, setEnabled, loops, stats}
• 音量面板：mountMixer() 挂在右下 dock，DOM 全动态创建 + 样式内联（不动 index.html / styles.css，避免踩 z-index 阶梯表）
• ⚠️ 两个坑都踩过：按钮必须 position: static（.dock-btn 基类是 fixed）；wrap 要挂 dock 末尾（否则和同样 fixed 的「作品文档」按钮静态位置重叠、被盖住）

3.7 UI 与网络

3.8 不在 public/src/ 里的 3 个前端模块

它们经服务端 /assets/mecha/model 静态路由到达浏览器，被 mecha.js 静态 import。 算前端模块时容易漏掉这三个（源码目录树里看不到）。

另外 public/vendor/addons/libs/meshopt_decoder.module.js（29KB，内联 WASM）是 EXT_meshopt_compression 的解码器，被 glb-loader.js 静态 import —— 发布时不能漏（漏了就是"建筑/矿产/无人机全部不显示"）。

4. 服务端模块地图（11 个）

依赖方向（箭头 = import）：

server.js
 ├─> world-config.js
 ├─> store.js ──> bag.js ─> items.js
 │            └─> build.js ─> items.js + world-config.js
 │            └─> tech.js
 │            └─> guide.js ─> public/src/guide-steps.js（步骤文案表，两端共用）
 ├─> npc.js              （自包含球面数学）
 ├─> world-boss.js       （自带最小球面数学）
 ├─> sim.js ──> items.js + build.js + public/src/{resource-field,logistics-const}.js
 └─> public/src/{terrain-field,resource-field,flora-harvest}.js

口径：server.js 只做入口 + 校验 + 广播，业务状态在 store.js（账户 / 背包 / 建筑 / 科技，会落盘）与 sim.js（基地生产运行时，不落盘）。

5. 前后端共用层（确定性）

反面教材：_logs/gather_tip_check.cjs 里自己内联了一份 cellToDir，与资源Search对不上，导致扫不到矿。 不要自己另写一套坐标换算——去 import 现成的。

6. 世界装配与主循环

6.1 装配（boot()）

main.js 的 boot() 是一条直线流程，每步之间 await nextFrame() 让加载条刷新：

读服务端 cfg → deepMerge → 投影当前世界 → 预加载过渡 → 并行下载机甲 GLB
→ 登录 / 创建角色 → 钱包 / 出生点 / 摧毁列表（并发）
→ WebGLRenderer / scene / 光照
→ terrain → planet → flora → physics(+地面+障碍物流) → effects/debris/damageNumbers/destructibles
→ resources → buildMode → logistics → loot → （雷达与面板并行下载）
→ 载具模型 → npcs → boss + bossFx → mecha 落地 → mining → player + camera
→ paperPlanes → sky → input → 首帧渲染 → 雷达 / 面板实例化 → net.connect → setAnimationLoop

没有 createWorldRuntime / disposeWorld：切世界靠整页重载，别去找这个函数。

6.2 主循环（26 个阶段）

6.3 safe() 包装（本项目最贵的一课）

renderer.setAnimationLoop 的回调抛一次错就不再排下一帧 —— 整局冻死，键鼠全无反应，只能 F5。 而且 F5 会清控制台，玩家回头报"没有报错"。

所以主循环里每一个易错模块调用都包 safe(标签, fn)：出错只丢该模块这一帧，且同一标签只 warn 一次。 2026-10-15 的冻屏事故就是这个机制的直接产物（纸飞机命中 NPC 时 normal.dot is not a function）。 新增模块进主循环时，第一件事是给它套 safe()。

7. 坐标系与球面约定（全项目铁律）

8. Server-authoritative边界

这是"哪些能自己算、哪些必须问服务端"的清单：

9. 运行时状态与落盘

最后一行是"幽灵矿"事故的根源，详见 玩法系统现状。

10. 已知禁区（改动前必读）

相关文档

• 玩法与系统现状（含数值）：玩法系统现状
• 接口与协议：接口与协议
• 开发与调试：开发指南
• 测试：测试指南
• 部署：部署与发布
• 方案原文（设计意图，非现状）：玩法方案-Planet Civilization-v1