Superpowers实战指南：浏览器中的TypeScript多人协作游戏开发

想要安装 Superpowers 的人不少，这名字起得确实很有诱惑力：谁不想给自己的项目加持“超能力”？但你在搜索栏敲下这个词之后，大概率会看到一堆对不上号的结果，有讲个人成长心态的，有讲某个浏览器插件的，真正想找的开源游戏开发平台反而被藏在后面。如果你正是冲着“在浏览器里做游戏、还能多人实时协作、用 TypeScript 写逻辑”这个方向来的，那这篇东西就是给你准备的。

Superpowers 不是一个装机即用的“傻瓜引擎”，它更像一套跑在你电脑上的游戏开发服务器加编辑器。你装好之后，打开浏览器就是工作台，创建项目的时候你的朋友可以立刻加进来，几个屏幕同时操作同一个场景。对习惯单打独斗的独立开发者来说，这种工作方式第一次接触时会有点不适应，但上手之后真的会打开新思路。这篇文章我会从安装、启动、创建项目、写第一段逻辑，到多人协作、常见问题的排查顺序完整走一遍，尽量把踩过的坑直接写出来，让你少走弯路。

1. 先搞清楚 Superpowers 到底是什么

很多人栽在安装上，不是因为步骤多，而是因为没弄明白它的运行模式。Superpowers 本质上是一个自托管的 Web 游戏开发环境，它不是像 Unity 或 Godot 那样打开一个庞大的桌面程序，而是由一个本地服务器加几个网页组成。你安装的主体是服务器端，真正干活的是浏览器里的编辑器。这个设计的好处非常明显：编辑器跨平台，Windows、macOS、Linux 通吃，客户端零下载，只要能上网就有团队协作的基础。

项目本身是开源的，游戏逻辑用 TypeScript 编写，底层渲染依赖 WebGL，场景结构上大量借鉴了传统游戏引擎的“实体-组件”思路。你在其中创建的东西叫 Actor，所有可见对象都是一个 Actor，给它挂上不同的组件，比如 2D 精灵、3D 模型、灯光、摄像机、脚本，就组成游戏世界。这个模型比一般“一个场景放满对象”的思路更灵活，因为组件可以组合、复用。

实际体验中，Superpowers 最区别于其他引擎的是实时协作。同一个项目会连接到同一个服务器，你在文件管理器里新建一个脚本，同事那边立刻就能看到；你拖拽了一个模型进场景，对方的场景编辑器里也会同步出现。这种“像 Google Docs 一样写代码做游戏”的体验，在 2018 年那批 Web 游戏引擎里几乎是独一无二的。虽然现在有不少工具也加了云协作，但 Superpowers 把协作做成了核心机制，而不是事后补丁。

它适合谁？我个人的看法是，特别适合三件事：Game Jam 快速出原型、小团队远程协作、教学演示。因为它启动快、上手门槛低、没有资产管线负担，图形素材可以直接拖 PNG 或者 glTF 资源进项目。但如果你追求的是重度 AAA 管线、复杂物理、高性能大型场景，那它不是你的菜。认清边界，才好继续往下走。

2. 安装前需要知道的几件事

想顺利装好，先理解它的几个部件。整个系统分三块：Superpowers 服务器、客户端浏览器界面、项目文件存储。服务器负责保存所有项目数据、处理多人同步消息、提供编辑器静态页面；浏览器只是渲染器和输入终端；项目文件可能存放在你机器的数据目录里，也可能放在服务器端配置的储存路径里。你通过修改服务器配置，决定项目保存在哪里、开哪些端口、允不允许匿名协作。

因此安装前你要准备好 Node.js。Superpowers 当前可用的发行版本，本质上是一个 npm 包。我实测下来，Node 版本老一点反而省心，太新的 Node 有时候会触发底层依赖编译报错。建议优先装 Node.js 的 LTS 版本，不要一上来就追最新版。这个问题我后面会专门展开，很多人就是在这里卡住的。

另一件需要知道的事是端口占用。Superpowers 默认会开一个 HTTP 端口和一个 WebSocket 端口，两个端口通常连在一起。如果你本地有其他开发服务占了端口，启动时会提示 address in use，需要换端口或者关掉冲突服务。装之前用netstat -ano | findstr :4237（Windows）或lsof -i :4237（macOS/Linux）先查一下端口是否空闲，是个好习惯。

还要提醒一点：虽然重点在浏览器，但你别把它完全当“在线云服务”使。自己装的 Superpowers，服务器就是你的本机或局域网机器。如果你想让朋友从外部访问，你得自己处理公网 IP、路由器映射这些事，它本身不提供免费云托管。很多新手以为装完就能有 URL 发给全世界，这是最常见的预期偏差。头几次玩，建议就在同一局域网内测试协作。

3. 一步步装好 Superpowers

下面这套安装流程基于当前主流 npm 包版本，我按实际操作顺序写，每一步尽量说明为什么这么做。

3.1 安装 Node.js 与 npm

去 Node.js 官网下载 LTS 版本，安装过程一路下一步即可。装完后在终端里确认：

node -v npm -v

如果能正常输出版本号，说明基础环境没问题。如果你电脑上已经有多个 Node 版本，推荐用 nvm（Windows 用 nvm-windows）管理，这样后面如果某个版本不兼容 Superpowers，可以快速切换，不用卸载重装。这一步看起来不起眼，但能为你省掉很大麻烦。

3.2 全局安装 Superpowers

打开终端，执行：

npm install -g superpowers

全局安装的目的是为了让superpowers命令直接可用。如果你不想装到全局，也可以npx superpowers运行，但后续访问路径和配置方式会绕一些，新手没必要折腾。安装过程中如果看到大量红色警告，不要慌，很多 npm 警告只是“可选依赖没装上”或“peer dependency 冲突”，只要最终显示包已添加，并且superpowers -v能输出版本，就说明安装成功了。

这里要特别说一个坑：如果你用的是 Node 17 以上版本，npm install 时 npm 会尝试编译某个原生模块，这个模块在老版本上编译正常，新版本可能因为 OpenSSL 版本变化而报错。遇到这类情况，最直接的解决办法不是去找补丁，而是切换到 Node 16 的 LTS 版本再试。这不是我拍脑袋说的，而是我在好几个机器上复现后的结论。

3.3 启动服务器并进入编辑器

安装完成后，在你想作为工作目录的地方运行：

superpowers

默认情况下，它会把服务器跑在http://localhost:4237或者环境变量配置的端口。看到终端打印出访问地址后，用 Chrome 或 Edge 打开。打开后第一次访问，会要求你输入一个昵称，这个昵称就是你在协作系统里的身份标记，别人能看到。然后它会带你去一个项目列表页，此时你的 Superpowers 环境已经跑通了。

如果打开页面后白屏或连接中断，先回头检查终端是否还在运行。终端窗口一旦关闭，服务器就停了，浏览器再开自然连不上。注意：这不是网页服务，是本地进程，注意进程生命周期。

3.4 创建第一个项目

在项目列表页点击创建项目，填一个项目名，再选一个模板。它内置了几套模板，比如空项目、2D 平台跳跃示例、3D 基础场景等。想快速感受编辑器，选 2D 模板；想干干净净从头来，选空项目。创建之后点进去，应该看到默认场景和几个测试对象。

我想特别建议新手把示例模板先跑一下，不是浪费时间，而是你能最快看到“一个完整玩法在 Superpowers 里是怎么组织的”：场景文件、资源、脚本之间的引用关系，比枯燥地读文档直观得多。等你看懂了模板的组织方式，再回到空项目自己搭。

4. 界面与核心概念拆解

第一次进 Superpowers 的编辑界面，你会觉得它不像传统引擎，更像一个融合了 IDE 和编辑器的网页应用。整个界面由几个面板组成：左边是资源面板和 Actor 树，中间是场景视图，右边是属性检查器，底部是控制台和脚本编辑器。这些面板的布局可以拖动，环境比较简朴，没有动画编辑器、没有材质编辑器那种“重工业”模块，一切都靠代码和基础组件组合。

你首先得理解 Actor。一个 Actor 是场景里的逻辑容器，它可以没有可见外观，纯粹用来挂逻辑；也可以挂上 SpriteRenderer、ModelRenderer 这类组件变成可见对象。你在场景视图里点击任何物体，右边属性检查器会列出它的所有组件。想给某个 Actor 叠加行为，就挂一个 Script 组件。

这个过程中最需要适应的是：资源管理器里的 asset 与场景中的实例不是一回事。你把一个 Sprite 资源拖进场景，会自动创建一个挂着 SpriteRenderer 的 Actor，这个 Actor 是资源的一个引用实例，改了 Actor 的位置不会改到资源本身，改了资源的图片则所有引用它的 Actor 会一并变化。这个概念和 Unity 的 Prefab 有一定相似性，但更轻量。

脚本编辑器里，Superpowers 使用 TypeScript，项目会有一个类型定义层，你在脚本里写的代码能获得基本的补全提示。由于编辑器基于 CodeMirror，体验上可能赶不上 VS Code，但核心代码编写、查找替换、文件重命名都有。我第一次用的时候觉得有点简陋，但用多了发现它的轻量反而是优点，打开快，不会动不动崩溃。

场景视图本身支持 2D 和 3D，2D 项目里是正交视图，3D 项目里可以用鼠标右键旋转视角、滚轮缩放。初始摄像机需要你自己挂，如果场景里没有摄像机，Preview 起来会黑屏。这个细节我见过不少人踩，后面也会专门提。

5. 别急着写游戏：先把协作模式跑起来

安装 Superpowers 如果只是为了单机写游戏，那它和别的引擎比优势不会特别明显。它的魅力一定是在多人协作里体现的。所以我的建议是，创建项目之后，先别急着堆玩法，喊一个同事或朋友一起把协作流程跑通。

具体操作很简单：确保对方在同一局域网内，能访问到你的机器 IP。你启动 Superpowers 时终端打印的是localhost地址，对方不能用这个，你要根据自己的局域网 IP 生成访问地址。Windows 下ipconfig查 IPv4，macOS 下ipconfig getifaddr en0，一般在192.168.x.x之类的网段。启动服务器时如果不绑定固定 IP，默认通常监听所有接口，所以对方直接访问http://你的IP:端口就行。

对方打开后输入自己的昵称，就能在项目列表里看到你的项目。如果项目列表里没有，可能是项目的可见性权限没有开。正常情况下，同一个服务器托管的所有项目对所有能访问服务器的人可见。Superpowers 的权限模型比较简朴，它默认信任同一套服务器环境下的所有开发者，真要做好权限隔离，你需要从服务器配置层面做限制，而不是在编辑器里点一个“私有项目”按钮。

两个人进到同一个项目后，就能体验实时同步了：一个人建一个文件夹，另一个人的资源面板马上刷新；一个人拖动物体，另一个人的场景视图里物体会跟着动。这种同步甚至包括脚本代码的编辑：你的同事写了半行代码，你能看到字符逐个出现。听起来很黑科技，实现上其实基于 Operational Transformation 类似的思想，把所有编辑操作变成带时间戳的消息广播给其他客户端。

但协作不是没有代价。如果两个人同时编辑同一个脚本的同一行，Superpowers 会尝试合并，如果合并不了，后提交的一方可能会被拒绝或者覆盖。处理方式不是锁文件，而是“谁最后操作谁生效”。团队协作时最稳妥的做法是：明确拆分工位，比如小明负责场景搭建，小红负责脚本，尽量避免同一个资源同时被两个人改。毕竟它不是后端存储系统，而是实时编辑器，协议再聪明也有边界。

另外，局域网协作的体验依赖网络稳定性。Wi-Fi 波动大时，编辑操作会明显迟滞，甚至短暂断线。断线后通常会自动重连，项目状态一般不会丢，因为所有操作早已同步到服务器。如果你实在需要跨公网协作，可以把 Superpowers 跑在云端虚拟机上，然后用公网 IP 或域名访问，但要注意延迟和带宽消耗，图片资源如果很大，加载会很痛苦。

6. 用 TypeScript 写第一个小玩法

协作只是前提，真正让项目活起来的是脚本。Superpowers 的脚本组件使用 TypeScript，一个脚本文件就是一个行为类。下面这套最小示例基于常见版本的 API，你照抄就能跑。

先创建一个 Actor，给它挂上 Script 组件，新建一个脚本文件，命名为PlayerBehavior.ts。双击脚本文件进入编辑器，输入：

class PlayerBehavior extends Sup.Behavior { speed = 3; awake() { Sup.log("游戏逻辑已启动"); } update() { if (Sup.Input.isKeyDown("LEFT")) { this.actor.moveX(-this.speed * Sup.Time.deltaTime); } if (Sup.Input.isKeyDown("RIGHT")) { this.actor.moveX(this.speed * Sup.Time.deltaTime); } } } Sup.registerBehavior(PlayerBehavior);

写完保存，回到场景，刚才那个 Script 组件上应该能看到一个 Behavior 下拉框，选择 PlayerBehavior，然后点击顶部 Preview 按钮预览。你会看到 Actor 会响应左右方向键移动。

这段代码能跑起来的关键点有两个。第一，你必须在 Script 组件的“行为”属性里选择对应的 Behavior 类，否则脚本虽然存在，但不会执行。很多人写完代码忘了挂，预览时没有任何反应，排查半天发现只是没关联。第二，Sup.Time.deltaTime是帧间隔时间，用来把速度从“每帧速度”换算成“每秒速度”，这样不同帧率下移动速度基本一致。如果没有乘它，画面会在高刷屏上明显偏快。

想给 Actor 加上点击响应也非常直接。比如做一个点击后改变颜色的功能：

class ClickToChangeColor extends Sup.Behavior { awake() { this.actor.spriteRenderer.setColor(new Sup.Color(1, 0, 0)); } update() { if (Sup.Input.wasMouseButtonJustPressed(0)) { let ray = Sup.Input.getMouseRay(); let hit = ray.intersectActor(this.actor); if (hit) this.actor.spriteRenderer.setColor(new Sup.Color(0, 1, 0)); } } } Sup.registerBehavior(ClickToChangeColor);

这套接口在 2D 和 3D 项目里基本通用，三维项目里射线和 Actor 的相交判断也按同一套逻辑走。实际开发里，建议把游戏数值都拆成组件属性，而不是硬编码在代码里，这样你可以在属性检查器里直接调整。比如刚才的speed，如果你在类里定义成普通属性，编辑器里就能暴露出来，设计师不用改代码也能调手感。

Superpowers 还内置消息系统，用于 Actor 之间通信。你可以给一个 Actor 派发消息，所有注册了对应监听器的组件都会收到。这套模式比直白的全局函数调用稍微绕一点，但特别适合做解耦。比如玩家血量变化时，一个脚本只负责this.actor.sendMessage("onHealthChanged", currentHealth)，其他 UI 脚本自行监听并更新。项目复杂后，这种解耦能让协作冲突少得多。

写脚本时还有一点要提醒：浏览器环境的 TypeScript 和 Node 环境的 TypeScript 有一点细微差别，Superpowers 内置的是自己的运行时，你不需要也不能使用 Node 的require或 ES Module 的import去加载游戏资源。它会自动建立资源引用关系，你在编辑器里拖一个 asset 到代码里，通常会生成一个资源引用变量，这个机制是 Superpowers 的特色，别拿传统的 Node 工程思维硬套。

7. 常见问题排查与避坑指南

我在实际安装和使用过程中碰到过不少问题，也见过群里新手反复踩同样的坑。下面把这些整理成一个速查表，先看的能少走几步弯路。

除了表格里的，我更想说几个方法论层面的建议。

第一个建议是：正式开发前先跑通“最小路径”。所谓最小路径，就是只创建一个空场景、一个立方体、一个移动脚本，从预览到重新加载，再到关闭设备重进，全流程都稳定跑过，再往项目里堆内容。因为这个工具的特殊结构，如果中途出现问题，最小路径是最容易定位的。我见过有人一上来就导了几十张图片和一整套地图资源，然后出问题后完全不知道是资源问题、脚本问题还是同步问题，排查成本极高。

第二个建议是：善用项目备份。Superpowers 的项目数据是存在服务器数据目录里的，你可以直接把整个项目文件夹压缩备份。因为插件和内置功能都比较克制，项目目录结构很透明，备份和恢复非常容易。建议每次 Game Jam 结束或大功能完成后手动备份一次，别指望自动快照。

第三个建议是：注意浏览器选择。虽然大多数现代浏览器都能跑，但如果你遇到渲染异常或者编辑面板卡顿，优先试试 Chrome 系浏览器。Superpowers 早期开发时主要针对 Chrome 做兼容，Firefox 或 Safari 在某些 WebGL 特性上偶有瑕疵。操作系统层面，Windows 和 Linux 上我最稳，macOS 也能用，但偶尔会出现输入法焦点问题。

第四个建议是：物理资源别贪大。Web 游戏引擎的优势是加载快，你要是塞一堆 4K 贴图，哪怕本地服务器也会变得迟缓。尽量控制单张贴图尺寸，3D 模型合理减面。很多玩家其实不在乎光影多炫，他们只在乎帧率流畅。Superpowers 的定位是新奇协作体验和快速原型，别拿它和离线大型引擎拼渲染上限。

还有一个隐藏技巧：如果你对界面布局不满意，面板顶部的设置里可以切换主题、调整快捷键，部分版本还支持自定义编辑器脚本。不过这些功能藏得比较深，不是核心路径。需要的时候翻一翻官方文档，不需要就略过。

8. 再说几句个人体会

如果你只是随手试玩，Superpowers 可能不会第一眼就惊艳你：它的界面不算华丽，资源商店也几乎没有，很多地方透着开源工具那股“够用就好”的自觉。但当你真正把协作跑起来，发现另一个人正在自己桌上移动你刚才创建的方块、在同一个文件里补上你写了一半的循环时，你会感受到一种很特别的开发氛围。游戏开发通常被视为各司其职再整合的流水线，而 Superpowers 给出的答案是：把所有人放进同一个画布，同时动手，边写边看。

我后来在几个小项目里尝试用它做原型，最大的收获其实是心态上的：因为协作成本被压得非常低，提想法和验证想法的间隔短了，反而催生了很多“要不试试看”的冲动。坏处也很明显：不适合做大型商业项目，插件生态薄弱，遇到疑难杂症经常只能靠自己读源码。如果你能接受它的定位，它绝对值得你在下一次 Game Jam 或团队脑暴时拿出来当白板用。