CUBELET 开发复盘:用原生 JavaScript 和 WebGL 搭一个体素世界

记录版本:CUBELET 1.0.0 · 2026-11-11
本文依据当前项目源码和实际修复过程整理。配图均从当前游戏运行画面截取;专门搭建的验证场景会在图注中说明。

把 Minecraft 的纹理画到立方体上,只是这个项目的起点。真正困难的是让地图、光照、流体、碰撞、背包和存档对同一个世界保持一致:水面看起来连着,碰撞体也得连着;箱子界面打开了,世界里的箱盖也应该打开;方块能在 Y=255 放下,重新读档后也必须还在。

CUBELET 使用原生 JavaScript、WebGL 和 Canvas,游戏运行时没有第三方库依赖。它参考 Minecraft 1.0 的资源和规则,实现主世界中的采集、制造、建造,以及生存和创造两种模式。世界高度按项目要求扩展为 256 格,有效方块坐标为 Y=0~255。地形生成器、存储格式和部分调度逻辑由项目自行实现,不能把它当成原版的逐格、逐帧复制。

CUBELET 1.0.0 主菜单:石块风格标题、黄色倾斜标语、全景背景和像素按钮

图 1:当前主菜单。标题贴图已改成 CUBELET,版本文本为 1.0.0;背景、字体和按钮继续沿用项目选取的原版资源。

阅读导航

源码与材料

一、架构与运行环境

按状态的归属拆分代码

项目没有引入引擎,而是把世界数据、表现和交互分开。入口按依赖顺序加载普通脚本,各模块通过全局接口协作。

层次主要文件负责的事情
入口和资源index.html、assets.js、art.js页面、图片路径、资源就绪状态
内容定义content.js方块、物品、材质、工具、配方和碰撞形状
世界world.js地形、区块、方块修改、光照、液体和作物
表现render.js、ui.jsWebGL 世界、模型、物品图标、Canvas 界面
交互和模拟main.js、actions.js、mobs.js主循环、输入、采掘、战斗、实体和移动
物品状态inventory.js槽位、堆叠、合成、转移和装备
持久化store.jsIndexedDB、多世界列表、JSON 导入导出

例如,放置火把首先修改世界数据,再使附近光照和网格失效,最后由渲染器重建需要更新的部分。界面不直接往 GPU 里“补一个火把”,渲染器也不负责扣除背包物品。这样才能在读档、卸载区块和切换界面后维持一致的状态。

从 Base64 到图片文件:需求变化碰到了浏览器边界

早期为了支持双击 index.html,图片被嵌入普通脚本。这样能绕过一部分本地文件读取问题,但生成文件很大,修改一张图也要重新打包,资源不方便浏览和替换。

后来按需求改为直接加载 PNG 文件。此时出现了一个容易误判的现象:浏览器能显示某张本地图片,并不意味着它允许把该图片用于 getImageData() 或 WebGL 的 texImage2D()。在实际 Chrome 检查中,file:// 加载出现了画布污染和跨源纹理上传错误。

项目曾采用选择资源文件夹、转换 Blob URL 的方案。随后需求明确改为:直接打开时提示使用本地静态服务器,不再要求选择或上传文件夹。 当前入口遵循这个决定。游戏仍不需要后端服务或联网接口,但 PNG 资源要通过同源的本地 HTTP 地址读取。“没有游戏服务器”和“页面不需要 HTTP 托管”是两件事,说明文档必须把它们写清楚。

art.js 保存图片路径清单和文本元数据,不嵌入图片字节。图片仍从 assets/art 读取。后文的 Node 测试和浏览器检查工具属于开发环境,玩家运行游戏不需要安装这些工具。

二、随机地图:让种子决定世界

由固定种子生成的森林、起伏地形和跨区块树冠

图 2:种子 checks 的自然生成地形,从高于出生点的位置观察。这里没有为了截图手工摆放地形或树木。

1. 坐标哈希替代全局随机序列

如果生成每棵树、每条矿脉时都调用同一个 Math.random() 序列,那么先去东边还是先去西边,就会改变随机数的消耗顺序。同一个种子也无法保证得到同一个世界。

本项目先将种子字符串转成整数,再结合世界坐标进行哈希。哈希内部使用 Math.imul、异或和无符号位运算,将结果映射到 [0,1)。静态生成结果可以表达为:

1方块、树木或矿脉特征 = f(种子, 世界坐标, 特征类型)

这样,访问顺序不参与地图的定义。不同特征使用不同偏移值,避免山体、树木和矿石重复使用完全相同的随机图案。运行中的生长、掉落等动态事件仍可使用随机数,不必与静态地图生成混为一谈。

2. 多尺度值噪声叠加地形

这里使用的是值噪声:先对网格角点取哈希值,再使用平滑函数 t²(3−2t) 和双线性插值求连续结果。它不是 Perlin 或 Simplex 噪声。

当前高度公式可以简写为:

1const land = noise(seed + 1, x, z, 110);
2const hill = noise(seed + 3, x, z, 62);
3const height = Math.floor(
4  45 + land * 35
5  + Math.max(0, hill - 0.48) * 58
6  + noise(seed + 2, x, z, 24) * 7
7  + noise(seed, x, z, 7) * 2
8);

110 格尺度控制大范围陆地起伏,62 格尺度增加山体,24 格和 7 格尺度补充局部变化。温度和湿度使用独立噪声场,组合出沙漠、雪地、森林和平原;海平面设置为 63。

这类组合的优点是参数直观、计算量可控。它也有明确边界:当前 generator=1 是自有生成器,同一个种子在 CUBELET 和原版 Minecraft 1.0 中不会生成相同地图。

3. 洞穴和矿脉用不同的方法

洞穴不对每个方块重复执行整套噪声。生成一个区块时,先构造 5×5×34 的粗采样场,再在每 4 格之间插值,用阈值决定是否挖空。粗采样减少计算,三维插值避免每列独立挖洞形成明显条纹。

矿脉则采用带种子的短距离随机游走,根据矿种设置不同高度上限和规模。铁矿主要分布在 64 以下,金矿在 32 以下,钻石和红石在 16 以下;这些上限描述当前生成器的配置,不代表已经照搬原版全部矿脉算法。

4. 树冠跨区块,生成责任仍要明确

只在区块内部寻找树木,会在边界切掉邻区块树冠。如果生成邻区块时再随意补树,又容易覆盖玩家修改,或者让结果依赖加载先后。

当前做法是在区块外侧也检查一圈候选树位。候选位置来自全局网格和种子,每个区块独立重建落在自身范围内的树叶;树干的归属也保持确定。矿脉同样明确归属于自己的区块。

这里的教训是:随机地图的正确性包括加载顺序独立性。 回归测试会用相同种子、不同探索顺序比较地形、矿石和跨区块树冠,而不仅仅检查“生成出来了”。

三、区块与 WebGL 渲染

1. 256 格高度不等于一口气分配所有方块

每个区块为 16×16×256,垂直划分为 16 个 16³ 区段。区段按需分配,其中方块 ID 和元数据分别保存在 Uint8Array(4096) 中:

1// 区段内坐标:x、z 为 0~15,y 取低四位。
2const localIndex = ((y & 15) << 8) | (z << 4) | x;
3
4// 整个区块内的索引,用于修改记录等。
5const columnIndex = (y << 8) | (z << 4) | x;

一个已分配区段的这两份数组合计 8 KiB,不含对象、网格和光照。天空光缓存仍会为已加载区块分配完整的 65536 字节数组,因此不能把整个世界系统描述成“全部稀疏存储”。

负坐标也要按同一规则处理:整数世界坐标通过 x >> 4 找区块,通过 x & 15 找区块内部位置。不能用向零截断代替向下取整,否则原点西侧和北侧会出现接缝。

高度扩展要检查整条链路:放置、查询、碰撞、光照、网格、存档都得接受 Y=255;Y=256 的非法放置则必须在扣除物品之前被拒绝。Y=127/128 的跨区段测试能找出仍把高度写死为 128 的路径。

2. 只上传可见表面,并限制每帧重建工作

相邻实心方块的内部面不生成。每个区段维护自己的网格版本,方块修改后只让相关网格失效。顶点包含位置、UV、颜色,以及天空光和方块光两个分量;一个四边形拆成两个三角形后上传 WebGL 顶点缓冲。

渲染器先筛选距离和视野内的区段,再优先处理附近网格。每帧重建使用约 8 毫秒的预算,并允许至少完成一个网格,避免预算耗尽后永久没有进展。该预算约束的是重建工作,不能据此推出整帧一定达到某个帧率。

当前没有实现贪心网格合并,也没有用 Worker 并行生成网格。性能说明应写已做的剔除、缓存和预算,不能套用其他体素引擎的优化清单。

3. 修改影响的不一定只有六个相邻方块

普通立方体的暴露面主要依赖六邻域。但水面高度取决于四角周边的多个方块,区块边界还可能读取对角邻居。只重建当前区块,会留下旧的水面高度和接缝。

修复后,边界修改会让相关相邻区段、对角区块以及必要的下方网格失效;区块加载、卸载也要更新依赖它的邻居。网格本身是缓存,失效规则属于正确性逻辑,不能只当成性能细节。

4. 透明物体不能只按区块排序

不透明部分先画并写深度。透明部分保留深度测试,关闭深度写入,再使用 SRC_ALPHA / ONE_MINUS_SRC_ALPHA 混合。

早期透明面只按区段远近排序,但两个区段中的水面可能交错,区段中心更远不代表其中每个面都更远。当前会收集可见透明面,按面中心在相机前向轴上的深度排序,再合并到可复用缓冲区提交。

这是常见透明场景的实用修复,仍有 CPU 排序和上传成本,也不是严格的无序透明渲染。截图看起来正确,不等于所有相交透明面都已获得数学上完美的顺序。

四、光照:洞口为什么曾经漆黑

封闭石室内,火把照亮地板、墙壁及拐角附近的表面

图 3:人工搭建的带隔墙石室,用于观察火把光衰减和遮挡。它不是自然洞穴,也不是旧版与修复版的对比图。

天空光与发光方块分开计算

光照等级为 0~15。天空光先从每列顶部向下传播:无遮挡空气保留直射光,树叶削弱一级,水和冰削弱三级,不透明方块阻断。随后进行六方向队列传播,让光线可以沿洞口向侧面和下方扩散。

旧实现用有限距离的横向扫描近似间接天空光。它能处理部分直线洞口,却无法可靠绕过拐角或进入向下的入口,于是出现“洞穴外侧也是黑的”。扩大扫描距离只能缓解某些场景,不能解决传播路径本身缺失的问题。

修复采用广度优先式传播:某个单元收到更强的光,就把它放进队列,继续向六邻域传递;间接传播至少衰减一级。直接垂直天空光单独处理,避免把无遮挡空气也逐格衰减。

火把、熔岩和燃烧熔炉使用独立的方块光,亮度分别包括 14、15、13。移除光源后,还要清理旧贡献并使受影响网格重建,否则“火把已经挖走,墙上仍然亮着”。昼夜主要改变天空光的显示贡献,不能连火把一起变暗。

目前发光方块变更后的传播仍包含按光源重算的做法,尚未实现完整优化的增光、退光双队列。它是当前可维护的选择,也是一处后续大规模场景的优化空间。

五、水:形状、透明度和推动力

水源池、逐级降低的流水,以及从高处落下的水柱

图 4:人工搭建的水面验证场景,分别展示静水、不同等级的流水和叠层落水。截图时暂停模拟以保留各状态,不表示这些方块在持续流动后仍会保持当前分布。

1. 方块水位要转换成共享角点

最初按每格的元数据绘制一张平顶水面,高度近似写成 0.88 − level × 0.1。相邻两格水位不同,就出现台阶、裂缝;上下叠水时,下层也可能被错误画成没有填满。

修复参考原版液面角点计算:每个角读取周围四格;上方仍有水时提高到满高度;源水和落水增加权重;非实心空气也参与边缘高度计算。相邻方块计算同一个角时读取同一组数据,连接处才会一致。

水的顶面和侧面使用各自的图集位置,侧面 UV 随高度裁切,内部水面剔除。玩家是否进入水下,也要比较相机与实际液面,而不能只看相机是否进入该格的整数范围。

2. 透明度不能重复相乘

水纹理自身已有 Alpha,早期又额外乘了一层透明系数,造成水过于透明。修复应先确认纹理输入,再处理混合状态和排序。仅仅“把透明度调高一点”可能掩盖贴图与渲染管线之间的重复计算。

3. 无限水源是邻域规则

项目补上了两格水源补水:水平方向四邻域中至少有两个真正的源水,且下方为实心支撑或源水时,当前水格可更新为源水。斜对角不计数,普通流水和落水不充当源水,熔岩不使用该规则。

这里要区分方块 ID 和流体状态:流动水的 ID 不等于一定没有源头,判断还要看水位元数据。只统计“周围有几格水”会把流水误算成源水。

4. 水流方向与受力共享一套计算

水流根据相邻水位梯度生成方向;边缘下方有水时向出口流动,贴墙落水则加入向下分量。玩家、MOB、掉落物和经验球共用水流查询,减少几套实现互相偏离。

受力条件要考虑实体身体是否接触实际液面。掉落物即便已经落在水底,也不能因为“着地后停止移动”的分支而失去水流推动。当前把水流推动与抛出时的速度区分处理;静止源水没有凭空的横向推力,创造飞行也有对应豁免。

六、物理、模型和动画

1. 固定 tick 与画面插值

玩家运动按 20 Hz 固定步长推进,画面按浏览器刷新节奏绘制。主循环使用累积时间执行模拟,再用剩余时间比例插值显示位置。这样不会让高刷新率显示器上的玩家跑得更快。

参考旧版参数时还要保留积分顺序。例如竖直运动不能随意把“先移动,再更新重力和阻尼”改成另一种顺序;即使常数相同,跳跃高度和落地时刻仍会变。

2. 楼梯能画出来,不等于走得上去

玩家使用以脚底为基准的 AABB,移动按轴处理,并限制每次较大位移的子步长。原先只有阻挡判断,楼梯作为半高碰撞体仍会挡住水平移动。

自动跨步需要额外的候选路径:检测实际障碍顶面是否在允许的约 0.6 格以内,检查抬高后的头顶净空,再验证水平扫掠和落脚支撑。不能简单地“前面碰撞就把 Y 加半格”,否则玩家会爬墙、穿屋顶或在边缘悬空。

碰撞修复中还遇到浮点边界:实体贴着墙时,极小误差会被当成真实穿入,竖直修正可能把实体送到墙顶。重叠判断采用小量容差,并配合贴墙回归;容差也不能大到吞掉真正的薄碰撞。

3. 可见模型、选择范围和碰撞形状分别定义

仙人掌的问题就是把几个概念绑在一起:若把整张贴图随较小碰撞体一起缩进去,边缘的刺看起来就会朝内。当前将碰撞形状和可见形状分开,面沿法向内缩,同时保留纹理在切向上的正确覆盖,并补上接触伤害。

耕地也说明这种区别:可见顶面高度与碰撞规则并非必须完全相同。模型系统需要允许这种历史规则,而不是强制所有方块共用一个盒子。

4. 动物贴图错误往往来自局部坐标

项目曾出现羊脸被遮住、猪缺少鼻部、牛腹部跑到背面的问题。检查时要沿着“部件几何 → 局部旋转 → UV 展开 → 贴图”逐项定位。只翻转整张图片,可能修好一个面,却破坏其他部件。

当前八种已实现生物的模型进行了对应检查;旧存档中的尺寸也需要迁移。增大实体碰撞体后,如果它正贴着墙,读档时要寻找附近可站立位置,避免把旧实体直接塞进方块。

静止时腿仍走动则是另一类问题:早期直接按时间增加行走相位,即使速度为零也继续摆腿。现在相位由实际水平位移推动,并平滑衰减摆幅;顶墙原地踏步也会停止。鸡在空中的翅膀动作单独处理,不能全部绑到步行动画上。

5. 第一、第三人称要统一方向约定

手臂攻击反向、头部俯仰反向,来自相机、身体和部件局部坐标的符号关系不一致。修复时用明确的方向测试:向上看时头部朝向应与相机一致,攻击时手持物的主运动应指向前方,再核对前视、后视两种第三人称。

挥动采用固定 tick 的进度,而不是每次点击临时叠加旋转。箱子也拆成箱体、箱盖和锁扣,围绕铰链更新开合角;仅打开容器 UI 不会自动产生模型动画。

6. 箭矢看不见,不一定是飞得太快

真实发射后的飞行箭矢,侧视可见箭杆、羽翼和端部截面

图 5:在临时测试世界中蓄力发射后,将镜头移到侧面观察飞行中的箭。画面使用 tick 间位置插值,未降低箭矢的物理速度。

这个问题包含三个因素:几何长轴与 UV 的长边没对齐,从正后方观察时缺少必要截面,以及纹理在第一次发射时才开始加载。

修复时重建羽翼和尾部截面,调整缩放和局部偏移,并预加载纹理。显示位置在上次与本次物理坐标之间插值,碰撞仍使用真实模拟位置。箭速较快并不是应该偷偷降低速度的理由,先排查模型投影、资源就绪和显示插值更有效。

7. 寻路也要服从实体碰撞

当前 MOB 使用有搜索半径和节点上限的三维 A*,检查站立空间、向上跨步、向下落差和整个身体的通行范围,并禁止斜向穿过墙角。重算路径有时间间隔,避免每帧全量搜索。

不同生物的攻击分支分别处理,例如骷髅发射箭、苦力怕接近后引爆、蜘蛛的攀爬与扑击。它们共享碰撞基础,但不等于复制了原版全部 AI 调度与随机行为。

七、像素 UI 与背包事务

创造模式单页滚动物品栏,方块使用立体图标,普通物品使用平面像素图

图 6:当前创造物品栏。箱子、楼梯等使用模型缩略图;滚动条与物品网格共享界面坐标。

1. 清晰图标需要足够的中间分辨率

界面使用 Canvas 绘制原版图集与字体,按整数 UI 倍率布局,并考虑 devicePixelRatio 扩大实际画布分辨率。图片绘制关闭平滑插值。

背包图标曾比原版模糊,原因不只是滤波方式:如果先画进一个很小的离屏画布,再放大,即便关闭平滑也只能得到放大的低分辨率结果。现在图标按最终像素密度生成、缓存,缩放变化时清理旧缓存。

方块图标也不能一律裁一张正面贴图。普通物品可以使用平面精灵;箱子、楼梯、台阶等应由相应几何生成缩略图。投影中心和模型包围范围要一致,否则某些方块就显得歪、大或偏离格子。

2. 控件贴图、坐标和原生文本各有陷阱

滚动条偏斜需要统一轨道、滑块和鼠标命中区域的坐标系,而不是只移动可见贴图。设置滑块曾误用普通按钮所在的图集行,改为凹槽底图加独立滑块两端。

文本输入保留原生输入框处理输入、选区与焦点,显示则由像素字体绘制。选中文本时,浏览器原生选区曾把另一套字体露出来,造成字体突然变化。修复同时处理原生文字、选区和光标的透明样式,再由 Canvas 绘制对应状态。

这里的经验是:DOM 与 Canvas 混用时,视觉状态和交互状态必须对应;隐藏普通文字并不意味着浏览器的选区、光标也自动隐藏。

3. ESC 与鼠标锁定受浏览器控制

ESC 是浏览器退出鼠标锁定的保留交互。背包关闭与锁定恢复要考虑按下、松开和 pointerlockchange 的顺序,过早请求可能与浏览器本次退出操作冲突。

项目最终采用了用户明确选择的规则:游戏内 ESC 打开暂停菜单并解锁;暂停菜单只通过点击 Back to game 返回并请求锁定,ESC 不返回。背包等界面另处理关闭后的恢复时序。浏览器也不允许网页随意把系统光标移动到屏幕中心,因此该要求被取消,没有用假光标伪装成功。

F1、F3、F5 则在需要时拦截默认行为,分别对应禁用帮助、显示调试信息和切换人称。键盘逻辑必须在目标浏览器中验证,单独调用界面函数不能覆盖浏览器保留按键的行为。

4. 槽位操作应按事务设计

背包交互不仅是拖拽图标,还要同时维护数量、元数据、耐久和目的槽位规则。Shift 转移先计算可合并堆叠与剩余空位,护甲槽检查类型,拆分和逐个放置不能越过上限。

合成结果尤其容易出错:只有完整产物能放下时才消费输入,不能扣完材料后才发现光标只能容纳一半产物。有序配方支持裁去空边、平移和镜像;无序配方按多重集合匹配,不能用普通集合丢掉重复原料的数量。

这些规则适合做小范围行为测试,因为可以准确断言“输入减少多少、输出增加多少、失败时哪些状态保持原样”。

八、生存规则与数值边界

“记得原版大概是这样”在复刻旧版本时很危险。现代版本的规则会混进记忆,桶、食物、战斗和作物生长尤其容易受到影响。

项目将硬度、工具等级、耐久、食物、配方和燃料时间集中定义,再为采掘、伤害、熔炼和生长编写行为测试。常数正确只是第一步,整数舍入、执行顺序和状态分支同样会改变玩法结果。

类别曾出现的偏差修复后采用的规则
采掘错误工具仍获得速度加成区分能否采收;错误工具走硬度 ×100 的路径,正确采收再结合工具速度
环境惩罚水下或悬空速度计算不完整分别应用相应的五倍减速
耐久各工具挖掘、近战统一扣耐久按工具种类和动作分别处理,保留创造豁免
护甲每次至少扣一点血25 分制计算并携带伤害余数,小伤害可能被完全吸收
伤害时序溺水复用普通免伤计时空气耗尽后按对应 tick 间隔处理;摔落按 ceil(距离−3)
熔炼按新版本记忆保留空熔岩桶目标版本的熔炉会消耗桶,不返回空桶
作物固定几秒进行一次简单概率生长考虑光照、湿润耕地、周围耕地和行列布局,再处理随机 tick
掉落未成熟小麦保证给种子根据生长阶段进行对应概率判定

256 格高度还带来一个隐蔽问题:若把相同次数的随机选择直接摊到更大的体积,每块作物平均被选中的频率就会降低。当前保留每个方块约 81.92 秒被选中一次的平均频率,再按作物规则决定是否生长,而不是把世界变高同时悄悄降低农业效率。

验证时要分别检查参数配置、状态转移和可见结果。例如,燃料时间正确不代表输入槽位限制也正确,截图中出现成熟小麦也不代表它的生长概率正确。数值测试、行为测试和实机观察需要互相补充。

九、存档:成功提示必须等到提交

1. 保存种子与修改,而不是重复保存全部自然地形

自然地形由种子和生成器版本重建,玩家修改保存为区块差量。每个修改位置使用区块内索引,方块和元数据打包为:

1const packed = (blockId << 4) | metadata;

这里的方块 ID 为 0 也必须保存:它表示玩家把原有方块挖成空气。不能因为值为零就当成“没有修改”。箱子物品、熔炉进度等附加状态另存,玩家、时间、液体与农业状态也进入快照。

存档包含生成器版本,是因为同一个种子在不同算法下会生成不同地形。未来修改生成器时,需要版本分支或迁移策略,否则旧建筑旁边的未修改区域可能突然变样。JSON 存档为项目自定义格式,不兼容原版 NBT/region 文件。

2. IndexedDB 的请求成功不等于事务提交

世界正文和列表摘要写入同一个事务,只有 transaction.oncomplete 后才返回持久化成功。若只等单次 put() 的 onsuccess,后面的事务仍可能因配额等原因回滚,界面却已经告诉玩家保存完成。

保存调用先复制状态快照,再进入串行保存队列,避免异步写入过程中世界对象继续变化。游戏约每 20 秒自动保存;保存并退出同样要等写入结果,不能先回标题页再假设会成功。

浏览器存储不可用或写入失败时,当前状态可以暂存在内存供导出,但这不具备刷新后的持久性。返回值必须反映失败,并提示导出 JSON,而不是把内存缓存包装成成功存档。导入时还会检查格式、坐标、槽位和数量,防止非法数据进入模拟循环。

十、黑屏、缓存与验证方法

一次真实报错暴露了脚本版本问题

新建世界后黑屏或卡住,控制台报告:

1main.js:247 Uncaught TypeError:
2w.tickFarms is not a function or its return value is not iterable

磁盘中的 world.js 已经有 tickFarms(),但浏览器加载的旧脚本没有。新版 main.js 调用了旧版世界对象不存在的方法,主循环中断,看上去像渲染故障。

当前入口在每次加载页面时生成统一版本参数,并明确保持脚本执行顺序:

1const gameLoadVersion = Date.now().toString(36);
2for (const name of ['art', 'assets', 'content', 'inventory', 'world',
3                    'render', 'mobs', 'actions', 'store', 'ui', 'main']) {
4  const script = document.createElement('script');
5  script.async = false;
6  script.src = 'game/' + name + '.js?v=' + gameLoadVersion;
7  document.body.appendChild(script);
8}

这个修复适合当前频繁修改的本地项目,但每次新时间戳都会绕过脚本缓存。正式发布更适合用构建版本或内容哈希:内容没变就复用缓存,发布时让整组依赖对应同一版本。

测试要覆盖真实循环,不能只画一帧

早期浏览器检查暂停模拟后调用一次渲染,能发现纹理和 WebGL 错误,却漏掉了真实更新循环中的缺失方法。后来增加持续运行、移动和缓存回归:先缓存一个缺少该 API 的旧世界脚本,再重新加载页面,检查新脚本是否替换旧接口、循环是否继续推进。

当前验证分成几层:

检查方式适合发现的问题不能单独证明的事情
参数与配方测试硬度、配方、耐久、燃料和食物数值所有视觉与时序一致
Node 行为测试高度边界、确定性、事务、碰撞、光照和模型计算浏览器原生输入行为
临时 Chrome 检查资源加载、持续主循环、读档、真实发射和 WebGL 状态Chrome、Edge、Firefox 全部人工验收
实机截图图标、透明面、光照、模型的可见表现截图前后所有状态都正确

可复查命令如下,Chrome 路径按本机安装位置调整:

1node --test tests/*.test.cjs
2node tools/browser-check.cjs "C:/Program Files/Google/Chrome/Application/chrome.exe" --active --stale-cache
3node tools/browser-check.cjs "C:/Program Files/Google/Chrome/Application/chrome.exe" --blog-shots

本文整理时,回归测试共 66 项通过;博客截图运行也完成,WebGL 错误码为 0。截图工具启动临时本地 HTTP 服务和独立 Chrome 配置,结束后关闭并清理,不读写玩家日常浏览器中的世界。

截图使用自动化 Chrome 的软件 WebGL 环境,因此本文不提供代表真实显卡性能的帧率结论。修复前的截图没有完整留存,本文也没有把重建的错误画面冒充历史记录。

十一、问题索引与后续边界

把实际修复与代码中需要防范的风险放在一起,可以按根因而不是按出现日期分类。下表将两者明确区分,避免把设计约束写成已经发生过的故障:

类别性质与具体问题修复或防范方法
随机状态依赖设计约束:避免探索顺序改变树木或矿脉静态生成使用坐标哈希,明确跨区块归属
邻域依赖遗漏已修复:水面接缝、边界旧网格把对角和跨高度依赖纳入失效范围
算法近似不成立已修复:洞口或转弯处过暗用六向传播表达实际路径
渲染管线不完整已修复:水层混合错误、透明度异常分离不透明/透明阶段,检查排序与纹理 Alpha
几何和 UV 不匹配已修复:牛腹翻面、仙人掌刺向内、箭矢消失分别核对局部坐标、模型部件、面朝向和贴图展开
物理与表现耦合已修复:楼梯挡路、静止仍摆腿、箱盖不动独立碰撞形状,动画读取真实状态或位移
像素与逻辑坐标混用已修复:图标模糊、方块偏大、滚动条偏斜统一布局坐标,按最终像素密度生成缩略图
浏览器原生行为已调整:ESC 解锁、F1 帮助、选区字体变化尊重指针锁定与用户手势,显式处理控件状态
旧版本记忆混入已修复:熔炉桶、伤害、采掘规则偏差明确目标版本的规则,分别测试参数、舍入和状态分支
保存完成点设计约束:避免把单次写入或内存缓存当成持久化成功等待事务提交,失败时提供导出
依赖版本不一致已修复:旧世界脚本与新主循环混载按一致版本和依赖顺序加载脚本
验证范围不足已补充:单帧绘制检查漏掉运行后黑屏同时验证模拟循环、资源、缓存和持久化

项目仍聚焦主世界中的现有玩法。下界、末地通关、完整红石与交通系统、多人联机不在当前范围内;现有地形、AI 和流体调度也没有声明与原版逐步一致。后续扩展时,应继续保留这种边界说明,让新增功能、复刻差异和已经验证的行为各自有可查依据。

文中最常用的检查思路是沿数据链路追踪一个动作:输入改变了什么状态,哪些缓存因此失效,画面读取了哪个版本,保存又在什么时刻真正完成。 从这个角度看,许多表面上的“贴图问题”或“渲染黑屏”,最终都能定位到具体的坐标、依赖、时序或状态归属。

评论