BeamNG.Earth架构深度解析:Floating Origin浮动原点与伴生服务器设计(附10个关键原理)
BeamNG.Earth架构深度解析:Floating Origin浮动原点与伴生服务器设计(附10个关键原理)
BeamNG.Earth 是一个把 1:1 真实地球带进 BeamNG.drive 的开源 Mod 项目。它的核心架构可以概括为两句话:Floating Origin(浮动原点)让坐标原点跟着车移动,伴生服务器 earthd 在本地下载并构建真实地球数据,再以流式方式喂给游戏。真实高程、卫星影像、LOD 流式加载,都建立在这套设计之上。本文面向新手,拆解它背后的 10 个关键原理。
🌍 整体架构:地球在服务器里,游戏里只有一个"局部气泡"
BeamNG.Earth 采用"globe in the companion, flat bubble in the game"(地球在伴生端,平面气泡在游戏里)的模式——与微软飞行模拟的 anchor space、Cesium 的 origin shifting、KSP 的 floating origin 同源:
互联网数据(DEM 高程 / 卫星影像 / OSM 路网)
│ 下载 · 缓存 · 限速
伴生服务器 earthd(监听 127.0.0.1)
· 持有 float64 精度的完整 WGS84 地球
· 瓦片构建 · LOD 选择 · 二进制 .cdae 输出
│ 本地 TCP:JSON 控制消息 + 瓦片文件
游戏 Mod(Lua 扩展 beamngEarth)
· 加载瓦片 · 隐形物理地形块 · Floating Origin 重基准
│
BeamNG.drive 场景:局部 ENU 平面(仅几公里见方)
- 游戏侧只能看到锚点(anchor)周围几公里的局部 East-North-Up(ENU)坐标系:+X 向东、+Y 向北、+Z 沿椭球法线。重力仍近似均匀指向 -Z(8 km 处方向误差约 0.07°,可忽略)。
- 服务器侧用 float64 保存真正的 WGS84 地球(ECEF 坐标),所有瓦片顶点在服务器上就已变换到当前锚点的 ENU 坐标系再发出。地球曲率(1 km 处下沉 7.8 cm、10 km 处 7.85 m)由此"免费"获得,全程无 Web-Mercator 变形。
- 设计全文见 docs/ARCHITECTURE.md,入口说明见 README.md。
⚙️ Floating Origin 浮动原点:为什么原点必须"跟着车走"
游戏场景物体的位置是 float32(32 位浮点),数值越大,能表示的"最小刻度"(ULP)越粗:
| 距原点距离 | float32 ULP | 影响 |
|---|---|---|
| 2 km | 0.12 mm | 无感 |
| 8.2–16.4 km | 0.98 mm | 4K 下约 0.9 px,基本无感 |
| 16.4–32.8 km | 1.95 mm | 开始可感知抖动 |
如果原点固定不动,车开得越远,世界就抖动得越厉害。BeamNG.Earth 的解法是 rebase(重基准):当玩家距锚点超过 15 km(默认值,上限 16 km——超过 16384 m 后 ULP 直接翻倍)时,选一个新锚点,对所有瓦片、车辆、相机和道路施加一次刚体变换(一次平移 + 约 d/R 的小角度旋转,15 km 时约 0.14°),然后一次性重建碰撞与导航图。
关键细节:
- 变换用
veh:setClusterPosRelRot(-1, …)原地移动车辆,速度完全保留——实测 3 km 跳跃下速度 20.0 → 20.1 m/s,零损伤、零失稳。 - 单次 rebase 的开销主要来自一次碰撞重建,约 50 ms 一帧,加上远端瓦片重新流式(旧瓦片保持可见,不出现空洞)。
- 服务器会提前 300 m 预取新锚点(
PREFETCH_MARGIN),并带"陈旧锚点丢弃/重发"规则,防止慢服务器把玩家甩在原地。
实现见 mod/beamng_earth/lua/ge/extensions/beamngEarth/rebase.lua,精度预算的完整推导见 docs/research/2026-10-10-origin-distance.md。
📡 伴生服务器 earthd:为什么必须外挂一个本地服务
这不是可选优化,而是引擎限制逼出来的架构:
- BeamNG 的 Lua 沙箱禁止访问互联网:luasocket 只放行 localhost/LAN/beamng.com,
ffi.load、os.execute全部被封(官方字符串luasocket_sandbox为证)。 - 但 localhost TCP 完全可用且飞快:实测二进制安全(NUL/0xFF 字节无损)、吞吐约 700 MB/s。
于是分工明确——游戏不能上网,就让服务器上网。server/earthd.py 是一个常驻 127.0.0.1 的 Python 服务(重计算由 Rust 模块 native/earthfast/ 承担),职责包括:
- 下载:Mapterhorn/USGS 高程、EOX Sentinel-2 与 NAIP 卫星影像、Overture/OpenStreetMap 路网建筑数据,全部走带令牌桶限速、熔断器与故障转移的统一下载层(
server/netfetch.py)。 - 构建:地形高度图、远处渲染瓦片(.cdae)、道路/建筑网格、导航图节点,全部在锚点 ENU 坐标系内生成。
- 传输:原子写入
<user>/temp/beamngEarth/<session>/(游戏视为/temp/…),配合 4 字节长度前缀 + JSON 的控制消息(协议 4)推送给 Mod。 - 缓存:默认 20 GB 上限的磁盘 LRU 缓存,支持
--offline纯离线游玩。
完整参数与协议表见 server/README.md。
🧩 LOD 流式:瓦片如何做到"零闪烁"
远端视野由一棵 S2 风格立方球四叉树(cube-sphere quadtree)管理,瓦片在全球(含两极)大小近均匀:
| 环带 | 范围 | 地面分辨率 | 碰撞 |
|---|---|---|---|
| R0 | 0–1 km | 1–2 m DEM + 建筑 | 有 |
| R1 | 1–5 km | ~8 m | 无 |
| R2 | 5–30 km | 30–60 m | 无 |
| R3 | 至视距地平线 | ~250 m | 无(雾/大气隐藏边缘) |
保证"不闪不洞"的三招:
- 滞回(hysteresis)25%:瓦片细化后,要退到切换距离的 1.25 倍才会退化,避免在边界反复横跳。
- swap group 交换组:父瓦片保持可见,直到它的全部子瓦片加载完成,才整体"升起新的、沉下旧的"——覆盖范围精确对齐,永不露洞。
- 视距地平线(--horizon):远端半径不再是固定 80 km,而是按眼睛高度算出的真实视线地平线(惠特尼山顶可达 503 km,最高 1500 km),配合天空半径 6371 km 渲染,远处的山脊能真实地出现在地平线上。
🚗 隐形物理块:车底的地面如何"追着车跑"
渲染地面是一堆远处瓦片,但物理地面只有一个:一块 512²/1024² 的 TerrainBlock 高度图(2 m 格网),关闭渲染、只留物理,每移动约 128–256 m 就重新导入一次新中心的高度图(一次导入约 43–130 ms,碰撞重建仅 1.6–7 ms)。
两个精妙设计:
- 2 m 世界锁定格网:高度按每锚点统一的量子 Q 取整,相邻块的重叠采样点逐位相同(bit-identical)——物理地面在移动中不会"起伏"。
- 速度预测:Mod 按当前速度提前请求,服务器再沿速度方向预取下一个块;超过 150 m/s 自动切"fast mode"(更远提前量),实测 134 m/s 巡航时车辆始终在块内 171 m 以上。
🔦 流式世界如何跟上你:细节不打折
从几公里外的山脊到路边的限速标志,全部由服务器按需推送:
- 道路、建筑、行道树、交通标志都按 256 m 瓦片流式下发,加载顺序优先相机视角锥内的瓦片(视锥外的计 3 倍距离),保证屏幕先填满。
- 服务器崩溃/重启:Mod 用"会话接管(session adoption)"机制认领旧瓦片文件夹,以恒等变换重新同步——车不动、画面不断,重连后静默恢复。
- 边缘守卫(edge guard):服务器失联时,车辆接近物理块边缘会被限速、拉回块内,永远不会"掉出世界"。
- 离线降级:所有瓦片有磁盘缓存,网络不可用时状态栏提示 "Offline - using cached data",已去过的地方照样能开。
✅ 10 个关键原理速查清单
- 地球在伴生端,气泡在游戏里:完整 WGS84 地球用 float64 存在 earthd,游戏只见几公里 ENU 平面。
- 浮动原点 rebase:15 km 触发一次整体刚体变换,速度、高度连续,单次约 50 ms。
- 16384 m 精度红线:float32 ULP 在 16.384 km 处从 0.98 mm 翻倍到 1.95 mm,故 rebase 上限 16 km。
- 曲率免费获得:顶点在服务器端即变换到锚点 ENU,下沉量 d²/2R 自然正确。
- 伴生服务器是被逼出来的:Lua 沙箱禁外网,但 localhost TCP 达 700 MB/s,"服务器上网、游戏收菜"。
- 四叉树 + 25% 滞回 + 交换组:LOD 切换零闪烁、零空洞。
- 单一隐形物理块跟车:512²/1024² TerrainBlock 只物理不渲染,2 m 格网跨块逐位一致。
- 服务器端预制二进制瓦片:.cdae 导入约 1.9 ms(Collada 约 22 ms),单瓦片 ≤ 8k 三角形避免主线程挂起。
- 预取 + 速度预测:提前 300 m 预取新锚点,沿速度方向预取地形块,队列前 12 个瓦片的影像先行下载。
- 容错是设计出来的:会话接管让重启无感、边缘守卫防坠落、20 GB LRU 缓存支持离线。
📚 延伸阅读:项目内文档导航
想继续深挖,建议按这个顺序读:
- README.md —— 功能总览与安装
- docs/QUICKSTART.md —— 快速上手
- docs/ARCHITECTURE.md —— 架构设计与全部实测数据(本文的主要依据)
- docs/V1_4_SPEC.md —— 当前版本规格
- server/README.md —— earthd 参数、协议 4 消息表
- docs/ROADMAP.md —— 路线图
小结:BeamNG.Earth 把"精度问题"(浮动原点)、"网络问题"(伴生服务器)和"性能问题"(LOD 流式 + 跟车物理块)拆成三个独立子系统,各自在本地闭环,再靠一套带会话与容错的 JSON 协议缝合——这就是它能以 Mod 形态承载整个地球的原因。

