最近一直在折腾 Superpowers 这个开源项目越用越觉得它被低估了。如果你平时做前端、做小游戏或者带学生做创意编程那 Superpowers 值得花一个晚上去试一下。简单说它是一个可以在浏览器里直接运行的实时协作开发环境不需要配本地 IDE也不用手动搭后端装好之后打开浏览器就能开始做 3D 场景、2D 小游戏、互动页面。最打动我的是它的实时协作能力几个人同时连到同一个地址编辑器和场景是同步的谁改了哪一行代码、哪个物体其他人能立刻看到。这种体验比传统“改完上传再看结果”的流程高效太多了。文章主要面向两类人一类是想快速做点交互作品、但不想被复杂引擎吓住的新手另一类是已经玩过 Three.js、Unity 之类的老手想找一个轻量、协作友好的工具来搞原型或者教学。下面我会从项目设计思路讲起把安装步骤、核心功能、完整创作流程和常见问题一次性拆开说最后再补上一些我实际踩坑后总结的细节。1. 项目概述Superpowers 到底想解决什么问题1.1 为什么一个编辑器敢叫“超能力”我第一次看到 Superpowers 这个名字第一反应是又一个名字起得比本事大的玩具。真正用完之后反而觉得名字挺贴切。它的核心思路是“把创作环境本身做成一个实时协作的应用”编辑器跑在浏览器里数据存在本地服务器上你用键盘、鼠标、摄像头甚至多个人同时操作同一个项目。你不需要安装庞大的客户端也不需要和版本管理工具搏斗因为它天然就支持多人实时编辑。这个项目源自一个开源社区多年积累的设想与其让开发者各自闷头写代码再互相合并不如让编辑器、场景、脚本全部实时同步像 Google Docs 一样。这种思路对做游戏素材、做互动教学、做现场演示特别有用。比如我在一个线下工作坊里几个人同时往同一个 3D 场景里面扔素材、调灯光、改脚本配合起来非常自然完全不需要“你先来、我再改”的串行等待。1.2 与传统开发工具的核心差异传统的开发流程是本地装好 IDE - 写代码 - 启动构建 - 浏览器预览。Superpowers 把这套流程压缩成一个地址你打开http://localhost:端口就是编辑器右侧就是实时预览。所有项目资源、脚本、场景都在同一个界面里管理不用来回切换窗口。另一个核心差异是它把 TypeScript 作为内置脚本语言而不是给个 Lua 或者 Python 插件。TypeScript 的好处是类型检查可以提前捕捉很多低级错误在浏览器里写代码时编辑器会直接报错提示不用等运行了才发现。对于新手来说这可能稍有点门槛但对于已经写过一点 JS 的人反而更安全。更重要的是Superpowers 内置的脚本接口封装了大量场景操作、资源加载和输入事件调起来比从零开始写 Three.js 顺手不少。1.3 适用场景不只是做游戏很多人以为 Superpowers 只能做游戏其实不是。我实践下来它很适合做三类事情交互式教学课件直接在 3D 空间里摆模型写几行脚本让物体跟随鼠标旋转比 PPT 演示直观得多。快速原型验证先做一个小场景验证创意再决定要不要投入资源去 Unity 或 Unreal。多人协作练习教学或团队内部培训时大家都在同一个项目里动手体验比各改各的再合并高效得多。所以如果你只是想找一个小巧的“超能力工具箱”Superpowers 不是给你 SDK它是给你一个能一起动手的工作房间。理解了它的定位后面安装和配置就不会被各种陌生概念劝退了。2. 环境准备与安装步骤2.1 安装前的依赖准备注意下面的依赖和命令我基本都在 Windows 10 和一些 Linux 环境上验证过macOS 理论上也没问题但路径要自己对应一下。Superpowers 本体是通过 npm 发布的命令行工具所以第一步是保证你机器上有 Node.js 和 npm。Node.js 版本建议 14 以上太老的版本在依赖安装阶段比较容易出问题。我一开始用 12.x结果 npm 装依赖时直接报了一堆 peer dependency 警告虽然能跑但吓人。升级到 16 / 18 之后就安静了。npm 本身建议 6 以上。顺便说一句如果你网络环境里 npm 下载慢可以临时换到国内镜像源比如npm config set registry https://registry.npmmirror.com装完再换回来。这一步和内核无关纯粹是节省时间。2.2 使用 npm 安装 Superpowers 服务安装超级简单打开终端执行npm install -g superpowers这个命令会把 Superpowers 的命令行工具装到全局。安装过程中如果看到很多依赖包在跑不用管等它结束就好。安装完成后执行superpowers如果没有意外终端会输出一个本地访问地址通常是http://localhost:4234。这个地址就是你的工作台入口。注意启动前最好确认 4234 端口没有被占用。我遇到过 4234 被别的服务抢走的情况启动会失败或者访问不到后面第 5 节里我会说排查方法。2.3 启动服务并创建第一个项目启动之后用浏览器打开上面那个地址第一次进去会看到几个模板选项。有做 3D 场景的、有做 2D 游戏的也有空项目模板。这里建议选 3D 模板因为内容最丰富也最能体现 Superpowers 的实时协作特色。点击模板后需要给你的项目起个名字。它会自动在服务器的存储目录里生成一个项目文件夹这个文件夹存放所有场景、资源、脚本和配置文件。第一次创建项目时它会下载一些内置资源包所以会等待一会儿。完成之后你就进入编辑器主界面了左侧是资源树中间是 3D 视口右边是属性面板。到这里安装和基础启动就完成了。从零到看到编辑器快的话五到十分钟。如果这时想叫朋友一起编辑可以把地址发给对方连同一个端口就能实时协作。关于协作机制下面单独说。3. 核心功能解析与实操要点3.1 层级场景编辑器Superpowers 的场景组织方式和很多现代引擎类似采用的是层级树结构。你可以把模型、灯光、相机都挂在同一层也可以把它们嵌套到空物体下面。这样移动父级时子级会跟着动做整体布局特别方便。最让我喜欢的是“实体组件”的模型。一个实体就是一坨对象它没有固定的数据类型你可以给它添加任意组件比如模型组件、点光源组件、脚本组件。这比传统引擎里“一个类只能干一件事”灵活很多。比如我希望一个立方体既能显示模型又能旋转还要能响应鼠标点击直接给它加对应的几个组件就行不用去继承什么基类。实操上你要注意组件之间的执行顺序。比如我给角色加了“移动脚本”和“动画脚本”如果两个脚本都操作同一个属性后一个脚本会覆盖前一个。这种问题在我刚开始写交互时很容易遇到解决办法是尽量让不同脚本各管各的属性或者把逻辑合并进同一个脚本。3.2 实时协作机制到底是怎么跑的Superpowers 的协作方法和一般“共享屏幕”不是一回事。它更像实时数据库同步每个人连接的是同一个服务器服务器把同一份项目数据发给所有客户端并且每次编辑都会通过一种增量更新的方式同步到其他人。所以不止是场景同步代码编辑也同步。比如你写脚本时删掉一行另一边的人能实时看到那行变红再消失。实际体验下来这种同步延迟在局域网环境几乎感觉不到。跨地区的话延迟会取决于服务器所在位置。如果你在用的是云服务器可以把服务跑在离团队近的区域这样延迟会更低。这个协作能力非常实用我用来做过远程“结对编程”我一边讲另一边直接在项目里改参数所有变化都实时出现在画面上教学效果比录屏好太多。3.3 脚本系统与可视化编程的平衡Superpowers 的脚本默认是 TypeScript。打开一个脚本组件你可以直接写类类里声明属性这些属性还会自动出现在右侧属性面板上。这是它特别聪明的地方不是让你完全可视化连线也不是让你全裸写代码而是把“数据驱动”和“代码逻辑”结合在一起。举个例子我写了一个“自动旋转”脚本export class AutoRotate extends Sup.Script { speed 30; update() { this.actor.rotate(0, this.speed * Sup.Input.dt, 0); } }speed这个属性不用额外写交互代码它自己就会出现在属性面板里运行时直接改数值物体的旋转速度立刻变。这种设计对新手非常友好你不需要理解复杂的事件机制只需要照着模板改几个数字就能快速看到效果。需要注意一点Superpowers 的脚本不是纯 ES 模块它要求每个脚本导出一个类或者对象并且用Sup.Script作为基类。如果你之前习惯用普通函数组件刚上手时容易找不到入口。多看模板里自带的例子就会很快适应。3.4 资源管理贴图、模型、音频在资源管理器里你可以直接拖入图片、glTF 模型、音频文件拖动完成之后它就会出现在资源树上。双击资源可以查看属性把它拖到场景里就能实例化。整个操作和很多在线编辑器很像学习成本不高。贴图和模型这里要注意格式。贴图支持常见格式模型建议用 glTF/glb这是比较通用的格式。我遇到过用其他格式导入后材质丢失的问题后来统一用 glb 就稳定了。音频方面小体积音频直接用内置播放器没问题大体积音频建议压缩后导入否则加载会变慢。资源管理里还有一个“动态加载”的概念你可以在脚本里通过Sup.load之类的接口按需加载资源而不是一进场景就把所有资源都拉进来。对做复杂项目来说非常重要等场景多了再换掉全部加载方案要花不少功夫。4. 实操过程从空白场景到一个小型交互演示4.1 准备资源并建立项目为了让大家有完整的获得感我建议从“空白项目”模板开始自己搭一个简单的 3D 展示间地面上摆几个箱子箱子上方有一盏灯点击箱子可以让它旋转。第一步创建空白项目然后从资源树右键新建一个“场景”。场景是一个空的 3D 空间里面默认会有一个主相机。接着右键新建一个“立方体”把它拖到场景中。你会看到视口里出现一个灰白色方块。默认材质是白色的不太好看可以给它新建一个材质贴上一张自己准备的贴图或者直接用内置的“彩色材质”。Superpowers 内置了简单的颜色材质直接调整颜色即可。4.2 添加灯光与环境灯光在 3D 场景里特别重要没有灯光的场景看起来又灰又平。右键新建一个“点光源”把它拖到立方体上方然后在属性面板调整强度、颜色、范围。如果你想要阴影需要手动开启光源的“投射阴影”选项并且让地面也参与阴影计算。这里有几个经验默认的白色光源强度可能偏亮可以先从 0.5 开始试。点光源范围不是越大越好超过场景范围反而会让画面对比度变差。如果场景里有多盏灯注意每盏灯都会增加计算量简单展示场景用一盏主灯完全够了。4.3 编写点击交互脚本场景里有了方块和灯现在写一个点击才执行的动作。新建脚本命名ClickToSpin把脚本拖到立方体上。然后双击脚本打开内置代码编辑器写export class ClickToSpin extends Sup.Script { Sup.Math.Number speed 90; actorMouseDown() { // 当鼠标点击该物体时让它持续旋转 this.currentSpin true; } update() { if (this.currentSpin) { this.actor.rotate(0, this.speed * Sup.Input.dt, 0); } } }这只是一个示例实际写的时候要注意几个点actorMouseDown是内置的输入事件只要碰撞体存在才能触发所以立方体上最好加一个物理碰撞体组件。不加碰撞体的话鼠标点击穿透在编辑器中很难选中目标。这是最容易被初学者忽略的。4.4 本地测试与导出准备脚本写完保存场景里的预览就会立刻更新。如果你点击立方体发现旋转没有触发第一件事是检查有没有碰撞体组件。如果触发了但旋转方向不对调一下 speed 的正负号就行。Superpowers 本身不是为“打包 APK”设计的它更像一个在线运行环境。它支持“导出为 HTML 应用”会把当前项目打包成可以在浏览器里离线运行的文件。这个导出功能非常实用你可以把一个演示场景导出后分享给朋友对方打开 HTML 就能看到效果不需要安装 Superpowers。导出时注意“构建目标”选项。默认是浏览器大多数场景选这个就行。如果导出后有资源没加载出来多半是文件路径设置问题检查一下是否用了绝对路径。5. 常见问题与排查技巧实录5.1 启动失败或端口被占用启动 superpowers 时报错或者访问不了先试试superpowers --port 4321换一个端口看能不能启动。如果能说明原端口被占用了。在 Windows 上可以用netstat -ano | findstr :4234找到占用进程然后结束它在 Linux 上可以用lsof -i :4234。另外如果你是在云服务器上跑需要确认防火墙放行对应端口。这个问题我踩过一次本地能访问远程访问不了最后发现是安全组没开端口。5.2 多人协作连接不上如果朋友输入你的地址打不开先确认你们是否在同一网络或者服务器是否映射到公网。局域网内直接用局域网 IP 访问外网则要配置端口映射。如果你只是临时演示可以用内网穿透工具但这不在今天的范围。另一个常见问题是多人同时编辑时素材冲突。虽然 Superpowers 支持实时协作但同一个资源被两个人同时大改还是可能出现意外覆盖。稳妥的做法是需要大改某个素材时先口头说一下或者用不同资源树分支避免冲突。5.3 浏览器兼容与性能问题Superpowers 的编辑器依赖 WebGL建议使用最新版 Chrome、Edge 或 Firefox。我遇到过老版 Safari 里视口显示黑屏其实就是 WebGL 加速没开或者版本太旧。更新浏览器后基本正常。性能方面场景里的模型面数、灯光数量、粒子数量是主要瓶颈。如果你发现视口卡顿先从这三个方面排查。内置场景里如果导入了高精度模型很可能出现掉帧这时可以降低模型精度或者把大模型拆开远处用低模近处再切高模。5.4 脚本加载失败的排查思路如果你拖入脚本后场景没有反应打开浏览器控制台看报错。最常见的三类类没有继承Sup.Script检查类定义。脚本里用了不存在的属性比如把this.actor写成this.scene。事件名拼写错误比如update写成Update大小写必须一致。还有一个小技巧在脚本开头添加console.log然后运行刷新浏览器控制台就能看到脚本是否被加载了。这个排查方式在很多在线编辑器里通用不只在 Superpowers 里有。6. 扩展思路把 Superpowers 用出“超能力”的感觉6.1 结合外部工具做素材流水线Superpowers 的内置编辑器毕竟不是建模软件复杂模型、精细贴图还是在 Blender 里做更高效。我常用的流程是在 Blender 里制作模型导出为 glb再导入 Superpowers 中摆场景。这样既有专业建模的自由度又有 Superpowers 快速协作的能力。音频素材也可以用外部软件预处理然后做成素材库根据不同项目复用。你会发现当素材库积累起来之后上线一个交互场景的速度会明显提升相当于给团队建了一个共享素材资产库。6.2 用脚本接口做自动化工具Superpowers 的脚本不只是用在场景对象上理论上你也可以写一些工具脚本来批量创建物体、批量设置属性。比如我写过一个批量生成随机箱子的脚本省去了一个个手动摆放的枯燥时间。这个思路适合所有做场景重复劳动的人参考。6.3 教学与远程协作的落地我个人最看重的是它的教学场景价值。我现在的线下工作坊流程很简单把 Superpowers 跑在一台普通笔记本上给每个参与的人发一个地址和项目名他们打开自己浏览器里的同一个项目我这边引入一个模型所有人立刻能看到。这种“所见即所得”的协作学习体验比看 PPT 或者录屏强太多。如果你也是带团队做创意课程非常值得试一下。踩过几次坑之后我的体会是Superpowers 最厉害的不是某个具体功能而是它把“实时协作”和“可视化场景”通过一个轻量级 Web 服务串了起来。新手用它不会迷路老手用它做原型和教学也能找到乐趣。如果你一直想找一个能快速上手、能多人一起折腾的开源工具那就别犹豫直接照着上面的步骤开个项目试试。真的跑起来之后你会回来感谢那个装完没删的下午。 
长河君 · 2026/10/7 6:53:14 · 阅读 1.2k Superpowers：在浏览器中实时协作构建3D场景的开源工具
最近一直在折腾 Superpowers 这个开源项目越用越觉得它被低估了。如果你平时做前端、做小游戏或者带学生做创意编程那 Superpowers 值得花一个晚上去试一下。简单说它是一个可以在浏览器里直接运行的实时协作开发环境不需要配本地 IDE也不用手动搭后端装好之后打开浏览器就能开始做 3D 场景、2D 小游戏、互动页面。最打动我的是它的实时协作能力几个人同时连到同一个地址编辑器和场景是同步的谁改了哪一行代码、哪个物体其他人能立刻看到。这种体验比传统“改完上传再看结果”的流程高效太多了。文章主要面向两类人一类是想快速做点交互作品、但不想被复杂引擎吓住的新手另一类是已经玩过 Three.js、Unity 之类的老手想找一个轻量、协作友好的工具来搞原型或者教学。下面我会从项目设计思路讲起把安装步骤、核心功能、完整创作流程和常见问题一次性拆开说最后再补上一些我实际踩坑后总结的细节。1. 项目概述Superpowers 到底想解决什么问题1.1 为什么一个编辑器敢叫“超能力”我第一次看到 Superpowers 这个名字第一反应是又一个名字起得比本事大的玩具。真正用完之后反而觉得名字挺贴切。它的核心思路是“把创作环境本身做成一个实时协作的应用”编辑器跑在浏览器里数据存在本地服务器上你用键盘、鼠标、摄像头甚至多个人同时操作同一个项目。你不需要安装庞大的客户端也不需要和版本管理工具搏斗因为它天然就支持多人实时编辑。这个项目源自一个开源社区多年积累的设想与其让开发者各自闷头写代码再互相合并不如让编辑器、场景、脚本全部实时同步像 Google Docs 一样。这种思路对做游戏素材、做互动教学、做现场演示特别有用。比如我在一个线下工作坊里几个人同时往同一个 3D 场景里面扔素材、调灯光、改脚本配合起来非常自然完全不需要“你先来、我再改”的串行等待。1.2 与传统开发工具的核心差异传统的开发流程是本地装好 IDE - 写代码 - 启动构建 - 浏览器预览。Superpowers 把这套流程压缩成一个地址你打开http://localhost:端口就是编辑器右侧就是实时预览。所有项目资源、脚本、场景都在同一个界面里管理不用来回切换窗口。另一个核心差异是它把 TypeScript 作为内置脚本语言而不是给个 Lua 或者 Python 插件。TypeScript 的好处是类型检查可以提前捕捉很多低级错误在浏览器里写代码时编辑器会直接报错提示不用等运行了才发现。对于新手来说这可能稍有点门槛但对于已经写过一点 JS 的人反而更安全。更重要的是Superpowers 内置的脚本接口封装了大量场景操作、资源加载和输入事件调起来比从零开始写 Three.js 顺手不少。1.3 适用场景不只是做游戏很多人以为 Superpowers 只能做游戏其实不是。我实践下来它很适合做三类事情交互式教学课件直接在 3D 空间里摆模型写几行脚本让物体跟随鼠标旋转比 PPT 演示直观得多。快速原型验证先做一个小场景验证创意再决定要不要投入资源去 Unity 或 Unreal。多人协作练习教学或团队内部培训时大家都在同一个项目里动手体验比各改各的再合并高效得多。所以如果你只是想找一个小巧的“超能力工具箱”Superpowers 不是给你 SDK它是给你一个能一起动手的工作房间。理解了它的定位后面安装和配置就不会被各种陌生概念劝退了。2. 环境准备与安装步骤2.1 安装前的依赖准备注意下面的依赖和命令我基本都在 Windows 10 和一些 Linux 环境上验证过macOS 理论上也没问题但路径要自己对应一下。Superpowers 本体是通过 npm 发布的命令行工具所以第一步是保证你机器上有 Node.js 和 npm。Node.js 版本建议 14 以上太老的版本在依赖安装阶段比较容易出问题。我一开始用 12.x结果 npm 装依赖时直接报了一堆 peer dependency 警告虽然能跑但吓人。升级到 16 / 18 之后就安静了。npm 本身建议 6 以上。顺便说一句如果你网络环境里 npm 下载慢可以临时换到国内镜像源比如npm config set registry https://registry.npmmirror.com装完再换回来。这一步和内核无关纯粹是节省时间。2.2 使用 npm 安装 Superpowers 服务安装超级简单打开终端执行npm install -g superpowers这个命令会把 Superpowers 的命令行工具装到全局。安装过程中如果看到很多依赖包在跑不用管等它结束就好。安装完成后执行superpowers如果没有意外终端会输出一个本地访问地址通常是http://localhost:4234。这个地址就是你的工作台入口。注意启动前最好确认 4234 端口没有被占用。我遇到过 4234 被别的服务抢走的情况启动会失败或者访问不到后面第 5 节里我会说排查方法。2.3 启动服务并创建第一个项目启动之后用浏览器打开上面那个地址第一次进去会看到几个模板选项。有做 3D 场景的、有做 2D 游戏的也有空项目模板。这里建议选 3D 模板因为内容最丰富也最能体现 Superpowers 的实时协作特色。点击模板后需要给你的项目起个名字。它会自动在服务器的存储目录里生成一个项目文件夹这个文件夹存放所有场景、资源、脚本和配置文件。第一次创建项目时它会下载一些内置资源包所以会等待一会儿。完成之后你就进入编辑器主界面了左侧是资源树中间是 3D 视口右边是属性面板。到这里安装和基础启动就完成了。从零到看到编辑器快的话五到十分钟。如果这时想叫朋友一起编辑可以把地址发给对方连同一个端口就能实时协作。关于协作机制下面单独说。3. 核心功能解析与实操要点3.1 层级场景编辑器Superpowers 的场景组织方式和很多现代引擎类似采用的是层级树结构。你可以把模型、灯光、相机都挂在同一层也可以把它们嵌套到空物体下面。这样移动父级时子级会跟着动做整体布局特别方便。最让我喜欢的是“实体组件”的模型。一个实体就是一坨对象它没有固定的数据类型你可以给它添加任意组件比如模型组件、点光源组件、脚本组件。这比传统引擎里“一个类只能干一件事”灵活很多。比如我希望一个立方体既能显示模型又能旋转还要能响应鼠标点击直接给它加对应的几个组件就行不用去继承什么基类。实操上你要注意组件之间的执行顺序。比如我给角色加了“移动脚本”和“动画脚本”如果两个脚本都操作同一个属性后一个脚本会覆盖前一个。这种问题在我刚开始写交互时很容易遇到解决办法是尽量让不同脚本各管各的属性或者把逻辑合并进同一个脚本。3.2 实时协作机制到底是怎么跑的Superpowers 的协作方法和一般“共享屏幕”不是一回事。它更像实时数据库同步每个人连接的是同一个服务器服务器把同一份项目数据发给所有客户端并且每次编辑都会通过一种增量更新的方式同步到其他人。所以不止是场景同步代码编辑也同步。比如你写脚本时删掉一行另一边的人能实时看到那行变红再消失。实际体验下来这种同步延迟在局域网环境几乎感觉不到。跨地区的话延迟会取决于服务器所在位置。如果你在用的是云服务器可以把服务跑在离团队近的区域这样延迟会更低。这个协作能力非常实用我用来做过远程“结对编程”我一边讲另一边直接在项目里改参数所有变化都实时出现在画面上教学效果比录屏好太多。3.3 脚本系统与可视化编程的平衡Superpowers 的脚本默认是 TypeScript。打开一个脚本组件你可以直接写类类里声明属性这些属性还会自动出现在右侧属性面板上。这是它特别聪明的地方不是让你完全可视化连线也不是让你全裸写代码而是把“数据驱动”和“代码逻辑”结合在一起。举个例子我写了一个“自动旋转”脚本export class AutoRotate extends Sup.Script { speed 30; update() { this.actor.rotate(0, this.speed * Sup.Input.dt, 0); } }speed这个属性不用额外写交互代码它自己就会出现在属性面板里运行时直接改数值物体的旋转速度立刻变。这种设计对新手非常友好你不需要理解复杂的事件机制只需要照着模板改几个数字就能快速看到效果。需要注意一点Superpowers 的脚本不是纯 ES 模块它要求每个脚本导出一个类或者对象并且用Sup.Script作为基类。如果你之前习惯用普通函数组件刚上手时容易找不到入口。多看模板里自带的例子就会很快适应。3.4 资源管理贴图、模型、音频在资源管理器里你可以直接拖入图片、glTF 模型、音频文件拖动完成之后它就会出现在资源树上。双击资源可以查看属性把它拖到场景里就能实例化。整个操作和很多在线编辑器很像学习成本不高。贴图和模型这里要注意格式。贴图支持常见格式模型建议用 glTF/glb这是比较通用的格式。我遇到过用其他格式导入后材质丢失的问题后来统一用 glb 就稳定了。音频方面小体积音频直接用内置播放器没问题大体积音频建议压缩后导入否则加载会变慢。资源管理里还有一个“动态加载”的概念你可以在脚本里通过Sup.load之类的接口按需加载资源而不是一进场景就把所有资源都拉进来。对做复杂项目来说非常重要等场景多了再换掉全部加载方案要花不少功夫。4. 实操过程从空白场景到一个小型交互演示4.1 准备资源并建立项目为了让大家有完整的获得感我建议从“空白项目”模板开始自己搭一个简单的 3D 展示间地面上摆几个箱子箱子上方有一盏灯点击箱子可以让它旋转。第一步创建空白项目然后从资源树右键新建一个“场景”。场景是一个空的 3D 空间里面默认会有一个主相机。接着右键新建一个“立方体”把它拖到场景中。你会看到视口里出现一个灰白色方块。默认材质是白色的不太好看可以给它新建一个材质贴上一张自己准备的贴图或者直接用内置的“彩色材质”。Superpowers 内置了简单的颜色材质直接调整颜色即可。4.2 添加灯光与环境灯光在 3D 场景里特别重要没有灯光的场景看起来又灰又平。右键新建一个“点光源”把它拖到立方体上方然后在属性面板调整强度、颜色、范围。如果你想要阴影需要手动开启光源的“投射阴影”选项并且让地面也参与阴影计算。这里有几个经验默认的白色光源强度可能偏亮可以先从 0.5 开始试。点光源范围不是越大越好超过场景范围反而会让画面对比度变差。如果场景里有多盏灯注意每盏灯都会增加计算量简单展示场景用一盏主灯完全够了。4.3 编写点击交互脚本场景里有了方块和灯现在写一个点击才执行的动作。新建脚本命名ClickToSpin把脚本拖到立方体上。然后双击脚本打开内置代码编辑器写export class ClickToSpin extends Sup.Script { Sup.Math.Number speed 90; actorMouseDown() { // 当鼠标点击该物体时让它持续旋转 this.currentSpin true; } update() { if (this.currentSpin) { this.actor.rotate(0, this.speed * Sup.Input.dt, 0); } } }这只是一个示例实际写的时候要注意几个点actorMouseDown是内置的输入事件只要碰撞体存在才能触发所以立方体上最好加一个物理碰撞体组件。不加碰撞体的话鼠标点击穿透在编辑器中很难选中目标。这是最容易被初学者忽略的。4.4 本地测试与导出准备脚本写完保存场景里的预览就会立刻更新。如果你点击立方体发现旋转没有触发第一件事是检查有没有碰撞体组件。如果触发了但旋转方向不对调一下 speed 的正负号就行。Superpowers 本身不是为“打包 APK”设计的它更像一个在线运行环境。它支持“导出为 HTML 应用”会把当前项目打包成可以在浏览器里离线运行的文件。这个导出功能非常实用你可以把一个演示场景导出后分享给朋友对方打开 HTML 就能看到效果不需要安装 Superpowers。导出时注意“构建目标”选项。默认是浏览器大多数场景选这个就行。如果导出后有资源没加载出来多半是文件路径设置问题检查一下是否用了绝对路径。5. 常见问题与排查技巧实录5.1 启动失败或端口被占用启动 superpowers 时报错或者访问不了先试试superpowers --port 4321换一个端口看能不能启动。如果能说明原端口被占用了。在 Windows 上可以用netstat -ano | findstr :4234找到占用进程然后结束它在 Linux 上可以用lsof -i :4234。另外如果你是在云服务器上跑需要确认防火墙放行对应端口。这个问题我踩过一次本地能访问远程访问不了最后发现是安全组没开端口。5.2 多人协作连接不上如果朋友输入你的地址打不开先确认你们是否在同一网络或者服务器是否映射到公网。局域网内直接用局域网 IP 访问外网则要配置端口映射。如果你只是临时演示可以用内网穿透工具但这不在今天的范围。另一个常见问题是多人同时编辑时素材冲突。虽然 Superpowers 支持实时协作但同一个资源被两个人同时大改还是可能出现意外覆盖。稳妥的做法是需要大改某个素材时先口头说一下或者用不同资源树分支避免冲突。5.3 浏览器兼容与性能问题Superpowers 的编辑器依赖 WebGL建议使用最新版 Chrome、Edge 或 Firefox。我遇到过老版 Safari 里视口显示黑屏其实就是 WebGL 加速没开或者版本太旧。更新浏览器后基本正常。性能方面场景里的模型面数、灯光数量、粒子数量是主要瓶颈。如果你发现视口卡顿先从这三个方面排查。内置场景里如果导入了高精度模型很可能出现掉帧这时可以降低模型精度或者把大模型拆开远处用低模近处再切高模。5.4 脚本加载失败的排查思路如果你拖入脚本后场景没有反应打开浏览器控制台看报错。最常见的三类类没有继承Sup.Script检查类定义。脚本里用了不存在的属性比如把this.actor写成this.scene。事件名拼写错误比如update写成Update大小写必须一致。还有一个小技巧在脚本开头添加console.log然后运行刷新浏览器控制台就能看到脚本是否被加载了。这个排查方式在很多在线编辑器里通用不只在 Superpowers 里有。6. 扩展思路把 Superpowers 用出“超能力”的感觉6.1 结合外部工具做素材流水线Superpowers 的内置编辑器毕竟不是建模软件复杂模型、精细贴图还是在 Blender 里做更高效。我常用的流程是在 Blender 里制作模型导出为 glb再导入 Superpowers 中摆场景。这样既有专业建模的自由度又有 Superpowers 快速协作的能力。音频素材也可以用外部软件预处理然后做成素材库根据不同项目复用。你会发现当素材库积累起来之后上线一个交互场景的速度会明显提升相当于给团队建了一个共享素材资产库。6.2 用脚本接口做自动化工具Superpowers 的脚本不只是用在场景对象上理论上你也可以写一些工具脚本来批量创建物体、批量设置属性。比如我写过一个批量生成随机箱子的脚本省去了一个个手动摆放的枯燥时间。这个思路适合所有做场景重复劳动的人参考。6.3 教学与远程协作的落地我个人最看重的是它的教学场景价值。我现在的线下工作坊流程很简单把 Superpowers 跑在一台普通笔记本上给每个参与的人发一个地址和项目名他们打开自己浏览器里的同一个项目我这边引入一个模型所有人立刻能看到。这种“所见即所得”的协作学习体验比看 PPT 或者录屏强太多。如果你也是带团队做创意课程非常值得试一下。踩过几次坑之后我的体会是Superpowers 最厉害的不是某个具体功能而是它把“实时协作”和“可视化场景”通过一个轻量级 Web 服务串了起来。新手用它不会迷路老手用它做原型和教学也能找到乐趣。如果你一直想找一个能快速上手、能多人一起折腾的开源工具那就别犹豫直接照着上面的步骤开个项目试试。真的跑起来之后你会回来感谢那个装完没删的下午。