Superpowers安装全指南：从下载到跑通实时协作游戏编辑器

最近总有人在社区里问“想安装 superpowers，怎么弄”。我猜你搜到的应该也是那款开源的实时协作游戏创作工具 Superpowers，而不是什么超级英雄插件。这套工具的安装确实不像普通软件那样双击下一步就完事，官方文档写得又比较零散，所以我把自己的安装过程和踩坑记录整理成这篇博文。文章适合三类人：想自己动手试试的独立开发者、准备拉小队做游戏 jam 的人，以及单纯想看看多人实时游戏编辑器到底长啥样的围观群众。不管你是第一次听说还是已经折腾过一轮，我尽量把从下载到跑通 demo 的全过程讲清楚。

1. 为什么一个开源游戏创作工具值得单独写一篇安装文

1.1 实时协作：同一个游戏项目，几个鼠标一起点

先说 Superpowers 最打动我的点：它不是传统单机游戏编辑器，而是把“实时协作”刻在骨子里的工具。传统做游戏的方式，通常是一个人改完场景保存，另一个人再同步过来，两个人同时操作同一个文件很容易互相覆盖。Superpowers 的做法更像多人同时编辑一份在线文档，你加一个模型、我调一下材质、他写一段脚本，大家在同一项目里同时操作，彼此能看到对方的光标和改动，几乎零延迟。

我参加过一次线上 game jam，四个人分处不同城市，用 Superpowers 协作，八小时内从零做出一个可以玩的小游戏。那种“我这边加了个机关，你那边立刻看到并接着往下做”的体验，比用网盘传压缩包高效太多了。这种能力在远程协作越来越普遍的今天，显得特别实用。类似的协作机制其实很多工具想做，但能像 Superpowers 这样把实时编辑和游戏引擎直接结合的开源项目并不多见。

1.2 TypeScript 和 WebGL：前端开发者的主场

Superpowers 的整个编辑器跑在浏览器里，底子就是 Web 技术栈。游戏逻辑用 TypeScript 写，渲染走 WebGL，导出的游戏可以直接嵌入网页。对于前端开发者来说，这份熟悉感是巨大的优势——不用再去学一门陌生的语言，场景里的每个实体、组件、行为，本质都是对象和属性，跟操作 DOM 的思路很像。

我刚上手时甚至有种错觉：这不是游戏引擎，而是一个长了 3D 视口的开发工具。你可以像写小工具一样写游戏逻辑，也可以把它当原型设计工具用。因为开源，代码全在 GitHub 上，想改引擎内部行为也有得参考。对于想学习游戏引擎架构的朋友，它本身就是一份不错的 WebGL 游戏开发学习素材。

1.3 安装问题产生的源头：新环境与旧代码的摩擦

既然它这么好，为什么安装还需要专门写一篇？因为 Superpowers 的核心代码诞生得比较早，后来维护节奏放缓，而我们的操作系统、浏览器、Node.js 环境一直在更新。新环境碰上旧代码，就会出现各种“意料之外但符合逻辑”的问题。比如下载链接藏得深、某些浏览器版本下的界面错位、端口被占用后启动器不打任何日志直接失败。

这些坑不是绝症，基本都能解决，但如果没有经验，很容易在第一步就被劝退。我写这篇的核心目的，就是把那些默认情况下能让我们“绕半圈”的障碍提前标出来，让后面的人少走点弯路。

2. 安装前的三个判断：别急着动手

2.1 桌面客户端还是自建服务端

第一次接触 Superpowers 的人容易被安装方式搞晕，因为官方同时提供好几种运行模式，最常用的就是“桌面客户端”和“服务端模式”。我建议在下载之前先想清楚自己的场景，不然装了一半发现不是自己要的方式，还得重来。

我个人经验是：想快速体验编辑器，先用桌面客户端；确定要长期做项目、多人协作频繁，再迁移到服务端模式。桌面客户端本身也内置了本地服务，启动后同样可以用浏览器访问，所以并不需要一开始就纠结架构问题。

2.2 系统与浏览器要求

Superpowers 对系统本身的依赖不算苛刻，主流的 Windows、macOS、Linux 都有对应的安装包或可运行脚本。关键在于浏览器，它会把编辑器界面跑在现代浏览器里，所以一个支持 WebGL 的浏览器是必需的。Chrome、Firefox、Edge 的较新版本我都试过，表现都比较稳定。

如果你的电脑太老，核显或显卡驱动不支持 WebGL，打开项目后可能会出现黑屏或卡死。这种情况先更新显卡驱动，再在浏览器设置里开启硬件加速。另外，如果公司电脑限制了安装软件或改了 hosts 文件，也可能导致界面资源加载不出来，这时候可能需要申请管理员权限或者换个人机器试。

2.3 端口与权限：最容易翻车的环节

安装完启动后，Superpowers 会在本机开一个端口，默认一般是 8080（不同版本可能不同）。很多“启动失败”其实不是程序坏了，而是端口被其他软件占用了。我见过排查出是某个网盘客户端占用了 8080 端口的情况，改个端口就好。

在 Windows 上可以这样查端口占用：

netstat -ano | findstr :8080

macOS 或 Linux 上这样查：

lsof -i :8080

查到进程 ID 后，可以在任务管理器或kill命令结束它。如果你懒得换端口，也可以直接在启动时选择其他端口。另外，如果是第一次启动服务端模式，系统防火墙可能会弹窗询问是否允许网络访问，这时候要选择“允许”，否则本地能开但别人连不上。

3. 下载安装的完整步骤（路线一：桌面客户端）

3.1 去官网下载，别被第三方站带偏

Superpowers 的官网信息比较简洁，下载按钮就在首页，一般会提供 Windows、macOS、Linux 几个平台的包。我当时搜索时遇到不少第三方下载站，页面做得像是官方，实际下载下来是广告安装包，非常坑。所以第一步要认准官方渠道，从 GitHub Releases 页面下载也是安全的，项目的仓库名就是 superpowers/superpowers。

下载的时候注意系统是 32 位还是 64 位，现在大多数机器都能跑 64 位包。文件通常是个压缩包或安装包，几十到几百兆不等，体积不是判断是否完整的标准，但下载后最好校验一下哈希值，如果官网提供了的话。没有校验也没关系，直接双击能跑起来基本就没事。

3.2 从解压到首次启动

如果拿到的是压缩包，先解压到一个靠谱的位置。我强烈建议解压路径不要带中文和空格，某些旧版依赖解析相对路径时遇到中文目录会抽风，这是老项目的通病。比如我一开始解压到“D:\游戏工具\Superpowers”，启动后界面资源加载不完整，改到“D:\Tools\Superpowers”就正常了。

Windows 下解压后运行目录里的可执行文件，界面会先尝试打开浏览器，浏览器地址通常是http://localhost:端口号。如果浏览器没有自动弹出，就手动打开，输入提示的那个地址。macOS 下如果下载的是 dmg 镜像，直接拖动安装到“应用程序”；如果是未签名的应用，第一次打开需要右键点击图标，选择“打开”，跳过系统的校验提醒。Linux 下可能需要给可执行文件加执行权限：

chmod +x Superpowers

然后运行它。首次启动通常会要求设置一个数据目录，也就是存放项目文件的地方。建议放在独立分区，或者至少不要放在系统盘的系统目录里，因为单个项目积累的资源可能不少。

3.3 首次启动：创建工作区与界面初识

启动成功后看到的界面像一个小型 IDE：左侧是一棵场景树，中间是 3D 视口，底部是资源面板，右侧是属性检视器。首次使用需要创建一个工作区，相当于一个项目集。创建工作区就是指定文件夹和名称，之后所有项目都放在这个工作区下面。

我第一次看到这界面有点懵，因为它不像普通游戏引擎那样有完整的菜单引导。但它的逻辑其实很清晰：资源面板管“有什么”，场景树管“在哪里”，属性面板管“怎么样”。只要理解这三个面板，后面创建实体、挂组件就顺畅了。想把界面显示成中文？目前没有官方中文包，不建议乱装汉化，因为版本一升级容易出问题。

4. 另一种常见安装路径：用 npm 启动服务端

4.1 服务端模式解决什么问题

桌面客户端虽然方便，但如果你的目标是多人协作、集中管理项目，服务端模式可能是更顺手的方案。你自己不一定要有桌面客户端，团队所有人只需要浏览器，打开一个统一地址就能进入编辑器。这种模式适合固定团队：场景、脚本、资源都在服务器上统一存储，不会出现某个成员的本地文件丢失导致项目缺胳膊少腿的情况。

也可以把服务端跑在你自己的台式机或树莓派上，出差时用笔记本打开浏览器继续做。相当于给自己搭了一个私人游戏开发服务器。缺点是需要维护一个 Node.js 环境，对不熟悉命令行的朋友稍微有点门槛，不过相信我，这门槛真的很低。

4.2 准备 Node.js 环境与安装命令

先安装 Node.js，建议选 LTS 版本。Node.js 自带 npm 包管理器，安装完成后在终端里验证：

node -v npm -v

虽然 Superpowers 的技术栈偏老，但现代 Node.js 基本都能兼容。装好之后，用 npm 全局安装：

npm install -g superpowers

这条命令会把 superpowers 的命令行工具装到全局。运行：

superpowers

第一次运行会提示设置端口和其他配置，按默认来就行。启动后同样会输出一个本地访问地址，复制到浏览器就能打开编辑器。如果你在 Windows PowerShell 里遇到“无法加载脚本”之类的安全限制，可以先执行：

Set-ExecutionPolicy RemoteSigned

再继续。运行后如果提示找不到命令，多半是 npm 的全局 bin 目录没有配置到 PATH 环境变量里，需要手动加一下。不同系统的全局目录不一样，Windows 下通常在你的用户目录下的AppData\Roaming\npm里。

4.3 局域网协作与安全边界

服务端跑起来以后，队友怎么连？同一局域网内，他们直接访问你的局域网 IP 加端口就行。先查一下本机 IP：

• Windows：ipconfig，看“IPv4 地址”
• macOS / Linux：ifconfig或ip addr

如果你的 Windows 防火墙开启了，记得放行对应端口，不然队友访问会一直卡住。这一步可以通过控制面板的“防火墙允许应用”功能添加这个端口。

我在这里必须提醒一句：这种自建服务端默认没有 TLS 加密，别人知道地址也能连进来。所以别傻乎乎地把服务端暴露到公网。如果真要在公网环境跑，一定要用反向代理加 HTTPS 做一层保护，并且给项目设置好权限。我的建议是，先老老实实在可信的局域网里用，这是体验最舒服也最安全的方式。

5. 在编辑器里跑通第一个旋转方块

5.1 场景、实体、组件的关系

Superpowers 的编辑器遵循了典型实体系统：场景是容器，实体是场景中的对象，组件是挂在实体上的功能模块。你可以把场景当成一个房间，实体是房间里的一把椅子，组件则是椅子的“轮子”——没有轮子椅子也能放着，但需要功能时就得靠组件。

理解这个关系很重要，因为后面写脚本也要顺着这个概念来。给实体添加行为组件，相当于把脚本“贴”到实体上，引擎会在合适的时机调用脚本里的钩子函数。这个概念和 Unity、Unreal 不是很像吗？对，Superpowers 在这套已经很成熟的设计上做了简化，特别容易入门。

5.2 创建对象和脚本组件的具体操作

打开一个项目后，在场景树面板右键或使用顶部菜单，创建一个新的实体。接着在资源面板里新建一个立方体模型资源，把它拖到场景中，这样视口里就会出现一个默认方块。

接下来要做的是让方块活起来。在右侧属性面板里找到“添加组件”按钮，选择“行为”或“Behavior”组件。此时会提示选择行为脚本，如果还没有脚本，就到资源面板新建一个行为脚本文件，文件以.ts结尾，会自动打开编辑器里的代码文本。双击打开脚本文件，右侧会变成代码编辑器，界面上方还能看到脚本编译状态。

5.3 写一段 TypeScript 让方块转起来

下面是一段最基础的旋转脚本，在实际项目中相当有代表性：

class RotatingCube extends Sup.Behavior { speed = 1; update() { this.actor.rotate(0, this.speed * 0.016, 0); } } Sup.Component.register("RotatingCube", RotatingCube);

Sup.Behavior是基类，update()会在每一帧被调用。this.actor.rotate是让当前实体绕 Y 轴旋转。0.016大约是一帧的时间（60 帧每秒时），配合speed变量就能控制旋转速度。

写完脚本后保存，回到场景树选中刚才的方块，在属性面板的 Behavior 组件里选择刚刚注册的RotatingCube行为。运行项目，方块就开始转了。如果没反应，先回到代码编辑器看有没有编译报错，同时确认行为组件确实挂到了方块实体上。我喜欢这种“改代码、立即运行”的节奏，比传统编译型引擎要轻快很多。

5.4 验证实时协作

跑通单个方块还不算体验完，必须验证协作。把访问地址复制到另一个浏览器或另一台电脑上，打开同一个项目，你会发现两边能同时看到视口。在一个浏览器里移动方块，另一个浏览器里几乎同步看到位置变化。如果你在脚本里改了一行代码，另一个窗口的任务栏会立刻刷新编译状态，双方都能看到最新的运行结果。

这种实时反馈对协调工作非常有用，比如两个人一起做关卡设计时，一个人搭路、一个人放置敌人，完全不会互相覆盖。但也要注意，并不是所有数据都适合多人同时改同一文件，协作的重点在“沟通和分工”，后面我会说几个冲突场景。

6. 几个我踩过的坑，和对应解决办法

6.1 浏览器白屏或按钮没反应

我遇到过几次打开界面后整个视口空白，按钮点击没响应。排查下来主要三种情况：第一是端口被占用，启动器打开了个假地址；第二是浏览器缓存了旧版本的脚本，导致界面组件加载失败；第三是 WebGL 硬件加速被禁，渲染直接失败。

解决办法按顺序来：先强制刷新页面，把 URL 改成带端口的形式直接访问；如果还是白屏，用无痕模式开一次，排除缓存干扰；再不行，检查浏览器设置里的硬件加速是否打开。问题依旧的话，把启动器关掉，杀掉后台所有 superpowers 进程，换一个端口重新启动。

6.2 行为脚本没反应，又不报错

脚本运行后没有任何反馈，也不提示错误，这是新手最容易迷茫的地方。按照我的排查顺序，先看代码有没有保存成功，再看行为组件上是否选对了脚本，最后看脚本里有没有拼错类名或注册名。有一个隐藏坑是：启动运行后改了代码，必须让项目重新加载一下脚本，或者按运行界面的刷新按钮，不然改动不会生效。

另一次我遇到脚本报“类型不存在”，原因是脚本文件所在目录没有被当作模块正确识别。我的做法是不在脚本文件顶部乱加import，因为 Superpowers 的行为系统有自己的模块注册机制，早期版本不太喜欢标准 ES Module 的写法。除非你足够熟悉它内部模块体系，否则先保持示例里的写法最省心。

6.3 协作时多人修改脚本的冲突

既然支持实时协作，那就会遇到多人同时改一个脚本的情况。Superpowers 的同步机制偏向“最终写入覆盖”，A 改了脚本第 10 行，B 同时也改了第 15 行，后保存的人可能会把前面的改动覆盖掉。这不是工具 Bug，而是协作策略的问题。

我的建议是脚本文件尽量拆小，一个人负责一个模块，比如“玩家控制.ts”“敌人 AI.ts”“关卡生成.ts”，从源头上减少交叉。重要的改动先在本地建一份备份，推到工作区前和队友喊一声。我习惯在团队里约定一个“谁改了什么”的简单规矩，比任何技术配置都有效。

最后再分享一个小技巧：我习惯在创建项目之前先写好一份 README，把端口、访问地址、分工约定都写在工作区同目录下。这样一来，哪怕隔了一个月再开项目，也不会忘了环境怎么搭。如果你准备用这个工具搞协作，建议从桌面客户端入手，跑通一个旋转方块的小 demo 再考虑折腾服务端。装不上别急着删，多试一次，往往就是端口或缓存的事。祝你把第一个小游戏跑起来。