概览

OpenWarp = 可视化积木编程编辑器（2D / 3D 舞台）+ 独立播放器产物。这份文档记录**接口、格式、引擎口径**，全部对着代码写，不凭印象。

三个工程的关系

数据流

工程文件夹 ──readProject──▶ project 对象 ──createRuntime──▶ 运行时（解释执行积木）
     │                              │                              │
     │                              │                              └─▶ 画布每帧读 state / liveOf / cameraOf / lightOf
     │                              └─▶ 编辑器 UI（React，只读快照 + 改数据）
     └─packager──▶ 单个 HTML（bundle + 运行时 + 播放器，双击即玩）

技术选型（2D / 3D 到底用什么写的）

术语

工程格式（磁盘）

FORMAT_VERSION = 2。工程就是一个**普通文件夹**，没有数据库、没有加密（加密只在发行包 build-secure 那一层）。

我的作品/
├── project.json            工程级：模式 / 舞台 / UI / meta / 角色索引
├── Sprite/Code/<角色id>.json 每个角色的**完整文档**（积木 / 变量 / 造型 / 位置）
├── Images/                 素材：图片（png/jpg/svg…）
├── Sounds/                 素材：音频
├── Models/                 素材：3D 模型（glb/gltf/fbx/stl）
├── Variables/<角色id>.json  **可读副本**（读工程时**不读它**，只认 Sprite/Code）
├── Lists/<角色id>.json      同上
└── Logs/save.log           每次保存写一行，调试用

project.json

Sprite/Code/<角色id>.json

资源地址三条规则

读取实现的三个副本（改一个要想三个）

• main/openwarp-project.js 的 readProject —— 桌面版（唯一权威）
• OpenWarp-packager/src/pure.js 的 normalizeProject —— 打包器（Node + 浏览器共用）
• renderer-webpack/web/web-bridge.js 的 importEntries —— 网页版导入（文件夹 / .ow 共用同一段）

.ow 作品包

整个工程压成**一个文件**，桌面版与网页版互通。容器是**标准 ZIP**，别人拿 7-Zip 直接就能打开看。

里面装什么

project.json              同上（roles 只留索引）
Sprite/Code/<角色id>.json  每个角色的完整文档
Images/  Sounds/  Models/  素材真文件（各目录**本级**的文件）

读写实现：main/openwarp-ow.js

零依赖、Node 与浏览器共用同一份：只用两边的公共能力 CompressionStream('deflate-raw')（Node ≥18 / Chromium ≥103）。拿不到这个 API 时自动退化成 store（照样能读，只是大一点）。整个文件没有 import/require，所以网页版 bundle 得进去。

兼容性与校验

• 只写 store(0) 与 deflate(8)；读的时候两种都认。其它压缩方法（bzip2/lzma）**明确报错**，不静默产出坏工程
• ZIP64 不支持（明确报错）；每个条目做 **CRC32 校验**；中央目录与尾记录位置做收尾校验
• 文件名带 UTF-8 标志（中文素材名）
• zip-slip 双向拦：写入时 cleanPath 拒 ..，落盘时主进程再过一遍 path.resolve 前缀检查

两边的落点

宿主接口 window.OpenWarpEditor

渲染层只认这一个全局对象（const api = () => window.OpenWarpEditor）。桌面版由 preload 提供，网页版由 web-bridge.js 提供，安卓壳将来自己实现 —— 这三者就是「宿主」。

契约（自己写宿主时必须守）

• 每个方法都要返回 Promise。渲染层会写 api().setChanged(x).catch(…) —— 同步函数返回 undefined 会变成 undefined.catch 抛错，整个界面白屏（线上真崩过）
• 只有两种「订阅」方法例外：onDetachedChanged / onStageDetachedChanged（以及 onAiChatDelta）—— 它们返回**取消订阅的函数**，不是 Promise
• 返回形状要对齐：打开/新建/导入类 → {name, project} 或 null（取消）或 {name, error}；readAsset → **data URL**；saveAs → {ok:true, path} / {ok:false, canceled:true}
• 没有的能力就别挂：扩展按「宿主有没有这个方法」判断「本机能不能用」（platform 字段另说）
• platform：'win'（桌面）/ 'web'（网页）/ 'android'（安卓壳）。扩展窗口的导航栏按它判断可用性

方法一览

标记：桌面 网页 安卓 非网站可用（网页版故意不挂）。

桌面版：IPC 名对照

preload 里每个方法就是对 ow.* 的一次 ipcRenderer.invoke，名字基本一一对应：ow.get-initial-folder、ow.new-project、ow.open-project、ow.workspace-root、ow.select-workspace-root、ow.list-projects、ow.open-project-path、ow.create-project-in-root、ow.export-ow、ow.import-ow、ow.save-project、ow.set-changed、ow.list-assets、ow.read-asset、ow.add-asset、ow.delete-asset、ow.read-asset-address、ow.list-dir、ow.read-project-file、ow.copy-project-file、ow.rename-project-file、ow.delete-project-file、ow.write-project-file、ow.make-dir、ow.write-project-text、ow.copy-entry、ow.move-entry、ow.delete-entry、ow.entry-exists、ow.list-entry、ow.read-project-text、ow.run-command、ow.open-text-file、ow.save-as、ow.clipboard-write、ow.copy-image、ow.show-item-in-folder、ow.alert、ow.confirm、ow.ai-*、ow.lan-*、ow.detach-blocks、ow.detach-stage。

主进程往渲染层推的事件：ow.detached-changed、ow.stage-detached-changed、ow.ai-chat-delta。

加一件新能力要动三步

1. main/windows/openwarp-editor.js   this.ipc.handle('ow.xxx', async (event, …) => {…})
2. preload/openwarp-editor.js        xxx: (…) => ipcRenderer.invoke('ow.xxx', …)
3. 渲染层（App.jsx / 某个组件）        typeof (api() || {}).xxx === 'function' 判一下再用
   ↳ 网页版：renderer-webpack/web/web-bridge.js 里补同名方法（没有就"非网站可用"）

运行时 API（createRuntime）

积木的「解释执行」只有这一个实现（renderer-webpack/editor/openwarp-editor/components/runtime.js）。编辑器、打包器产物、播放器用的都是它 —— 打包器现读现内联这一份，不复制（复制就会漂移）。

import {createRuntime} from './components/runtime.js';

const rt = createRuntime({
  api: () => window.OpenWarpEditor,   // 宿主桥（读素材、跑命令…用）
  getProject: () => project,          // 每次现取，运行时**不缓存**工程对象
  net,                                // 可选：联机（82 个 net_* 积木全委托给它）
  cloud                               // 可选：云变量（cloud_* 积木）
});

返回的成员

state 里有什么

• mouse {x, y, down, button} —— 世界坐标
• keys（Set of KeyboardEvent.code）、clicked（Set of roleId）
• volume、world {w, h}（画布当前有多少世界单位）
• pen（笔迹数组：线段 / 图章快照）、pens（哪些角色落着笔）

执行模型

积木与 opcode

积木定义全在 components/BlocksEditor.jsx 的 buildCategories() 里（当前约 296 条定义，含 compat 里给 sb3 转换兜底的那批）。

命名约定

<家族>_<动作>，家族 id 与积木分类（CAT 的第一个参数）同名。四个家族不走大 switch，而是按前缀先分流到专用处理器（execBlock / evalBlock 开头那几行）：

其余全部进 switch (block.opcode)。取值块在 evalBlock 的 switch 里、命令块在 execBlock 里 —— 加一块新积木两处都要写（形状是 reporter/boolean 的只需前者）。

分类

形状与插槽写法

帽子积木（HAT_OPCODES）

event_when_run、func_define、prefab_start、net_onConnected、net_onDisconnected、net_onKicked、net_onMessage、net_onEvent、net_onVarChange、net_onZoneChange、net_onPeerJoin、net_onPeerLeave、cloud_onConnected、cloud_onDisconnected、cloud_onChange。

引擎与口径

这一节的数字（0.75 / 0.8 / 1000 / 50°）都是**约定值**，散落在运行时、2D 画布、3D 画布、播放器四处 —— 改一处必须一起改。

两个画布分别是什么技术

这条分工是刻意的：运行时只存状态、画布只读状态 —— 积木与画布因此完全解耦（同一个运行时能同时喂 2D 画布、3D 画布和打包产物的播放器）。

打包产物的播放器同样是 Canvas 2D + three：player.js 是 2D 主循环、three3d.js 是 3D；three 用 UMD 版 three.min.js 原样内联成经典脚本，播放器只读全局 THREE、不打包它。

「画板」窗口同理：位图 / 像素板是 Canvas 2D，矢量板是生成 SVG，3D 板是 three.js。

坐标系与单位

• 2D：左上角 (0,0)，x 向右、y 向下（Scratch 口径），旋转 0° 指向右、顺时针为正
• 3D：世界坐标 y 向上（three 口径）—— 同一个 x/y 字段在两种模式下屏幕方向不同，写 3D 积木时要留意
• 1 世界单位 = 1 像素（角色方块 60px、网格 4000px、默认视距 1200px）

摄像机

3D 取景：fov 固定 50°，比例 = 分辨率 宽:长；「取景距离」由「长」反推 d = (长/2)/tan(fov/2) —— 黄框摆在相机前方 d 处，正好等于摄像机看到的那一块。

光照（3D）

角色的舞台显示状态（liveOf）

{x, y, z, rotation, pitch, roll, size, ghost, visible, image, texture, text, font, dataUrl, img, stretchX, stretchY}

• size 是百分比（100 = 原大小），ghost 0~100（透明度）
• image 与 texture 互斥：使用资源 = 一张平面图（像 Unity 的 Quad），使用纹理 = 贴到角色的 3D 形状上。设一个会把另一个清掉
• img / dataUrl 是 2D 画布直接画的东西（按需加载）

预制件（≈ 克隆体）

• 副本 id = prefab_<源角色id>_<序号>，在 live 里是**独立的一条**（画布照 roleId 画）
• 私有变量/列表不另起一套：键先过 ownerOf() 归一化到源角色（和 Scratch 一致）
• 放置时直接跑源角色的 prefab_start 帽子脚本（自带调度，不需要外部壳）
• 上限 300；结束预制件 只销毁自己（本体调用无操作）

碰撞（touching）

• 2D 用**轴对齐矩形**（角色边长由 size 决定）：碰到 鼠标指针 / 屏幕边缘 / 角色名或id
• 世界无限大：「屏幕」= 摄像机那块矩形（宽 × 长），出框就算碰到边缘
• 颜色碰撞：读画布像素，支持 #f00 这种简写
• 3D 产物里这套也是 2D 判定（编辑器 Canvas3D 的射线拾取没搬过去）—— 对「点一下角色」够用，精细 3D 碰撞不精确

画笔

笔迹**不是**往画布里画像素，而是往 state.pen 里记「线段 / 图章快照」，画布按同一个变换再画一次。采集挂在 notify() 上：落笔的角色位置一变就补一段线（所以 notify 里 penTrail 那半不能合并）。

音频 / 资源

素材读取一律走宿主桥（readAsset / readAssetAddress），运行时侧有音频缓存与图片缓存。图片地址变了才重新加载。

联机与云变量

联机（components/net.js）—— 血统与结论已定稿

局域网协作（主进程 main/lan-relay.js）

没有公网也要能一起做作品：主进程起一个**本地 HTTP 服务**当中继，渲染层只调桥方法。

云变量（components/cloud.js）

• 对接 TurboWarp 云变量服务器（原生 WebSocket，零依赖）
• 变量名对用户不带 ☁ 前缀（模块进出自动加/去）
• 服务器只认数字值；同一个变量每秒别发超过 10 次（官方限制）
• 帽子块：cloud_onConnected / cloud_onDisconnected / cloud_onChange

打包器与产物

把工程打成**一个自包含 HTML**：工程数据 + 素材（dataURL）+ 运行时 + 播放器全在里面，双击就能玩，不需要联网、不需要 Electron。

两种用法（同一份逻辑）

两者共用 src/pure.js（归一化 / 统计 / 提醒 / 自检）与 src/html.js（模板），所以产物结构不可能不一样。差别只有「文件从哪来」。

产物结构

<script>window.__OPENWARP_BUNDLE__ = {
  format:'openwarp-bundle', version:1, packedBy, packedAt, title,
  project: {…},                      // 工程对象
  assets: {images:{文件名:dataURL}, sounds:{…}}
}</script>
<script>(function(){ 运行时 + 播放器 + 启动 })()</script>

• 工程数据用 JSON.stringify 后把 < 转成 \u003c（防 </script> 截断）
• 内联脚本必须是**经典脚本**（不能 type="module"）—— 运行时去掉 export 后和播放器同作用域
• 打包时new Function(script) 自检一次，宁可不给也不给白屏产物
• 运行时是现读编辑器那一份（components/runtime.js），不复制 —— 复制就会漂移
• 3D 工程才内联 three（three.min.js + 播放器的 three3d.js + 模型加载器），2D 产物保持小

播放器（src/player/）

打包器侧的**第二份**显示实现（产物里没法内联 React 组件）。规矩是「只抄显示」：不抄黄框 gizmo、选中高亮、右键菜单、舞台拖动。取景口径与 Canvas3D **逐字一致**（CAM_FOV / POINT_REF / 灯位默认值必须两处同值）。

player.js = 2D 主循环（对着 Canvas2D / Stage 抄的 worldToScreen / screenToWorld / fitBox）；three3d.js = 3D 渲染（光源 / 阴影 / 模型 / 使用资源平面 / 使用纹理）。

已知限制

• 素材按**文件名**内联：工程里写绝对/相对路径的素材，网页里只能按文件名兜底匹配；工程文件夹之外的素材不会被打进去
• 3D 产物里 碰到颜色不可用（WebGL 画布不能当 2D 读）；3D 碰撞走 2D 判定
• WebRTC 无 TURN；没有撤销、没有工程编辑器（产物是播放器）
• 页面版依赖 webkitdirectory / webkitGetAsEntry（Chromium 系最稳）

网页版编辑器

网页版不是另一套代码：**同一个 App.jsx**，换一个入口 + 装一个浏览器桥，由单独的 webpack 配置打出来（给 Cloudflare Pages 这类纯静态托管）。

构建

入口与桥

// renderer-webpack/web/index.jsx
installWebBridge();   // ⚠️ 顺序要紧：先装桥（App 里所有 api() 都读它）
initTheme();
ReactDOM.render(<App />, document.getElementById('app'));

网页版的 platform 是 'web'，扩展窗口的导航栏按它判断可用性。

目录与脚本

关键文件

npm 脚本

刻意接受的重复：必须两处一起改

常见改动的完整步骤

加一块新积木

1. BlocksEditor.jsx  buildCategories()           加 {opcode:'家族_动作', shape, label, defaults, menus}
       · 菜单插槽写 [NAME]、输入框写 {NAME}
       · 帽子块还要登记进 HAT_OPCODES
2. runtime.js  evalBlock 的 switch               取值块（reporter / boolean）
3. runtime.js  execBlock 的 switch               命令块（stack / c）
       · 要读插槽：先 await（少个 await 就把 Promise 传下去了）
4. npm run webpack:compile                       桌面渲染层
   npm run web:build                             网页版
   （改了 runtime.js 还要 npm run build:ui       打包器页面）

加一个扩展

1. BlocksEditor.jsx  EXTENSIONS  加 {id, category, icon, color, name, desc, platforms?}
       platforms 省略 = 三端通用；['win'] = 桌面专属（导航栏会按 platform 判断）
2. 同文件  CAT('分类id', …)      定义积木（分类 id 要和 EXTENSIONS 的 category 相同）
3. runtime.js                     实现（前缀分流家族要单独写处理器）
4. 想"作品里用到就自动加载"→ 不用做事：自动加载按 opcode 前缀扫工程文本

加一件宿主能力

1. main/windows/openwarp-editor.js   this.ipc.handle('ow.xxx', …)
2. preload/openwarp-editor.js        xxx: (…) => ipcRenderer.invoke('ow.xxx', …)
3. 渲染层                            typeof (api() || {}).xxx === 'function' 再调
4. 网页版（可选）                     web-bridge.js 里补同名实现，否则那个扩展就是"非网站可用"