@iwsdk/create 0.5.2 → 1.0.0-rc.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.
Files changed (107) hide show
  1. package/dist/cli.js +7223 -215
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
  82. package/package.json +8 -7
  83. package/scripts/verify-release-ready.mjs +25 -0
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  89. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  94. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  100. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  105. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  106. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  107. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -1,257 +0,0 @@
1
- ---
2
- name: iwsdk-scene-composer
3
- description: Compose editable static IWSDK scenes from text, images, or hybrid references using a shared application asset manifest, v1 scene JSON, modular scene files, and the managed editor's validation and rendering tools. Use for 3D environments, props, architecture, staged scenes, procedural Three.js assets, custom PBR or shader materials, glTF assets, prefabs, patterns, lighting, camera matching, or visual review.
4
- ---
5
-
6
- # IWSDK Scene Composer
7
-
8
- Author native IWSDK assets and scene files. Application code owns geometry and
9
- materials; scene JSON owns composition; the managed editor provides visual feedback
10
- and human transform/component adjustment.
11
-
12
- Read these references when relevant:
13
-
14
- - [scene-format.md](references/scene-format.md) before editing scene JSON;
15
- - [asset-authoring.md](references/asset-authoring.md) before creating or changing
16
- glTF or procedural assets;
17
- - [text-intake.md](references/text-intake.md) for text-only requests;
18
- - [image-intake.md](references/image-intake.md) for image or hybrid requests;
19
- - [composition-patterns.md](references/composition-patterns.md) for decomposition
20
- and repetition strategies;
21
- - [review-and-stop.md](references/review-and-stop.md) before final review.
22
-
23
- ## Fixed Boundaries
24
-
25
- - Use only `iwsdk.scene.v1`. There is no compatibility schema.
26
- - Scene files are the composition source of truth. Create and edit them with normal
27
- filesystem tools under `public/scenes/`.
28
- - Scene JSON has one renderable content kind: `asset`. It does not define models,
29
- primitive geometry, material resources, or material overrides.
30
- - The default export of the configured application asset manifest is the asset source
31
- of truth. It may contain URL-backed glTF and UIKitML entries plus parentless
32
- `Object3D` prototypes with arbitrary Three.js geometry and materials.
33
- - The application runtime and editor import the same manifest module independently.
34
- Never depend on shared object identity, iframe messaging, DOM state, or a live
35
- runtime world when defining assets.
36
- - Humans use the editor for selection, hierarchy, transforms, components, root
37
- lighting, and preview visibility. They do not edit geometry or materials there.
38
- - Agents may edit asset TypeScript and scene JSON, then use the editor to validate and
39
- render the result.
40
-
41
- The public scene MCP surface is intentionally small:
42
-
43
- ```text
44
- scene_open
45
- scene_render_file
46
- scene_flatten_file
47
- scene_get_state
48
- scene_get_capabilities
49
- scene_screenshot
50
- scene_select
51
- scene_set_camera
52
- scene_set_preview_visibility
53
- scene_measure_image_regions
54
- ```
55
-
56
- Document creation and mutation happen through direct file edits. Do not look for MCP
57
- create/add/update/remove/patch/save/compose/review/publish tools.
58
-
59
- When MCP is unavailable, use the CLI equivalents:
60
-
61
- ```bash
62
- npx iwsdk dev status
63
- npx iwsdk dev up
64
- npx iwsdk scene capabilities --raw
65
- npx iwsdk scene render-file \
66
- --input-json '{"path":"public/scenes/room.iwsdk.scene.json","viewId":"hero"}' \
67
- --output-file artifacts/room.png
68
- npx iwsdk scene flatten \
69
- --input-json '{"path":"public/scenes/room.composition.iwsdk.scene.json","outputPath":"public/scenes/room.iwsdk.scene.json"}' --raw
70
- npx iwsdk scene open \
71
- --input-json '{"path":"public/scenes/room.iwsdk.scene.json"}' --raw
72
- npx iwsdk scene state --raw
73
- ```
74
-
75
- `iwsdk dev up` starts the server in the background, launches the configured
76
- managed editor browser, and waits for the command bridge. Do not edit
77
- `vite.config.ts` to change browser mode as an ad hoc startup workaround.
78
-
79
- `scene_render_file` renders a file without replacing the editor's active document,
80
- but it still uses the managed editor browser for manifest evaluation and WebGL.
81
- If startup reports `dev_browser_not_ready`, inspect `iwsdk dev status` and
82
- `iwsdk dev logs --tail 100`. Retry only when the diagnostics indicate a transient
83
- startup failure. Do not invent a custom CPU or Playwright renderer and present it as
84
- authoritative editor evidence. Preserve the structured failure, continue
85
- type/schema/build checks that remain meaningful, and report the visual-verification
86
- gate as blocked.
87
-
88
- Camera parameters are intentionally distinct: `view` accepts only the built-in
89
- presets (`current`, `top`, `front`, `back`, `left`, `right`, `quarter`, `orbit`),
90
- while `viewId` selects an exact camera declared in `authoring.views`. Outside
91
- immersive XR, a loaded level's saved hero view owns runtime framing and
92
- supersedes the initial `World.create({ render: { camera } })` pose. In XR, the
93
- tracked player rig owns the camera, so the player-spawn view is a separate
94
- required framing check.
95
-
96
- ## Workflow
97
-
98
- ### 1. Specify
99
-
100
- Turn the request into a compact implementation brief:
101
-
102
- - required and optional features;
103
- - source evidence regions for image input;
104
- - silhouette, proportions, parts, negative space, contacts, and material response;
105
- - hero and diagnostic views;
106
- - measurable acceptance criteria;
107
- - assumptions, uncertainty, and fidelity ceiling.
108
-
109
- A single image proves visible composition, not hidden geometry. Do not silently invent
110
- occluded detail or lower requested fidelity.
111
-
112
- ### 2. Plan Assets And Modules
113
-
114
- Call `scene_get_capabilities` once. Inspect `src/assets.ts` and existing asset modules.
115
-
116
- Choose an external asset source deliberately:
117
-
118
- - Use the configured MetaVR asset search, or
119
- `npx @meta-quest/metavr --json asset search "<query>"`, for ready-made static
120
- props and background dressing. Results provide previews plus GLB/FBX downloads,
121
- but do not promise semantic subparts, rigging, articulation, or independently
122
- editable pieces. Inspect the downloaded hierarchy, and copy selected files into
123
- project-owned storage instead of persisting a returned CDN URL.
124
- - Use `npx @drawcall/market skill` and `npx @drawcall/market types`, then search a
125
- concrete need with `npx @drawcall/market search "<query>" --type <type> --limit 3`,
126
- when an installable reusable asset, template, or provider-generated result is a
127
- better starting point. Preview finalists and install the exact printed
128
- `name@version`; trust the install output for consumer paths.
129
- - Drawcall Market is a marketplace/install/generation CLI, not a universal
130
- procedural-geometry engine. When the request depends on controllable parts,
131
- parametric dimensions, articulation, or code-driven variation and no suitable
132
- code-backed template exists, author a deterministic Three.js `Object3D` prototype.
133
-
134
- For every visible form, choose one of:
135
-
136
- 1. reuse an existing manifest asset;
137
- 2. add a glTF entry to the manifest;
138
- 3. register a UIKitML file with `AssetType.UIKitML`;
139
- 4. create a deterministic parentless `Object3D` prototype in code and register it;
140
- 5. assemble existing assets with a scene prefab or module.
141
-
142
- Create custom geometry and materials in asset code, not JSON. Prefer separate
143
- `*.scene-asset.ts` modules for substantial procedural assets and import their
144
- prototypes into `src/assets.ts`.
145
-
146
- For initial construction, plan independent semantic groups as standalone scratch
147
- scene modules. Give each module a local origin, size envelope, attachment points,
148
- required views, and asset IDs. Asset and component IDs are application-global;
149
- imported node and prefab IDs are namespaced. Imports are an authoring-only assembly
150
- mechanism, never a runtime or editable-project format.
151
-
152
- ### 3. Build
153
-
154
- Author assets first, then scene JSON. Build in dependency order:
155
-
156
- 1. support/stage and representative lighting;
157
- 2. large composition masses;
158
- 3. identity-critical groups;
159
- 4. repeated secondary detail;
160
- 5. hero camera and final environment.
161
-
162
- Use meters, stable descriptive IDs, deterministic ordering, and explicit transforms.
163
- Groups supply hierarchy, never visible mass. Use `castShadow` and `receiveShadow` on
164
- asset nodes only when needed. Use prefabs and patterns for repetition; keep repeated
165
- asset prototypes resource-sharing friendly.
166
-
167
- ### 4. Validate And Materialize
168
-
169
- With the managed editor command-ready, call `scene_render_file` on every changed
170
- scratch module, then the composition root. It resolves imports for authoring preview,
171
- validates schema and manifest references, lowers the scene, and returns a PNG plus
172
- diagnostics without changing the active document. Fix failures in the owning asset or
173
- scratch file.
174
-
175
- After the composition root passes, run `scene_flatten_file` / `iwsdk scene flatten`
176
- once to materialize an import-free final scene. The command preserves import wrapper
177
- groups, validates the output, and refuses to write if its runtime hash differs from
178
- the composed source. This is a one-way publication boundary: the flat file becomes
179
- the sole source of truth, and later scratch-module changes must not be re-flattened
180
- over human edits.
181
-
182
- Call `scene_open` only on the flattened file for live collaboration. Import-bearing
183
- files remain renderable composition previews but are never opened as editable scenes
184
- and never load in the application runtime.
185
-
186
- Use `scene_get_state` for selection, hashes, diagnostics, dirty/conflict state, runtime
187
- readiness, and render statistics. Use camera, screenshot, selection, and preview
188
- visibility tools only when their live-editor context is useful.
189
-
190
- ### 5. Review And Refine
191
-
192
- Review in three passes:
193
-
194
- 1. **Layout**: hierarchy, scale, support contacts, and arrangement.
195
- 2. **Geometry**: silhouette, proportions, parts, negative space, and alternate views.
196
- 3. **Final**: material response, color, lighting, environment, and hero framing.
197
-
198
- Keep review orchestration and evidence outside the editor. The editor supplies
199
- authoritative screenshots, hashes, camera state, diagnostics, and render measurements.
200
- Derive comparisons, defect lists, lineage, and stop decisions in ordinary task files.
201
-
202
- Fix the highest-impact defect in its owning asset or scene module, rerender that file,
203
- then rerender the root. Default to two focused correction rounds. Stop earlier on a
204
- repeated defect, oscillation, plateau, missing input/asset, or representation ceiling.
205
-
206
- ### 6. Finish
207
-
208
- Finish only when:
209
-
210
- - every scratch module and the composition root validates and renders;
211
- - the final editable scene is flattened and contains no `imports`;
212
- - the active editor state is clean and conflict-free;
213
- - required views are nonblank and correctly framed;
214
- - required features pass measurable and visual checks;
215
- - manifest asset IDs resolve in both editor and application runtime;
216
- - the application build and selected scene load without blocking errors.
217
-
218
- If a required gate is unavailable, finish with an explicit blocked or
219
- accepted-with-gaps result. Passing a local schema check, production build, or custom
220
- diagnostic image does not substitute for authoritative editor renders and state.
221
-
222
- ## Modular Composition
223
-
224
- ```json
225
- {
226
- "version": "iwsdk.scene.v1",
227
- "units": "meters",
228
- "imports": [
229
- {
230
- "id": "reading-nook",
231
- "src": "./modules/reading-nook.iwsdk.scene.json",
232
- "transform": { "position": [1.8, 0, -0.6] }
233
- }
234
- ],
235
- "resources": {},
236
- "nodes": []
237
- }
238
- ```
239
-
240
- Each scratch module must be valid by itself. Imports resolve recursively in
241
- declaration order. The import entry becomes a transform group. The composition root
242
- owns global components, environment, metadata, and authoring settings. Cycles, unsafe
243
- IDs, missing files, duplicate namespaced IDs, and invalid modules fail composition.
244
-
245
- For parallel initial construction, assign one scratch module file per worker. Never
246
- let two workers edit one file. Render modules independently, import only passing
247
- modules, correct cross-module scale, contact, occlusion, lighting, and framing at the
248
- composition root, then flatten exactly once. Parallel module iteration ends at that
249
- boundary; continue all later edits in the flat file.
250
-
251
- ## Regeneration And Provenance
252
-
253
- Preserve stable IDs when revising the flat file. Never overwrite unrelated
254
- human-authored files or re-flatten over editor changes. Record the skill/runtime
255
- versions, input hashes, composition/final/module paths, capability hash,
256
- source/composed/runtime hashes, assumptions, and fidelity ceiling in authoring
257
- metadata or adjacent task evidence.
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: 'IWSDK Scene Composer'
3
- short_description: 'Compose editable IWSDK scenes from text or images'
4
- default_prompt: 'Use $iwsdk-scene-composer to compose this request as an editable, validated IWSDK scene.'
@@ -1,295 +0,0 @@
1
- # IWSDK Scene Asset Authoring
2
-
3
- ## Contents
4
-
5
- 1. Shared Manifest Contract
6
- 2. URL Assets
7
- 3. Procedural Assets
8
- 4. Geometry And Materials
9
- 5. Runtime And Editor Semantics
10
- 6. Repetition And Performance
11
- 7. Validation Checklist
12
-
13
- ## Shared Manifest Contract
14
-
15
- Keep the manifest in a dedicated module and point the project authority at it:
16
-
17
- ```json
18
- {
19
- "assets": { "module": "./src/assets" }
20
- }
21
- ```
22
-
23
- The application consumes the expanded project options, so it cannot drift from
24
- the editor's catalog:
25
-
26
- ```ts
27
- // src/index.ts
28
- import { World } from '@iwsdk/core';
29
- import projectOptions from 'virtual:iwsdk-project';
30
-
31
- await World.create(document.getElementById('scene-container')!, projectOptions);
32
- ```
33
-
34
- The runtime and managed editor evaluate `src/assets.ts` separately in different
35
- worlds. The module must therefore be deterministic and self-contained:
36
-
37
- - do not read a `World`, scene, iframe, editor object, or DOM element;
38
- - do not rely on singleton object identity across realms;
39
- - do not start timers, fetch arbitrary state, or attach prototypes to a parent;
40
- - keep prototypes immutable after registration.
41
-
42
- The manifest ID is the stable application-global reference used by scene JSON.
43
-
44
- ## URL Assets
45
-
46
- Register glTF files and non-renderable application assets normally:
47
-
48
- ```ts
49
- // src/assets.ts
50
- import { AssetType, defineAssets } from '@iwsdk/core';
51
- import readingChair from './scene-assets/reading-chair.scene-asset.js';
52
-
53
- const publicAssetUrl = (path: string) =>
54
- `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
55
-
56
- export default defineAssets({
57
- room: {
58
- type: AssetType.GLTF,
59
- url: publicAssetUrl('gltf/room.glb'),
60
- name: 'Room shell',
61
- },
62
- ambience: {
63
- type: AssetType.Audio,
64
- url: publicAssetUrl('audio/ambience.mp3'),
65
- },
66
- 'status-panel': {
67
- name: 'Status panel',
68
- type: AssetType.UIKitML,
69
- url: publicAssetUrl('ui/status-panel.uikitml'),
70
- },
71
- 'reading-chair': readingChair,
72
- });
73
- ```
74
-
75
- Renderable entries appear in the editor asset catalog: glTF, UIKitML, and direct
76
- `Object3D` prototypes. Audio, texture, and HDR entries remain available to application
77
- systems but are not scene-node content. A UIKitML file in `public/ui/` is not placeable
78
- until its URL is registered with `AssetType.UIKitML`.
79
-
80
- Build public URLs from `import.meta.env.BASE_URL` so runtime, managed editor, and
81
- subpath builds resolve the same files. Never put URLs or asset declarations in
82
- scene JSON, and never guess a path without checking the project.
83
-
84
- UIKitML scene nodes use the same asset-only JSON contract as glTF and procedural
85
- objects:
86
-
87
- ```json
88
- {
89
- "id": "status-panel",
90
- "content": { "type": "asset", "asset": "status-panel" },
91
- "transform": {
92
- "position": [0, 1.4, -1.5],
93
- "rotationDeg": [0, 0, 0]
94
- }
95
- }
96
- ```
97
-
98
- A minimal Horizon-compatible document uses normal `<style>` plus nested `<div>`
99
- elements. Numeric sizes are UIKit units (centimeters), not browser CSS pixels:
100
-
101
- ```html
102
- <style>
103
- .panel {
104
- flex-direction: column;
105
- width: 240;
106
- padding-top: 18;
107
- padding-right: 18;
108
- padding-bottom: 18;
109
- padding-left: 18;
110
- background-color: #10171a;
111
- border-color: #34464d;
112
- border-width: 1;
113
- border-radius: 14;
114
- }
115
- .title {
116
- color: #f6fbff;
117
- font-size: 24;
118
- font-weight: 700;
119
- line-height: 1.25;
120
- }
121
- </style>
122
- <div class="panel">
123
- <div id="status" class="title">Ready</div>
124
- </div>
125
- ```
126
-
127
- UIKitML is an HTML/CSS-shaped language, not a browser engine. Validate instead of
128
- assuming full CSS support. In particular, expand multi-value shorthands such as
129
- `padding: 12 18`, use unitless line-height multipliers such as `1.25`, and prefer
130
- uniform `border-color`/`border-width` over directional border properties. Parser
131
- errors include source locations.
132
-
133
- Panel surfaces are single-sided and their front faces local **+Z**. Rotate the local
134
- +Z axis toward the intended viewer; for a viewer at the origin and a panel at
135
- `[0, 1.4, -1.5]`, the unrotated panel above already faces the viewer. For a computed
136
- yaw, use `atan2(viewerX - panelX, viewerZ - panelZ)` with no extra 180-degree term.
137
- Verify the authored rotation rather than assuming a missing preview is a loader
138
- failure. Use
139
- `npx iwsdk ui render-preview --input-json '{"assetId":"status-panel"}'` for an
140
- isolated proof, and `scene render-file` for in-scene placement. Both commands reload
141
- the current same-URL source, so before/after evidence does not require a server
142
- restart.
143
-
144
- At runtime, retain a directly instantiated `UIKitMLAsset`, or resolve a scene-authored
145
- one by stable node id:
146
-
147
- ```ts
148
- import { UIKit, UIKitMLAsset } from '@iwsdk/core';
149
-
150
- const panel = world.requireSceneObject<UIKitMLAsset>('status-panel');
151
- const status = panel.requireElementById<UIKit.Text>('status');
152
- status.setProperties({ text: 'Ready' });
153
- ```
154
-
155
- `UIKit.Text` is the public element type for text nodes and its public
156
- `setProperties({ text })` method updates content. No deep import from pmndrs UIKit is
157
- needed.
158
-
159
- Do not search for an editor-only panel component or depend on a transient entity
160
- index. The manifest ID identifies the reusable asset; the scene node ID identifies
161
- its placed runtime instance; element `id` attributes identify fields inside it.
162
-
163
- ## Procedural Assets
164
-
165
- A procedural asset module exports one parentless `Object3D` prototype:
166
-
167
- ```ts
168
- // src/scene-assets/reading-chair.scene-asset.ts
169
- import { BoxGeometry, Group, Mesh, MeshPhysicalMaterial } from '@iwsdk/core';
170
-
171
- const upholstery = new MeshPhysicalMaterial({
172
- color: '#52604a',
173
- roughness: 0.82,
174
- sheen: 0.18,
175
- sheenColor: '#8a927d',
176
- });
177
-
178
- const wood = new MeshPhysicalMaterial({
179
- color: '#4b281c',
180
- roughness: 0.56,
181
- clearcoat: 0.08,
182
- });
183
-
184
- const chair = new Group();
185
- chair.name = 'Reading chair';
186
-
187
- const seat = new Mesh(new BoxGeometry(0.78, 0.18, 0.76), upholstery);
188
- seat.position.y = 0.52;
189
- chair.add(seat);
190
-
191
- const back = new Mesh(new BoxGeometry(0.78, 0.92, 0.18), upholstery);
192
- back.position.set(0, 1.04, 0.28);
193
- chair.add(back);
194
-
195
- for (const x of [-0.31, 0.31]) {
196
- for (const z of [-0.27, 0.27]) {
197
- const leg = new Mesh(new BoxGeometry(0.1, 0.52, 0.1), wood);
198
- leg.position.set(x, 0.26, z);
199
- chair.add(leg);
200
- }
201
- }
202
-
203
- export default chair;
204
- ```
205
-
206
- The exported root must have `parent === null`. Its children may form any hierarchy.
207
- The registry rejects an already-parented prototype because a prototype is a reusable
208
- definition, never a placed scene instance.
209
-
210
- Use `Group`, `Mesh`, `BufferGeometry`, standard Three.js geometries, imported helper
211
- libraries, or custom shader materials as needed. The editor does not need source-level
212
- knowledge of these internals; it imports and renders the resulting prototype.
213
-
214
- ## Geometry And Materials
215
-
216
- Geometry and material authoring belongs in asset code. This includes:
217
-
218
- - custom `BufferGeometry` attributes and indices;
219
- - generated curves, extrusions, lathed surfaces, vegetation clusters, and decals;
220
- - shared `MeshStandardMaterial` or `MeshPhysicalMaterial` instances;
221
- - textures, normal maps, alpha maps, and generated `DataTexture` values;
222
- - `ShaderMaterial` or `RawShaderMaterial` where the static scene requires it;
223
- - multi-material meshes and complete glTF material assignments.
224
-
225
- The scene editor deliberately does not expose material reassignment or editing. To
226
- change a material, edit the owning asset module, let Vite reload it, and rerender the
227
- scene. This keeps glTF multi-material assets intact and allows arbitrary shader code
228
- without expanding the JSON schema.
229
-
230
- Prefer shared material objects within a manifest evaluation. Do not dispose geometry,
231
- materials, or textures from placed asset clones; the registry treats them as shared
232
- prototype resources. World/application teardown owns their lifetime.
233
-
234
- ## Runtime And Editor Semantics
235
-
236
- For every placement, the registry returns a distinct hierarchy clone. Direct
237
- `Object3D` assets use skeleton-safe cloning. Geometry and material references remain
238
- shared unless the asset itself deliberately creates distinct resources.
239
-
240
- Bounds are computed from the instantiated asset with `Box3`. They drive placement,
241
- selection, validation, framing, and scatter collision radius. Ensure that:
242
-
243
- - transforms are finite;
244
- - geometry has valid bounding data;
245
- - the prototype origin is meaningful for composition;
246
- - the local Y=0 convention is deliberate;
247
- - invisible helpers do not inflate bounds unexpectedly.
248
-
249
- Scene files reference only the manifest ID:
250
-
251
- ```json
252
- {
253
- "id": "chair",
254
- "content": {
255
- "type": "asset",
256
- "asset": "reading-chair",
257
- "castShadow": true,
258
- "receiveShadow": true
259
- },
260
- "transform": { "position": [0, 0, 0] }
261
- }
262
- ```
263
-
264
- Changing a prototype updates every scene node that references its ID after reload.
265
-
266
- ## Repetition And Performance
267
-
268
- Use scene prefabs and patterns for repeated placements. The lowerer can convert a
269
- pattern to `InstancedMesh` when the prefab resolves to one eligible mesh without
270
- components or child structure. More complex prefabs expand to cloned hierarchies but
271
- still share prototype geometry and materials.
272
-
273
- For large repeated sets:
274
-
275
- - make a single-mesh asset when individual hierarchy is unnecessary;
276
- - reuse one prefab and deterministic pattern distribution;
277
- - avoid unique materials per instance;
278
- - minimize shadow casters and transparent overdraw;
279
- - split near identity-critical assets from distant simplified assets;
280
- - measure draw calls and triangles from editor render statistics.
281
-
282
- Do not add bespoke batching metadata to scene JSON. Optimize the registered asset and
283
- prefab shape so normal lowering can batch it.
284
-
285
- ## Validation Checklist
286
-
287
- - `vite.config.ts` points at the real manifest module.
288
- - The application imports the same manifest default export.
289
- - Every scene asset ID exists in the manifest.
290
- - Every direct prototype is parentless and deterministic.
291
- - Both editor and runtime can import the module without DOM/world dependencies.
292
- - Selection bounds match the visible object.
293
- - Repeated assets share geometry/materials and avoid unnecessary draw calls.
294
- - Asset code, scratch modules, the composition root, and the flattened final scene
295
- build without warnings or blocking errors.