Files
vibemake/docs/experience-packages.txt
Jerry 1c837766cd feat: integrate robot assembly and simulation with resilient loading
Add backend-driven assembly and simulation experiences, MAKE branding, mobile rendering budgets and desktop-only CAD/PCB routes. Improve logo loading progress, document image recovery and URDF request handling; include dev packaging and regression coverage.
2026-10-30 18:38:39 +08:00

148 lines
9.0 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Vibemake 装配 / 行走资源包接入说明
协议版本:1;2026-10-28
一、两个字段
项目详情响应中的项目对象增加两个可空字符串:
{
"assemblyManifestUrl": "https://资源域名/experiences/项目ID/assembly/v1/manifest.json",
"walkingManifestUrl": "https://资源域名/experiences/项目ID/walking/v1/manifest.json"
}
没有相应功能返回 null。前端分别显示 / 隐藏两个按钮,不再根据项目编号或名称判断。
临时本地预览例外:后端未接入期间,本机 / 局域网的 Microban(ppsx17fhhtzq)详情页
会补上空的两个字段,打开 275 分件装配和现有 Microduck 行走样例;后端有效地址优先。
此配置仅在 js/project-experiences.js,正式域名和其他项目不使用,可在联调完成后删除。
字段是 ZIP 解压后的 manifest.json 地址,不是 ZIP 下载地址、GLB 地址或 HTML 页面地址。
保存接口也需要接受这两个字段;详情接口必须返回,列表接口可选。
主展示区的 urdfMainUrl 保持独立。前端不会在字段为空时回退到固定的演示资源。
二、后台上传与发布
项目编辑页设置“AI 装配资源包”“行走演示资源包”两个 ZIP 上传位,均允许清空。
1. 上传到临时区。拒绝绝对路径、..、软链接、重复路径和解压炸弹,在解压过程中限额。
2. 解压到独立版本目录,保留路径、文件名和大小写。本次两个 ZIP 根目录就是 manifest.json。
3. 检查 schemaVersion、kind、files 中每个文件的存在性、实际 bytes、SHA256 和内部引用。
4. 验证模型 / 配置。行走策略还需算法团队在隔离环境确认动力学和推理结果。
5. 完整发布到对象存储 / CDN 后,再将 manifest 地址写到项目字段。失败时保留旧版本。
本版输入上限:清单 2 MB、资源 1000 个、清单所列资源解压总计 200 MB。
后端解压限额也要计入 README、许可证等文件,不能先全部解压再检查。
装配包单个 GLB 不超过 50 MB、实例不超过 1000;这不是手机流畅度保证。
推荐目录:/vibemake_dev/experiences/<projectId>/<kind>/<version>/。
正式目录可用 /vibemake/experiences/...。这两种 linkerbot OSS 路径已接入本地 / 局域网代理。
其他资源域名可直接读取,但需要配置 CORS。代理不会转发任意域名。
资源必须支持 GET、正确 Content-Type(JSON / XML / GLB / ONNX / STL / 音频等)和 HTTPS。
公开资源使用匿名读取,当前请求不携带 Cookie;只给 manifest 签名不会授权同目录其他文件。
私有资源的逐文件签名、令牌刷新等需要扩展协议,本版不支持。
每次更新发布新版本目录,避免缓存混用;不要只发布清单、遗漏网格、贴图或策略。
ZIP 不允许指定浏览器脚本或 iframe 入口,上传目录按数据资源管理,不作为可执行网页发布。
三、AI 装配包
microban-assembly.zip:
manifest.json
models/robot.glb
README.txt
模型是用户提供的“机器人.glb”,文件和材质参数未修改。
GLB SHA256:5976d400a8f87877fee0be58731e13b8c1db84271b24d35ed889f255e56f894a
网页使用自身的光照、环境反射和色调映射,最终明暗与 Blender 环境可能不同。
当前包是完整模型,steps 为空,仅展示总装,不凭空生成安装工序。
未来多零件仍然只用 assemblyManifestUrl,不需要再增加字段。
包内放多个 GLB,manifest 指定实例、层级、最终位置和步骤。例如:
{
"schemaVersion": 1,
"kind": "assembly",
"title": "示例机器人",
"unit": "meter",
"displayQuaternion": [0,0,0,1],
"files": [
{"path":"parts/body.glb","bytes":实际字节数,"sha256":"实际64位小写哈希"},
{"path":"parts/arm.glb","bytes":实际字节数,"sha256":"实际64位小写哈希"}
],
"parts": [
{"id":"body","file":"parts/body.glb","position":[0,0,0]},
{"id":"left","file":"parts/arm.glb","parentId":"body",
"position":[0.12,0.2,0],"quaternion":[0,0,0,1],"scale":[1,1,1],"installOffset":[0.08,0,0]},
{"id":"right","file":"parts/arm.glb","parentId":"body",
"position":[-0.12,0.2,0],"quaternion":[0,1,0,0],"installOffset":[-0.08,0,0]}
],
"steps": [
{"id":"s1","label":"安装主体","parts":["body"]},
{"id":"s2","label":"安装左臂","parts":["left"]},
{"id":"s3","label":"安装右臂","parts":["right"]}
]
}
上述 bytes、sha256 为文字占位,实际清单必须填真实数值和哈希。
制作约定:
- 使用静态、自包含、未压缩 GLB 2.0,贴图与缓冲区嵌入 GLB。
暂不支持骨骼动画、Draco / Meshopt 压缩、KTX2 贴图,需要时再接解码器。
- 统一单位米、GLB Y-up 坐标;源模型方向不同时可用 displayQuaternion 整体修正。
- parentId 省略 / null 表示总装根节点;position、quaternion、scale 相对父节点。
- quaternion 顺序 x,y,z,w,必须归一化;缺省 [0,0,0,1];scale 缺省 [1,1,1]。
- 保留正确局部原点。每个 GLB 如果已在总装坐标中,使用零位移根节点即可。
不要把各个 GLB 单独居中 / 缩放后丢失定位信息。前端只对整体统一取景。
- id 唯一,仅英文字母、数字、横线、下划线。同一 GLB 可复用为多个螺丝等实例。
- steps 可为空:显示整体。提供步骤则覆盖全部零件,每个各装一次,父零件先装或同一步装。
- installOffset 是安装开始位置相对最终位置的偏移,默认 [0,0.08,0]。
前端已实现逐步装配 / 查看整体、前后步骤切换,以及新增零件平移到最终位置。
本版不处理拧螺丝旋转、复杂轨迹、碰撞检测或 CAD 装配约束。
- 大型总装须控制面数和纹理尺寸;后续可增加分级模型与分步加载。
多个 GLB 不能自动说明如何安装。作者 / CAD 导出工具需要提供位姿、层级和步骤。
未来 AI 可以生成同一份 manifest,经作者校对后上传,不影响详情接口。
四、行走包
microduck-walking.zip:
manifest.json 类型、运行器版本、控制配置入口、文件清单
controller.json 关节顺序、默认姿态、维度、控制频率等
robot/mjlab/ 物理模型 XML、网格、运动学 JSON、GLB 等
policies/ 已训练、已导出的 ONNX 策略
assets/ 场景、音效等既有资源
LICENSE / NOTICE / UPSTREAM.md / README.txt
这是 Microduck 的资源,不是 Microban 的行走策略。
可临时挂在测试项目联调,但正式发布应绑定真正对应的机器人项目。
GLB 只解决显示;物理模型、关节映射、观测与动作语义必须和策略匹配。
运行流程:离线训练 -> 导出 ONNX、匹配的物理模型与配置 -> 打包上传 ->
前端固定运行器读取资源 -> MuJoCo WASM 仿真 + ONNX Runtime 推理 -> Three.js 显示。
不要上传 Python 训练环境、.pt/.pth 检查点、node_modules、浏览器脚本或 WASM 引擎。
训练不在浏览器进行。
目前只支持 runtimeProfile: microduck-alpha-v1、robotId: microduck-alpha、autoWalk: false。
文件路径按运行器约定保留,不可随意改名。14 维动作、61 维观测、13 维指令;
物理步长 0.005 秒、每 4 步推理一次(50 Hz)。controller.json 不匹配会拒绝启动。
ONNX 启动检查单输入 / 单输出、输出形状、有限数值及不同输入下的响应。
这些检查不能证明策略稳定,仍需算法团队验证真实的模型参数和控制效果。
其他机器人、其他观测预处理 / 动作后处理需要新增平台运行器适配,
不能只改 runtimeProfile、维度数字或 GLB 就兼容。协议可扩展,现有算法并非通用。
五、前端部署边界与验证
已接入两个字段、清单校验、动态资源目录、装配步骤和加载错误重试。
公共协议:js/experience-packages.js;行走适配:sandbox/src/game/package-config.js。
资源 SHA256 的真实核验由上传后端完成,浏览器不逐文件重算哈希。
浏览器校验结构和大小信息,装配 GLB 还检查实际字节数与自包含要求。
首次安装:npm --prefix sandbox ci
构建运行器:npm run build:walking
完整部署:npm run build,将 /play/microduck/ 与其他站点文件一起部署。
两个 ZIP 不包含运行器;上传包不能替代部署本次前端代码。
重新生成交付包:npm run package:experiences
生成多零件测试积木:node scripts/experience-fixtures.mjs
协议回归:npm run test:experiences
渲染 / 控制回归:npm --prefix sandbox test
本地服务:npm run dev
联调页:http://localhost:8091/examples/experience-preview.html
联调页使用真实加载组件,可填写后端地址,不修改远端项目;不包含在正式构建中。
两个 ZIP 已做解压与跨源加载验证。手机尺寸下检查界面,不等同于低配手机 / Windows 实机性能验收。
真实 OSS、上传接口和后端字段需要后端上线后联调;本地通过不代表生产接入已完成。