1. 先弄清楚 box.fun 在让你做什么，而不是急着拖方块

第一次打开神奇代码岛（box.fun）的时候，大多数人会做同一件事：在场景里疯狂堆方块，堆出一座歪歪扭扭的塔，然后兴高采烈地按下运行，发现角色站在原地动不了，于是关掉标签页。我见过不止一个人是这样退坑的。问题不在手笨，而在于没搞明白这个平台的性质——它不是一个"3D 版画图工具"，而是一个把体素场景搭建和脚本逻辑绑在一起的轻量创作环境。你搭的东西只是皮，让它动起来的是下面那层脚本。

我先把它的定位说清楚：这是一个浏览器里直接打开的 3D 创作平台，不用装任何引擎，不用配环境，打开网址就能建场景、摆角色、写逻辑、发布出去让别人进来玩。它提供了两条写代码的路径——一条是拖积木的图形化编程，一条是直接敲 JavaScript 或 TypeScript。这意味着它的受众很宽：完全没写过代码、但想体验"自己做一个 3D 小游戏"的人可以从积木起步；写过一点前端、想快速验证玩法原型的人可以直接上代码，省掉引擎学习那一大段成本。如果你是做编程教学的，它的价值就更明显了——学生不用在环境配置上浪费两节课。

但"轻量"这两个字是双刃剑。它把门槛压得很低，同时也意味着很多在成熟引擎里理所当然的东西，这里需要你自己想办法绕。比如没有可视化的动画状态机，没有现成的寻路组件，UI 系统相对简陋。我后面几节会重点讲这些绕法，因为这才是真正决定你作品能不能做出来的东西。

1.1 编辑器里那几块面板，各自该在什么时候用

刚进去最容易被忽略的是面板之间的协作关系。场景视图是你看世界的地方，对象列表（层级）是你管理世界里所有实体的地方，属性面板改的是选中对象的静态参数，脚本编辑器负责逻辑。新手常犯的错是：所有东西都靠属性面板调，调不动了才想起来写代码，结果写了一堆硬编码坐标。

我自己的习惯是分三层管理。静态层——地形、建筑、装饰物，这些全部用体素手搓或者用批量填充，摆完就不用管了，属性面板调好位置就锁定。动态层——玩家、敌人、可拾取物、触发器，这些必须进对象列表并且起好名字，因为脚本要靠名字或者标签去找它们。规则层——计分、胜负判定、关卡切换，这些不落在任何具体物体上，单独写在一个总控脚本里。

起名字这件事我要单独说一句，因为我吃过亏。默认名字（比如"方块1""方块2""方块12"）在你做到三十个物体之后会彻底失控，脚本里world.getEntity("方块7")这种写法你三天后回来看根本不知道指的是哪个。我的约定是用前缀分类：env_开头是环境，item_是道具，npc_是角色，trig_是触发器。看起来是小事，但项目一旦超过一百个物体，这个习惯能省掉你一半的调试时间。

1.2 积木、纯代码、混合写法，各自适合什么场景

平台给了三条路，很多人纠结选哪条。我的判断标准很简单，看你卡在哪：

我实际项目里用得最多的是第三种。原因很实际：核心玩法我用脚本写，但调试阶段经常需要临时加个"按一下传送回出生点"的按钮，这种一次性的东西用积木拖两下就完事，不值得为它写代码。等作品要发布了，再把这些临时开关清理掉。

需要提醒的是，混合写法有个隐藏成本——积木和脚本之间的数据流通不太顺畅。积木里算出来的值想给脚本用，通常得借道某个实体属性或者全局变量，绕一圈。所以我的原则是：同一条数据链只走一条路，别一半积木改一半脚本改，否则出问题时你根本不知道是谁覆盖了谁。

1.3 为什么我劝零基础的人先别碰纯代码

这条建议反直觉，但我坚持。很多人觉得自己"以前写过 Python"，就直接开脚本编辑器，结果被事件驱动模型按在地上摩擦。因为 3D 创作跟普通脚本编程的思维差异很大：普通程序是从上往下一行行执行，而这里的代码是注册回调——你写的东西大部分不会立刻执行，而是在某个时刻被引擎叫起来。新手写的第一版代码往往长这样：

// 新手常见写法：以为会一直执行 const player = world.getPlayer(); player.position.x += 1;

跑起来角色纹丝不动。因为这段代码只在初始化时执行了一次，加完 1 就结束了。正确的心智模型是"我要告诉引擎：每一帧都帮我做这件事"。

// 正确写法：注册到每帧更新里 const player = world.getPlayer(); let speed = 5; world.onTick((dt) => { player.position.x += speed * dt; });

注意dt这个参数——它是上一帧到这一帧经过的时间，单位是秒。所有跟"移动""变化速度"相关的计算都必须乘它，否则在配置好一点的机器上角色会像飞一样，在旧电脑上又像在爬。这是我从第一个作品里学到的：我在自己电脑上调好的速度，发给同学之后他那边快了三倍，原因就是我没乘dt，帧率一高就跑飞了。凡是涉及时间累积的逻辑，dt是必须项，没有例外。

2. 从空场景到"能走能跳有反馈"，第一天的完整路径

我给人带过几次入门，摸索出一套一天能出成果的流程。关键不是把所有功能都学一遍，而是尽快让屏幕上的东西对操作有反应——人对"有反馈"的容忍度远高于"没反馈"，只要角色能跟着走，后面再枯燥的调参都愿意做。

2.1 地形：手搓还是批量生成

体素世界的核心代价在方块数量上。一块 100×100 的地面如果老老实实铺满，就是上万个体素，还没加任何建筑。所以第一步就得决定地形怎么来。

手搓适合小面积、需要精确控制的地方，比如一个房间、一座桥、一个跳台。优点是所见即所得，缺点是超过几百个方块之后手指会废。

批量填充是必学功能。选一个区域，指定填充的方块类型和高度范围，一次生成一大片。我通常用它做三件事：铺底层地面（厚度 2-3 层就够，太厚纯属浪费）、做围墙、挖水池。这里有个细节——底层地面不需要铺满整个可见范围，玩家视野外的地方留空，用远景或雾遮住，能省下大量性能预算。

程序生成适合做地形起伏。平台支持用脚本批量放方块，我的做法是用一层简单的噪声函数决定每个格子的高度，而不是用随机数。随机数生成的地形会变成刺猬，走都走不动；噪声出来的地形有缓坡和平台，角色能站得住。伪代码大致是这样：

// 简易起伏地形：用正弦叠加代替纯随机 function heightAt(x, z) { return Math.floor( Math.sin(x * 0.15) * 2 + Math.cos(z * 0.12) * 2 + 4 ); } for (let x = -30; x <= 30; x++) { for (let z = -30; z <= 30; z++) { const h = heightAt(x, z); for (let y = 0; y <= h; y++) { world.setVoxel(x, y, z, y === h ? 'grass' : 'dirt'); } } }

这段代码生成的地形有起伏但不会太陡，表面积大约四千多个方块，在中低端设备上还能接受。千万别一上来就 200×200，我见过有人这么做，然后卡到怀疑人生，以为自己电脑坏了，其实是自己给自己埋了颗雷。

2.2 角色手感：那几个必须亲手调的数字

角色控制是"手感"的全部来源。很多人以为手感是玄学，其实是几个具体参数配合的结果，而且有可以参考的起始值。

调参的顺序很重要，不要五个一起动。我的顺序是：先定重力，再定跳跃。因为跳跃高度基本由这两个决定，公式是h = v² / (2g)。想要跳起 2 个单位高，重力取 25，那初速度就应该是sqrt(2 × 25 × 2) ≈ 10。用手算一下再去调，比瞎拖动效率高十倍——我一开始就是一直拖滑块，拖了半小时也不知道自己在调什么。

跳跃定完之后再调速度，用"走完一个标准平台需要几秒"来验证。最后调空中控制和摩擦。这套顺序做下来，二十分钟能定出手感。

注意：跳跃高度如果超过 3 个单位，需要考虑头顶碰撞。体素世界里很多"卡在方块里"的问题，根源都是跳太高顶进了天花板，而不是碰撞检测出错。

2.3 相机跟随：三种做法和唯一不能踩的坑

相机有第一人称、第三人称跟随、固定俯视三种。做平台跳跃类我推荐第三人称跟随，做解谜或塔防固定视角更舒服。

第三人称跟随最容易踩的坑是每一帧硬设相机位置。直接camera.position = player.position的后果是镜头跟角色完全同步，角色跑动时画面会剧烈晃动，看得人头晕，而且因为帧率波动，镜头会有细微抖动。

正确做法是插值跟随，用每帧把相机位置朝目标位置拉近一点的方式：

const player = world.getPlayer(); const offset = { x: 0, y: 6, z: -8 }; const followSpeed = 5; // 越大跟得越紧 world.onTick((dt) => { const target = { x: player.position.x + offset.x, y: player.position.y + offset.y, z: player.position.z + offset.z }; const cam = world.getCamera(); // 指数插值，与帧率无关 const t = 1 - Math.exp(-followSpeed * dt); cam.position.x += (target.x - cam.position.x) * t; cam.position.y += (target.y - cam.position.y) * t; cam.position.z += (target.z - cam.position.z) * t; cam.lookAt(player.position); });

那个1 - Math.exp(-k * dt)是让插值与帧率解耦的写法。如果直接写成cam.position += (target - cam.position) * 0.1，在 30 帧的机器上跟随会变慢一半，在 144 帧的机器上则会跟得死紧。我第一版就是这么写的，结果在教室的多台设备上表现完全不一样，排查了很久才明白是帧率耦合。

3. 脚本层最烧脑的部分：客户端、服务端和事件边界

这一节是我认为整个平台里最需要花时间理解的地方，也是最多人做出"我这里好好的、别人那里没反应"的原因。如果你的作品只有你一个人玩，很多问题不会暴露；一旦发布出去让别人进来，代码执行位置的差异会立刻炸出来。

3.1 为什么你的代码"在别人屏幕上是静默的"

多人场景下，代码分两个地方跑：一端在本机，一端在场景的主控侧。本地侧的代码处理玩家自己的输入、镜头、界面这些只跟自己有关的东西；主控侧的代码处理大家都需要一致的数据，比如谁得了分、金币被谁拿走了、Boss 还剩多少血。

同一条逻辑写错位置的典型症状是：你自己玩得好好的，别人进来看不到任何变化；或者两个人同时捡同一个金币，双方都显示捡到了，金币却只消失一次。

判断标准很朴素：这条数据需要所有人看到的都一致吗？需要就放主控侧，不需要就放本地侧。

我在做第一个多人小游戏时，把"谁先到终点谁赢"写在了本地侧，结果两个人同时到终点，两边都弹出了胜利界面。这种情况在单机测试里永远发现不了，因为我没办法同时扮演两个人。

3.2 事件和定时器：什么时候用哪个

这平台里的时间推进有两种方式，选错了一种就会出问题。

每帧更新适合做连续的、需要看帧的事情：移动、检测距离、播放动画。定时器适合做离散的、固定间隔的事情：每隔几秒刷一个怪、倒计时读秒。

定时器有两个坑。第一个是精度漂移——setInterval那类写法在帧率不稳时会累积误差，跑十分钟能偏出好几秒。我的解决方式是自己在每帧累加时间：

let acc = 0; const SPAWN_INTERVAL = 2.0; // 秒 world.onTick((dt) => { acc += dt; if (acc >= SPAWN_INTERVAL) { acc -= SPAWN_INTERVAL; // 注意是减，不是清零 spawnMonster(); } });

写成acc = 0会丢掉超出的那部分时间，长时间跑下来同样会漂。用减法保留余量，误差不会累积。

第二个坑是定时器没有随对象销毁而停止。怪物被打死之后，它的刷新定时器还在跑，于是你不存在的怪物每隔两秒继续刷出来。所以任何跟对象绑定的定时逻辑，必须在对象销毁时显式清掉，或者在回调里先判断"我还活着吗"。

3.3 碰撞与触发器：能用引擎判定就别自己算

新手容易有一种执念，觉得碰撞检测自己写更有掌控感。这在体素环境里绝对是自找麻烦——自己算 AABB 要处理边界、穿透、连续碰撞，稍微一快就穿模。平台提供的碰撞体和区域触发器已经足够用，老老实实用现成的。

常用的是两种：碰撞体（挡住移动）和区域触发器（进入时触发事件但不阻挡）。后者的用法比想象中多，可以做检查点、可以做隐藏区域的解密、可以做伤害区。我做的第一个跑酷关卡，所有检查点都是用区域触发器实现的，玩家进入某个区域就记录位置，掉下去就复活在最近的检查点。

这里有个小技巧：触发器的判定区域建议比视觉边界稍微大一点点（比如视觉上是个 1 格的旗子，判定区域做成 2 格宽）。因为玩家跑动速度快的时候，单帧位移可能超过判定区宽度，直接穿过去不触发。这个现象叫"穿透"，跟帧率和速度都有关。我在一个高速移动的关卡里被这个问题坑了整整一个下午——玩家明明从旗子正中间穿过去了，检查点却没记录。

4. 让作品从"能跑"到"像个作品"：完成度那几件事

大部分人的作品死在一个尴尬的阶段：核心玩法能跑了，但看上去就是半成品，自己都不想打开第二次。这不是能力问题，而是漏掉了几件提升完成度的事，这些事的投入产出比极高。

4.1 界面和新手引导：让第一次进来的人知道干什么

我做过一个统计：自己测试时从来不看引导，因为我知道怎么玩；发给朋友之后，十个人有七个在第一屏就不知道要干嘛。这个反馈很贵，但很有价值。

最简单的入门引导不需要多复杂，三件事就够：告诉目标（屏幕上写一句"收集全部八枚金币到达终点"）、告诉操作（"WASD 移动，空格跳跃"）、第一秒钟给个反馈（出生点附近放一枚必吃的金币）。

按钮和计分板这类界面元素，能少则少。我见过把整个屏幕塞满按钮的作品，玩家连场景都看不清。原则是：常驻信息只留跟当前目标相关的（计分、剩余时间、血量），其他全部收进暂停菜单。

字体大小也是个坑。在编辑器里调好觉得正好的字号，发布之后在别人的大屏幕上可能小得看不清。我现在的习惯是所有界面文字按"最坏情况"来定——假设玩家用一台小屏笔记本，字号至少能舒服地读出来。

4.2 存档：键名设计比代码本身更重要

需要持久化的东西通常不多：玩家进度、解锁的关卡、最高分、上次玩到哪。但键名的设计会决定你后面加内容时有多痛苦。

我的做法是用分层命名：save_level_01_clear、save_level_02_clear、save_best_score。好处是后面加关卡不用改逻辑，而且想清空某一类数据时能用前缀批量处理。最糟的写法是data1、data2这种，两周后你完全不记得哪个是哪个。

另一个容易忽略的点：存档要能容错。玩家第一次玩的时候这个键根本不存在，直接读会拿到空值。所有读取都应该有默认值兜底：

function loadProgress(key, fallback) { const v = world.getStorage(key); return (v === undefined || v === null) ? fallback : v; } const cleared = loadProgress('save_level_01_clear', false);

我吃过一次亏：测试时因为自己已经通关，数据一直存在，所以没发现问题；换台机器一测，第一关直接报错卡住。

4.3 发布前的自测清单

这份清单是我每次发布前都会过一遍的，不长但每一条都救过我：

• 换一台设备（或者换个浏览器、换个分辨率）完整玩一遍，重点看界面布局和性能。
• 清掉本地存档，从零开始玩，看第一分钟能不能看懂。
• 让别人进来联机测一次，重点看分数和胜负判定有没有重复触发。
• 故意做出"错误操作"：掉进地图外、站在两个方块交界处、对着墙连点、疯狂按键，看会不会卡死。
• 在场景里放满道具和特效的位置站三十秒，看帧率会不会掉到看不下去。
• 把音量调大听一遍，确认没有突然爆音的音频。

5. 性能：体素世界的帧率是被什么吃掉的

体素这个东西有个特点：好看和流畅是直接冲突的。同样的画面，方块密集的地方永远比空旷的地方卡。理解几个主要的性能消耗点，比盲目删东西有用得多。

5.1 几个最常见的性能杀手

我印象最深的一次是"玩一会儿越来越卡"。查了半天以为是内存泄漏，最后发现是每打一个怪就创建一个飘字特效，特效播完没销毁，留在了场景里。跑了五分钟之后场景里有三百多个不可见的特效对象，每帧都在更新它们的位置。加上"播放完自动销毁"之后，问题当帧解决。

5.2 对象池：这个技巧值得单独说

在需要频繁创建销毁的东西上（子弹、特效、飘字、金币），对象池能带来肉眼可见的提升。思路很简单：开局一次性建好 N 个，用完不销毁，只是藏起来，下次直接从池子里捞一个出来复用。

const pool = []; const POOL_SIZE = 30; // 初始化：全部藏起来 for (let i = 0; i < POOL_SIZE; i++) { const b = world.createEntity('bullet'); b.visible = false; b.data = { alive: false, life: 0 }; pool.push(b); } function fireBullet(pos, dir) { const b = pool.find(e => !e.data.alive); if (!b) return; // 池满了，直接抛弃，不要扩容 b.data.alive = true; b.data.life = 2.0; b.position = pos; b.velocity = dir; b.visible = true; } world.onTick((dt) => { for (const b of pool) { if (!b.data.alive) continue; b.data.life -= dt; b.position.x += b.velocity.x * dt; b.position.y += b.velocity.y * dt; if (b.data.life <= 0) { b.data.alive = false; b.visible = false; } } });

池满了就抛弃而不是扩容，这一点很关键。扩容会让最坏情况下的性能不可预测——玩家连点的时候突然多出两百个对象，那一帧直接卡死。宁可少显示几发子弹，也不要让帧率崩掉。

注意遍历的时候我用的是for (const b of pool)而不是每帧新建数组筛选，那也是一个常见的隐形开销来源。

5.3 低端设备上的妥协策略

你没法保证玩家的设备跟你一样。我现在的默认策略是"按最低配来设计"：特效数量砍一半、阴影能不用就不用、粒子只用二维贴图不用模型、远处的东西不渲染。

有一个特别便宜的优化：加雾或者加远景遮挡。把可视距离压到合理范围，玩家看不到的地方就不需要渲染，视觉上还更有层次感。这比删场景里的东西划算得多。

另一个是分级降级。如果你的作品确实需要一些开销大的效果（比如二十个敌人同屏），可以做一个简单的开关：检测到连续几秒帧率低于阈值，就自动减少特效、降低刷新频率。玩家只会有"稍微朴素一点"的感觉，但不会卡到玩不下去。

6. 我踩过的坑：完整排查链路，你可以照着走

这一节我按"症状—怀疑范围—逐步排除—根因—修复"的方式写，因为真正有用的不是答案，是排查的方法。下次遇到不一样的问题，思路能复用。

6.1 角色穿过地板掉出地图

症状：角色在地形边缘或者高速下落后，直接穿过地面掉进虚空，再也回不来。

排查过程。第一步我先确认是不是地形有洞——把整个地面区域用脚本扫了一遍，检查每个格子是否存在方块，结果发现地形是完整的。第二步怀疑是速度太快导致单帧穿透：把移动速度降到 1，问题消失，说明确实是穿透。第三步看高度的下落速度，在下落很快的时候问题复现率极高。

根因是连续碰撞检测的缺失。角色一帧内位移了 0.8 个单位，而地面只有 1 个单位厚，如果这一帧的起始位置在地面上方、结束位置在地面下方，中间那一瞬间"穿过"了地面，帧末检测时角色已经在地底，检测不到与地面的接触了。

修复方案有三条，我全用上了：加厚地面到底层三层（治标但最有效）、限制最大下落速度（给下落速度设上限，比如 -40）、在地图底部加一个"死亡区域"触发器兜底（万一还是掉出去了，直接复活而不是永远下坠）。第三条是任何有坠落风险的关卡都该配的保险，成本几乎为零。

提示：只要你的关卡存在"掉下去"的可能，就一定在底部放一个兜底区域。第一次测试可能不会发生，但玩家总会以你想不到的方式掉出去。

6.2 复制粘贴一段代码之后，报错说找不到对象

症状：单独测试一段逻辑完全没有问题，把它复制到项目里就报undefined。

排查过程。先打印看看拿到的是什么，发现是undefined，说明查找对象那一步就失败了。检查被查找对象的名字，源文件里叫item_coin，项目里叫item_coin2——因为项目里已经有一个同名物体，粘贴时被自动重命名了。

根因是硬编码名字加自动重名。这个问题在复制物体、复制关卡、多人协作时反复出现。

修复方案是干脆不用名字查找，改用标签。物体打上coin标签，代码里按标签批量拿：

// 脆弱：名字一变就崩 // const c = world.getEntity('item_coin'); // 稳健：按标签拿全部 const coins = world.getEntitiesByTag('coin'); for (const c of coins) { c.data.collected = false; }

按标签还有个额外好处：做"清空所有金币""重开一局"这种批量操作时，一行就搞定，不用一个个写名字。我现在的所有项目里，除了极个别确实唯一的东西（玩家、主控器），其他全用标签。

6.3 编辑器里好好的，发布之后表现完全不同

症状：本地测试一切正常，发布后别人进来，发现计分不对、或者进度不保存、或者角色卡住。

排查过程。先分清是哪一类差异。如果是"只有别人看到问题、我自己没问题"，基本就是前面说的本地侧和主控侧混淆。如果是"换了设备才有问题"，多半是帧率相关——所有没乘dt的地方在别的帧率下都会失准。如果是"刷新之后出问题"，那是存档相关的初始化没做好。

我在一个项目里同时踩了这三种。那个作品发布出去之后收到三种反馈，一开始以为是同一个 bug，越查越乱。后来把它们分开记录，逐个验证，才发现是三件独立的事：移动没乘dt（帧率）、分数在本地算（同步）、首次进入读存档没兜底（初始化）。

修复方案形成了一个习惯，我现在写任何涉及时间的代码，先默念"乘 dt"；写任何涉及共享状态的代码，先问"这个大家要不要一致"；写任何读存档的代码，先写一个兜底默认值。这三个检查加起来不到十秒，能省掉后面几小时。

6.4 一个隐藏很深的问题：定时器泄漏导致联机卡顿

症状：单人玩很流畅，两个人一起玩，玩到四五分钟之后开始明显卡。

排查过程。先怀疑是同步数据太多，砍掉一半同步字段，改善有限。接着怀疑是特效，删掉所有特效，还是卡。于是开始数对象——在每帧打印当前对象列表长度，发现这个数字一直在缓慢上涨，五分钟涨了两百多个。

根因是每次有玩家进入某个区域，就新建一个管理对象并挂一个每帧回调，但玩家离开时没有销毁。两人反复进出十几次，就积累了十几份重复的循环逻辑，每一份都在每帧跑。

修复方案是给管理逻辑加"单例"判断：创建前先检查是否已经存在，存在就直接复用；同时在离开时显式销毁并解绑回调。

let zoneManager = null; function ensureZoneManager() { if (zoneManager && zoneManager.alive) return zoneManager; zoneManager = world.createEntity('zone_manager'); zoneManager.onTick = (dt) => { /* ... */ }; return zoneManager; }

这个坑教会我的事情是：任何"进入时创建"的逻辑，都必须配一个"离开时销毁"。写的时候就要成对写，别指望事后补。

6.5 给排错这件事本身的一点经验

我后来发现，排查效率高低跟工具有关，跟聪明程度关系不大。几个特别值的做法：在关键位置打印状态（对象数量、某个变量的值、当前帧率，比盯着屏幕猜快十倍）；一次只改一个变量（同时改三处，修好了也不知道是哪一处起的作用）；保留能复现的最小场景（把出问题的部分单独拎出来做个小场景，比在完整项目里查快得多）。

还有一条我吃过亏的：遇到问题时先别急着改代码，先想清楚"什么条件下会触发"。我早期有个毛病，一看到异常就开始改，改到后面连原本是好的地方都改坏了，最后连问题是什么都说不清楚。现在我会先写一句"现象是 A，在 B 条件下必然出现，在 C 条件下不出现"，写清楚之后再动手，成功率完全不一样。

最后分享一个小习惯，是我做过的所有项目里性价比最高的一个：每个作品留一个"开发者模式"的开关，按某个组合键打开，显示帧率、对象数、玩家坐标、当前关卡状态。这个开关从开发到发布后排查玩家反馈都能用，写它的成本不到半小时。我在一个已经发布的作品上收到反馈说"某个位置走不过去"的时候，就是靠它让对方报出坐标，一分钟定位到了具体是哪一块地形出了问题——那个位置的方块因为生成逻辑的边界处理，缺了一格。