superpowers：浏览器中的多人实时协作开源游戏编辑器

打开浏览器，输入本地地址，一个多人在线编辑的 3D 游戏场景就在眼前实时同步——这不是什么商业云平台的演示，而是一个叫 superpowers 的开源项目。我第一次刷到它时，第一反应是"这名字取得真够直白的"，第二反应是"这不就是我一直想要的 Web 游戏编辑器吗"。自己动手装过一遍之后，我才发现它和我们熟悉的 game engine 其实不是一回事，它更像一个"编辑器 + 协作服务器 + 插件系统"的组合体。这篇文章我会从安装开始，带你把它跑起来，再讲清楚里面几个容易踩坑的细节，最后附上我实际遇到过的排查记录。不管你是 Web 开发者、想拉团队一起做原型游戏的人，还是单纯好奇"开源超级能力工具"到底有什么用，这篇应该都能给你点参考。

1. superpowers 到底是个什么东西

1.1 它不是游戏引擎，而是"编辑器 + 服务器"的一套组合

很多人第一次看到 superpowers 的时候，会下意识拿它跟 Unity、Godot 这类引擎比。但装上用下来你会发现，它的定位完全不一样。Unity 是给你一个桌面端 IDE，让你在本机建工程、写 C#、打包发布；superpowers 则是把整个编辑器搬到了浏览器里，由本地的一个 Node.js 服务来托管项目和插件资源，编辑器本身是一个跑在浏览器里的单页应用。

这个设计带来的直接影响有两个。第一，项目文件不在某个隐形的数据库里，而是直接落在你本机的目录结构中，service 端可以同时管理多个项目，每个项目都有独立的逻辑、资源和场景文件。第二，因为编辑器和运行环境都是浏览器，天然就支持多人同时打开同一个项目，大家看到的内容是实时同步的，这一点在原型协作阶段非常占优势。

我实际测试下来，这个架构更适合"快速出原型"和"小团队并行修改"，而不是重资产商业项目。它最大的价值在于：你不需要先安装一大坨开发环境，装好服务端，浏览器打开，马上就能开始拖场景、写脚本。对于想验证玩法、做 Game Jam、带学生入门的人来说，省下来的那一大截环境折腾时间，比什么都值钱。

1.2 核心能力拆解：插件、实时协作、TypeScript 脚本

superpowers 的能力基本可以拆成三块。

第一是插件系统。项目名字里的 superpowers，其实指的是一组"超级能力插件"。主程序只是个空壳，真正让你能写游戏、做场景、做交互的，是从官方仓库拉下来的能力插件。你装好主程序后首次启动，它会自动把这些插件拉下来，之后创建项目时才能看到对应的模板。不同的插件决定你能做什么类型的项目，比如常用的是以 3D 和 2D 场景为主的游戏制作插件，还有偏交互故事向、音乐可视化方向的能力扩展。

第二是多人实时协作。它是通过 WebSocket 和服务端的事件同步来做的，有点像多人文档编辑的逻辑，只不过同步的对象变成了场景里的实体、属性、脚本代码。我们团队内部拉了个三个人小分队试了一下午，一人拖地形，一人调光照，一人写角色控制脚本，改动几乎能做到秒级同步，体验相当流畅。这个机制在代码里对应的是基于分布式数据模型的状态同步，不是简单的画面共享，所以两个人同时操作同一个场景不会互相锁死。

第三是 TypeScript 脚本系统。它没有把脚本绑定在某种私有语言上，而是直接用 TypeScript，底层运行时是浏览器 JavaScript。这意味着你对前端这一套越熟，上手就越快。连组件、属性、事件绑定也都是围绕着熟悉的编程范式来做，没有传统引擎里那种"必须记一堆编辑器专用 API"的割裂感。

1.3 它到底适合谁用

从我的经验来看，最合适的人群有三类。一类是 Web 前端想试试游戏开发的人，因为技术栈亲近，学习成本低；第二类是需要快速做玩法原型的小团队，多人实时协作省掉了很多"你改完我再改"的等待时间；第三类是学校或培训机构做教学演示，浏览器一开就能展示完整项目，不需要让学生各自装环境。如果你要找的是能端出商业级单机大作、拥有一整套特效管线、一键导出到 PS5 或者 Switch 的引擎，那它显然不是你的菜。抱着这种预期来用，大概率会失望。

2. 安装前必做的准备和方案选择

2.1 先把 Node.js 环境搞定

superpowers 的服务端跑在 Node.js 上，所以第一步是装 Node.js 环境。这里我多说一嘴，版本选择能省你后面一堆事。

我在安装前特意查了一下，这个项目本身跟最新版的 Node.js 匹配度一般。实测下来用 Node.js 14 或 16 的 LTS 版本最稳，用太新的版本（比如 20+ 的高大版本）有概率出现依赖编译报错。原因不复杂：老项目的部分原生依赖没有跟进新版本的 ABI 变化，重新编译时可能缺少旧版本工具链。如果你机器上已经装了多个 Node 版本，建议直接用 nvm 这类版本管理工具切到 14 或 16 再继续，别在系统默认版本上硬刚。

注意：如果实操过程中报错信息里出现node-gyp、binding或ERR! stack这类字样，基本就是 Node 版本和原生模块不匹配，不用怀疑别的原因，换 Node 版本重新装大概率就好。

2.2 网络与镜像源准备

因为 superpowers 首次运行要拉取插件，而这个拉取动作走的是网络请求。如果你的网络访问 GitHub 等站点不太稳定，插件下载很容易半路失败，表现是启动时进度条卡住不动，或者提示某些插件缺失。

常见的解决办法是给 npm 配一下国内镜像源。你可以在用户目录下找到 .npmrc 配置，或者直接命令行执行设置 registry 的命令，改成 npmmirror 的地址。这样做之后，npm install 下载依赖的速度会有明显提升。我不在这里赘述具体命令，因为镜像地址可能会随时间调整，建议以当前主流可用的源为准。

还有个小技巧：首轮启动最好在命令行前台执行，虽然 superpowers 本身是一个长期运行的服务，但首轮插件下载过程会在终端打印日志。如果你用后台方式拉起，一旦卡住，排查起来比前台看日志麻烦得多。

2.3 全局安装还是目录安装

这里有个容易困惑的点。superpowers 官方推荐的是全局安装，也就是通过 npm 装到全局 node_modules 里，这样你可以在任意目录下直接输入superpowers命令来启动服务。它的插件缓存也是放在用户主目录下的固定位置，全局安装最方便。

但如果你偏好在某个工作目录下单独维护一套环境，也可以局部安装。区别只是命令入口不一样，局部安装后需要用相对路径去调用命令。我个人建议新手直接全局安装，最简单，而且插件缓存目录是全局共享的，不会出现"这个目录建的项目，换个目录就看不到"的错觉。

3. 安装与启动完整实操

3.1 全局安装命令与等待

环境准备好之后，安装本身只有一条命令：通过 npm 全局安装 superpowers。安装过程里，npm 会把主程序下载下来，连带安装一批依赖。这一步的耗时取决于网络和环境，如果网络状况好，通常几分钟内结束。

我在这一步踩过一个不算坑的坑：命令行终端里长时间没有输出，我以为卡死了，实际上它只是下载比较慢。后来我学会先看一眼终端有没有报错，再确认是不是真的没动静。npm 在某些版本下不回显进度，是正常现象，不用急着 Ctrl+C。

安装完成后，你可以输入带版本号的命令来验证一下是否成功。如果能正确打印出版本信息，说明安装没问题。如果提示找不到命令，多半是全局 bin 目录没加进系统 PATH，这个可以手动加到环境变量里，或者重新安装。

3.2 首次启动时它在做什么

装好之后，输入启动命令，你会看到终端开始输出一些初始化日志，第一次启动的时间会比较长。这很正常，因为第一次运行要干两件大事：创建服务端需要的配置目录，以及下载插件列表和插件本体。

插件下载完成后，服务端会启动一个本地 Web 服务，默认端口是 4237。看到日志里提示你访问类似http://localhost:4237的地址时，服务就是起来了，这时不要在命令行里退出，因为关掉终端等同于关掉服务。

提示：如果你是在服务器上部署，想在后台长期运行，可以考虑使用系统服务管理工具，比如 systemd 服务，或者进程守护工具（如 pm2），而不是直接挂在前台窗口。否则一关终端，服务就没了。

3.3 浏览器里打开，第一步要做什么

打开浏览器访问本地地址，你会先看到一个欢迎页。这里一般会让你输入用户名。因为 superpowers 本身支持多人协作，所以它需要有一个简单的身份标识。用户名随便起，但建议用一眼能认出的名字，因为协作模式下，场景里哪个对象是谁改的，会跟这个用户名关联起来。

登录之后，会进入一个项目管理界面。第一次打开时项目列表是空的，你需要新建项目。新建时要选择项目类型，默认推荐的就是游戏项目模板。模板依赖前面说的插件，如果插件下载完整，这里会出现可选模板。如果列表为空，大概率是插件没拉全，回头检查网络和启动日志。

4. 上手实操：从空项目到第一个可跑场景

4.1 界面布局怎么看

进入项目后，整个编辑器界面和我们熟悉的 IDE 有一定相似，但侧重点不同。左侧是场景层级树和资源管理器，可以在这里创建实体、导入资源；中间是 3D 场景视口，用来拖拽对象、调整位置和视角；右侧是属性面板，选中某个实体后，它的变换参数、组件、脚本绑定都会显示在这里；下方通常还有日志和运行状态区域。

第一次用可能会觉得布局有点密，但别慌，它的操作逻辑基本符合 Web 时代的直觉。比如在 3D 视口里，鼠标左键旋转视角、右键拖拽平移、滚轮缩放，和主流编辑器保持一致。这套交互其实默认帮用户省了很多学习成本。

4.2 创建场景、光源、相机三步走

新建项目之后，系统会默认带一个空场景，但场景里没有任何能看到的物体。我建议按这个顺序来做第一步搭建。

先添加一个地面或者立方体，这样你的场景有了参照物。再检查场景里有没有光源，没光源的话物体显示为全黑，很多人第一次说自己"场景渲染坏了"，其实就是缺光。然后确认相机位置，相机不在场景里看物体，或朝向不对，画面也会是空的。

这里有一个容易忽略的点：superpowers 的 3D 渲染底层是 WebGL，所以如果你的浏览器禁用了硬件加速，或者显卡驱动有问题，视口可能显示不出来内容。我排查过一次"画面全黑"的问题，最后发现是浏览器里关闭了硬件加速，打开之后一切正常。

4.3 写第一段 TypeScript 脚本

场景能看到了，我们来写脚本让它动起来。在资源面板里新建一个脚本组件，文件名随意，superpowers 会给它生成一个基于组件的模板。我拿最经典的"立方体旋转"来演示：

import { Component, Entity } from "superpowers"; export class Rotator extends Component { angle = 0; onUpdate(dt: number) { this.angle += dt * 60; this.entity.position.setX(Math.cos(this.angle * Math.PI / 180)); } }

这段代码做的事情很简单：每一帧根据增量时间 dt 更新角度，再用三角函数控制立方体在水平方向来回移动。注意我这是在演示脚本的基本结构，不是让你直接复制跑，因为组件挂载方式和项目模板有关，不同版本的 API 命名可能有差异。

写完脚本之后，回到场景层级中，选中你的立方体实体，在右侧属性里给它添加这个组件。组件挂上后，点击编辑器里的运行按钮，就能看到立方体动了。这一步是从"空场景"到"程序驱动场景"的门槛，迈过去之后，剩下的就是按需查 API 了。

4.4 多人协作功能怎么触发

协作是 superpowers 的亮点，使用方式也简单：把本地访问地址发给你队友，他们在自己浏览器里打开，输入用户名，就能打开同一个项目。需要保证的是所有人能访问到同一台运行 superpowers 服务的机器，局域网内直接用 IP 访问，远程则需要做网络映射或通过可公网访问的部署。

我在内网试过两个人同时编辑同一个场景，一个调整模型位置，一个改脚本代码，互不影响。注意，它同步的是数据状态，不是锁文件，所以两个人同时改同一个属性的话，还是会出现后写覆盖先写的情况，和文档协作的表现类似，但机制是数据模型的实时合并，整体比文件锁灵活很多。

5. 常见问题与排查技巧实录

我把实际踩过的、以及身边朋友问过的问题整理成一张速查表，遇到同类报错可以照方抓药。

5.1 端口 4237 被占用怎么办

superpowers 默认监听 4237 端口，如果这个端口已经被其他进程占用，服务启动时直接会报错，浏览器也访问不到。可以通过命令行查看端口占用情况，找到占用进程后，要么停掉它，要么给 superpowers 指定一个其他端口。

怎么换端口，取决于启动参数支持情况，不同版本不太一样。我建议先查一下当前版本的帮助说明或配置文档，用对应参数指定一个新端口，比如 4238。重启服务后再访问新地址，通常就正常了。

5.2 Node 版本不匹配的坑

这是最容易被忽略的一类问题。如果 npm install 阶段出现和原生模块相关的错误，先别抱着"说不定下次就好了"的心态重试，直接切 Node 版本 14/16 LTS。我试过用最新 LTS 版本硬装，折腾了半小时没搞定，切回老版本后一次通过。这个项目有一点年头了，新 Node 版本带来的收益在这里并不明显，稳定才是第一位。

5.3 插件缺失导致项目模板列表为空

项目模板列表为空，基本就是插件没有正确下载。你可以优先看服务启动日志里有没有下载失败的记录，有的话把对应插件目录删掉，重新启动服务让它再拉一遍，要确保日志中的下载进度确实跑完，而不是卡在某个百分比。插件拉取属于服务端初始化的一部分，它的状态直接影响之后建项目。

5.4 场景能开但画面不动

运行项目后发现画面没有反应，脚本难道没生效？这时候先检查运行按钮是否真的点中了，superpowers 里场景预览和编辑是两个状态。确认运行后打开浏览器控制台，看有没有报错。我遇到过一次是组件挂到了实体上，但脚本文件本身有语法报错，运行日志被淹没了。修掉脚本里的低级错误，画面立刻活过来。

5.5 远程协作连不上

局域网内能连，放到公网就连不上，这是网络环境问题。你需要检查运行服务的主机防火墙是否放行了对应端口，以及部署方式是否做了端口转发。需要提醒的是，如果你要长期暴露到互联网，要注意访问控制，毕竟服务本身没有内置复杂的权限体系，任何人都可以打开页面、输入用户名就能进入协作，身份机制更多是"标记者"而非"门禁"。

6. 我自己在实操中的一些体会

折腾完 superpowers 这套流程，我最直观的感受是：它把"多人实时协作做游戏"这件事的门槛降到了一个很低的水平。你不用搭 Git 工作流、不用开会分模块、不用反复合并冲突，打开页面大家就能在同一块画布上干活。虽然它在商业级渲染、资源管线和最终打包能力上跟主流引擎差着一大截，但作为原型验证、线上教学和 Game Jam 的基地，它是真的很好用。

最后再分享一个小技巧：如果你打算长期用它做项目，尽量把服务部署在一台相对稳定的机器上，比如一台常开的旧笔记本或小主机，让它 7×24 小时跑着，团队成员随时打开浏览器就能进来改东西。这种感觉，比轮流传工程文件要舒服太多。没用过的人可能会低估"打开即用 + 多人同屏"这两个特性带来的效率提升，可只要你实际经历一次，就会明白为什么它值得被叫做 superpowers 了。