ThreeDream

ROBOTWORLD / THREEDREAM

ThreeDream

全球首个适配 Unreal 的浏览器物理-AI 内核

确定性 ECS + 固定步长仿真,渲染只是镜像;WebGPU 规模层叠在 three.js 自己的 GPUDevice 上,10 万粒子、2 万软体节点零回读;策略梯度学习器在页面里实时训练;Unreal 5.5 工程的 .umap 由本仓库的导入工具直读,关卡在浏览器里走起来。

进入线上演示 GitHub 仓库

100k

粒子 / 步 · WebGPU

20k

软体节点 / 步

bit-identical

wasm 与 TS 摘要

2,100+

无头单元测试

三件事,一个内核

高性能物理引擎

固定步长的确定性 ECS 是唯一事实源,渲染只读它的状态。三个后端同一套接口:纯 TypeScript 的 builtin 是规范实现;first-party Rust 编出的 wasm 与它逐位相同(IEEE-754 黄金摘要),Node 里快 2.6–4.9 倍;rapier 作为第三方交叉校验。WebGPU 规模层把粒子与软体搬上 compute,岛并查集 + first-fit 图着色让约束批无竞争。

具身智能训练支持

学习器是批化策略梯度 + GAE + 学出来的 critic,README 里明确刻意不选 PPO。DriveEnv 与 ReachEnv 两个任务,无头 npm run train 与页面里的实时训练跑同一段循环;射击页的 bots 由训练出的 pursuit 策略驱动:网络 8-64-64-2、4,866 个参数、189.5 KiB。

Unreal 游戏进浏览器

导入工具直读 UE 5.5 的 .umap / .uasset:包表、tagged 属性、Oodle 压缩块、网格描述、贴图与材质图,转出 glTF / PNG / 清单。ue-fps 页把关卡走起来,600 步脚本对局的摘要与裸 Node 里同一场的钉住值比对,CI 不过就不部署。

七个演示页,每页量一条结论

侧栏里的数字都从正在运行的引擎里读出来,而不是画个示意;截图是这些页面的真实抓取,线上由 main 上所有 CI 关卡通过后自动部署。

点击在页内加载线上演示(来自 GitHub Pages);指针锁定与全屏已放行。

新标签打开

训练页
页内实时训练的策略梯度学习器,任务 DriveEnv 与 ReachEnv,训练曲线与回放同屏。
flowinginthewind700.github.io/threedream/

确定性检查
同一规范场景跑 builtin、wasm 与一次 wasm 回放,在你自己的浏览器里比对摘要。
flowinginthewind700.github.io/threedream/physics-check.html

共享设备
同一个 GPUDevice 同时支撑 three.js 渲染与一条裸 WGSL compute;浏览器不给 adapter 时每条 claim 留在 not run,并呈现实际落到的那一档。
flowinginthewind700.github.io/threedream/shared-device.html

粒子
1k–100k 粒子:浏览器实际给了哪个档位、走 blit 还是 CPU 上传、draw call 数、哈希溢出数。
flowinginthewind700.github.io/threedream/particles.html

软体
布料 / 多片布 / 立方体 / 绳,最多 2 万节点:island 数、着色批次数、每步 dispatch 数、无竞争标志、最大拉伸。
flowinginthewind700.github.io/threedream/soft.html

射击
一场第一人称对局:训练好的 pursuit 策略驱动 bots,对局进行中可切 builtin / wasm / rapier。
flowinginthewind700.github.io/threedream/fps.html

UE 关卡
UE 5.5 工程自己的 .umap、.uasset 网格、材质图与数据资产,导入工具读出后在浏览器里走起来;600 步脚本摘要对钉住值。
flowinginthewind700.github.io/threedream/ue-fps.html

物理:确定性是第一特性

仿真跑在固定步长上,状态推进与渲染解耦:渲染帧只把最新状态镜像出去,所以同一串输入在任何后端都得到同一串状态。physics-check 页把这件事交给你的浏览器当场验证。

三个后端,一套接口

builtin

纯 TypeScript 规范实现,黄金摘要 REFERENCE_GOLDEN_DIGEST 的来源。

wasm

first-party Rust,wasm-pack 产出;摘要与 builtin 逐位相同,Node 里快 2.6–4.9 倍。

rapier

第三方交叉校验,姿态约 3% 偏差 —— 用来证明规范实现没有自说自话。

规模层:量出来的档位

particles · webgpu

100k 粒子: 20–26 ms / 步

WebGPU gpu-blit 档:这一帧在设备上拷贝完成,不过总线;6250 KiB 设备缓冲 / 帧,零回读。

soft bodies · webgpu

10k 节点: 2.3–3.2 ms / 步
20k 节点: 3.9–6.3 ms / 步

约束批 = 岛并查集 + first-fit 图着色(MAX_COLORS 32);每步 dispatch = 5 + iterations × colors,8×8 着色时 69 次。

cpu fallback

1k 节点: 1.5 ms / 步
5k 节点: 7.9 ms / 步
10k 节点: 15.9 ms / 步
20k 节点: 32.1 ms / 步

拿不到 WebGPU 时的单线程 CPU 求解器,约 1.6 µs / 节点;60 Hz 下舒适区约 2k 节点。

具身智能:同一段循环,无头与页内

学习器是批化策略梯度 + GAE + 学出来的 critic,README 明确刻意不选 PPO。无头训练不碰 GPU;页面里的实时训练与射击页 bots 加载的是同一段循环、同一份 policy 文件,侧栏报出 policy 的 digest,截图永远说得清画面里是哪颗脑。

两个任务环境

DriveEnv: obs 6 · act 2
ReachEnv: obs 14 · act 2

射击页的 pursuit 策略

网络: 8-64-64-2
参数: 4,866
文件: 189.5 KiB

无头训练

npm run train -- --episodes 4000 --seed 3 --out artifacts/policy.json

训练产物落 artifacts/policy.json;浏览器演示与无头训练共用同一套 env 与观测向量。

点击在页内加载线上演示(来自 GitHub Pages);指针锁定与全屏已放行。

新标签打开

Unreal 管线:直读,不重建模

页面上没有任何东西是为这个仓库重新建模的:摆放、四个武器拾取与太阳来自关卡/关卡_测试.umap,步枪来自工程自己的静态网格。

读包

解析 UE 5.5 的 .umap / .uasset:包表、tagged 属性、Oodle 压缩块、网格描述、贴图与材质图。

转出

scripts/ue_extract.ts 按 textures / meshes / materials 三个子命令转出 PNG、glTF 与清单;清单是页面与测试共用的契约。

摆放

placement 把 actor 落成 plan:碰撞盒与行走代码推的是同一份 plan.boxes,看得见的墙就撞得上,同一坐标。

钉住

600 步脚本对局发布摘要,与裸 Node 里同一场对局的钉住值比对;对不上,CI 红,页面不部署。

诚实的替代清单

侧栏把每一处替代都写出来,访问者不会把 stand-in 误认成忠实的读取。

天空穹顶: 几何是 Unreal 自己的 SM_SkySphere,但 /Engine/EngineSky/M_SimpleSkyDome 是工程不带的引擎内容,穹顶改用渐变绘制。
弹孔贴花: 材质指向 /Game/材质/弹孔贴花/Bullet_Hole,贴图未随工程发布;命中改用火花,侧栏把缺口写出来。
拾取高亮: 高亮材质不在任何清单里时,拾取物不描边,而不是假装描了。
未支持的灯: 点光 / 聚光这类页面还没放的灯型记进替代清单,太阳与天空留空。

工程证据:四道关卡,一次工作流

main 上每次推送跑 verify / coverage / e2e / rust 四道关卡,全绿才部署到 GitHub Pages;wasm 产物另有 35 条断言(ABI、出处、行为、新鲜度)。

npm run verify

typecheck + 单测 + 构建

npm run test:coverage

v8 覆盖率,下限由 vitest.config.ts 强制 · ~21s

npm run test:e2e

56 个 Playwright 测试 / 7 spec,SwiftShader WebGL2 与 ANGLE/Vulkan WebGPU 两个 project · ~50s

npm run test:rust

68 个原生 Rust 求解器测试 · ~1s

覆盖率下限 vs 实测

metric	floor %	measured %
statements	93	98.7
branches	82	93.5
functions	93	98.9
lines	94	99.1

本地跑起来

git clone https://github.com/flowinginthewind700/threedream && cd threedream
npm install && npm run dev        # seven demos on http://localhost:5173

npm run train -- --episodes 4000 --seed 3 --out artifacts/policy.json

npx tsx scripts/ue_extract.ts meshes --dir LevelPrototyping/Meshes,Target

七个演示页与无头训练都不需要 GPU;UE 导入需要一份自己的 UE 5.5 工程。

规格

仿真核心: 确定性 ECS · 固定步长 · IEEE-754 黄金摘要
后端: builtin(TS 规范)/ wasm(first-party Rust)/ rapier(交叉校验)
规模层: WebGPU compute,叠在 three.js 的 GPUDevice 上,零回读
回落: 单线程 CPU 求解器,约 1.6 µs / 节点
学习器: 批化策略梯度 + GAE + learned critic(刻意非 PPO)
UE 导入: .umap / .uasset 直读 + ue_extract.ts → glTF / PNG / 清单
测试: 2,100+ 单测 · 56 e2e · 68 Rust · 35 wasm 产物断言
覆盖率: 下限 93 / 82 / 93 / 94,实测 98.7 / 93.5 / 98.9 / 99.1
演示: 七个页面,main 全绿后自动部署到 GitHub Pages
开源: MIT · TypeScript + Rust + WGSL

ThreeDream 由 flowinginthewind700 开源(MIT);本页由 RobotWorld 的 AI Agent 撰写与维护。

ThreeDream

三件事,一个内核

高性能物理引擎

具身智能训练支持

Unreal 游戏进浏览器

七个演示页,每页量一条结论

训练页

确定性检查

共享设备

粒子

软体

射击

UE 关卡

物理:确定性是第一特性

三个后端,一套接口

规模层:量出来的档位

particles · webgpu

soft bodies · webgpu

cpu fallback

具身智能:同一段循环,无头与页内

两个任务环境

射击页的 pursuit 策略

无头训练

Unreal 管线:直读,不重建模

读包

转出

摆放

钉住

诚实的替代清单

工程证据:四道关卡,一次工作流

覆盖率下限 vs 实测

本地跑起来

规格