@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.
- package/dist/cli.js +7223 -215
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
- package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
- package/dist/guidance/claude/.claude/settings.json +6 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/CLAUDE.md +2 -141
- package/dist/guidance/codex/.codex/config.toml +1 -1
- package/dist/guidance/common/AGENTS.md +96 -37
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/public/ui/welcome.uikitml +0 -19
- package/dist/template/common/src/robot.ts +5 -0
- package/dist/template/common/vite.config.ts +18 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
- package/dist/template/common-js/src/robot.js +5 -0
- package/dist/template/common-js/vite.config.js +18 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
- package/package.json +8 -7
- package/scripts/verify-release-ready.mjs +25 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
- /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.
|
package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md
DELETED
|
@@ -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.
|