《霜刃》是一个只跑在浏览器里的武侠魂游。故事放在安史之乱(755 到 757 年),主角沈既白是个被判"逆脉"的磨剑人,从终南山一路打到渭水便桥,最后在长安大明宫的含元殿前收尾。三章、三个 boss,没有人死,只有"落败";没有血,只有墨、霜与火星。
从第一个会话到现在大约六天。代码是 280 个 TypeScript 文件、89,057 行,运行时依赖只有一个:three.js 0.187。这些代码几乎全是 AI coding agent 写的:9 个主会话、366 个子 agent 的记录、31 个编排脚本。我的角色更像是美术指导、制作人和测试员。
这篇文章讲四件事:美术方向是怎么定下来、又怎么被推翻的;怎么让它在一个浏览器标签页里跑得动;几个我很喜欢的图形技巧;以及怎么让一群 agent 并行写同一个游戏而不互相踩脚。
先把这六天按日子记一下,后面每一节都会回到其中某一天。
11 月 11 日,周三。 下午一点多开了第一个 agent 会话。我给的只有一句话的设定:安史之乱、一个磨剑人、浏览器里能玩的魂游。三个小时之内,接口契约、架构文档、游戏设计文档和那份 681 行的美术规范都写好了。这一天结束时,97 个源文件已经成形。
11 月 13 日到 14 日。 角色有了身体:Tripo 生成的模型、动捕数据、成群的敌人、贴墙攀边的动作。14 日凌晨一点,仓库才有了第一个 git commit。之前两天的东西都在 agent 的工作目录里,这也是为什么 git 历史不能当时间线用。
11 月 15 日。 整天在做场景审计。一轮一轮截图、挑毛病、改 PBR 材质、改天空、补程序化细节。我对前几轮的评价是"很一般,看起来都不明显",于是定了一条规矩:每个改动都必须在跟随镜头里一眼看得出来。
11 月 16 日。 清理和性能。做了一个风格实验室,把几种画风并排渲染出来比较,最后选了写实的那一档。最后一次改动是晚上十点四十六分。
一、美术:写了一份很美的规范,然后推翻了它
第一版:水墨
第一天下午,美术规范就写好了,681 行。一句话的核心是:"磨石即砚,剑即笔,霜即白。别人用墨画,沈既白用白破墨。"
参考的是《王者荣耀》的"墨染江湖"系列皮肤。规范里总结了十二条可迁移的原则,比如"墨属于世界,主角是白的":他是画面里那块会动的留白。整个画面只允许三种强调色:
每一章的雾就是"纸的颜色":终南山是雾青 #A9C2C0,渭水是夜雨 #0F1A24,长安从焦黑 #1A1210 一路烧到鱼肚白,再到黎明的金。
第二版:去掉描线
第一次试玩之后,我的反馈只有一句:"全是黑描线,很脏。"
深度边缘的墨线、衣褶线、积墨、角色轮廓,在所有画质档位上都被设成了 0。规范里最核心的那部分,在游戏里不再存在了。
第三版:风格实验室
最后我让 agent 做了一个可切换的风格实验室,同一个场景可以一键换成五种画风:
real:清理过的 PBR 写实,现在的默认off:更早的、雾更重的调色painted:调色板拉近的反照率、明暗两段的绘画 ramp、分带的 Kuwahara 滤波guofeng:国风重彩,石青、石绿、赭石、朱砂,加纸纹pixel:约 300 像素高,8 级色阶,有序抖动
- mist
- ×0.5
- contrast
- ×1.3
- saturation
- ×1.1
- brush
- off
- paper
- 0
A drawn stand-in, not a game frame: each look applies its preset values from the game's style.ts. Grayscale, so saturation and the guofeng mineral palette don't show.
我最后选了写实。不是因为水墨不好看,而是在一个要盯着敌人起手、算格挡时机的游戏里,清楚比风格更重要。
太阳不许乱跑
还有一个反馈改变了整个光照系统:"跑着跑着就能看到太阳疯狂的移动。"
原来的设计是太阳沿着关卡路线连续移动:从午后到日落到夜晚。听起来很电影,实际玩的时候,你往前跑二十米,影子就转了一个角度。
改成了分段的时辰:午后、黄昏、夜晚三个固定阶段。午后和黄昏共用同一个太阳方向;阶段切换只在"看不见的时刻"发生:加载区域、在灯火处休息、镜头一帧内跳了 8 米以上、boss 登场过场。其他时候用 6 秒左右的匀速交叉淡化。改完之后,直到 boss 过场之前,每一帧的主光仰角都是 38°(改之前是 15° → 32° → 6°)。
Drag along the path. Afternoon and dusk share one sun direction; a stage changes at a hidden moment or over a ~6 s crossfade.
二、地形、天空、天气:能用代码写的都用代码写
虽然游戏最后用了不少外部素材(AI 生成的模型、动捕、Poly Haven 的扫描贴图),但地形、天空、天气、水、植被分布和大部分建筑都是代码生成的。
地形
地形是 512 米见方、513×513 的高度图。生成顺序是:噪声层、按顺序叠加的"印章"(山丘、压平、矩形、路径)、可选的水力侵蚀、派生贴图。噪声用的是带 domain warp 的 fBm:先用两个低频噪声场把采样点"拧弯",再采样。
let sx = x, sz = z;
if (L.warp) {
const wf = f * 0.5;
sx += (fbm2(x*wf + 19.1, z*wf + 7.3, 2, spec.seed + l + 1000) - 0.5) * 2 * L.warp;
sz += (fbm2(x*wf - 11.7, z*wf + 23.9, 2, spec.seed + l + 2000) - 0.5) * 2 * L.warp;
}
v += L.amplitude * (fbm2(sx*f, sz*f, L.octaves, spec.seed + l, 2, 0.5, L.ridged === true) - 0.5) * 2;终南山的种子是 7103,两层噪声:一层低频大起伏(振幅 26 米、warp 30),一层带脊线的细节。物理用的高度场和 LOD 0 的网格是同一套三角剖分,所以"角色的脚和画面永远不会对不上"。
512 m square at 257² (the game uses 513²). Noise layers only; the game then adds its stamps (hills, flattened yards, paths). Zhongnan is seed 7103; Weishui 9203, Chang'an 3301.
侵蚀是一个"做了、测了、关掉了"的故事。粒子水力侵蚀写好了:水滴在加速的地方带走泥沙,在减速的地方放下。试了 14 万到 28 万个水滴,加载多了 0.7 秒,而冲出来的沟壑在游戏距离上被草和树挡得根本看不见。所以终南山关掉了它。
天空
天空是 Nishita 单次散射:Rayleigh(为什么天是蓝的)加 Mie(雾霾和太阳周围的光晕),每条视线 16 步、每步朝太阳 6 步,烘焙进一张 128×64 的半精度查找表。只有太阳动的时候才重新渲染这张表,单次不到 0.1 毫秒。
const vec3 kR = vec3(5.5e-6, 13.0e-6, 22.4e-6); // Rayleigh
float kM = 21e-6 * haze; // Mie
const float hR = 8e3, hM = 1.2e3, g = 0.76;
for (int i = 0; i < N; i++) {
vec3 x = r0 + r * (t + ds * 0.5);
float h = length(x) - rP;
float dR = exp(-h / hR) * ds, dM = exp(-h / hM) * ds; odR += dR; odM += dM;
/* 内层循环:朝太阳累积 lR, lM */
vec3 att = exp(-(kM * (odM + lM) + kR * (odR + lR)));
tR += dR * att; tM += dM * att;
}云是一层弯曲的云层,在 6360 公里半径的星球上空 1.6 公里,所以能一直延伸到地平线。测下来,程序化天空和原来 2k 的 HDRI 全景图成本差不多(4.6 / 7.0 毫秒对 8.7 / 8.8 毫秒),但可以随光照变化。
天气和风
天气是包在相机周围的 GPU 实例化粒子体积:终南山是桃花瓣和竹叶,渭水是两层深度的雨丝加水面涟漪,长安是下沉的灰烬和上升的火星。关键在于:每个粒子的位置是种子和累积漂移的纯函数,所以没有逐粒子的模拟,也永远不会"跳"。
风是一个共享的阵风场:四团阵风按 24 秒的周期横穿地图,叠在更宽的微风上。植被摆动、草地的光泽、花瓣和叶子的飞行都读这个场,所以叶子只在阵风经过的地方飞。
三、在一个浏览器标签页里跑起来
目标是在 M 系列核显或 GTX 1650 这类机器上,1080p、中画质 60 帧。
自适应分辨率
这是整个渲染器里我觉得最值的一块。它用 WebGL2 的 EXT_disjoint_timer_query_webgl2 测量每一帧真实的 GPU 时间,然后在四档内部分辨率之间调整:100%、88%、78%、70%。
if (timer.available) {
if (timer.fresh) a.gpu += (timer.ms - a.gpu) * 0.12; // GPU 毫秒的 EMA
hot = a.gpu > GPU_HOT_MS; // 14.5 ms
const up = a.idx > 0 ? SCALES[a.idx - 1] / SCALES[a.idx] : 1;
cool = a.idx > 0 && a.gpu * up * up < GPU_COOL_MS; // 升一档之后还能在 10.5 ms 以内吗?
}
a.hot = hot ? a.hot + realDt : Math.max(0, a.hot - realDt * 2);
if (a.hot > 1.2 && a.idx < SCALES.length - 1) { a.idx++; a.settle = 1.5; applySize(); }
else if (a.cool > 5) { a.idx--; a.settle = 1.5; applySize(); }几个细节:
- 降档:平滑后的 GPU 时间超过 14.5 毫秒并持续 1.2 秒。
- 升档:不看当前时间,而是看预测的时间:像素数和分辨率的平方成正比,所以预测值是 。预测值低于 10.5 毫秒并持续 5 秒才升。
- 两个阈值之间 4 毫秒的间隙防止来回震荡;每次切换后有 1.5 秒的冷却。
- Safari 和 Firefox 默认没有计时器查询,就退回到看帧间隔:超过 1/52 秒算"热"。如果降了一档帧时间没有改善 7% 以上,说明瓶颈在 CPU 或显示器刷新率,不在像素,就升回去并锁住。
Illustrative load, not a measurement. The stepping rules and thresholds are the game's. At 88% the middle stretch would cost about 9.3 ms, but stepping back to 100% predicts 12 ms, so it stays.
一次清理,长安街从 16.3 毫秒到 2.8 毫秒
最大的一次性能收益来自一轮"清理加性能"。几处改动:god rays 从 20 步降到 12 步,SSAO 半分辨率、4 个采样,远处阴影级联从每 3 帧更新改成每 10 帧,HDR 目标上开 MSAA。
要老实说明的是:这些数字是在 Apple silicon 上的无头 Chrome 里测的,同时还有别的 agent 在用同一块 GPU 渲染。长安的"之前"还包含了另一个 agent 当时正在砍掉的细节和 POM 成本。
几个排查故事
500 个 draw call。 有一个场景 draw call 冲到 500 以上、620 万三角形。一开始以为是另一个 agent 加的道具,实际原因是地面植被:64 米的格子里,那些已经被顶点着色器在 34 米外缩成零的草叶,还在占 120 到 150 个 draw call。修复是每帧把超出淡出距离 4 米的格子整个隐藏。
合并几何体毁了剔除。 为了减少 draw call,把长安坊墙里的房子合并进了街道扇区。结果整个扇区的视锥剔除失效了,背对着街也多出 100 个 draw call。最后给坊和宫殿单独分扇区,额外成本只有 4.5 个 draw call、1.5 万个三角形。
三角形预算超了两三倍。 预算写的是 150 万,实测终南山平均 319 万。但 GPU 时间只有 6.75 毫秒,因为大部分三角形是实例化的植被。预算是提示,profiler 才是事实。
素材压缩
4096 PNG → 2048 WebP, quantized attributes
characters, props, weapons (after includes LOD and crowd variants)
FBX → 22 bones, 30 fps, int16
Each bar is scaled to its own before size.
四、几个我很喜欢的图形技巧
雾在后处理里,剑光在雾之后
渲染分两遍。第一遍是所有写深度的东西:光照、阴影、4× MSAA,然后在后处理里加雾。第二遍是不写深度的透明物:粒子、剑光拖尾、天气、光晕卡片,在雾之后才画。这样雾永远不会把一道剑光、一片花瓣或一颗火星洗掉。
解析的高度雾
雾不是光线步进,而是沿视线对指数高度雾做闭式积分:
、 是视线两端相对雾底的高度, 是高度衰减, 是距离。再用两层滚动的噪声调制密度,就有了在近景和中景里流动的雾团。雾的颜色也随视角变化:朝着太阳的方向偏暖,背离太阳的一侧偏冷、暗一级。
剑光会"干",不会"淡"
拖尾的片元着色器里有大约 60 根"笔毛":横向高频、纵向低频的噪声。随着时间推移,阈值上升,笔画不是变透明,而是干掉,直到只剩几缕丝。缝隙就是"飞白"。
// 横跨笔画约六十根笔毛,沿笔画方向变化缓慢。缝隙就是飞白。
float n = fbm3(vec2(v*60.0 + vSeed*31.0, u*2.0 + vSeed*7.0))*0.75
+ vnoise(vec2(v*21.0 + vSeed*5.0, u*8.0))*0.25;
float streak = clamp((n - 0.22) / 0.56, 0.0, 1.0);
// 越到笔画末端、越老,越干;笔画干成丝,而不是淡出。
float th = mix(vS.x, vS.y, u) + (1.0 - life) * 1.15 + vBrk * 1.2;这是水墨规范里活下来的为数不多的东西之一。
水面上的灯影
水面只用一个 draw call,没有任何渲染目标。8 盏暖色灯在水面上各拉出一条长长的倒影:先算灯在水平面上的镜像点,再沿视线方向画一个各向异性的高斯,宽度随波浪斜率左右抹开。
主角衣服上的点阵
有一段时间,主角的白袍在自己阴影的边缘出现一片规则的点阵。agent 用 A/B 测试一个个排除:反照率贴图、法线贴图、receiveShadow、SSAO、normalBias,都不是。只有把阴影半径设成 0 才消失。原因是 three r187 的 PCF 用交错梯度噪声逐像素旋转 5 个采样点,在阴影边缘恰好形成了规则图案。修复是在模块加载时给 shader chunk 打一个补丁,把旋转角固定成 。
五、让一群 agent 一起写游戏
这部分是我觉得最有意思的。
先写契约,再并行
第一个会话开始大约三小时后,契约、架构文档、GDD 和美术规范就都写好了。然后十个模块并行开工:core、engine、world/env、world/level、character、combat、ai、fx+audio、ui、game。
规则写在 ARCHITECTURE.md 的第一节,核心几条:
- 所有权按路径划分。 每个 agent 只能改自己的路径。
src/core/**归 lead,是"终版"。契约错了也不许改:"在你自己的模块里绕过去,在交接说明里报告。" - 模块之间不许互相 import。 只能 import
three和src/core/*,跨模块访问只能通过类型化的Game上下文(contracts.ts,2,013 行)或者事件总线。 - 不加 npm 依赖,不联网。
- 每个模块一个公开的
index.ts,第一版就是满足契约的空壳。工厂函数分两步(先createX(game),再init()),所以启动顺序永远安全。 - 项目必须随时能通过
npm run typecheck和npm run build。 这就是合并门槛。
设计阶段本身也是一个编排:三个独立的故事方案并行写,然后战斗规范,然后一个评审打分合成,然后架构师搭脚手架、写契约、列出不超过 9 个模块的工作清单,最后是只读的对抗性审阅。架构师的提示词以这句话结尾:"npm run typecheck 和 npm run build 在空壳上都要通过。修到通过为止。"
- owns
- src/engine/**
- imports
- three src/core/*never another module
- entry
- createRenderer · createCameraRig · createInput
Merge gate: npm run typecheck and npm run build pass at all times.
window.__game:给 agent 用的遥控器
agent 没法像人一样玩游戏,所以游戏给它们暴露了一个自动化 API:
snapshot():帧号、状态、区域、fps、draw call、三角形、玩家、敌人、bossteleport()、loadArea()、quickStart():瞬移到任何地标spawnBoss()、spawnEnemy()、killAll()、god()press(action, frames)、move(x, y):注入输入stepFrames(n):同步跑 n 个模拟步audit():找浮空、陷地、穿插的物体
这套 API 能用,是因为模拟本身就是确定性的:固定 60 Hz、不用 Math.random 和 Date.now。同样的输入加同样的步数,就是同样的快照。每个区域都必须有命名的地标,所以 agent 可以瞬移到任何地方去验证。
ARCHITECTURE.md 里有一句我很喜欢的话:"每个模块的任务说明都以验收检查结尾;'能编译'不算一条。"
截图审计循环
画面质量靠一个截图审计的循环推进。每一轮:
- 固定的机位,比如三个区域里的 12 个点,1280×720 跟随镜头。
- agent 先截"之前"的图,改代码,再截"之后"的图,加上 fps、draw call、三角形的统计。
- 列出"什么最伤画面",排好序。第一轮有 10 条,比如"多面体感的低模石头"、"瀑布是一张平的白卡片"。
- 一张改动表:文件、函数、改了什么。
- 一行性能对比,以及"还没解决的"。
审计文档有 795 行,跑了二十多轮:植被、光照、远景、建筑立面、PBR、天空、装饰、清理……有一轮"穿模扫描"沿着每个区域的路径每 15 米瞬移一次,四个朝向各截一张,一共 184 帧,全部在拼图上看一遍。


人的反馈也在这个循环里。我的每一句原话都变成了一个范围明确的任务,外加一个备份目录:"很一般,看起来都不明显","光影太夸张","全是黑描线,很脏","跑着跑着就能看到太阳疯狂的移动"。
并行带来的坑
- GPU 是共享的,性能数字会撒谎。 有一次在长安的塔下测到 21 到 23 fps,换一块没人用的 GPU 就复现不了:是别的 agent 的浏览器在抢 GPU。
- 前后对比会被并行工作污染。 "长安的'之前'也包含了 kit agent 同时在砍的细节和 POM 成本。"
- 并行编辑会打断彼此。 一个 agent 的文件改动触发 Vite 热更新,把另一个 agent 正在跑的长测试打断。
- 静默的框架 bug。 instanced 材质用
MeshStandardMaterial.copy()复制,而copy()会重置defines,结果大约 90 个实例化原型悄悄丢了着色器钩子。 - git 记录不了这些。 主分支只有 14 个 commit,第一个 commit 就有 1,038 个文件。大部分工作发生在未提交的工作区和 59 个按任务命名的备份目录里。这是我下次一定会改的地方。
六、我学到的
- 契约先行是并行的前提。 十个 agent 能同时工作,是因为它们互相看不见,只看得见契约。
- 给 agent 一个能操作游戏的接口,比给它一份说明书有用得多。 确定性的模拟加
stepFrames,让"验证"变成了一件 agent 自己能做的事。 - 截图是最诚实的测试。 编译通过、类型正确,都不说明画面好看。
- 美术方向要经得起试玩。 写得再漂亮的规范,玩家一句"很脏"就能推翻。
- 预算是提示,profiler 才是事实。