alitrack

DuckDB 当 3D 物理引擎,浏览器里跑通了

一块瑞士杠杆擒纵机构的手表在浏览器里滴答走。15 个齿的擒纵轮、红宝石叉瓦、摆轮,金属件咬合、碰撞、松开。点一下暂停,仪表上跳出最后一拍的判定:某个轮角加叉角的状态,blocked。

它没有物理引擎。没有力矩方程,没有碰撞检测库,没有游戏引擎。决定这只表每一拍能不能走的,是数据库里的一条条 SQL。页面每帧发一条点查,数据库回答堵没堵,页面照着画。

项目叫 watchduck,纯静态页面,GitHub Pages 上直接跑,没有后端,没有构建步骤,源码在 GitHub 开源。这篇文章完整讲一遍它是什么、怎么工作、你能玩什么。

● ● ●

一、四个入口,一个引擎

打开首页是四个入口,背后共享同一套判定引擎。

3D 擒纵机构(escapement3d.html)是主门面。three.js 渲染的立体场景:金属色的擒纵轮、两粒红色叉瓦、摆轮横在上方,走时的时候零件碰撞处会发红光。除了看,还能做三件事,后面细讲。

2D 工程图(index2d.html)是同一个引擎的正交视图。轮廓线、碰撞状态直接标在图纸上,工程制图的观感。3D 和 2D 两个视图永远不打架,因为它们都只是同一张碰撞表的两个投影。

34 件全机芯(index34.html)把规模拉满:完整机芯 34 个零件、107 个拼合件,拆解过程在浏览器里由 DuckDB 现场判定,8 轮拆完,和参考实现的黄金拆解表逐行对得上。

View the SQL 直接展示拆解用的 SQL 谓词原文,数据库执行什么你就看什么,没有中间商。

● ● ●

二、SQL 怎么当物理引擎

思路一句话:建模金属,不建数学。每个零件都是多边形,数据库只被问一个问题:这两个形状碰上了吗?

SELECT ST_Intersects(
  ST_Rotate(tooth, wheel_angle),
  ST_Rotate(stone, fork_angle)
);

齿转到这个角度,叉瓦摆到那个角度,相交就是卡死,不相交就能走。擒纵机构的锁定、释放、再锁定,就是一串布尔判定。

开机先建碰撞图:轮角乘叉角扫一遍 97 乘 49 的网格,约 9500 次相交判定,本机实测 87 毫秒左右(线上复测一次 134 毫秒,随机器负载波动),得到一张 4753 个状态的表,其中 1438 个是卡死态。之后每一帧,页面只发一条点查:当前状态在不在卡死集合里。查询是预编译的,解析开销只付一次。

最有意思的数字是节拍。这只表每拍擒纵轮前进 12 度,正好是 24 度齿距的一半,但代码里没有任何地方写着 12。这个数从零件形状里长出来:齿多宽、叉瓦摆多远、什么时候松开,几何定了节拍就定了。页面有实时读数,跑两百拍实测收敛在 11.92 度,和理论值差不到百分之一。

递归查询还能更进一步:把整个仿真塞进一条递归 CTE,5000 步、200 拍的完整走时历史就是一张查询结果,浏览器里 986 毫秒跑完。这里有个真实的坑:递归种子里 0.0 会被推断成 DECIMAL(2,1),轮角累加到 10.38 度直接溢出,显式转成 DOUBLE 才行。写数值仿真的递归 SQL,种子类型别偷懒。

● ● ●

三、亲手弄坏它

3D 页面的实验卡是最好玩的部分。它只动一个真实几何参数:进瓦沿自身长轴的偏移,单位毫米,滑杆范围负 0.8 到正 0.8。

拖到负 0.6 提交。页面不播放任何动画,DuckDB 现场重建整套物理:重新生成叉瓦几何,按新几何重建碰撞图,重新预编译查询,表从头再走。354 毫秒后碰撞图变了,卡死态从基线 1438 涨到 1920。几秒后,表真的停了:轮子卡在 20.5 度,连续 601 个子步全被 SQL 判为 blocked,页面浮出标签 STALLED BY SQL SOLVER。

这不是录好的故障录像,是几何真的坏了,数据库真的判了卡死。

两个方向都有死法。参数扫描实测(4753 个状态里 blocked 的数量):

进瓦偏移
blocked 状态
−0.40 mm
1801
−0.30 mm
1723
0.00(基线)
1438
+0.10 mm
1324
+0.20 mm
1197
+0.30 mm
1070
+0.40 mm
937

往负拖过 0.55 毫米,碰撞图出现整列死轮相位,求解器卡死,就是上面那一幕。往正拖过 0.45 毫米,锁定丢失,轮子空转到飞起。两种死法都是重建出来的碰撞图的属性。扫描结果不是网页自己说了算:页面引擎和命令行版 DuckDB 各扫一遍,两边逐字一致。

点 Reset,表回到基线重新走时,故障清零,155 毫秒。

● ● ●

一个容易误解的地方要先说清:3D 视图本质是 2D 截面碰撞模型渲染成 3D,用的就是同一张碰撞表。它不是力学求解器。

但这个 2D 简化不是嘴上说说,是被持续检验的。页面里跑着一个独立裁判:一个 Web Worker,里面是 SFCGAL 2.3.0 的 WebAssembly 版,CGAL 精确有理数内核。它对同一套几何做真正的三维体积求交,旋转后的齿棱柱对两个瓦棱柱,逐拍重算。SQL 判定先行,3D 校验慢一帧跟上,仪表上一行状态灯:绿色是两个引擎一致,红色是分歧。

这个裁判上岗第一天就抓到过一条假警报。主循环喂给它的是物理推进后的轮角,配的却是推进前的 SQL 判定,一个子步约 0.72 度的错位,跨过 13.25 度的接触边界就误报分歧。SQL 和 3D 其实都对,错的是喂参。修好之后长跑,判定全部一致,其中一次红色报警是真阳性:3D 判接触,SQL 判卡死,两边对得上。

表每走一拍,数据库判一次,几何库验一次。两个引擎,一拍一查。

● ● ●

五、性能面板把账摊开

诊断面板不藏数。碰撞图构建多少毫秒、每次重建多少毫秒、每帧点查延迟的分位数(滚动 512 样本窗口统计,样本数永远标在旁边,零样本时老实写 not measured)、渲染帧率、启动各阶段分别耗时,全部真实测量,还提供一键复制诊断数据。性能数据挂在页面对象上,外部脚本可以独立核验。

● ● ●

六、诚实的边界

这只表是几何正确、动力学简化的作品,边界都写在 README 里:

摆轮只是画出来,惯性没有仿真,叉瓦走的是预设的 5 赫兹三角波。轮子自由状态是匀速,没有力矩驱动。齿形是凸四边形,不是真实摆线。34 件页面的几何用的是离线快照(868KB,相位已烘焙),因为 WASM 引擎约 256MB 的线性内存装不下 107 个拼合件的现场生成,但每个拆解判定仍是浏览器里的真实查询。浏览器只在 Chromium 上系统测过,Firefox 和 Safari 没有 guarantee。

● ● ●

七、它从哪来

祖先是 sqlartist 的 The Watchmaker 项目,最初用 SQL Server Spatial 做,后来搬到 PostGIS,再被移植到 DuckDB。watchduck 把它推进到浏览器:DuckDB-WASM 加 spatial 扩展,约 40MB,首次加载后缓存,离线也能开。首次加载约 40MB 的下载是实打实的门槛,换来的是零安装、零后端、一条链接全包。

3D 呈现和交互灵感来自 Bartosz Ciechanowski 的 Mechanical Watch,那篇交互式讲解至今仍是这个主题的天花板。

● ● ●

八、这块表证明了什么

对做数据的人,watchduck 是一个不常见的实证:DuckDB 的 spatial 扩展能做几何仿真,递归 CTE 能跑数值迭代,浏览器里的 WASM 引擎扛得住每帧点查。87 毫秒建 9500 次相交,986 毫秒跑完 5000 步仿真,11.92 度的涌现节拍,这些数字比任何架构图都有说服力。

对更广的读者,它演示了一个正在成立的组合:计算归数据库,渲染归 3D 库,两层各干各的。物理判定住在 SQL 里,所以它可以被查询、被重建、被另一个独立几何库逐拍复核。你拖动滑杆弄坏的不是动画,是数据。Reset 救回来的也不是动画,是几何。

想亲手弄坏它,链接在下面。

● ● ●

参考来源

https://alitrack.github.io/watchduck/

https://github.com/alitrack/watchduck

https://sqlartist.github.io/posts/the-watchmaker-building-a-mechanical-watch-in-a-database/

https://ciechanow.ski/mechanical-watch/

https://duckdb.org/2021/10/29/duckdb-wasm.html