Superpowers：一款支持实时协作的开源游戏开发平台上手指南

1. Superpowers 到底是个什么项目1.1 我第一次看到 superpowers 时的反应第一次听到 superpowers 这个词我以为是某个效率工具合集或者是什么“开发者超能力清单”。真正安装完那一套之后才反应过来这其实是一个主打实时协作的开源游戏开发平台。你不需要安装几十个插件也不需要先把代码写完再打开引擎看效果直接在浏览器里就能完成从创建场景、拖资源、写 TypeScript 脚本到发布网页游戏的全流程。这个项目能解决什么问题往大了说它把“多人同时在一个游戏项目里干活”这件事变得非常自然。往小了说它适合做课程教学、Game Jam、快速原型验证和团队内部工具演示。你打开一个项目队友的光标、改动、新增资源都会实时同步过来那种体验更接近 Google Docs 里多人写文档而不是传统意义上“一个人改完另一个人再拉分支”的流程。我建议谁去试只要你对 2D/3D 网页小游戏感兴趣或者你正在找一个能让学生/团队成员快速上手的创作工具都值得花半小时装一遍。它不会替代你的主力引擎但它是一种非常特别的“轻量级协作沙盒”尤其适合那些不想被复杂工程流程拖住的项目。1.2 核心功能拆解它到底能做哪些事Superpowers 不是一个大而全的引擎它的功能很有针对性场景编辑器支持 2D 场景和基础 3D 场景你可以拖拽摆放 Actor调整位置、旋转、缩放也可以给 Actor 挂组件。资源管理图片、音频、材质、Sprite、动画、Prefab 都可以直接拖进面板资源引用关系用 JSON 描述方便做版本管理。TypeScript 脚本系统项目的业务逻辑用 TypeScript 编写运行时通过浏览器加载。它提供了一套全局对象Sup让你操作 Actor、Input、Audio、TextRenderer 等。实时协作这是它区别于其他引擎的最大卖点。多个客户端连接同一个服务器后编辑操作会同步到所有参与者包括场景树、资源导入、脚本修改和运行状态。导出与发布可以把项目导出成纯 HTML5 静态资源放到任意静态服务器上就能跑不依赖后端数据库。这些功能单独拿出来都不稀奇但组合在同一个开源项目里并且默认协作优先这就很有意思了。最简单的理解它是“多人实时写代码 搭场景”的工作坊而不是“单机版游戏引擎”。1.3 为什么选它而不是 Unity 或 Phaser很多人会在 Superpowers 和几个常见方案之间纠结我做了一张简单的对比方案协作友好度上手门槛生态成熟度适合场景Superpowers原生多人协作低浏览器操作小众插件少快速原型、教学、Game JamUnity协作需要额外配置中高非常成熟中大型商业项目Phaser需要自建协作层中优秀Web 2D 游戏偏代码化Construct不支持多人环境低中等纯可视化的简单游戏选 Superpowers 的理由其实很具体当你需要“几个人同时在一个项目里改东西”时它开箱即用当你希望场景结构和代码都能被 Git 管起来时它的 JSON 数据格式非常友好当你只想做一个在浏览器里运行的互动原型时它没有繁重的本地工程概念。缺点是也挺明显社区小、插件少、大型 3D 能力弱。所以不要指望拿它做商业大作它更像是一个“团队创意工作间”。如果你能接受这个定位那它的价值会被完全释放。2. 安装 superpowers 前先搞清楚你要装什么版本2.1 客户端版还是服务器版很多人第一次安装就卡在“我到底该下载哪个文件”。Superpowers 的发行版通常分两类桌面客户端版自带一套运行时和编辑器界面适合单机使用。启动后会在本地跑一个 Superpowers 服务器然后打开编辑窗口。服务器版只有服务端程序用来部署到一台常开的机器上供团队多人连接。它本身不包含桌面窗口启动后提供 WebSocket 服务和 Web 页面。我个人的建议如果你只是想自己试一试下载桌面客户端版最省事。如果你有固定团队或者想让学生/朋友都能连上来那就部署一个服务器版。团队使用的时候没必要每人跑一套完整编辑器资源、项目都集中在服务器上大家通过浏览器访问即可。2.2 环境准备清单安装前准备好这些能极大减少后面出问题的概率操作系统Windows、macOS、Linux 都可以官方对三大平台都有支持。浏览器Chrome、Edge、Firefox 均可需要支持 WebGL 和 WebSocket。旧版 IE 就别想了。Node.js如果你自己从源码构建需要装 Node.js 14 以上的 LTS 版本如果只是用官方发行版则不一定需要手动装因为发行版自带运行时。磁盘空间建议至少留 500MB 以上的空闲空间项目资源和构建产物比想象中占地方。网络环境客户端和服务器之间走本机或局域网保证端口可用即可。下文默认配置端口是 4237。还有一个关键认知Superpowers 的所有项目数据默认保存在服务器本地的数据目录里所以如果你要备份备份那个目录就好。这一点我会在后面详细说。2.3 官方安装步骤与常见坑以官方 Release 包为例安装流程其实很简单去 GitHub Releases 页面下载最新稳定版文件名一般包含server或client字样。解压到不含中文和空格的目录。这一步很重要因为某些工具对路径里的特殊字符很敏感。Windows 下直接运行Superpowers.exemacOS 如果提示“无法验证开发者”右键选择打开Linux 下给可执行文件加执行权限后再运行。首次启动会初始化数据目录稍等片刻。浏览器访问http://localhost:4237看到服务器控制台页面就说明启动成功了。我踩过的最典型的坑是解压一半时杀毒软件把可执行文件隔离了导致客户端始终打不开。后来我干脆把整个文件夹加入白名单再解压问题再也没有出现。另一类是端口被占用电脑上如果已经有个服务占用了 4237Superpowers 会启动失败日志里会写EADDRINUSE。这时候用--port参数换个端口即可比如superpowers --port 42382.4 验证是否真的装好了启动成功后不要急着开项目。先在浏览器地址栏输入http://localhost:4237打开控制台看是否有“Superpowers server is running”之类的状态信息。再创建一个测试用户登录后新建项目随便拖一个图片到场景里看场景视图是否有反应。如果这些都能顺利操作就说明安装没问题。如果页面一直转圈优先检查防火墙是否放行了本地端口。Windows 用户经常遇到“第一次启动时没有允许访问网络”的弹窗点掉后就再也找不到入口了只能去防火墙规则里手动放行。这一条值得记下来。3. 第一次打开 superpowers界面、模板与目录结构3.1 从服务器控制台到编辑器Superpowers 的逻辑不是“打开软件直接新建项目”而是先启动一个服务器然后通过浏览器进入。你看到的localhost:4237页面本质上是服务器控制台它负责用户管理、项目列表、在线成员显示和服务器设置。第一次使用先创建一个管理员账号再点新建项目。系统会让你选择模板。我的经验是2D 项目模板是最好的上手入口它自带一套简单的演示资源包括角色、地面、脚本你可以立刻感受到“改一行代码刷新页面就能看到变化”的快感。3D 模板也可以但初学者对坐标系和相机的概念还没有建立容易一头雾水。项目创建完成后你会看到类似文件管理器的资产面板。点选项目里的某个场景就进入了真正的编辑器页面。3.2 编辑器界面分不清一张图口述版我第一次打开编辑器时也傻了眼因为整个界面元素非常多。但只要把它拆成五个区域就好记了左侧是资源面板形状像侧边栏展示项目里的所有文件比如图片、音频、脚本、场景。中间是场景视图也是最大的那块画布拖动画布可以改视角选中物体会出现坐标轴或操控手柄。左下角/右侧是层级面板展示当前场景里的 Actor 和组件树。你可以在里面重命名、复制、删除对象。右侧最靠边的是属性面板选中对象后它会把 Transform、SpriteRenderer、Behavior 组件以及所有配置选项列出来。顶部有菜单栏用来运行游戏、暂停、保存、导入资源。理解了分区后你就不需要在菜单里乱翻了。日常 80% 的操作都在场景视图、资源面板和属性面板之间来回切换。3.3 项目目录结构里的那些隐藏规则如果你打开服务器数据目录下的某个项目文件夹会发现里面都是 JSON 文件和资源文件夹。它的逻辑是assets/存放原始资源图片、音频等。场景、资源定义、配置都以 JSON 文件存放。project.json和settings.json是项目核心配置。这种设计对版本管理特别友好用 Git 可以把整个项目目录管起来Merge 场景变更的时候也能看到具体字段变化。不过要提醒一句不要在 Superpowers 运行时手动去改项目目录里的 JSON因为服务端的索引和文件缓存不同步容易出现资源找不到的问题。要改就通过界面改或者停掉服务器再改文件。4. 从零搭一个能玩的 2D 小游戏完整实操记录4.1 准备资源并搭出第一个场景场景搭建其实没什么魔法。先找一个图片素材拖进资源面板它会被识别成 Texture然后可以创建 Sprite。新建一个场景双击打开把 Sprite 从资源面板拖到场景视图里。这个 Sprite 就变成了场景中的一个 Actor你可以用鼠标直接拖动它也可以在属性面板输入 Transform 数值。我习惯的做法是先给地面铺一个大一点的长方形 Sprite再给玩家角色做一个小的圆形 Sprite玩家在上面跑模拟俯视角移动。因为 Superpowers 内置了物理基础你也可以加 Box Collider、RigidBody 之类的组件不过第一个小项目不需要纯代码控制位置会更容易理解。4.2 让角色动起来第一个 TypeScript 脚本在资源面板新建一个脚本文件命名为PlayerBehavior.ts双击打开代码编辑器写入下面的内容class PlayerBehavior extends Sup.Behavior { speed 0.15; update() { // 获取方向键输入 const horizontal (Sup.Input.isKeyDown(RIGHT) ? 1 : 0) - (Sup.Input.isKeyDown(LEFT) ? 1 : 0); const vertical (Sup.Input.isKeyDown(UP) ? 1 : 0) - (Sup.Input.isKeyDown(DOWN) ? 1 : 0); // 如果玩家没按键就不动 if (horizontal 0 vertical 0) return; // 基于当前位置叠加移动 const position this.actor.getPosition(); const moveX position.x() horizontal * this.speed; const moveY position.y() vertical * this.speed; this.actor.setPosition(moveX, moveY, 0); } } Sup.registerBehavior(PlayerBehavior);写完后回到场景选中你的玩家 Actor在组件面板点击 Add Behavior选择PlayerBehavior。这样运行时这个脚本就会自动绑定到角色上。点顶部菜单的 Play 按钮再用方向键控制你就能看到角色在场景里移动了。这里值得解释一下脚本的机制Superpowers 并不要求你用固定的生命周期方法名反复注册它会扫描项目里的Sup.Behavior子类并通过Sup.registerBehavior记录。update()在每个渲染帧都会调用所以控制移动很直接。如果你更习惯使用start()做初始化它也一样支持。4.3 给游戏再加一个简单的得分逻辑移动有了但还差点交互。再新建一个脚本CoinBehavior.ts让角色碰到金币后金币消失得分加一。核心代码大致像这样class CoinBehavior extends Sup.Behavior { start() { Sup.getActor(Score).textRenderer.setText(Score: 0); } update() { const player Sup.getActor(Player); const coin this.actor; const distance Sup.Math.distance(player.getPosition(), coin.getPosition()); const threshold 0.6; if (distance threshold) { const currentScore parseInt(Sup.getActor(Score).textRenderer.getText().split(:)[1] || 0, 10) 1; Sup.getActor(Score).textRenderer.setText(Score: currentScore); this.actor.destroy(); } } } Sup.registerBehavior(CoinBehavior);这里边用到了Sup.getActor来按名字拿到场景对象用Sup.Math.distance计算距离用textRenderer更新文本。实际操作中你需要在场景里提前创建一个名字叫Score的空 Actor并给它的 TextRenderer 组件设置一个 “Score: 0” 的初始文本。金币挂上CoinBehavior就能触发销毁。这种写法的优点是直观但你也能看出如果场景里有几十个硬币挨个挂脚本非常繁琐。所以更合理的做法是把金币做成 Prefab 预设然后循环生成。Superpowers 的右侧资源面板支持新建 Prefab将一个 Actor 拖到资源面板里就能变成预设然后在代码里用Sup.appendScene或实例化来动态创建。4.4 导出成网页部署到任意静态空间游戏做完后导出功能非常好用。点击编辑器菜单里的 Build或 Export选择导出目标它会自动生成一个文件夹里面是index.html、js、assets等文件。这个产物是完全静态的不需要再跑服务端所以你可以直接扔到 GitHub Pages、对象存储、Nginx 目录里。我通常的做法是在本地跑通后把导出的文件压缩传到对象存储再用 CDN 加速。由于没有后端依赖加载速度取决于静态资源和脚本大小一个小原型做完只有几 MB首屏加载非常快。如果你后续想把小游戏发布到比赛或作品集网站导出的文件夹就是你的答案而不是让每个人各自安装编辑器。5. 实时协作才是 superpowers 的灵魂5.1 多人一起编辑到底是怎么实现的前面说过Superpowers 的服务器是核心。多人连接的流程是服务器控制台添加用户账号把你的服务器地址发给队友队友在客户端里输入地址并登录然后打开同一个项目。连接成功后你会看到其他人的鼠标光标并且他们创建的 Actor、脚本、资源会实时出现在你的界面上。这背后的机制是服务端维护了一套项目数据模型客户端每次操作都通过 WebSocket 推给服务端再由服务端广播给其他客户端。场景里的每个对象都有一个 ID所以资源引用不会因为多人操作而完全乱掉。官方对冲突处理做了不少优化但并不意味着没有冲突。两个人同时修改同一个字符串后写入的一方大概率会覆盖前一方两个人同时拖拽同一个 Actor它会跳来跳去。所以协作需要规则而不是指望系统自动解决所有问题。5.2 团队协作时需要提前约定好的规则我做了几个内部项目后总结了一套比较适用的协作约定场景文件尽量一人编辑。多人同时改同一个场景的“风险最大”不是系统不能用而是容易出现你删了对象、对方还在引用的尴尬。资源命名用统一前缀。比如角色图片全都以player_开头金币用coin_这样在资源面板里按字母排序时找起来很快。脚本改动要随时同步刷新。一个队员写完脚本后其他队员在运行游戏前需要等浏览器重新编译。如果发现脚本还是旧的行为检查编辑器是否保存成功。小步提交经常备份。Superpowers 项目数据是文件直接在服务器上做git commit是最稳妥的。如果你是团队管理员建议给每个成员分配独立账号不要所有人共用同一个管理员账号。否则出了问题根本不知道是谁改的。Superpowers 服务器控制台里的在线成员列表能帮你定位谁还在连接。5.3 我踩过的协作坑和解决办法第一个坑是资源被覆盖。两个人同时导入了一个同名文件后导入的会把先导入的覆盖掉虽然不是恶意但美术资源丢了很痛苦。解决办法约定每个成员使用自己的前缀比如maying_、xiao_。第二个坑是场景运行时卡住。一个人点了运行其他人也点运行导致场景状态不一致。后来我们规定运行状态统一由一个人操控其他人通过共享屏幕或者聊天工具观察不要同时操作播放暂停。第三个坑是版本回滚找不到状态。Superpowers 自身有版本历史但我还是习惯让服务器端项目目录用 Git 管理。每完成一个里程碑在服务端手动提交一次这种双重保障让我安心很多。6. 安装和使用过程中常见问题与排查技巧实录6.1 连不上服务器先从这三步查问题表现客户端输入服务器地址后一直转圈或者显示 WebSocket 连接失败。排查顺序很重要看端口服务器程序是否真的在运行命令行执行netstat -ano | findstr 4237Windows或者lsof -i :4237macOS/Linux确认端口在监听。看防火墙如果是局域网访问确保防火墙允许 4237 端口传入连接。Windows 的首次弹窗如果被误点成拒绝需要去“Windows Defender 防火墙”手动添加入站规则。看地址访问自己时用localhost访问别人时不要用localhost要用服务器电脑的局域网 IP比如http://192.168.1.20:4237。很多人在这里栽过。如果公司或学校网络有严格的端口限制那就把端口换成一个常见端口或者让 IT 管理员放行。没有太多技巧网络联通性问题只能一步步排除。6.2 脚本报错刷屏怎么看有效信息浏览器控制台是调试脚本的第一现场。按 F12 打开开发者工具切换到 Console 标签页Superpowers 的脚本错误会直接显示Uncaught Error或TypeError并且带文件名和行号。常见错误有几种Sup is not defined一般是因为脚本文件没有在项目中正确加载检查文件名是否以.ts结尾是否被系统识别成了普通资源。Behavior not found场景中的 Actor 挂载了一个脚本组件但脚本类名和组件名不一致。确认脚本里的类名和Sup.registerBehavior(类名)完全一致。Cannot read properties of undefined通常是Sup.getActor(名字)没找到对应 Actor检查场景里是否真的有这个名字。另外脚本保存后如果编辑器没有提示编译可能不会立即生效。我的习惯是保存后回到场景视图随便点击一下空白处强制刷新一次焦点再重新进入运行模式。6.3 页面白屏和 WebGL 初始化失败白屏和 WebGL 问题往往跟浏览器硬件加速有关。遇到这类情况先试试切换浏览器Chrome 不行就换 FirefoxEdge 也一样。如果还不行到浏览器设置里关闭“硬件加速”再刷新页面。很多集成显卡的旧电脑在默认开启硬件加速时会渲染失败关闭后反而稳定。另外不要用最小化的浏览器窗口长时间运行项目。Superpowers 的场景渲染依赖于浏览器能正常获取绘制循环窗口长时间后台运行后某些浏览器会暂停渲染回到页面时可能出现短暂白屏。这是浏览器策略不是软件坏了。6.4 安装后双击程序没有反应如果你双击 Superpowers 客户端程序后没有任何窗口弹出来可以优先怀疑杀毒软件或系统安全策略。macOS 用户尤其多见下载的 dmg 启动后提示已损坏或无法验证开发者。这不是文件真的损坏而是 Gatekeeper 默认拦截了从网上下载的未签名应用。右键图标选择“打开”在弹窗里点“仍要打开”即可。Windows 用户如果没有生成日志也可以用命令行启动可执行文件往往能捕提到更具体的报错。如果看到缺 DLL 或缺少动态库那多半是解压不完整重新解压一遍。6.5 问题速查表症状可能原因解决办法访问 localhost 打不开服务端未启动或端口被占用检查进程换端口重启局域网其他设备连不上防火墙拦截放行 4237 端口脚本没有任何效果未绑定 Behavior 或类名不一致检查组件绑定和类名多人同时编辑场景乱跳冲突不是故障约定一人一场景导出后图片丢失资源引用路径问题重新 Build清理缓存后再导出页面白屏WebGL 渲染问题关硬件加速或换浏览器这些排查技巧不是一天积累出来的几乎每个都踩过真实的坑。记录下来的价值在于下次再遇到五分钟内就能定位而不是重新走一遍漫长的试错流程。7. 再往前走一步自托管、插件与项目扩展7.1 自托管服务器时Nginx 反向代理怎么配如果你希望团队成员通过一个固定域名访问 Superpowers不建议直接暴露 4237 端口。用 Nginx 做反向代理更安全也能顺便配 HTTPS。Superpowers 需要 WebSocket 保持长连接因此 Nginx 配置里必须包含 Upgrade 头server { listen 80; server_name your-domain.example.com; location / { proxy_pass http://127.0.0.1:4237; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; } }注意最关键的其实是proxy_set_header Upgrade $http_upgrade;和Connection upgrade两行少了它们 WebSocket 就会被 Nginx 断开。配置完记得执行nginx -s reload。加 HTTPS 只需要再配置证书并监听 443其他逻辑不变。如果访问量不大我甚至建议不要用反向代理因为一个额外环节就多一个故障点。自托管最稳定的拓扑是一台常开机器直连 4237 端口内网访问用 IP外网访问用安全组或端口映射。7.2 利用插件弥补功能短板Superpowers 的插件机制允许你扩展现有的资源类型、编辑器面板和生产工具。虽然生态不大但好在基础框架是开放的。我的建议是先从社区已有的插件里找需求比如批量导入、自定义导出模板、颜色主题等这些通常能让工作流顺畅很多。如果你自己写插件需要熟悉Sup.Plugin接口和项目的构建流程。一个最简插件可能只有几十行代码用来注册资源类型。不过别一上来就想搞复杂的先做一个小功能比如“一键把选中 Actor 的位置导出成 JSON”这样既能熟悉插件机制又能实际提升效率。7.3 把 Superpowers 接入日常开发链路我认为 Superpowers 的最佳使用方式不是“替代一切”而是当一个协作原型工具。它的产出可以继续拆分导出的 HTML5 游戏可以嵌入其他 Web 项目。场景资源可以作为美术参考图导出给正式项目。场景中的预制体设计思路可以迁移到 Unity 或 Phaser 里重新实现。项目数据本身是 JSON可以写脚本统计分析资源占用、脚本数量、场景复杂度。如果你有成为“效率偏执狂”的倾向还可以把 Server 数据目录纳入 Git 仓库通过 GitHub Actions 定时生成构建产物再自动上传到服务器。这样团队每次改完其他人马上能获得一个可浏览的在线版本。我个人一直觉得这个玩法比单纯安装软件本身更有价值因为它真正把创作流程打通了。回到最开始的点安装 superpowers 并不是终点装完了只是拿到了一个画布和一支笔。多花点时间研究协作规则、目录管理和导出路径它才能真正变成你团队里顺手的工作台。像我这样的本地开发者用它给客户做交互原型、给内部做演示已经省掉了非常多沟通成本。如果你正在寻找一种“大家一起在浏览器里做小游戏”的方式不妨按这套流程装起来亲自跑通一个小项目再决定要不要长期使用。