@nebula-spatial/studio 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -3
- package/dist/ai/contract.d.ts +73 -0
- package/dist/ai/host.d.ts +28 -0
- package/dist/asset/dependency-scan.d.ts +78 -0
- package/dist/asset/intake.d.ts +84 -0
- package/dist/asset/layout-detect.d.ts +40 -0
- package/dist/asset/media-type.d.ts +10 -0
- package/dist/asset/model-inspection.d.ts +127 -0
- package/dist/asset/record.d.ts +35 -0
- package/dist/asset/remote-asset-resolver.d.ts +36 -0
- package/dist/asset/repairs.d.ts +53 -0
- package/dist/asset/resource-locator.d.ts +15 -0
- package/dist/asset/revision-diff.d.ts +33 -0
- package/dist/asset/source-contracts.d.ts +21 -0
- package/dist/asset/source-paths.d.ts +15 -0
- package/dist/asset/usd-inspection.d.ts +39 -0
- package/dist/asset/usd-source-metadata.d.ts +142 -0
- package/dist/asset/visual-intake.d.ts +27 -0
- package/dist/asset/visual-record.d.ts +22 -0
- package/dist/asset/web-intake.d.ts +46 -0
- package/dist/asset-source-BExlEcRt.js +444 -0
- package/dist/assets/usd-export-worker-BsGubtAE.js +1 -0
- package/dist/builders-BAXRR5o5.js +1854 -0
- package/dist/core/asset-task.d.ts +105 -0
- package/dist/core/context.d.ts +23 -0
- package/dist/core/host.d.ts +432 -0
- package/dist/core/persistence-controller.d.ts +58 -0
- package/dist/core/plugins.d.ts +139 -0
- package/dist/core/scene-tree.d.ts +62 -0
- package/dist/core/versions.d.ts +2 -0
- package/dist/core/when.d.ts +13 -0
- package/dist/core/write-policy.d.ts +29 -0
- package/dist/delivery/build-plan.d.ts +2 -0
- package/dist/delivery/contracts.d.ts +362 -0
- package/dist/delivery/digest.d.ts +3 -0
- package/dist/delivery/evidence.d.ts +10 -0
- package/dist/delivery/export-evidence.d.ts +3 -0
- package/dist/delivery/index.d.ts +9 -0
- package/dist/delivery/prim-name.d.ts +17 -0
- package/dist/delivery/profile.d.ts +4 -0
- package/dist/doc/builders.d.ts +99 -0
- package/dist/doc/command.d.ts +195 -0
- package/dist/doc/domain-extensions.d.ts +34 -0
- package/dist/doc/node-facts.d.ts +87 -0
- package/dist/doc/physics-facts.d.ts +74 -0
- package/dist/doc/placement-policy.d.ts +71 -0
- package/dist/doc/random-placement.d.ts +30 -0
- package/dist/doc/scene-graph.d.ts +80 -0
- package/dist/doc/scene-regions.d.ts +29 -0
- package/dist/doc/schema.d.ts +452 -0
- package/dist/doc/task.d.ts +71 -0
- package/dist/doc/validate.d.ts +68 -0
- package/dist/editor/asset-source.d.ts +15 -0
- package/dist/editor/editor.d.ts +246 -0
- package/dist/editor/index.d.ts +22 -0
- package/dist/editor/shortcuts.d.ts +2 -0
- package/dist/editor/types.d.ts +143 -0
- package/dist/editor/ui-plugins.d.ts +64 -0
- package/dist/editor.js +1755 -0
- package/dist/editorial-BkAFWfbg.js +83 -0
- package/dist/export-evidence-B_0zRmb8.js +5027 -0
- package/dist/generalization/domain.d.ts +10 -0
- package/dist/generalization/generalization.d.ts +371 -0
- package/dist/generalization/index.d.ts +11 -0
- package/dist/generalization.js +1659 -0
- package/dist/history/undo-stack.d.ts +74 -0
- package/dist/index.d.ts +91 -0
- package/dist/index.js +2839 -0
- package/dist/persist/content-addressed.d.ts +11 -0
- package/dist/persist/create-scene-package-from-host.d.ts +7 -0
- package/dist/persist/indexeddb-store.d.ts +69 -0
- package/dist/persist/scene-file.d.ts +52 -0
- package/dist/persist/scene-package.d.ts +8 -0
- package/dist/persist/snapshot.d.ts +5 -0
- package/dist/physics-facts-tfQYyNTD.js +337 -0
- package/dist/placement-policy-DY_FNRDu.js +405 -0
- package/dist/ports/asset-ingestor.d.ts +41 -0
- package/dist/ports/asset-source.d.ts +57 -0
- package/dist/ports/delivery.d.ts +13 -0
- package/dist/ports/persistence.d.ts +29 -0
- package/dist/project/asset-catalog.d.ts +21 -0
- package/dist/project/contracts.d.ts +272 -0
- package/dist/project/editorial.d.ts +16 -0
- package/dist/project/identity.d.ts +20 -0
- package/dist/project/index.d.ts +9 -0
- package/dist/project/scene-document.d.ts +5 -0
- package/dist/project/source-dependencies.d.ts +7 -0
- package/dist/remote-asset-resolver-Cb8cfNmw.js +136 -0
- package/dist/scene/index.d.ts +12 -0
- package/dist/scene-graph-DBLKAhxa.js +681 -0
- package/dist/scene-session-BV1HnxNh.js +3506 -0
- package/dist/scene.js +244 -0
- package/dist/studio/delivery-catalog.d.ts +28 -0
- package/dist/studio/in-memory-asset-source.d.ts +15 -0
- package/dist/studio/index.d.ts +31 -0
- package/dist/studio/indexeddb-asset-source.d.ts +32 -0
- package/dist/studio/indexeddb-persistence.d.ts +13 -0
- package/dist/studio/remote-asset-importer.d.ts +56 -0
- package/dist/studio/source-package.d.ts +9 -0
- package/dist/studio/usd-export-client.d.ts +13 -0
- package/dist/studio/usd-export-protocol.d.ts +98 -0
- package/dist/studio/usd-export-worker.d.ts +1 -0
- package/dist/studio/usd-zip-reader.d.ts +14 -0
- package/dist/studio/web-asset-ingestor.d.ts +10 -0
- package/dist/studio/web-host.d.ts +8 -0
- package/dist/studio.js +5544 -0
- package/dist/util/asset-facts.d.ts +3 -0
- package/dist/util/data.d.ts +17 -0
- package/dist/util/diagnostics.d.ts +38 -0
- package/dist/util/geometry.d.ts +11 -0
- package/dist/util/hash.d.ts +9 -0
- package/dist/util/ids.d.ts +20 -0
- package/dist/util/math.d.ts +47 -0
- package/dist/util/ply-metadata.d.ts +19 -0
- package/dist/util/studio-source.d.ts +23 -0
- package/dist/version.d.ts +5 -0
- package/dist/view/appearance.d.ts +13 -0
- package/dist/view/authoring-appearance.d.ts +25 -0
- package/dist/view/bounds-preview.d.ts +34 -0
- package/dist/view/bounds.d.ts +11 -0
- package/dist/view/camera-zoom.d.ts +3 -0
- package/dist/view/geometry-anchors.d.ts +20 -0
- package/dist/view/gizmo-appearance.d.ts +5 -0
- package/dist/view/gizmo.d.ts +81 -0
- package/dist/view/group-selection.d.ts +13 -0
- package/dist/view/node-features.d.ts +39 -0
- package/dist/view/picking.d.ts +49 -0
- package/dist/view/placement.d.ts +48 -0
- package/dist/view/region-editing.d.ts +25 -0
- package/dist/view/rotation-guide.d.ts +36 -0
- package/dist/view/runtime-capabilities.d.ts +22 -0
- package/dist/view/scene-session.d.ts +258 -0
- package/dist/view/screen-bounds.d.ts +17 -0
- package/dist/view/selection-transform.d.ts +20 -0
- package/node_modules/@nebula-spatial/cad-loader/CHANGELOG.md +48 -0
- package/node_modules/@nebula-spatial/cad-loader/README.md +108 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/cad-types.d.ts +26 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/errors.d.ts +5 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/index.d.ts +24 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/index.js +2354 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/bin-group-reader.d.ts +9 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/bin-parser.d.ts +78 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/dxbs-sidecar.d.ts +24 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/geometry-segments.d.ts +20 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/text-roundtrip.d.ts +4 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/types.d.ts +81 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/runtime-text-decoder.d.ts +8 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/types.d.ts +153 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/utils/insert-bbox.d.ts +10 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/core/utils/viewport-rect.d.ts +21 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/index.d.ts +36 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/index.js +5829 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/geo-loader.d.ts +59 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/automatic-external-resources.d.ts +26 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/external-variant-sidecar-fetch.d.ts +13 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/flow-control.d.ts +29 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/frame-budget-scheduler.d.ts +21 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-compact-executor.d.ts +19 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-local-adapter.d.ts +2 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-pipeline.d.ts +92 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-worker-adapter.d.ts +13 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node-builder.d.ts +34 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node-load-sink.d.ts +28 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node.d.ts +304 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare-worker-types.d.ts +94 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare.d.ts +38 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare.worker.d.ts +1 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/insert-model-builder.d.ts +10 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/insert-runtime-geometry.d.ts +15 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/line-canonical.d.ts +37 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/line-quality.d.ts +9 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/prepare-credit-gate.d.ts +20 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/transport.d.ts +2 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/render-resource/cad-render-node.d.ts +80 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/render-resource/geo-node-cad-render-node.d.ts +12 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/scene/geo-cad-line-geometry.d.ts +28 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/scene/geo-cad-line-material.d.ts +18 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/block-geometry-registry.d.ts +35 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/insert-instance-table.d.ts +23 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/viewport-instance-presenter.d.ts +66 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/selection/cad-insert-selection.d.ts +35 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/selection/cad-text-selection.d.ts +31 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/annotation-idle-gate.d.ts +14 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-document-session.d.ts +187 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-font-runtime.d.ts +11 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-insert-id.d.ts +6 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-text-warmup.d.ts +38 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/create-cad-document-session.d.ts +5 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/load-session.d.ts +90 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/session/viewport-coverage.d.ts +32 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/abort.d.ts +3 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/cad-display-color.d.ts +55 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/cad-load-source.d.ts +8 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/color-buffer.d.ts +6 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/constants.d.ts +11 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/display-color-buffer.d.ts +27 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/errors.d.ts +2 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/text-builder.d.ts +25 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/text-font.d.ts +12 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/types.d.ts +57 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/insert-bbox.d.ts +1 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/timing.d.ts +2 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/viewport-rect.d.ts +1 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/shared/viewer-theme.d.ts +2 -0
- package/node_modules/@nebula-spatial/cad-loader/dist/workers/geo-prepare.worker.js +2264 -0
- package/node_modules/@nebula-spatial/cad-loader/package.json +62 -0
- package/node_modules/@nebula-spatial/viewer/CHANGELOG.md +426 -0
- package/node_modules/@nebula-spatial/viewer/FBX-MATERIAL-CONVERSION.md +97 -0
- package/node_modules/@nebula-spatial/viewer/README.md +1056 -0
- package/node_modules/@nebula-spatial/viewer/USD-VISUAL-MATERIAL-SUPPORT.md +89 -0
- package/node_modules/@nebula-spatial/viewer/basis/basis_transcoder.js +19 -0
- package/node_modules/@nebula-spatial/viewer/basis/basis_transcoder.wasm +0 -0
- package/node_modules/@nebula-spatial/viewer/dist/asset-ir-DEOK9SqE.js +382 -0
- package/node_modules/@nebula-spatial/viewer/dist/assets/ground-grid.d.ts +6 -0
- package/node_modules/@nebula-spatial/viewer/dist/assets/source-types.d.ts +19 -0
- package/node_modules/@nebula-spatial/viewer/dist/assets/types.d.ts +393 -0
- package/node_modules/@nebula-spatial/viewer/dist/assets/usd-worker-Bom5cjz3.js +1392 -0
- package/node_modules/@nebula-spatial/viewer/dist/cad/text.d.ts +2 -0
- package/node_modules/@nebula-spatial/viewer/dist/cad/types.d.ts +368 -0
- package/node_modules/@nebula-spatial/viewer/dist/index-ByBlfVc0.js +12132 -0
- package/node_modules/@nebula-spatial/viewer/dist/index.d.ts +32 -0
- package/node_modules/@nebula-spatial/viewer/dist/index.js +26 -0
- package/node_modules/@nebula-spatial/viewer/dist/inspection/types.d.ts +112 -0
- package/node_modules/@nebula-spatial/viewer/dist/mjcf-visual-DVRa0w90.js +72 -0
- package/node_modules/@nebula-spatial/viewer/dist/mujoco-runtime-Dhx6Ua2u.js +463 -0
- package/node_modules/@nebula-spatial/viewer/dist/plugins.d.ts +179 -0
- package/node_modules/@nebula-spatial/viewer/dist/scene/instances.d.ts +36 -0
- package/node_modules/@nebula-spatial/viewer/dist/scene/types.d.ts +258 -0
- package/node_modules/@nebula-spatial/viewer/dist/session-B-j6KdA-.js +389 -0
- package/node_modules/@nebula-spatial/viewer/dist/session-B4AICTeJ.js +963 -0
- package/node_modules/@nebula-spatial/viewer/dist/session-BAG5cDYe.js +9153 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/mujoco-runtime.d.ts +118 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/mujoco-wasm-module.d.ts +11 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/openusd-wasm-module.d.ts +10 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/physics-runtime-state.d.ts +75 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/types.d.ts +129 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-inspection.d.ts +66 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-query.d.ts +50 -0
- package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-resource-policy.d.ts +28 -0
- package/node_modules/@nebula-spatial/viewer/dist/types.d.ts +278 -0
- package/node_modules/@nebula-spatial/viewer/dist/ui/types.d.ts +48 -0
- package/node_modules/@nebula-spatial/viewer/dist/urdf-session-kemAnBn8.js +3231 -0
- package/node_modules/@nebula-spatial/viewer/dist/usd-session-QtwGKI7v.js +6771 -0
- package/node_modules/@nebula-spatial/viewer/dist/version.d.ts +5 -0
- package/node_modules/@nebula-spatial/viewer/dist/viewer.d.ts +2 -0
- package/node_modules/@nebula-spatial/viewer/dist/xacro-CYTPS7mh.js +1537 -0
- package/node_modules/@nebula-spatial/viewer/openusd/openusd-runtime-manifest.json +15 -0
- package/node_modules/@nebula-spatial/viewer/openusd/openusd_probe.js +14 -0
- package/node_modules/@nebula-spatial/viewer/openusd/openusd_probe.wasm +0 -0
- package/node_modules/@nebula-spatial/viewer/package.json +66 -0
- package/package.json +87 -6
package/README.md
CHANGED
|
@@ -1,3 +1,206 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# @nebula-spatial/studio
|
|
2
|
+
|
|
3
|
+
> 更新时间:2026-11-17。
|
|
4
|
+
|
|
5
|
+
可嵌入的场景编辑 SDK:维护纯数据场景文档、资产版本、命令和历史,通过唯一 Viewer 会话提供真实 USD / GLB 加载、选择、框选、frame/尺寸 facts、group gizmo、真实表面放置、OBB 禁止重叠、离屏截图、相机和可用的 MuJoCo 预演。
|
|
6
|
+
|
|
7
|
+
**SDK 不交付默认业务页面。** 左侧资产库、顶栏流程、右侧属性 / 检查 / 泛化面板及 HTML toolbar 位于 [`playground/sim-studio/`](../../playground/sim-studio/),用于本地验证 SDK 的上层组合能力。Playground 不是业务层,也不引入业务系统依赖;业务应用通过公开 API 注册自己的视图和适配器。
|
|
8
|
+
|
|
9
|
+
技术契约见 [data-model.md](../../docs/sim-studio/data-model.md),分工及可运行的插件接入示例见 [sdk-boundaries.md](../../docs/sim-studio/sdk-boundaries.md),资源接入见 [asset-source-integration.md](../../docs/sim-studio/asset-source-integration.md)。
|
|
10
|
+
|
|
11
|
+
`editor-ui` 和 `editor-workbench` 是长期 UI 产品化候选,短期不实施、不发布。当前版本继续提供 Headless SDK 和三个可选 UI 挂载槽位。槽位是消费方的接入合约,不是 SDK 页面标准,也不携带默认布局、业务导航或固定交互;页面尚未确定时不要求先扩张槽位。完整方向见 [SDK 当前架构与未来重构方向](../../docs/sim-studio/sdk-refactor-direction.md)。
|
|
12
|
+
|
|
13
|
+
## 本地调试
|
|
14
|
+
|
|
15
|
+
在仓库根目录运行:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install
|
|
19
|
+
npm run dev:sim-studio
|
|
20
|
+
# http://127.0.0.1:8320/sim-studio/
|
|
21
|
+
|
|
22
|
+
npm run build:sim-studio # Playground 网页
|
|
23
|
+
npm run build:sim-studio:package # 按依赖顺序构建 SDK 与公开类型
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Playground 首次进入为空场景;内置目录及加载逻辑位于 `playground/sim-studio/public-models.ts`、`public-catalog.ts`,按需读取 `web/public/models/` 中的真实资产。前端也可选择本地文件、文件夹、ZIP 或 USDZ 入库。选中的 USDZ 会先展开为内部 USD 层和纹理依赖,避免导出时形成缺失纹理闭包的嵌套包;opaque USDC 则保留完整显式 package closure。资产目录和网页样式不进入 SDK 发布包。
|
|
27
|
+
|
|
28
|
+
## 分层与公开入口
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
playground/sim-studio 本地验证页面、验证编排、资产目录、UI plugins
|
|
32
|
+
├─ /studio → StudioHost 文档、命令、历史、资产与持久化
|
|
33
|
+
└─ /editor → StudioEditor 画布控制、状态、动作、锚点和多选提交
|
|
34
|
+
├─ UI plugin host 可选挂载器;无默认面板、图标和页面布局
|
|
35
|
+
└─ /scene → Viewer 唯一 renderer / camera / RAF、拾取和手柄
|
|
36
|
+
/generalization 可选 Sim Studio 领域入口与版本化文档扩展
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
| 入口 | 能力 |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `@nebula-spatial/studio` | 场景数据、命令 builder、node/selection frame、尺寸、placement 与 physics facts、私有场景包、`UsdDeliveryPlanV4`、asset catalog、四个领域端口合同 |
|
|
42
|
+
| `@nebula-spatial/studio/studio` | `StudioHost`、Web/IndexedDB/in-memory adapters、delivery catalog resolution、Core 插件 |
|
|
43
|
+
| `@nebula-spatial/studio/editor` | `createStudioEditor`、`StudioEditor`、Action reader/commit、placement、截图类型、toolbar / overlay、`createStudioUiPluginHost` |
|
|
44
|
+
| `@nebula-spatial/studio/scene` | 低层 `createStudioSceneSession`、surface picking、capture 和 physics facts,供高级宿主使用 |
|
|
45
|
+
| `@nebula-spatial/studio/generalization` | Family / Region / Contract / Sample、领域校验和 `GENERALIZATION_DOMAIN_EXTENSION`;不从根入口导出 |
|
|
46
|
+
|
|
47
|
+
`/workbench` 入口已移除,`createStudioWorkbench` 和 perspective 定义属于 Playground。原集成方应改为 `/editor`,自行挂载页面或注册 UI plugin;不要从 SDK 反向导入 Playground。`core/` 不依赖 DOM、Viewer、JSZip 或具体 Web intake;纯数据层不依赖渲染库,构建前运行边界检查。
|
|
48
|
+
|
|
49
|
+
领域端口只在根入口公开:
|
|
50
|
+
|
|
51
|
+
- `StudioAssetSourceProvider`:按 revision 解析、注册、materialize 和释放 source;`register()` 返回 `created | reused`,同 revision 不同 facts 必须抛 `SOURCE_REVISION_CONFLICT`。Host 会在注册前对照 revision resources 校验 entry、path set、SHA-256、byteSize 和 mediaType,不匹配时抛 `ASSET_SOURCE_FACTS_MISMATCH`。浏览器空 `Blob.type` / 通用 MIME 走 asset 层共享路径推断;URL source 可省略 byteSize/mediaType,由 revision 权威事实补齐。
|
|
52
|
+
- `StudioAssetIngestor`:把调用方已经取得的文件转成确定的 revision/source 事实,不负责搜索、鉴权或下载。
|
|
53
|
+
- `StudioPersistenceAdapter`:读取和保存确定的 `StudioStateSnapshot`。
|
|
54
|
+
- `StudioDeliveryProvider`:把一个 visual source 转成一个目标 profile 的 delivery artifact。
|
|
55
|
+
|
|
56
|
+
`StudioHost` 不创建默认 asset source provider。调用方注入的 persistence / asset source provider 默认不由 Host 拥有;只有显式设置 `ownsPersistence` / `ownsAssetSourceProvider` 才负责 dispose。`/studio` 的 `createWebStudioHost()` 会显式安装 in-memory provider,或使用调用方提供的 IndexedDB/平台 provider,并只拥有自己创建的对象。`openSceneText()` 是异步入口,会顺序等待全部 source 注册完成后才替换文档;失败、取消或场景代次过期时只释放本轮 `created` source。
|
|
57
|
+
|
|
58
|
+
Visual 交付按独立异步编排执行:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
source catalog
|
|
62
|
+
-> resolveUsdDeliveryCatalog()
|
|
63
|
+
-> buildUsdDeliveryPlan()
|
|
64
|
+
-> encodeUsdDeliveryPackage()
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`buildUsdDeliveryPlan()` 仍是纯函数,不接触 provider、fetch、Blob 或 Host。runtime projection facts 由真实 `SceneSession` 发布并由 Editor 消费,Host 不持有第二套 runtime 状态。
|
|
68
|
+
|
|
69
|
+
当前 Schema v7 使用 `SceneDocument.domains` 保存版本化领域 payload,并使用受控 `domain` 节点承载需要场景树、选择、变换和 bounds 的领域对象。`AssetProvenance.externalRef` 和 `ScenePlaceholderNode.externalRef` 保存业务平台引用,不参与资源解析或节点寻址。未注册领域扩展时 Host 原样保存并在事务中给出 warning,导出时升级为 error;需要深度校验、规范化和导出门禁时,在 Host 选项中注册领域扩展。泛化注册 `GENERALIZATION_DOMAIN_EXTENSION`,其他领域使用同一 `StudioDocumentDomainExtension` 契约。普通加载只接受当前 Schema;旧文档、旧命令和旧 Editor API 不提供运行时迁移或兼容。
|
|
70
|
+
|
|
71
|
+
## 初始化编辑器
|
|
72
|
+
|
|
73
|
+
宿主创建容器与 canvas,配置 asset source provider / 持久化适配器,再把 `host` 传入控制器:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
import { createWebStudioHost } from '@nebula-spatial/studio/studio';
|
|
77
|
+
import { createStudioEditor } from '@nebula-spatial/studio/editor';
|
|
78
|
+
|
|
79
|
+
const viewport = document.createElement('div');
|
|
80
|
+
viewport.style.cssText = 'position:relative;width:100%;height:600px';
|
|
81
|
+
const canvas = document.createElement('canvas');
|
|
82
|
+
canvas.style.cssText = 'display:block;width:100%;height:100%';
|
|
83
|
+
viewport.append(canvas);
|
|
84
|
+
document.body.append(viewport);
|
|
85
|
+
|
|
86
|
+
const host = createWebStudioHost();
|
|
87
|
+
const editor = createStudioEditor({ host, viewport, canvas, ownsHost: true });
|
|
88
|
+
await editor.ready; // Promise 属性,不是 ready() 方法
|
|
89
|
+
|
|
90
|
+
const unsubscribe = editor.subscribe((event) => {
|
|
91
|
+
// 所有 Editor 事件携带完整快照;不存在 event.payload。
|
|
92
|
+
console.log(event.type, event.snapshot.toolbar);
|
|
93
|
+
}, { emitCurrent: true });
|
|
94
|
+
|
|
95
|
+
editor.setBoxSelectionEnabled(true);
|
|
96
|
+
editor.session.fit(); // 低层画布能力通过同一 session 调用,不创建第二个会话
|
|
97
|
+
|
|
98
|
+
// 页面卸载时:
|
|
99
|
+
// unsubscribe();
|
|
100
|
+
// await editor.dispose(); // ownsHost 为 true 时同时释放 host
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`StudioEditor` 内部同步 Host 文档、选择和临时 editorial 状态,处理拾取、框选以及多选变换批量命令。前端不再在 `onTransform` 中推算其他对象,也不重复订阅 Host 后调用 `session.sync()`。`sessionOptions` 是完成默认行为后的观察回调,不应再次提交同一变换或选择。
|
|
104
|
+
|
|
105
|
+
Playground 的隔离 sample 预览使用 `editor.setPreviewDocument(document)`,退出时传 `null`;不覆盖 Host 的基础文档。预览期间文档修改不可执行。
|
|
106
|
+
|
|
107
|
+
编辑器级只读浏览使用 `editor.setPreviewMode(true)`,退出时传 `false`。默认 `previewSelection: 'none'`,不响应模型选择;传 `{ selection: 'inspect' }` 或调用 `editor.setPreviewSelection('inspect')` 后允许只读点选和属性查看。两种选择策略都会禁用变换手柄、框选与所有文档 / editorial / asset 写入;绕过 UI 直接写 Host 也会返回 `PREVIEW_READ_ONLY`。它与仅替换显示文档的 `setPreviewDocument()` 相互独立。
|
|
108
|
+
|
|
109
|
+
## UI 插件和 toolbar
|
|
110
|
+
|
|
111
|
+
UI 插件宿主不是 SDK 自带的 UI,也不生成默认按钮或面板。它是消费方 UI 的可选接入协议:业务先创建槽位 DOM,再由插件把自有视图挂载进去,SDK 负责快照更新、生命周期、异常隔离和清理。
|
|
112
|
+
|
|
113
|
+
可选 `createStudioUiPluginHost({ editor, slots })` 提供三个命名槽位:
|
|
114
|
+
|
|
115
|
+
- `inspector`:右侧属性、检查、运行时、泛化等前端面板。
|
|
116
|
+
- `scene-toolbar`:固定的画布 / 场景控制栏,可由前端分成多个 bar。
|
|
117
|
+
- `selection-toolbar`:单选或多选后出现的对象 toolbar。
|
|
118
|
+
|
|
119
|
+
前端创建槽位容器并决定页面位置。插件使用 `contributions.addView({ id, slot, mount })` 挂载视图;`mount` 可返回 `update(context)`、`dispose()`,宿主在 SDK 事件到来时传递完整快照。注册返回卸载函数;`start()` 激活,`dispose()` 卸载视图和订阅,但不释放 editor。完整示例见 [UI 插件接入](../../docs/sim-studio/sdk-boundaries.md#ui-插件接入示例)。
|
|
120
|
+
|
|
121
|
+
插件只负责 DOM、按钮、Tooltip、响应式布局及 toolbar 拖拽偏移。SDK 提供 `editor.getToolbarState()` / `getSnapshot().toolbar`:
|
|
122
|
+
|
|
123
|
+
- `scene.actions` 与 `object.actions` 描述动作的 `visible`、`enabled`、`active`、`valueState`、`busy`、原因和明确目标。
|
|
124
|
+
- `object.overlay` 提供 viewport 内 CSS 像素锚点、显隐原因、场景会话、选择版本及顺序号。
|
|
125
|
+
- 无选择、框选、模型变换、相机运动、禁止编辑或预览模式时对象 toolbar 隐藏;恢复前 SDK 更新姿态和锚点。场景栏保留,通过动作状态禁用冲突操作。
|
|
126
|
+
- 前端将 `visible: false` 的按钮隐藏,将 `enabled: false` 的可见按钮禁用;只能进一步收紧,不能擅自启用。
|
|
127
|
+
- 点击通过 `editor.executeAction({ actionId, targetIds, expectedSceneSessionId, expectedSelectionVersion })` 执行;前端保留生成按钮时的上下文,不在确认框返回后替换成新选择。
|
|
128
|
+
|
|
129
|
+
当前对象动作支持移动 / 旋转 / 缩放、复制、删除、锁定、editorial hide、authored visible 和聚焦。混合锁定选择的变换、复制、删除显式返回 `execution: 'eligible-subset'`、实际 `targetIds` 与 `excludedTargets`;锁定动作覆盖整个有效选择,`valueState` 表示 on / off / mixed。Host / Editor 支持选择 group,Editor API 与 transform toolbar 可整体变换 group,子级 world transform、undo/redo 和场景树选择保持同步。祖先 group 的 hidden / locked editorial 状态向后代继承,锁定后代会在 Host inspect/commit 最终边界阻止 group 删除、复制、重排或变换。多选同时包含 ancestor group 和 descendant 时,动作 targetIds 使用 ancestor 闭包,每个场景对象只变换、复制、删除或分组一次;直接选中 group 可锁定和解组 group 自身,ungroup 可通过 history undo 恢复层级。
|
|
130
|
+
|
|
131
|
+
画布中的变换手柄、选中高亮、框选矩形、吸附和相机运动属于 SDK;已有模型仅通过可见手柄变换,直接拖动模型表面不改变姿态。插件 UI 的指针事件必须与画布隔离,拖 toolbar 不能拖动模型或取消选择。
|
|
132
|
+
|
|
133
|
+
Editor 只把 Placement Region 的最终 frame / shape 手势转发给消费方,不直接写文档,也不拥有泛化业务语义。`resolveRegionOverlays` 把领域数据投影成中立 overlay;消费方根据回调生成正式领域命令。外部命令在活动手势期间拒绝执行,隔离预览期间写入和变换手柄禁用。
|
|
134
|
+
|
|
135
|
+
本地 Playground 保留左侧面板与顶栏,`createStudioWorkbench(root, { uiPlugins })` 可替换三个默认插件,某一项传 `null` 可关闭对应 UI。该页面工厂不属于发布 SDK。
|
|
136
|
+
|
|
137
|
+
## 场景编辑 authoring API
|
|
138
|
+
|
|
139
|
+
- `getNodeFrame()` / `getSelectionFrame()` / `getAssetDimensions()` 返回冻结 facts;group bounds 由后代聚合。`sourceOrigin` 是资产内容坐标原点,`origin.local` 是实例真实 pivot,默认 `[0,0,0]`;作者 Prim pivot 无可靠证据时仍是 `unknown`。
|
|
140
|
+
- `setNodeOrigin()` 保存实例级真实 pivot,并原子调整节点根位姿以保持模型世界位姿不变;pivot 语义为 `pivot-root TRS × translate(-origin.local)`,旋转、缩放、渲染、物理源位姿和 USD 交付共用该语义。`setNodeUpDirection()` 复用四元数 transform 写入,不复制朝向状态。
|
|
141
|
+
- `NODE_ORIGIN_PRESETS` / `nodeOriginPresetLocal()` 提供 23 个快捷锚点:源模型原点、包围盒中心、底面/顶面中心、X/Y 各侧中心、长短边面及长/短边底部/顶部中心、几何中点 Median、表面质心和体积质心;这些只是计算 pivot 的快捷方式,不形成第二套持久化 policy。
|
|
142
|
+
- Median、表面质心和体积质心来自 `scene.measureNodeOriginAnchors()` 的运行时几何测量。测量按节点缓存,不进入 RAF;Median 是顶点算术平均,表面质心按三角面积加权,体积质心按有符号四面体体积加权并假设均匀密度。开放表面也会尝试计算;体积积分退化时回落到表面质心,没有有效三角面时再回落到 Median。
|
|
143
|
+
- Authoring overlay 在单选或多选时用橙色圆点标出每个已选节点的 effective `origin.world`;取消选择、进入区域模式或只读状态时隐藏。`Alt+拖拽` 橙色圆点可把 pivot 设置到几何命中点或相机平行平面上的点,提交时仍走一次普通文档命令和 undo/redo;取消手势不写入文档。
|
|
144
|
+
- `setNodeDimensions()` 只修改单实例 scale,支持 node-origin / bounds-center 锚点,不改变共享 asset revision。
|
|
145
|
+
- `changeTransform()` 显式接受 `space` 与 `scope`;group 与后代选择去重,不能表达 shear 时拒绝。
|
|
146
|
+
- `pickPlacementSurface()` 返回真实 Mesh hit point/normal;`prepareAssetPlacement()`、`prepareNodePlacement()` 生成绑定文档版本和 policy 的 plan,`commit*Placement()` 重新校验后提交。
|
|
147
|
+
- placement policy 支持 grid、surface snap/alignment、禁止重叠、clearance 和 tolerance。禁止重叠使用 15 轴 OBB SAT,是保守 bounds 精度,不是三角网格碰撞认证。
|
|
148
|
+
- `getPhysicsFacts()` 分层返回 authored、asset inspection 和 MuJoCo runtime facts;未知 mass/COM/inertia/axis 不猜测。
|
|
149
|
+
- authored preset/HDR、背景、强度、旋转和灯光仍可保存在文档中,但当前 `sync()` 不把它们投影到 Viewer;环境 capability 为 `not-applied`。
|
|
150
|
+
- `captureViewport()` 支持 PNG/JPEG/WebP、尺寸、crop、背景、全场景/选区 framing、overlay、取消和串行执行,并在失败后恢复 Renderer/overlay 状态。`scope` 支持 `viewport`、`selection` 和 `scene`;Playground 顶部工具栏截图保持当前视角,场景设置中的截图按钮可按所选模式执行一次截图,SDK 调用本身不修改用户相机。
|
|
151
|
+
|
|
152
|
+
Asset placement intent 的 `importShape` 支持 `object | scene-group`。scene-group 只创建一个 group 和一个源引用子节点,不展开 USD 内部 Prim;revision/source 与节点处于同一原子 receipt,重放幂等,payload 变化返回 `IDEMPOTENCY_CONFLICT`。
|
|
153
|
+
|
|
154
|
+
## Core 插件与资源边界
|
|
155
|
+
|
|
156
|
+
UI 插件与 `StudioHostOptions.corePlugins` 是两套扩展契约:
|
|
157
|
+
|
|
158
|
+
- UI plugin 用于 HTML 视图挂载;API version 为 `STUDIO_UI_PLUGIN_API_VERSION`。
|
|
159
|
+
- Core plugin 使用 manifest / 版本 / 依赖 / activation event,提供 action、checker、inspector 数据 provider 和 exporter。Core inspector 贡献点不直接渲染右侧 DOM。
|
|
160
|
+
- Core action 执行时只获得受限 facade。`studio.commit()` 自动绑定 action 启动时的 document / scene / selection / target 上下文,并拒绝 abort、取消、卸载或 dispose 后的迟到提交;Editor 写策略不可被插件清除。selection action 的目标校验区分既有节点写入、父级结构授权和同 batch 新建节点;`node.add` / `node.duplicate` 的新 ID 属于回执而不是输入 allowlist。
|
|
161
|
+
- Editor Action 的 `context.editor` 是只读 `StudioEditorActionReader`,只提供 snapshot、frame、尺寸和 physics facts。正式写入必须调用绑定的 `context.commit(commands)`;一次 action 只允许一次成功事务,迟到或重复提交返回 `ACTION_CANCELLED`、`CONTEXT_STALE` 或 `ACTION_ALREADY_COMMITTED`。
|
|
162
|
+
|
|
163
|
+
资产搜索、分类、权限、缩略图、版本选择和 AI 服务调用由前端 / 业务平台负责。SDK 接收已确定的版本及 `StudioAssetSource`(`local-package` 或 `remote-entry`),资源身份统一使用 `package-path` / `remote-url` locator。远端入口 URL 的 query 只用于当前 transport,不写入场景文档或 source index。`StudioSourceBundle` 是检查或 archive 的物化字节表示,已经公开导出,但不是第二套入场接口。
|
|
164
|
+
|
|
165
|
+
锁定和临时隐藏仍属于会话 editorial 状态,未作为普通文档命令保存或撤销。UI 应调用 Editor 的动作 / 修改入口以获得编辑保护;`editor.host` 和 `editor.session` 仍作为受控低层接入能力存在,但 Action 回调和普通业务插件应使用 facts + `context.commit()`,直接调用低层对象时宿主承担版本、锁定和取消编排责任。
|
|
166
|
+
|
|
167
|
+
## 现有工作流与限制
|
|
168
|
+
|
|
169
|
+
Playground 保留搭建、检查、泛化、仿真与交付验证入口,以及资产导入、属性 / USD 来源信息、检查诊断、Family / Region / Contract / Sample 编辑、随机静态预览和 IndexedDB 本地调试。这些入口用于验证 SDK 的支撑能力,不属于业务层,也不作为 SDK 内置页面发布。
|
|
170
|
+
|
|
171
|
+
已有 M1 垂直闭环:SceneDocument v9 JSON 序列化、`sim-studio.scene-package@5` 私有场景包、资产目录 v3、resource manifest v2、`UsdDeliveryPlanV4` 和独立 OpenUSD WASM exporter 的 USDA / USDC / USDZ 交付及回读 evidence。**GLB → USD 编译不在 SDK 内;visual 节点必须引用已解析 delivery artifact,否则 blocked。** 远端 native USD 在离线导出前 blocked,必须先 materialize 本地资源闭包。远端 revision diff 是纯函数 `diffAssetRevisions()`;默认 notify/update policy 留在业务层。已在 Studio UI 中完成 G2、EPAL、塑料栈板、冰红茶和 X1 的 USDZ 导出及 local-viewer 导入验证;G2 保留源资产自身的材质连接 warning。Isaac Sim 实际运行、cooking、contact/task 和 NVIDIA 外部认证仍保持 `not_run`;本地 OpenUSD/Storm 通过不能替代这些结论。
|
|
172
|
+
|
|
173
|
+
框选已有基础屏幕包围范围相交选择,支持追加且可选择被遮挡的可见实例;group / ungroup / reparent、组级选择、整体 gizmo 和锁定子树事务保护已有 SDK action/API 和回归测试。资产与节点的 surface placement plan、OBB 禁止重叠和 stale 校验已提供;连续放置、阵列和场景随机摆放仍需后续实现。Action Registry、Action 只读上下文/一次性 commit、simulation action 与 Core/Editor action 桥接已经完成。
|
|
174
|
+
|
|
175
|
+
资产导入使用 prepare → source provider persist → commit 任务边界。task AbortController 覆盖 intake、provider await 和 commit;partial 任务按 item receipt 只重试 failed/cancelled 项,visual 失败保留原始 visual revision/source。`stale` 批次不可重试,必须在当前场景重新 prepare。source provider 通过 revision + operation 级 `acknowledge()` 清除已恢复失败,不做全局清错。
|
|
176
|
+
|
|
177
|
+
无 `placementIntents` 的 `commitPreparedAsset()` 保持 `asset-library` scope,只注册 revision/source。显式传入非空 intents 时进入 `scene-import` scope,并按 prepared item 将资产/视觉 revision 注册与 `node.add` 放进同一 Host command batch/history transaction;receipt 返回真实 `createdNodeIds`。非空 intents 必须一一覆盖本批 prepared items,遗漏或重复会返回 `PLACEMENT_INTENT_INVALID`。相同 operation/item 重放不重复创建节点,payload 变化返回 `IDEMPOTENCY_CONFLICT`,partial 后只重试 failed/cancelled item。
|
|
178
|
+
|
|
179
|
+
`SceneDocument` 当前使用 schema v9,`SceneNode` 包含 group / asset / visual / placeholder / domain,并可用可选 `origin: { local }` 保存实例级真实 pivot;缺省即源模型原点。`AssetResource`、source、catalog、scene package 和 delivery 都使用 locator;placeholder 与 asset provenance 可带 `externalRef`;节点替换统一使用 `node.replaceModel`,支持 asset / placeholder 之间四种转换。普通加载对旧版及更高版本明确拒绝,不执行推测迁移。
|
|
180
|
+
|
|
181
|
+
**能力边界:** placement intent 可把一个 prepared revision/source 导入为独立对象或 scene-group。scene-group 只创建一个 group 和一个源引用子节点,不展开 USD 内部 Prim;相机落点、平台目录搜索/权限、推荐位置和业务卡片仍由消费方负责。OBB 禁止重叠是保守几何约束,不是网格或物理引擎碰撞认证。
|
|
182
|
+
|
|
183
|
+
SceneDocument 可保留非均匀父 scale 与旋转子节点的层级 TRS;`UsdDeliveryPlanV4` 按 nested group Xform 和 local TRS 编码。只有实际 flatten 到单个 TRS 的 Viewer placement、world-preserving reparent/ungroup 或 world-space gizmo 回写在矩阵含 shear 时明确拒绝为 `TRANSFORM_NOT_REPRESENTABLE`,不会静默近似。Editor API 与 group gizmo 在写 history 前先应用候选 command batch 并检查扁平投影;如果 group 新 TRS 会让 rotated descendant 新增 shear,则拒绝提交,文档、历史和 SceneSession 不进入半成功状态。
|
|
184
|
+
|
|
185
|
+
当前 Viewer 继续使用既有 room 环境,文档中的 preset/HDR、背景、强度、旋转和灯光不会覆盖它。MuJoCo 的 `physicsOverride` / `initialPose` 主投影为 `applied`,支持 motion、collider、mass、COM、drive 和 scalar initial pose;`physicsMaterial` 子能力为 `partial`,restitution 和不同静/动摩擦明确拒绝。配置失败不会回退到旧单实例运行时,也不代表完整 USD 编译、PhysX 或 Isaac Sim 认证。
|
|
186
|
+
|
|
187
|
+
## 验证与 CLI
|
|
188
|
+
|
|
189
|
+
在包目录运行:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
npm test
|
|
193
|
+
npm run typecheck
|
|
194
|
+
npm run check:boundary
|
|
195
|
+
npm run check:retired-api
|
|
196
|
+
npm run check:public-api
|
|
197
|
+
npm run build
|
|
198
|
+
|
|
199
|
+
npm run intake -- <资产目录> --out library.json
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`check:public-api` 比较五个入口排序后的 value/type symbol snapshot。新增或删除公开 symbol 必须显式更新 `public-api.snapshot.json` 并接受审查,不能靠 barrel 自动扩大。
|
|
203
|
+
|
|
204
|
+
开发 Playground 在 `window.simStudio` 暴露调试句柄,生产不暴露。
|
|
205
|
+
|
|
206
|
+
目标不变量:SceneDoc 为纯数据;所有正式文档修改经过唯一 command service 和历史;相同输入生成确定性 `UsdDeliveryPlanV4`;资产来源不决定物理能力;无法表达的 variant、payload、placeholder、domain 或 visual artifact 必须进入诊断并阻断;保存成功必须绑定实际适配器已确认的文档版本与资源状态。当前实现已覆盖不可变快照、受约束 action commit、资产 prepare/persist/commit、版本化保存回执、group 层级变换、OpenUSD 导出和 Action Registry;后续开放仍以真实消费需求为前提。
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The AI contract.
|
|
3
|
+
*
|
|
4
|
+
* AI scene authoring has no second write path: an AI run reads the same
|
|
5
|
+
* `SceneDocument` a human reads and emits the same `SceneCommand`s a human emits.
|
|
6
|
+
* That is what makes AI edits undoable, auditable and testable with the existing
|
|
7
|
+
* tooling (docs/sim-studio/data-model.md §5.3, requirements F4).
|
|
8
|
+
*
|
|
9
|
+
* This module therefore contains types and a validation gate only — no model
|
|
10
|
+
* calls, no prompting. Phase 1 ships the foundation the AI layer plugs into.
|
|
11
|
+
*/
|
|
12
|
+
import type { CommandRecord, SceneCommand } from '../doc/command';
|
|
13
|
+
import type { SceneDocument } from '../doc/schema';
|
|
14
|
+
import type { AssetRevision } from '../asset/record';
|
|
15
|
+
import type { Diagnostic } from '../util/diagnostics';
|
|
16
|
+
/** Read access an AI planner needs to understand the current scene. */
|
|
17
|
+
export interface SceneReader {
|
|
18
|
+
readonly doc: SceneDocument;
|
|
19
|
+
/** Assets the scene may reference; the planner must not invent asset ids. */
|
|
20
|
+
readonly library: readonly AssetRevision[];
|
|
21
|
+
}
|
|
22
|
+
/** Write access, expressed purely as commands. */
|
|
23
|
+
export interface SceneWriter {
|
|
24
|
+
/**
|
|
25
|
+
* Applies commands as one atomic step. Returns diagnostics and rejects the
|
|
26
|
+
* whole batch if any command fails, mirroring human batch edits.
|
|
27
|
+
*/
|
|
28
|
+
apply(commands: readonly SceneCommand[], intent: AiIntentMeta): AiApplyResult;
|
|
29
|
+
}
|
|
30
|
+
/** Provenance recorded on every AI-generated command. */
|
|
31
|
+
export interface AiIntentMeta {
|
|
32
|
+
/** Human-readable summary, shown in the undo stack and the audit log. */
|
|
33
|
+
readonly label: string;
|
|
34
|
+
/** Identifies one AI run so its commands can be grouped and reviewed. */
|
|
35
|
+
readonly batchId: string;
|
|
36
|
+
/** Which model/prompt produced it; kept for debugging, never required. */
|
|
37
|
+
readonly producer?: string;
|
|
38
|
+
}
|
|
39
|
+
export interface AiApplyResult {
|
|
40
|
+
readonly applied: readonly CommandRecord[];
|
|
41
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
42
|
+
/** True when the batch was rejected and the document is unchanged. */
|
|
43
|
+
readonly rejected: boolean;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Builds a reader over the current document.
|
|
47
|
+
*
|
|
48
|
+
* The reader is a pure snapshot: it cannot mutate the scene, which keeps the
|
|
49
|
+
* planner's inputs stable while it reasons.
|
|
50
|
+
*/
|
|
51
|
+
export declare function createSceneReader(doc: SceneDocument, library?: readonly AssetRevision[]): SceneReader;
|
|
52
|
+
/**
|
|
53
|
+
* Turns raw AI output into command records.
|
|
54
|
+
*
|
|
55
|
+
* Commands are validated before they can reach the document: an AI that emits
|
|
56
|
+
* an unknown asset id or a malformed transform is rejected the same way a human
|
|
57
|
+
* mistake would be, and the reason is reportable.
|
|
58
|
+
*/
|
|
59
|
+
export declare function prepareAiCommands(doc: SceneDocument, commands: readonly SceneCommand[], intent: AiIntentMeta): {
|
|
60
|
+
readonly records: readonly CommandRecord[];
|
|
61
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Applies AI commands to a document in one step.
|
|
65
|
+
*
|
|
66
|
+
* `SceneHistory.applyAll` is used by the host so the result lands on the human
|
|
67
|
+
* undo stack; this helper is the pure-document equivalent used in tests and by
|
|
68
|
+
* headless tools.
|
|
69
|
+
*/
|
|
70
|
+
export declare function applyAiCommands(doc: SceneDocument, commands: readonly SceneCommand[], intent: AiIntentMeta): {
|
|
71
|
+
readonly doc: SceneDocument;
|
|
72
|
+
readonly result: AiApplyResult;
|
|
73
|
+
};
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { AiApplyResult, AiIntentMeta } from './contract';
|
|
2
|
+
import type { CommandRecord, SceneCommand } from '../doc/command';
|
|
3
|
+
import type { Diagnostic } from '../util/diagnostics';
|
|
4
|
+
import type { SceneDocument } from '../doc/schema';
|
|
5
|
+
export interface StudioAiHostPort {
|
|
6
|
+
readonly document: SceneDocument;
|
|
7
|
+
commit(request: {
|
|
8
|
+
readonly commands: readonly CommandRecord[];
|
|
9
|
+
readonly expectedDocumentVersion?: number;
|
|
10
|
+
readonly expectedSceneEpoch?: number;
|
|
11
|
+
readonly expectedSelectionVersion?: number;
|
|
12
|
+
readonly gestureCommit?: boolean;
|
|
13
|
+
}): {
|
|
14
|
+
readonly changed: boolean;
|
|
15
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* AI intent orchestration over the Host's version-checked transaction service.
|
|
20
|
+
* This module stays in the pure AI layer through a structural Host port, so
|
|
21
|
+
* core never imports AI and AI never imports renderer or editor code.
|
|
22
|
+
*/
|
|
23
|
+
export declare function applyAiCommandsToHost(host: StudioAiHostPort, commands: readonly SceneCommand[], intent: AiIntentMeta, transaction?: {
|
|
24
|
+
readonly expectedDocumentVersion?: number;
|
|
25
|
+
readonly expectedSceneEpoch?: number;
|
|
26
|
+
readonly expectedSelectionVersion?: number;
|
|
27
|
+
readonly gestureCommit?: boolean;
|
|
28
|
+
}): AiApplyResult;
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import { type StudioAssetResourceLocator } from '../util/studio-source';
|
|
2
|
+
/** What kind of thing a `@...@` target points at. */
|
|
3
|
+
export type ReferenceClass =
|
|
4
|
+
/** A USD layer or other asset that must ship inside the package. */
|
|
5
|
+
'asset'
|
|
6
|
+
/**
|
|
7
|
+
* An MDL material module (`gltf/pbr.mdl`, `OmniPBR.mdl`,
|
|
8
|
+
* `nvidia/core_definitions.mdl`). These are looked up in the host's MDL search
|
|
9
|
+
* path (Isaac Sim / Omniverse ships them), not inside the asset package, so a
|
|
10
|
+
* missing file is expected and does not break self-containment.
|
|
11
|
+
*/
|
|
12
|
+
| 'material-module';
|
|
13
|
+
/** A single `@...@` reference found in a layer. */
|
|
14
|
+
export interface UsdReference {
|
|
15
|
+
/** Package-relative path of the layer that contains the reference. */
|
|
16
|
+
readonly fromPath: string;
|
|
17
|
+
/** Raw text between the `@` delimiters. */
|
|
18
|
+
readonly target: string;
|
|
19
|
+
/** Resolved package-relative path, or null when it cannot be resolved. */
|
|
20
|
+
readonly resolvedPath: string | null;
|
|
21
|
+
/** True when the target is an absolute URI (`https://`, `s3://`, …). */
|
|
22
|
+
readonly external: boolean;
|
|
23
|
+
/** True when the target starts with `./` or `../`. */
|
|
24
|
+
readonly anchored: boolean;
|
|
25
|
+
/** The primitive path suffix inside the referenced layer (`</A/B>`), if present. */
|
|
26
|
+
readonly primPath: string | null;
|
|
27
|
+
readonly kind: ReferenceClass;
|
|
28
|
+
}
|
|
29
|
+
export interface DependencyScanResult {
|
|
30
|
+
readonly references: readonly UsdReference[];
|
|
31
|
+
/** Asset references whose file is not present in the package. */
|
|
32
|
+
readonly missing: readonly UsdReference[];
|
|
33
|
+
/** Absolute URIs that point outside the package. */
|
|
34
|
+
readonly external: readonly UsdReference[];
|
|
35
|
+
/** Relative asset references that are not anchored with `./` or `../`. */
|
|
36
|
+
readonly unanchored: readonly UsdReference[];
|
|
37
|
+
/** MDL module references; informational, never blocking. */
|
|
38
|
+
readonly materialModules: readonly UsdReference[];
|
|
39
|
+
/** Layer paths that reference at least one dependency, sorted. */
|
|
40
|
+
readonly layers: readonly string[];
|
|
41
|
+
}
|
|
42
|
+
export declare function isMaterialModule(target: string): boolean;
|
|
43
|
+
/** Layers are scanned in sorted order so the result is reproducible. */
|
|
44
|
+
export declare function scanDependencies(layers: readonly {
|
|
45
|
+
readonly path: string;
|
|
46
|
+
readonly text: string;
|
|
47
|
+
}[], packagePaths: ReadonlySet<string>): DependencyScanResult;
|
|
48
|
+
/**
|
|
49
|
+
* Locator-aware dependency scan for materialized source bundles. Unlike the
|
|
50
|
+
* package-only scanner above, this preserves URL semantics for remote layers.
|
|
51
|
+
*/
|
|
52
|
+
export declare function scanLocatorDependencies(layers: readonly {
|
|
53
|
+
readonly locator: StudioAssetResourceLocator;
|
|
54
|
+
readonly text: string;
|
|
55
|
+
}[], available: readonly StudioAssetResourceLocator[]): DependencyScanResult;
|
|
56
|
+
export declare function extractReferences(fromPath: string, text: string, packagePaths: ReadonlySet<string>): UsdReference[];
|
|
57
|
+
/**
|
|
58
|
+
* Resolves a reference against the referring layer's directory.
|
|
59
|
+
*
|
|
60
|
+
* Unanchored references use USD's search path, which walks up from the layer.
|
|
61
|
+
* We mirror that by trying each ancestor directory in turn (nearest first) and
|
|
62
|
+
* finally the package root, so `gltf/pbr.mdl` written in `asset/variants/`
|
|
63
|
+
* still resolves to `asset/gltf/pbr.mdl`. Anything found nowhere stays
|
|
64
|
+
* unresolved rather than being guessed at.
|
|
65
|
+
*/
|
|
66
|
+
export declare function resolveFrom(fromPath: string, target: string, packagePaths: ReadonlySet<string>): string | null;
|
|
67
|
+
export declare function normalizePath(path: string): string;
|
|
68
|
+
/** True when a layer is textual (`.usda`) and can be scanned or repaired. */
|
|
69
|
+
export declare function isTextualLayer(path: string): boolean;
|
|
70
|
+
/**
|
|
71
|
+
* Decides whether layer bytes are text.
|
|
72
|
+
*
|
|
73
|
+
* `.usd` cannot be classified by extension: docs/sim-studio/assets.md §2.3
|
|
74
|
+
* notes the same extension covers both text and crate-binary layers. Sniffing
|
|
75
|
+
* the magic keeps entry layers such as `asset/chuanzi_01_usd.usd` scannable
|
|
76
|
+
* when they are actually text, while never decoding a binary crate.
|
|
77
|
+
*/
|
|
78
|
+
export declare function isTextualLayerBytes(path: string, bytes: Uint8Array | null | undefined): boolean;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Intake: turn a collected package into an immutable AssetRevision.
|
|
3
|
+
*
|
|
4
|
+
* The pipeline is deliberately staged so each step can be inspected and tested
|
|
5
|
+
* alone: detect layout → scan dependencies → repair → probe physics → hash
|
|
6
|
+
* resources → build the revision. Nothing here touches the filesystem directly.
|
|
7
|
+
*/
|
|
8
|
+
import type { AssetCategory, AssetProvenance, AssetRevision } from './record';
|
|
9
|
+
import type { PackageFile, PackageListing } from './layout-detect';
|
|
10
|
+
import { readManifestText } from './layout-detect';
|
|
11
|
+
import type { UsdReference } from './dependency-scan';
|
|
12
|
+
/** Metadata that cannot be derived from file contents and must be supplied. */
|
|
13
|
+
export interface AssetAnnotations {
|
|
14
|
+
/** URL-safe identifier, e.g. `pallet-plastic-chuanzi-01`. */
|
|
15
|
+
readonly slug?: string;
|
|
16
|
+
readonly label?: string;
|
|
17
|
+
readonly category?: AssetCategory;
|
|
18
|
+
readonly externalRef?: import('../doc/schema').StudioExternalAssetRef;
|
|
19
|
+
}
|
|
20
|
+
export interface IntakeOptions {
|
|
21
|
+
readonly annotations?: AssetAnnotations;
|
|
22
|
+
readonly origin?: AssetProvenance['source'];
|
|
23
|
+
readonly now?: () => string;
|
|
24
|
+
/** Explicit root layer when a group contains multiple independent entries. */
|
|
25
|
+
readonly entryPath?: string;
|
|
26
|
+
/** When false, structural problems are reported but the record is still built. */
|
|
27
|
+
readonly strict?: boolean;
|
|
28
|
+
}
|
|
29
|
+
export type IntakeStatus = 'ready' | 'ready-with-repairs' | 'blocked';
|
|
30
|
+
export interface IntakeResult {
|
|
31
|
+
readonly status: IntakeStatus;
|
|
32
|
+
/** Built record; absent only when intake was blocked. */
|
|
33
|
+
readonly record: AssetRevision | null;
|
|
34
|
+
/** Rewritten layer contents that the caller must persist before recording. */
|
|
35
|
+
readonly rewrites: ReadonlyMap<string, string>;
|
|
36
|
+
readonly diagnostics: readonly IntakeDiagnostic[];
|
|
37
|
+
}
|
|
38
|
+
export interface IntakeDiagnostic {
|
|
39
|
+
readonly code: string;
|
|
40
|
+
readonly level: 'info' | 'warning' | 'error';
|
|
41
|
+
readonly message: string;
|
|
42
|
+
}
|
|
43
|
+
export declare const INTAKE_DIAGNOSTIC: {
|
|
44
|
+
readonly entryMissing: "ASSET_INTAKE_ENTRY_MISSING";
|
|
45
|
+
readonly entryNotUsd: "ASSET_INTAKE_ENTRY_NOT_USD";
|
|
46
|
+
readonly dependencyMissing: "ASSET_INTAKE_DEPENDENCY_MISSING";
|
|
47
|
+
readonly externalReference: "ASSET_INTAKE_EXTERNAL_REFERENCE";
|
|
48
|
+
readonly unanchoredReference: "ASSET_INTAKE_UNANCHORED_REFERENCE";
|
|
49
|
+
readonly repairApplied: "ASSET_INTAKE_REPAIR_APPLIED";
|
|
50
|
+
readonly annotationMissing: "ASSET_INTAKE_ANNOTATION_MISSING";
|
|
51
|
+
readonly glbNeedsCompilation: "ASSET_INTAKE_GLB_NEEDS_COMPILATION";
|
|
52
|
+
readonly physicsUnknown: "ASSET_INTAKE_PHYSICS_UNKNOWN";
|
|
53
|
+
readonly materialModuleReference: "ASSET_INTAKE_MATERIAL_MODULE";
|
|
54
|
+
readonly resourceBytesMissing: "ASSET_INTAKE_RESOURCE_BYTES_MISSING";
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* Runs the intake pipeline.
|
|
58
|
+
*
|
|
59
|
+
* `probe` is the physics probe result supplied by the caller (in practice the
|
|
60
|
+
* Viewer reporting a loaded stage); intake does not parse USD geometry itself.
|
|
61
|
+
*/
|
|
62
|
+
export declare function intakePackage(listing: PackageListing, probe: IntakePhysicsProbe | null, options?: IntakeOptions): IntakeResult;
|
|
63
|
+
/** Physics facts the caller obtained by actually loading the asset. */
|
|
64
|
+
export interface IntakePhysicsProbe {
|
|
65
|
+
readonly capability: {
|
|
66
|
+
readonly hasPhysics: boolean;
|
|
67
|
+
readonly hasArticulation: boolean;
|
|
68
|
+
readonly hasColliderGeometry: boolean;
|
|
69
|
+
readonly hasRigidBody?: boolean;
|
|
70
|
+
readonly source: 'usd-authored' | 'none' | 'unknown';
|
|
71
|
+
};
|
|
72
|
+
readonly measured?: {
|
|
73
|
+
readonly bounds?: import('../doc/schema').Vec3Bounds;
|
|
74
|
+
readonly jointCount?: number;
|
|
75
|
+
readonly meshCount?: number;
|
|
76
|
+
};
|
|
77
|
+
readonly approximateSize?: import('../doc/schema').Vec3;
|
|
78
|
+
readonly forwardAxis?: import('../doc/schema').ForwardAxis;
|
|
79
|
+
readonly variantSets?: readonly import('../doc/schema').AssetVariantSet[];
|
|
80
|
+
}
|
|
81
|
+
/** Turns a directory name into a URL-safe slug. */
|
|
82
|
+
export declare function slugFromRoot(rootName: string): string;
|
|
83
|
+
export type { PackageFile, PackageListing, UsdReference };
|
|
84
|
+
export { readManifestText };
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Asset layout detection.
|
|
3
|
+
*
|
|
4
|
+
* The four layouts in docs/sim-studio/assets.md §2 differ far more than their
|
|
5
|
+
* extensions suggest, so detection reads the actual package structure rather
|
|
6
|
+
* than trusting a file name. In particular `.usd` cannot be assumed to be text
|
|
7
|
+
* or binary (§2.3).
|
|
8
|
+
*/
|
|
9
|
+
import type { AssetLayout } from './record';
|
|
10
|
+
/** One file inside an intake package, as read by the caller. */
|
|
11
|
+
export interface PackageFile {
|
|
12
|
+
/** Package-relative path with `/` separators, no leading `./`. */
|
|
13
|
+
readonly path: string;
|
|
14
|
+
/** Bytes of the file, or null when the caller only has the listing. */
|
|
15
|
+
readonly bytes?: Uint8Array | null;
|
|
16
|
+
readonly size?: number;
|
|
17
|
+
}
|
|
18
|
+
export interface PackageListing {
|
|
19
|
+
/** Directory name the package was collected under; used for the slug fallback. */
|
|
20
|
+
readonly rootName: string;
|
|
21
|
+
readonly files: readonly PackageFile[];
|
|
22
|
+
}
|
|
23
|
+
export interface LayoutDetection {
|
|
24
|
+
readonly layout: AssetLayout;
|
|
25
|
+
/** Package-relative entry file that a viewer should open. */
|
|
26
|
+
readonly entryPath: string | null;
|
|
27
|
+
/** Why the layout was chosen; useful in intake reports. */
|
|
28
|
+
readonly reason: string;
|
|
29
|
+
}
|
|
30
|
+
export declare function extensionOf(path: string): string;
|
|
31
|
+
export declare function isUsdPath(path: string): boolean;
|
|
32
|
+
/**
|
|
33
|
+
* Detects the layout of a package.
|
|
34
|
+
*
|
|
35
|
+
* `.usdz` wins outright: it is a single self-contained file, so nothing else
|
|
36
|
+
* about the package can make it more or less self-contained.
|
|
37
|
+
*/
|
|
38
|
+
export declare function detectLayout(listing: PackageListing, preferredEntry?: string): LayoutDetection;
|
|
39
|
+
/** Reads the declared SimReady asset type from a packaging manifest, if any. */
|
|
40
|
+
export declare function readManifestText(files: readonly PackageFile[]): string | null;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export declare const DEFAULT_ASSET_MEDIA_TYPE = "application/octet-stream";
|
|
2
|
+
/** Returns a concrete MIME only when the package-relative path declares one. */
|
|
3
|
+
export declare function inferMediaTypeFromPath(path: string): string | null;
|
|
4
|
+
/** Asset facts require a concrete MIME, so unknown extensions stay generic. */
|
|
5
|
+
export declare function mediaTypeForAssetPath(path: string): string;
|
|
6
|
+
/**
|
|
7
|
+
* Resolves source metadata without treating a generic browser MIME as an
|
|
8
|
+
* assertion. Missing values remain null so revision facts can fill them.
|
|
9
|
+
*/
|
|
10
|
+
export declare function resolveMediaTypeFromFacts(path: string, ...declared: readonly (string | null | undefined)[]): string | null;
|