CUBELET 开发复盘:用原生 JavaScript 和 WebGL 搭一个体素世界
记录版本:CUBELET 1.0.0 · 2026-11-11
本文依据当前项目源码和实际修复过程整理。配图均从当前游戏运行画面截取;专门搭建的验证场景会在图注中说明。
把 Minecraft 的纹理画到立方体上,只是这个项目的起点。真正困难的是让地图、光照、流体、碰撞、背包和存档对同一个世界保持一致:水面看起来连着,碰撞体也得连着;箱子界面打开了,世界里的箱盖也应该打开;方块能在 Y=255 放下,重新读档后也必须还在。
CUBELET 使用原生 JavaScript、WebGL 和 Canvas,游戏运行时没有第三方库依赖。它参考 Minecraft 1.0 的资源和规则,实现主世界中的采集、制造、建造,以及生存和创造两种模式。世界高度按项目要求扩展为 256 格,有效方块坐标为 Y=0~255。地形生成器、存储格式和部分调度逻辑由项目自行实现,不能把它当成原版的逐格、逐帧复制。
图 1:当前主菜单。标题贴图已改成 CUBELET,版本文本为 1.0.0;背景、字体和按钮继续沿用项目选取的原版资源。
阅读导航
- 一、架构与运行环境
- 二、随机地图:让种子决定世界
- 三、区块与 WebGL 渲染
- 四、光照:洞口为什么曾经漆黑
- 五、水:形状、透明度和推动力
- 六、物理、模型和动画
- 七、像素 UI 与背包事务
- 八、生存规则与数值边界
- 九、存档:成功提示必须等到提交
- 十、黑屏、缓存与验证方法
- 十一、问题索引与后续边界
源码与材料
一、架构与运行环境
按状态的归属拆分代码
项目没有引入引擎,而是把世界数据、表现和交互分开。入口按依赖顺序加载普通脚本,各模块通过全局接口协作。
| 层次 | 主要文件 | 负责的事情 |
|---|---|---|
| 入口和资源 | index.html、assets.js、art.js | 页面、图片路径、资源就绪状态 |
| 内容定义 | content.js | 方块、物品、材质、工具、配方和碰撞形状 |
| 世界 | world.js | 地形、区块、方块修改、光照、液体和作物 |
| 表现 | render.js、ui.js | WebGL 世界、模型、物品图标、Canvas 界面 |
| 交互和模拟 | main.js、actions.js、mobs.js | 主循环、输入、采掘、战斗、实体和移动 |
| 物品状态 | inventory.js | 槽位、堆叠、合成、转移和装备 |
| 持久化 | store.js | IndexedDB、多世界列表、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 和流体调度也没有声明与原版逐步一致。后续扩展时,应继续保留这种边界说明,让新增功能、复刻差异和已经验证的行为各自有可查依据。
文中最常用的检查思路是沿数据链路追踪一个动作:输入改变了什么状态,哪些缓存因此失效,画面读取了哪个版本,保存又在什么时刻真正完成。 从这个角度看,许多表面上的“贴图问题”或“渲染黑屏”,最终都能定位到具体的坐标、依赖、时序或状态归属。