@iwsdk/cli 1.1.0 → 1.2.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/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-compose-scene
|
|
3
|
+
description: Compose and review IWSDK scenes from existing manifest assets using scene JSON, placement, scale, contacts, prefabs, patterns, lighting, environment, cameras, and final framing. Does not author geometry or materials; create or repair an individual 3D asset with iwsdk-build-model.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# IWSDK Compose Scene
|
|
7
|
+
|
|
8
|
+
Arrange existing IWSDK assets into a coherent scene. Scene JSON owns composition;
|
|
9
|
+
asset modules own geometry and materials; the managed editor provides visual
|
|
10
|
+
feedback and human transform/component adjustment.
|
|
11
|
+
|
|
12
|
+
If the request creates or materially changes one model, invoke `iwsdk-build-model`
|
|
13
|
+
for that asset first. If scene review reveals a defect inside one asset, route the
|
|
14
|
+
repair back to `iwsdk-build-model`. Keep placement, cross-asset contact, lighting,
|
|
15
|
+
environment, and cameras here.
|
|
16
|
+
|
|
17
|
+
## Route Before Loading References
|
|
18
|
+
|
|
19
|
+
Choose exactly one route before opening any reference:
|
|
20
|
+
|
|
21
|
+
- Use the **Fast Path** when the model handoff already supplies manifest ids, bounds,
|
|
22
|
+
and contact planes and the task needs only asset placement, built-in lighting or
|
|
23
|
+
environment, player spawn, and named views. Follow only that section and stop when
|
|
24
|
+
its finish gates pass.
|
|
25
|
+
- Use the **Extended Workflow** for imports, prefabs, patterns, unfamiliar components,
|
|
26
|
+
schema errors, image reconstruction, missing asset contracts, or genuinely ambiguous
|
|
27
|
+
composition evidence.
|
|
28
|
+
|
|
29
|
+
After selecting the Extended Workflow, read
|
|
30
|
+
[extended-workflow.md](references/extended-workflow.md). Do not load it on the Fast
|
|
31
|
+
Path; it routes the additional format, intake, composition, and review references.
|
|
32
|
+
|
|
33
|
+
## Bounded Opening
|
|
34
|
+
|
|
35
|
+
Read the applicable scoped scene/assets instructions and inspect
|
|
36
|
+
`iwsdk.config.json`, the configured asset manifest, relevant model handoffs, and the
|
|
37
|
+
active scene in one bounded pass. Reach the first scene edit within roughly eight
|
|
38
|
+
tool calls. Do not begin with dependency-tree searches, generated declarations,
|
|
39
|
+
repeated capability queries, or marketplace browsing.
|
|
40
|
+
|
|
41
|
+
For the routine Fast Path, the scoped rules plus the model handoff are sufficient.
|
|
42
|
+
Load the long scene-format material only for imports, prefabs, patterns, or after a
|
|
43
|
+
concrete schema rejection.
|
|
44
|
+
|
|
45
|
+
## Fixed Boundaries
|
|
46
|
+
|
|
47
|
+
- Do not author geometry or materials in this skill. An asset-internal defect belongs
|
|
48
|
+
to `iwsdk-build-model`; scene-relative placement and lighting defects stay here.
|
|
49
|
+
- A display stand, architectural shell, terrain piece, or set-dressing object is still
|
|
50
|
+
a model. If one is missing or must materially change, pause composition and finish it
|
|
51
|
+
with `iwsdk-build-model`; do not create or edit its asset module here.
|
|
52
|
+
- Repetition inside one manifest asset belongs to `iwsdk-build-model`; repetition of
|
|
53
|
+
placed assets belongs here through scene prefabs and patterns.
|
|
54
|
+
- UIKitML panels belong to `iwsdk-ui`, not either 3D skill.
|
|
55
|
+
- Use only `iwsdk.scene.v1`. There is no compatibility schema.
|
|
56
|
+
- Scene files are the composition source of truth. Create and edit them with normal
|
|
57
|
+
filesystem tools under `public/scenes/`.
|
|
58
|
+
- Scene JSON has one renderable content kind: `asset`. It does not define models,
|
|
59
|
+
primitive geometry, material resources, or material overrides.
|
|
60
|
+
- The default export of the configured application asset manifest is the asset source
|
|
61
|
+
of truth. It may contain URL-backed glTF and UIKitML entries plus parentless
|
|
62
|
+
`Object3D` prototypes with arbitrary Three.js geometry and materials.
|
|
63
|
+
- The application runtime and editor import the same manifest module independently.
|
|
64
|
+
Never depend on shared object identity, iframe messaging, DOM state, or a live
|
|
65
|
+
runtime world when defining assets.
|
|
66
|
+
- Humans use the editor for selection, hierarchy, transforms, components, root
|
|
67
|
+
lighting, and preview visibility. They do not edit geometry or materials there.
|
|
68
|
+
- Agents may edit asset TypeScript and scene JSON, then use the editor to validate and
|
|
69
|
+
render the result.
|
|
70
|
+
|
|
71
|
+
## Small Stateful Interactions
|
|
72
|
+
|
|
73
|
+
When a composed scene needs a small stateful interaction, keep it in one project
|
|
74
|
+
system with project components. Use `createComponent` plus `defineComponents`, then
|
|
75
|
+
`createSystem` queries whose `entities` values are Sets. React to ray activation with
|
|
76
|
+
a query qualified by `Pressed`; read or move scene-authored entities through each
|
|
77
|
+
entity's `object3D`.
|
|
78
|
+
|
|
79
|
+
Use `"OneHandGrabbable": {}` for proximity grab and `"RayInteractable": {}` for ray
|
|
80
|
+
activation. `Grabbed` is a transient tag managed by `GrabSystem`; use query
|
|
81
|
+
qualify/disqualify transitions for lifecycle work and `GrabSystem.forceRelease()` for
|
|
82
|
+
reset. Import these APIs and Three.js runtime classes from `@iwsdk/core`; do not inspect
|
|
83
|
+
package source or generated declarations to rediscover established contracts.
|
|
84
|
+
|
|
85
|
+
Route substantial UI behavior to `iwsdk-ui`, unfamiliar grab or ray behavior to the
|
|
86
|
+
matching interaction skill, and runtime failures to `iwsdk-debug`.
|
|
87
|
+
|
|
88
|
+
The public scene MCP surface is intentionally small:
|
|
89
|
+
|
|
90
|
+
```text
|
|
91
|
+
scene_open
|
|
92
|
+
scene_render_file
|
|
93
|
+
scene_flatten_file
|
|
94
|
+
scene_get_state
|
|
95
|
+
scene_get_capabilities
|
|
96
|
+
scene_screenshot
|
|
97
|
+
scene_select
|
|
98
|
+
scene_set_camera
|
|
99
|
+
scene_set_preview_visibility
|
|
100
|
+
scene_measure_image_regions
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Document creation and mutation happen through direct file edits. Do not look for MCP
|
|
104
|
+
create/add/update/remove/patch/save/compose/review/publish tools.
|
|
105
|
+
|
|
106
|
+
When MCP is unavailable, use the CLI equivalents:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
npx @iwsdk/cli dev status
|
|
110
|
+
npx @iwsdk/cli dev up
|
|
111
|
+
npx @iwsdk/cli scene capabilities --raw
|
|
112
|
+
npx @iwsdk/cli scene render-file \
|
|
113
|
+
--input-json '{"path":"public/scenes/room.iwsdk.scene.json","viewId":"hero"}' \
|
|
114
|
+
--output-file artifacts/room.png
|
|
115
|
+
npx @iwsdk/cli scene flatten \
|
|
116
|
+
--input-json '{"path":"public/scenes/room.composition.iwsdk.scene.json","outputPath":"public/scenes/room.iwsdk.scene.json"}' --raw
|
|
117
|
+
npx @iwsdk/cli scene open \
|
|
118
|
+
--input-json '{"path":"public/scenes/room.iwsdk.scene.json"}' --raw
|
|
119
|
+
npx @iwsdk/cli scene state --raw
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`iwsdk dev up` starts the server in the background and launches the configured
|
|
123
|
+
managed editor browser. It can return while that browser is still starting; use
|
|
124
|
+
`iwsdk runtime wait` or inspect `iwsdk runtime status` before browser-backed
|
|
125
|
+
commands. Pass the `--ai-mode` that AGENTS.md's session rule picks; do not edit
|
|
126
|
+
`vite.config.ts` to change browser mode as an ad hoc startup workaround.
|
|
127
|
+
|
|
128
|
+
`scene_render_file` renders a file without replacing the editor's active document,
|
|
129
|
+
but it still uses the managed editor browser for manifest evaluation and WebGL.
|
|
130
|
+
MCP screenshot tools persist their PNG and return `screenshotPath`; read the file only
|
|
131
|
+
when the requested visual check requires it.
|
|
132
|
+
If readiness does not arrive, inspect `iwsdk runtime status` and `iwsdk dev logs
|
|
133
|
+
--tail 100`. Use `iwsdk runtime recover` only when the diagnostics indicate a
|
|
134
|
+
recoverable launch failure. Do not invent a custom CPU or Playwright renderer
|
|
135
|
+
and present it as authoritative editor evidence. Preserve the structured
|
|
136
|
+
failure, continue type/schema/build checks that remain meaningful, and report
|
|
137
|
+
the visual-verification gate as blocked.
|
|
138
|
+
|
|
139
|
+
Camera parameters are intentionally distinct: `view` accepts only the built-in
|
|
140
|
+
presets (`current`, `top`, `front`, `back`, `left`, `right`, `quarter`, `orbit`),
|
|
141
|
+
while `viewId` selects an exact camera declared in `authoring.views`. Outside
|
|
142
|
+
immersive XR, a loaded level's saved hero view owns runtime framing and
|
|
143
|
+
supersedes the initial `World.create({ render: { camera } })` pose. In XR, the
|
|
144
|
+
tracked player rig owns the camera, so the player-spawn view is a separate
|
|
145
|
+
required framing check.
|
|
146
|
+
|
|
147
|
+
## Fast Path
|
|
148
|
+
|
|
149
|
+
Use this path when the handoff already provides manifest ids, envelopes, and contact
|
|
150
|
+
planes and the scene needs only placed assets, built-in lights/environment, player
|
|
151
|
+
spawn, and named authoring views:
|
|
152
|
+
|
|
153
|
+
1. inspect the existing scene once;
|
|
154
|
+
2. write one import-free scene JSON with all placements, lighting, and only the
|
|
155
|
+
requested authoring views;
|
|
156
|
+
3. render the first hero at 512×512 or smaller;
|
|
157
|
+
4. make at most one coherent visual correction;
|
|
158
|
+
5. verify that correction at 384×384 or smaller; do not raise the resolution;
|
|
159
|
+
6. open the file, confirm clean state, and run the application build;
|
|
160
|
+
7. stop. Do not continue into the Extended Workflow after these gates pass.
|
|
161
|
+
|
|
162
|
+
Keep the ordinary starting player pose unless the request explicitly requires a
|
|
163
|
+
different spawn. In the stock scaffold the viewer is near `[0, 1.6, 0]` and looks
|
|
164
|
+
down negative Z, so primary no-locomotion content normally belongs around
|
|
165
|
+
`z = -0.5` to `-2.5`; positive Z is behind the player. After any diagnostic camera
|
|
166
|
+
or headset movement, restore that starting pose and verify one live frame there.
|
|
167
|
+
|
|
168
|
+
The default Fast Path budget is at most three scene renders, two compact image reads,
|
|
169
|
+
and one correction round. Expand it only to diagnose a specific failed criterion.
|
|
170
|
+
|
|
171
|
+
Agent-loop images are inspection evidence, not delivery renders. The evaluator or
|
|
172
|
+
delivery workflow can capture the unchanged scene at higher resolution after the
|
|
173
|
+
agent stops; do not feed that larger duplicate image back into the model context.
|
|
174
|
+
|
|
175
|
+
In Claude Code, `Write` echoes the complete document into the transcript. Use it only
|
|
176
|
+
when the new scene is roughly 80 lines or 8 KB or smaller. For a longer initial scene,
|
|
177
|
+
use single-quoted Bash heredocs (`<<'EOF'`) capped at roughly 120 lines or 12 KB per
|
|
178
|
+
tool call: create with `>` and append in later calls with `>>`. End each call at its
|
|
179
|
+
heredoc delimiter rather than adding command substitutions or validation. For
|
|
180
|
+
corrections above roughly 120 lines, do not use `Edit`; use one narrowly scoped
|
|
181
|
+
scripted replacement that asserts exactly one match, writes once, and prints only a
|
|
182
|
+
short confirmation. Do not put JSON or TypeScript template literals in `node -e`.
|
|
183
|
+
|
|
184
|
+
A player transform is not an authoring view. Do not add an extra player-spawn or
|
|
185
|
+
inspection view unless the task requests it. Every authored view must declare a valid
|
|
186
|
+
`role`; the common Fast Path normally needs only the `hero` view shown below.
|
|
187
|
+
|
|
188
|
+
Use this complete minimal shape instead of looking up the common schema. Duplicate
|
|
189
|
+
asset and light nodes as needed, then choose positions from the handed-off bounds:
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{
|
|
193
|
+
"version": "iwsdk.scene.v1",
|
|
194
|
+
"units": "meters",
|
|
195
|
+
"components": {
|
|
196
|
+
"com.iwsdk.components.DomeGradient": {
|
|
197
|
+
"sky": [0.02, 0.03, 0.05, 1],
|
|
198
|
+
"equator": [0.05, 0.06, 0.08, 1],
|
|
199
|
+
"ground": [0.01, 0.01, 0.015, 1],
|
|
200
|
+
"intensity": 1
|
|
201
|
+
},
|
|
202
|
+
"com.iwsdk.components.IBLGradient": {
|
|
203
|
+
"sky": [0.25, 0.3, 0.4, 1],
|
|
204
|
+
"equator": [0.12, 0.14, 0.18, 1],
|
|
205
|
+
"ground": [0.03, 0.035, 0.04, 1],
|
|
206
|
+
"intensity": 1
|
|
207
|
+
}
|
|
208
|
+
},
|
|
209
|
+
"resources": {},
|
|
210
|
+
"authoring": {
|
|
211
|
+
"views": [{
|
|
212
|
+
"id": "hero", "role": "hero", "projection": "perspective",
|
|
213
|
+
"position": [4, 3, 4], "target": [0, 1, -1.5], "fov": 42
|
|
214
|
+
}]
|
|
215
|
+
},
|
|
216
|
+
"nodes": [
|
|
217
|
+
{
|
|
218
|
+
"id": "Hero", "content": {
|
|
219
|
+
"type": "asset", "asset": "HeroModel",
|
|
220
|
+
"castShadow": true, "receiveShadow": true
|
|
221
|
+
},
|
|
222
|
+
"transform": {"position": [0, 0, -1.5]}
|
|
223
|
+
},
|
|
224
|
+
{
|
|
225
|
+
"id": "KeyLight", "transform": {
|
|
226
|
+
"position": [-4, 6, 2], "rotationDeg": [-45, -35, 0]
|
|
227
|
+
},
|
|
228
|
+
"components": {"com.iwsdk.components.DirectionalLight": {
|
|
229
|
+
"color": [1, 0.92, 0.8, 1], "intensity": 3, "castShadow": true
|
|
230
|
+
}}
|
|
231
|
+
},
|
|
232
|
+
{
|
|
233
|
+
"id": "Fill", "components": {"com.iwsdk.components.AmbientLight": {
|
|
234
|
+
"color": [0.45, 0.55, 0.8, 1], "intensity": 0.45
|
|
235
|
+
}}
|
|
236
|
+
}
|
|
237
|
+
]
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Directional lights emit along local `-Z`. Start from the shown transform or another
|
|
242
|
+
simple intentional angle and refine it from the render; do not write a look-at solver.
|
|
243
|
+
The common light payloads are `AmbientLight: {color, intensity}`,
|
|
244
|
+
`HemisphereLight: {skyColor, groundColor, intensity}` (there is no `color` field),
|
|
245
|
+
and `PointLight: {color, intensity, distance, decay, castShadow}`. A floor that should
|
|
246
|
+
have no visible edge gets `"com.iwsdk.components.DomeFade": {"start": 4, "end": 10}`
|
|
247
|
+
on the floor node itself: it fades that node's meshes into the root `DomeGradient`
|
|
248
|
+
between those horizontal distances from the node origin, and does nothing without a
|
|
249
|
+
`DomeGradient`. Do not paste sky GLSL into an `onBeforeCompile`. A clean state after
|
|
250
|
+
the correction is the finish gate; do not query capabilities again merely to confirm
|
|
251
|
+
these established fields.
|
|
252
|
+
|
|
253
|
+
Ground props with node components, not blob or catcher assets. Add
|
|
254
|
+
`"com.iwsdk.components.ContactShadow": {"size": [0.9, 0.9]}` to each node that stands
|
|
255
|
+
on the floor (origin at floor contact, size a little wider than the footprint). For
|
|
256
|
+
AR, add one component-only node with `ShadowCatcher: {size, opacity}` at floor height;
|
|
257
|
+
it shows the shadows of `castShadow` content only when `environment.shadows` is true
|
|
258
|
+
and a light has `castShadow`. `ContactShadow` and `ShadowCatcher` are established
|
|
259
|
+
schema too. For a complete look to copy (the starter's tilted clay-studio sky
|
|
260
|
+
with a fading floor, a default sky, or AR passthrough grounding), use
|
|
261
|
+
[environment-recipes.md](references/environment-recipes.md).
|
|
262
|
+
|
|
263
|
+
For this common path, do not read the references or call
|
|
264
|
+
`scene_get_capabilities`: `DomeGradient`, `IBLGradient`, `DomeFade`, `AmbientLight`,
|
|
265
|
+
`HemisphereLight`, `DirectionalLight`, `PointLight`, asset nodes,
|
|
266
|
+
`player.transform`, and perspective/orthographic `authoring.views` are established
|
|
267
|
+
schema. Do not write a separate projection or light-aim solver. Choose the initial
|
|
268
|
+
camera from the handed-off envelopes and refine it from the authoritative render.
|
|
269
|
+
Use the longer workflow and references only for imports, prefabs, patterns, unfamiliar
|
|
270
|
+
components, schema errors, image reconstruction, or ambiguous composition evidence.
|
|
271
|
+
|
|
272
|
+
## Extended Workflow
|
|
273
|
+
|
|
274
|
+
When the Fast Path does not apply, read and follow
|
|
275
|
+
[extended-workflow.md](references/extended-workflow.md). Do not load that reference
|
|
276
|
+
for a routine scene assembled from known manifest assets.
|
|
277
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e6feb83023b2ddbe9a3cceea3b0deda0fe8beb9743d4af6b8e0a89ea31e61b93 name=iwsdk-compose-scene (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# Environment Recipes
|
|
2
|
+
|
|
3
|
+
Copy-paste environment setups built only from built-in components. Merge the
|
|
4
|
+
root `components`, the `environment` block and the node `components` into the
|
|
5
|
+
scene; keep your own asset nodes. Every field, with its default and limits, is
|
|
6
|
+
in the `componentSchemas` of `scene_get_capabilities` with `full: true` (CLI:
|
|
7
|
+
`npx @iwsdk/cli scene capabilities --input-json '{"full":true}' --raw`), and the
|
|
8
|
+
editor shows each one with a label and limits.
|
|
9
|
+
|
|
10
|
+
## Clay Studio
|
|
11
|
+
|
|
12
|
+
The VR and Desktop 3D starter's look: a pale lavender-to-bone sky tilted toward
|
|
13
|
+
the front left, a floor that fades into it with no visible edge, soft image-based
|
|
14
|
+
light and a warm key light with soft shadows.
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"components": {
|
|
19
|
+
"com.iwsdk.components.DomeGradient": {
|
|
20
|
+
"sky": [0.843, 0.796, 0.882, 1],
|
|
21
|
+
"equator": [0.808, 0.855, 0.91, 1],
|
|
22
|
+
"ground": [0.902, 0.855, 0.82, 1],
|
|
23
|
+
"elevationDeg": 24,
|
|
24
|
+
"azimuthDeg": -31,
|
|
25
|
+
"dither": true
|
|
26
|
+
},
|
|
27
|
+
"com.iwsdk.components.IBLGradient": {
|
|
28
|
+
"sky": [0.72, 0.7, 0.8, 1],
|
|
29
|
+
"equator": [0.78, 0.78, 0.84, 1],
|
|
30
|
+
"ground": [0.5, 0.52, 0.58, 1],
|
|
31
|
+
"intensity": 0.2025
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
"environment": {
|
|
35
|
+
"toneMapping": "aces",
|
|
36
|
+
"exposure": 1.2,
|
|
37
|
+
"shadows": true,
|
|
38
|
+
"shadowMapType": "pcf"
|
|
39
|
+
},
|
|
40
|
+
"nodes": [
|
|
41
|
+
{
|
|
42
|
+
"id": "studio-floor",
|
|
43
|
+
"content": {
|
|
44
|
+
"type": "asset",
|
|
45
|
+
"asset": "studio-floor",
|
|
46
|
+
"receiveShadow": true
|
|
47
|
+
},
|
|
48
|
+
"components": {
|
|
49
|
+
"LocomotionEnvironment": {},
|
|
50
|
+
"DomeFade": { "start": 4, "end": 10 }
|
|
51
|
+
}
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"id": "key-light",
|
|
55
|
+
"transform": {
|
|
56
|
+
"position": [-2.3541, 11.2763, 1.762],
|
|
57
|
+
"rotationDeg": [-73.3982, -11.3134, 0]
|
|
58
|
+
},
|
|
59
|
+
"components": {
|
|
60
|
+
"DirectionalLight": {
|
|
61
|
+
"color": [1, 0.945, 0.87, 1],
|
|
62
|
+
"intensity": 2.3,
|
|
63
|
+
"castShadow": true,
|
|
64
|
+
"shadowMapSize": "2048",
|
|
65
|
+
"shadowCameraSize": 8,
|
|
66
|
+
"shadowCameraNear": 2,
|
|
67
|
+
"shadowCameraFar": 24,
|
|
68
|
+
"shadowRadius": 7,
|
|
69
|
+
"shadowBias": -0.0004,
|
|
70
|
+
"shadowNormalBias": 0.02
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
"id": "fill-light",
|
|
76
|
+
"components": {
|
|
77
|
+
"HemisphereLight": {
|
|
78
|
+
"skyColor": [0.78, 0.83, 0.96, 1],
|
|
79
|
+
"groundColor": [0.592, 0.608, 0.651, 1],
|
|
80
|
+
"intensity": 1.15
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- `elevationDeg` and `azimuthDeg` tilt the sky pole; `dither` removes banding in
|
|
89
|
+
the pale gradient, and the faded floor dithers with it.
|
|
90
|
+
- `DomeFade` goes on the floor node itself. Its meshes blend into the live sky
|
|
91
|
+
between 4 m and 10 m from the node origin; it does nothing without the
|
|
92
|
+
`DomeGradient`.
|
|
93
|
+
- Put a `ContactShadow` on each object that stands on the floor, or on a
|
|
94
|
+
component-only child node at its foot, sized a little wider than the
|
|
95
|
+
footprint.
|
|
96
|
+
- `IBLGradient` applies `intensity` once: 0.2025 here is 0.45 in a 1.0.x scene.
|
|
97
|
+
|
|
98
|
+
The starter grounds its pieces with these component-only child nodes, each
|
|
99
|
+
with just `transform.position` and `components.ContactShadow`: `size`, and
|
|
100
|
+
`height` where the blob sits lower than the 2 mm default. A round blob's
|
|
101
|
+
`height` is 2 mm times its width, so small blobs sit close to the surface and an
|
|
102
|
+
object's foot meets its blob without a gap.
|
|
103
|
+
|
|
104
|
+
| Node | Parent | `position` | `ContactShadow.size` | `ContactShadow.height` |
|
|
105
|
+
| ----------------------- | --------------- | ----------------------- | -------------------- | ---------------------- |
|
|
106
|
+
| `grab-plinth-contact` | `grab-plinth` | `[0, 0.002, 0]` | `[0.8, 0.8]` | `0.0016` |
|
|
107
|
+
| `select-plinth-contact` | `select-plinth` | `[0, 0.002, 0]` | `[0.8, 0.8]` | `0.0016` |
|
|
108
|
+
| `spin-plinth-contact` | `spin-plinth` | `[0, 0.002, 0]` | `[0.8, 0.8]` | `0.0016` |
|
|
109
|
+
| `graphite-cube-contact` | `grab-plinth` | `[-0.25, 0.921, -0.03]` | `[0.26, 0.26]` | `0.00052` |
|
|
110
|
+
| `graphite-gem-contact` | `grab-plinth` | `[0, 0.921, -0.03]` | `[0.24, 0.24]` | `0.00048` |
|
|
111
|
+
| `graphite-knot-contact` | `grab-plinth` | `[0.25, 0.921, -0.03]` | `[0.26, 0.26]` | `0.00052` |
|
|
112
|
+
| `robot-contact` | `select-plinth` | `[0, 0.921, -0.02]` | `[0.37, 0.37]` | `0.00074` |
|
|
113
|
+
| `graphite-ring-contact` | `spin-plinth` | `[0, 0.921, -0.02]` | `[0.4, 0.4]` | `0.0008` |
|
|
114
|
+
| `gallery-set-contact` | `gallery-set` | `[0, 0.002, 0]` | `[1.9, 1]` | default |
|
|
115
|
+
| `gallery-vase-contact` | `gallery-set` | `[-0.95, 0.002, -0.15]` | `[0.55, 0.55]` | `0.0011` |
|
|
116
|
+
| `sideboard-set-contact` | `sideboard-set` | `[0, 0.002, 0]` | `[2.3, 0.9]` | default |
|
|
117
|
+
| `floor-lamp-contact` | `sideboard-set` | `[1.1, 0.002, -0.08]` | `[0.45, 0.45]` | `0.0009` |
|
|
118
|
+
|
|
119
|
+
## Default Sky
|
|
120
|
+
|
|
121
|
+
A neutral daylight sky and matching image-based light, as the components'
|
|
122
|
+
defaults. Add a `DomeFade` to the floor node so the floor has no visible edge.
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
{
|
|
126
|
+
"components": {
|
|
127
|
+
"com.iwsdk.components.DomeGradient": {
|
|
128
|
+
"sky": [0.2423, 0.6172, 0.8308, 1],
|
|
129
|
+
"equator": [0.6584, 0.7084, 0.7913, 1],
|
|
130
|
+
"ground": [0.807, 0.7758, 0.7454, 1],
|
|
131
|
+
"intensity": 1
|
|
132
|
+
},
|
|
133
|
+
"com.iwsdk.components.IBLGradient": {
|
|
134
|
+
"sky": [0.6902, 0.749, 0.7843, 1],
|
|
135
|
+
"equator": [0.6584, 0.7084, 0.7913, 1],
|
|
136
|
+
"ground": [0.807, 0.7758, 0.7454, 1],
|
|
137
|
+
"intensity": 1
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## AR Passthrough
|
|
144
|
+
|
|
145
|
+
No sky, so passthrough stays visible; image-based light for the content, and a
|
|
146
|
+
shadow-only floor plus blobs to ground it. This is the AR starter's setup.
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"components": {
|
|
151
|
+
"com.iwsdk.components.IBLGradient": {
|
|
152
|
+
"sky": [0.96, 0.94, 0.9, 1],
|
|
153
|
+
"equator": [0.8, 0.76, 0.7, 1],
|
|
154
|
+
"ground": [0.46, 0.42, 0.38, 1],
|
|
155
|
+
"intensity": 0.25
|
|
156
|
+
}
|
|
157
|
+
},
|
|
158
|
+
"environment": {
|
|
159
|
+
"toneMapping": "aces",
|
|
160
|
+
"exposure": 1,
|
|
161
|
+
"shadows": true,
|
|
162
|
+
"shadowMapType": "pcf"
|
|
163
|
+
},
|
|
164
|
+
"nodes": [
|
|
165
|
+
{
|
|
166
|
+
"id": "shadow-catcher",
|
|
167
|
+
"framingRole": "support",
|
|
168
|
+
"transform": { "position": [0, 0.001, -1.35] },
|
|
169
|
+
"components": { "ShadowCatcher": { "size": [6, 6], "opacity": 0.25 } }
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
"id": "plinth",
|
|
173
|
+
"content": { "type": "asset", "asset": "plinth", "castShadow": true },
|
|
174
|
+
"transform": { "position": [0, 0, -1.5] },
|
|
175
|
+
"components": {
|
|
176
|
+
"ContactShadow": {
|
|
177
|
+
"size": [0.8, 0.8],
|
|
178
|
+
"opacity": 0.4,
|
|
179
|
+
"color": [0, 0, 0, 1]
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
},
|
|
183
|
+
{
|
|
184
|
+
"id": "key-light",
|
|
185
|
+
"transform": {
|
|
186
|
+
"position": [-2.3541, 11.2763, 1.762],
|
|
187
|
+
"rotationDeg": [-73.3982, -11.3134, 0]
|
|
188
|
+
},
|
|
189
|
+
"components": {
|
|
190
|
+
"DirectionalLight": {
|
|
191
|
+
"color": [1, 0.945, 0.87, 1],
|
|
192
|
+
"intensity": 2,
|
|
193
|
+
"castShadow": true,
|
|
194
|
+
"shadowMapSize": "1024",
|
|
195
|
+
"shadowCameraSize": 6,
|
|
196
|
+
"shadowCameraNear": 2,
|
|
197
|
+
"shadowCameraFar": 24,
|
|
198
|
+
"shadowRadius": 5,
|
|
199
|
+
"shadowBias": -0.0004,
|
|
200
|
+
"shadowNormalBias": 0.02
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
},
|
|
204
|
+
{
|
|
205
|
+
"id": "fill-light",
|
|
206
|
+
"components": {
|
|
207
|
+
"HemisphereLight": {
|
|
208
|
+
"skyColor": [0.96, 0.94, 0.9, 1],
|
|
209
|
+
"groundColor": [0.55, 0.52, 0.48, 1],
|
|
210
|
+
"intensity": 1
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
]
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
The AR starter grounds its stations with the first eight contact nodes of the
|
|
219
|
+
Clay Studio table (the plinths and the pieces on them, with the same parents,
|
|
220
|
+
positions, sizes and heights), each tinted like the plinth above.
|
|
221
|
+
|
|
222
|
+
- Leave out `DomeGradient` and `DomeTexture` for AR. The runtime hides them in
|
|
223
|
+
an AR session anyway, so they only change the editor and desktop preview,
|
|
224
|
+
which then show a sky the headset never does.
|
|
225
|
+
- `ShadowCatcher` shows shadows only with `environment.shadows`, a light with
|
|
226
|
+
`castShadow` and `castShadow` content above it. A `ContactShadow` needs none
|
|
227
|
+
of that.
|
|
228
|
+
- Tint `ContactShadow` black for AR, at a lower opacity than the 0.72 default:
|
|
229
|
+
`"opacity": 0.4, "color": [0, 0, 0, 1]`. The default blue-grey lightens
|
|
230
|
+
anything darker than itself, so over a dark room, or the near-black page the
|
|
231
|
+
editor and the managed browser show behind the desktop preview, the blob
|
|
232
|
+
glows. Black only darkens, so it reads as a shadow on light floors, dark
|
|
233
|
+
floors and passthrough alike; at 0.4 it is about as dark on a light floor as
|
|
234
|
+
the default blob.
|
package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# IWSDK Compose Scene: Extended Workflow
|
|
2
|
+
|
|
3
|
+
Read this reference only after the top-level skill has ruled out the Fast Path.
|
|
4
|
+
|
|
5
|
+
Use the focused references as needed:
|
|
6
|
+
|
|
7
|
+
- [scene-format.md](scene-format.md) when the existing scene does not demonstrate a
|
|
8
|
+
required construct, or when schema diagnostics need investigation;
|
|
9
|
+
- [text-intake.md](text-intake.md) for scene-layout evidence from text;
|
|
10
|
+
- [image-intake.md](image-intake.md) for scene-layout and camera evidence from image
|
|
11
|
+
or hybrid requests; route model-local reconstruction separately;
|
|
12
|
+
- [scene-composition.md](scene-composition.md) for modules, scene-level repetition,
|
|
13
|
+
lighting, cameras, and cost control;
|
|
14
|
+
- [scene-review.md](scene-review.md) before final review.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
Enter this workflow only when the routing criteria above exclude the Fast Path.
|
|
18
|
+
|
|
19
|
+
### 1. Specify
|
|
20
|
+
|
|
21
|
+
Turn the request into a compact implementation brief:
|
|
22
|
+
|
|
23
|
+
- required and optional features;
|
|
24
|
+
- source evidence regions for image input;
|
|
25
|
+
- silhouette, proportions, parts, negative space, contacts, and material response;
|
|
26
|
+
- hero and diagnostic views;
|
|
27
|
+
- measurable acceptance criteria;
|
|
28
|
+
- assumptions, uncertainty, and fidelity ceiling.
|
|
29
|
+
|
|
30
|
+
A single image proves visible composition, not hidden geometry. Do not silently invent
|
|
31
|
+
occluded detail or lower requested fidelity.
|
|
32
|
+
|
|
33
|
+
### 2. Inventory Assets And Modules
|
|
34
|
+
|
|
35
|
+
Inspect the existing scene, `src/assets.ts`, and relevant asset modules first. Call
|
|
36
|
+
`scene_get_capabilities` only when the task introduces a component, content kind,
|
|
37
|
+
pattern, import, or schema feature that the existing project and focused reference
|
|
38
|
+
search do not already demonstrate. Do not load the full schema for routine placement.
|
|
39
|
+
|
|
40
|
+
Classify each requested visible element as an existing manifest asset, a new model,
|
|
41
|
+
a UIKitML panel, or a scene-level assembly. Invoke `iwsdk-build-model` for each new
|
|
42
|
+
or materially changed 3D model—including support, architecture, and set dressing—and
|
|
43
|
+
`iwsdk-ui` for UIKitML. Continue here only once every visible asset has a stable
|
|
44
|
+
manifest id, object-local envelope, and relevant attachment anchors. From this point
|
|
45
|
+
until a model-local defect is discovered, do not create or edit asset TypeScript.
|
|
46
|
+
|
|
47
|
+
For initial construction, plan independent semantic groups as standalone scratch
|
|
48
|
+
scene modules. Give each module a local origin, size envelope, attachment points,
|
|
49
|
+
required views, and asset IDs. Asset and component IDs are application-global;
|
|
50
|
+
imported node and prefab IDs are namespaced. Imports are an authoring-only assembly
|
|
51
|
+
mechanism, never a runtime or editable-project format.
|
|
52
|
+
|
|
53
|
+
### 3. Compose
|
|
54
|
+
|
|
55
|
+
Author scene JSON in dependency order:
|
|
56
|
+
|
|
57
|
+
1. support/stage and representative lighting;
|
|
58
|
+
2. large placed assets and cross-asset scale;
|
|
59
|
+
3. identity-critical spatial relationships and support contacts;
|
|
60
|
+
4. repeated placed assets through prefabs or patterns;
|
|
61
|
+
5. hero camera and final environment.
|
|
62
|
+
|
|
63
|
+
Use meters, stable descriptive IDs, deterministic ordering, and explicit transforms.
|
|
64
|
+
Groups supply hierarchy, never visible mass. Use `castShadow` and `receiveShadow`
|
|
65
|
+
only when needed. Do not rebuild missing model detail from scene primitives or JSON.
|
|
66
|
+
|
|
67
|
+
### 4. Validate And Materialize
|
|
68
|
+
|
|
69
|
+
With the managed editor command-ready, call `scene_render_file` on every changed
|
|
70
|
+
scratch module, then the composition root. It resolves imports for authoring preview,
|
|
71
|
+
validates schema and manifest references, lowers the scene, and returns a PNG plus
|
|
72
|
+
diagnostics without changing the active document. Fix failures in the owning asset or
|
|
73
|
+
scratch file.
|
|
74
|
+
|
|
75
|
+
Keep agent-loop renders at 640×640 or smaller and prefer the MCP call, which persists
|
|
76
|
+
the image and returns `screenshotPath`. Read that file only when visual inspection is
|
|
77
|
+
needed. Generate a larger delivery image only after the final camera is chosen, and
|
|
78
|
+
do not feed that duplicate image back into the model context.
|
|
79
|
+
|
|
80
|
+
After the composition root passes, run `scene_flatten_file` / `iwsdk scene flatten`
|
|
81
|
+
once to materialize an import-free final scene. The command preserves import wrapper
|
|
82
|
+
groups, validates the output, and refuses to write if its runtime hash differs from
|
|
83
|
+
the composed source. This is a one-way publication boundary: the flat file becomes
|
|
84
|
+
the sole source of truth, and later scratch-module changes must not be re-flattened
|
|
85
|
+
over human edits.
|
|
86
|
+
|
|
87
|
+
Call `scene_open` only on the flattened file for live collaboration. Import-bearing
|
|
88
|
+
files remain renderable composition previews but are never opened as editable scenes
|
|
89
|
+
and never load in the application runtime.
|
|
90
|
+
|
|
91
|
+
Use `scene_get_state` for selection, hashes, diagnostics, dirty/conflict state, runtime
|
|
92
|
+
readiness, and render statistics. Use camera, screenshot, selection, and preview
|
|
93
|
+
visibility tools only when their live-editor context is useful.
|
|
94
|
+
|
|
95
|
+
### 5. Review And Refine
|
|
96
|
+
|
|
97
|
+
Review in three passes:
|
|
98
|
+
|
|
99
|
+
1. **Layout**: hierarchy, scale, support contacts, and arrangement.
|
|
100
|
+
2. **Asset fit**: silhouette and proportions in context, occlusion, and cross-asset
|
|
101
|
+
contacts. If the defect remains when the asset is viewed by itself, route it to
|
|
102
|
+
`iwsdk-build-model` instead of compensating with scene transforms.
|
|
103
|
+
3. **Final**: material response, color, lighting, environment, and hero framing.
|
|
104
|
+
|
|
105
|
+
Keep review orchestration and evidence outside the editor. The editor supplies
|
|
106
|
+
authoritative screenshots, hashes, camera state, diagnostics, and render measurements.
|
|
107
|
+
Derive comparisons, defect lists, lineage, and stop decisions in ordinary task files.
|
|
108
|
+
|
|
109
|
+
Fix the highest-impact scene defect in its owning scene module. Route model-local
|
|
110
|
+
geometry or material defects to `iwsdk-build-model`, then rerender that asset and the
|
|
111
|
+
scene. Default to two focused correction rounds. Stop earlier on a
|
|
112
|
+
repeated defect, oscillation, plateau, missing input/asset, or representation ceiling.
|
|
113
|
+
|
|
114
|
+
### 6. Finish
|
|
115
|
+
|
|
116
|
+
Finish only when:
|
|
117
|
+
|
|
118
|
+
- every scratch module and the composition root validates and renders;
|
|
119
|
+
- the final editable scene is flattened and contains no `imports`;
|
|
120
|
+
- the active editor state is clean and conflict-free;
|
|
121
|
+
- every new or changed model has passed `iwsdk-build-model` isolated review;
|
|
122
|
+
- required views are nonblank and correctly framed;
|
|
123
|
+
- required features pass measurable and visual checks;
|
|
124
|
+
- manifest asset IDs resolve in both editor and application runtime;
|
|
125
|
+
- the application build and selected scene load without blocking errors.
|
|
126
|
+
|
|
127
|
+
If a required gate is unavailable, finish with an explicit blocked or
|
|
128
|
+
accepted-with-gaps result. Passing a local schema check, production build, or custom
|
|
129
|
+
diagnostic image does not substitute for authoritative editor renders and state.
|
|
130
|
+
|
|
131
|
+
## Modular Composition
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"version": "iwsdk.scene.v1",
|
|
136
|
+
"units": "meters",
|
|
137
|
+
"imports": [
|
|
138
|
+
{
|
|
139
|
+
"id": "reading-nook",
|
|
140
|
+
"src": "./modules/reading-nook.iwsdk.scene.json",
|
|
141
|
+
"transform": { "position": [1.8, 0, -0.6] }
|
|
142
|
+
}
|
|
143
|
+
],
|
|
144
|
+
"resources": {},
|
|
145
|
+
"nodes": []
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Each scratch module must be valid by itself. Imports resolve recursively in
|
|
150
|
+
declaration order. The import entry becomes a transform group. The composition root
|
|
151
|
+
owns global components, environment, metadata, and authoring settings. Cycles, unsafe
|
|
152
|
+
IDs, missing files, duplicate namespaced IDs, and invalid modules fail composition.
|
|
153
|
+
|
|
154
|
+
For parallel initial construction, assign one scratch module file per worker. Never
|
|
155
|
+
let two workers edit one file. Render modules independently, import only passing
|
|
156
|
+
modules, correct cross-module scale, contact, occlusion, lighting, and framing at the
|
|
157
|
+
composition root, then flatten exactly once. Parallel module iteration ends at that
|
|
158
|
+
boundary; continue all later edits in the flat file.
|
|
159
|
+
|
|
160
|
+
## Regeneration And Provenance
|
|
161
|
+
|
|
162
|
+
Preserve stable IDs when revising the flat file. Never overwrite unrelated
|
|
163
|
+
human-authored files or re-flatten over editor changes. Record the skill/runtime
|
|
164
|
+
versions, input hashes, composition/final/module paths, capability hash,
|
|
165
|
+
source/composed/runtime hashes, assumptions, and fidelity ceiling in authoring
|
|
166
|
+
metadata or adjacent task evidence.
|