@iwsdk/create 0.4.1 → 0.5.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 +103 -41
- package/dist/cli.js +1003 -3418
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
- package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
- package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
- package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
- package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
- package/dist/guidance/claude/.claude/settings.json +19 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/CLAUDE.md +142 -0
- package/dist/guidance/codex/.codex/config.toml +2 -0
- package/dist/guidance/common/AGENTS.md +151 -0
- package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
- package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
- package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
- package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
- package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
- package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
- package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
- package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/gitignore.template +45 -0
- package/dist/template/common/index.html +16 -0
- package/dist/template/common/nvmrc.template +1 -0
- package/dist/template/common/public/audio/chime.mp3 +0 -0
- package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common/public/textures/webxr.png +0 -0
- package/dist/template/common/public/ui/welcome.uikitml +98 -0
- package/dist/template/common/src/assets.ts +54 -0
- package/dist/template/common/src/components.ts +11 -0
- package/dist/template/common/src/index.ts +19 -0
- package/dist/template/common/src/panel.ts +38 -0
- package/dist/template/common/src/robot-component.ts +10 -0
- package/dist/template/common/src/robot.ts +38 -0
- package/dist/template/common/src/vite-env.d.ts +2 -0
- package/dist/template/common/tsconfig.json +15 -0
- package/dist/template/common/vite.config.ts +27 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/gitignore.template +45 -0
- package/dist/template/common-js/index.html +16 -0
- package/dist/template/common-js/nvmrc.template +1 -0
- package/dist/template/common-js/public/audio/chime.mp3 +0 -0
- package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common-js/public/textures/webxr.png +0 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
- package/dist/template/common-js/src/assets.js +45 -0
- package/dist/template/common-js/src/components.js +9 -0
- package/dist/template/common-js/src/index.js +14 -0
- package/dist/template/common-js/src/panel.js +31 -0
- package/dist/template/common-js/src/robot-component.js +8 -0
- package/dist/template/common-js/src/robot.js +37 -0
- package/dist/template/common-js/vite.config.js +25 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
- package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
- package/package.json +23 -17
- package/scripts/verify-release-ready.mjs +76 -0
- package/LICENSE +0 -21
|
@@ -0,0 +1,458 @@
|
|
|
1
|
+
# IWSDK Scene Format
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
1. Capability First
|
|
6
|
+
2. Document Boundary
|
|
7
|
+
3. Asset Boundary
|
|
8
|
+
4. Nodes And Content
|
|
9
|
+
5. Prefabs And Patterns
|
|
10
|
+
6. Imports
|
|
11
|
+
7. Components And Constraints
|
|
12
|
+
8. Authoring And Review
|
|
13
|
+
9. Validation Traps
|
|
14
|
+
|
|
15
|
+
## Capability First
|
|
16
|
+
|
|
17
|
+
Call `scene_get_capabilities` before authoring. The active schema version, content
|
|
18
|
+
kinds, component hashes, pattern algorithms, and limits are authoritative.
|
|
19
|
+
|
|
20
|
+
The only format is `iwsdk.scene.v1`, in meters. Scene JSON is composition data. The
|
|
21
|
+
runtime projection strips `authoring` and hashes canonical JSON for runtime identity.
|
|
22
|
+
|
|
23
|
+
## Document Boundary
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"version": "iwsdk.scene.v1",
|
|
28
|
+
"units": "meters",
|
|
29
|
+
"components": {
|
|
30
|
+
"com.iwsdk.components.DomeGradient": {
|
|
31
|
+
"sky": [0.2423, 0.6172, 0.8308, 1],
|
|
32
|
+
"equator": [0.6584, 0.7084, 0.7913, 1],
|
|
33
|
+
"ground": [0.807, 0.7758, 0.7454, 1],
|
|
34
|
+
"intensity": 1
|
|
35
|
+
},
|
|
36
|
+
"com.iwsdk.components.IBLGradient": {
|
|
37
|
+
"sky": [0.6902, 0.749, 0.7843, 1],
|
|
38
|
+
"equator": [0.6584, 0.7084, 0.7913, 1],
|
|
39
|
+
"ground": [0.807, 0.7758, 0.7454, 1],
|
|
40
|
+
"intensity": 1
|
|
41
|
+
}
|
|
42
|
+
},
|
|
43
|
+
"metadata": {},
|
|
44
|
+
"authoring": {},
|
|
45
|
+
"resources": { "prefabs": [] },
|
|
46
|
+
"environment": {},
|
|
47
|
+
"nodes": []
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- `components` apply to the actual IWSDK level-root entity. `DomeGradient` and
|
|
52
|
+
`IBLGradient` are normal removable components, not editor-only environment fields.
|
|
53
|
+
- `LevelRoot`, `LevelTag`, and `Transform` are runtime-owned and must not appear in
|
|
54
|
+
`components`.
|
|
55
|
+
- `resources` contains only reusable scene prefabs.
|
|
56
|
+
- Use namespaced keys in opaque `metadata`. Do not hide structural fields there.
|
|
57
|
+
- Structural objects are closed. Unknown fields fail validation.
|
|
58
|
+
|
|
59
|
+
## Asset Boundary
|
|
60
|
+
|
|
61
|
+
Scene JSON never declares assets, URLs, geometry, or materials. Those live in the
|
|
62
|
+
`defineAssets()` module selected by `iwsdk.config.json` at `assets.module`.
|
|
63
|
+
|
|
64
|
+
Valid renderable content references a manifest ID:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"id": "hero-chair",
|
|
69
|
+
"name": "Hero reading chair",
|
|
70
|
+
"content": {
|
|
71
|
+
"type": "asset",
|
|
72
|
+
"asset": "reading-chair",
|
|
73
|
+
"castShadow": true,
|
|
74
|
+
"receiveShadow": true
|
|
75
|
+
},
|
|
76
|
+
"transform": {
|
|
77
|
+
"position": [0.6, 0, -0.8],
|
|
78
|
+
"rotationDeg": [0, -18, 0],
|
|
79
|
+
"scale": 1
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The `asset` string is application-global. It is not namespaced when a scene module is
|
|
85
|
+
imported. The editor validates it against the live manifest and derives bounds from
|
|
86
|
+
the registered object.
|
|
87
|
+
|
|
88
|
+
The following old branches are invalid and must never be emitted:
|
|
89
|
+
|
|
90
|
+
- `content.type: "model"`;
|
|
91
|
+
- `content.type: "primitive"`;
|
|
92
|
+
- `resources.assets`;
|
|
93
|
+
- `resources.materials`;
|
|
94
|
+
- node or prefab material overrides.
|
|
95
|
+
|
|
96
|
+
Create procedural shapes and custom PBR/shader materials in TypeScript, register the
|
|
97
|
+
resulting parentless `Object3D`, then reference its asset ID. See
|
|
98
|
+
[asset-authoring.md](asset-authoring.md).
|
|
99
|
+
|
|
100
|
+
## Nodes And Content
|
|
101
|
+
|
|
102
|
+
Every node has a stable `id` and may contain `name`, `content`, `transform`,
|
|
103
|
+
`constraints`, `components`, `metadata`, `framingRole`, and `children`.
|
|
104
|
+
|
|
105
|
+
Supported content kinds are:
|
|
106
|
+
|
|
107
|
+
### Group
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{ "id": "furniture", "content": { "type": "group" }, "children": [] }
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
A group has no visible surface. It cannot prove presence, silhouette, support, or
|
|
114
|
+
framing by itself.
|
|
115
|
+
|
|
116
|
+
### Asset
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"id": "table",
|
|
121
|
+
"content": {
|
|
122
|
+
"type": "asset",
|
|
123
|
+
"asset": "round-side-table",
|
|
124
|
+
"castShadow": true,
|
|
125
|
+
"receiveShadow": false
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Shadow flags default to false. Opt in only where the shadow contributes to the scene.
|
|
131
|
+
|
|
132
|
+
### Prefab Instance
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"id": "left-chair",
|
|
137
|
+
"content": {
|
|
138
|
+
"type": "instance",
|
|
139
|
+
"prefab": "chair-with-cushion",
|
|
140
|
+
"overrides": {
|
|
141
|
+
"cushion": {
|
|
142
|
+
"transform": { "position": [0, 0.03, 0] },
|
|
143
|
+
"visible": true
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Overrides may adjust transforms, visibility, and component payloads. They cannot
|
|
151
|
+
change geometry or materials.
|
|
152
|
+
|
|
153
|
+
### Pattern
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"id": "books",
|
|
158
|
+
"content": {
|
|
159
|
+
"type": "pattern",
|
|
160
|
+
"prefab": "book",
|
|
161
|
+
"distribution": {
|
|
162
|
+
"type": "linear",
|
|
163
|
+
"count": 12,
|
|
164
|
+
"step": [0.065, 0, 0]
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Supported distributions are capability-defined and normally include `linear`,
|
|
171
|
+
`grid`, `radial`, `along-path`, `scatter`, and `explicit`. Scatter uses an explicit
|
|
172
|
+
seed and algorithm. Use `collision: "allow"` or `"skip"` deliberately.
|
|
173
|
+
|
|
174
|
+
### Light
|
|
175
|
+
|
|
176
|
+
Lights are ECS components on otherwise ordinary scene nodes. The node transform
|
|
177
|
+
positions the light; directional, spot, and rectangular area lights emit along
|
|
178
|
+
the node's local `-Z` axis.
|
|
179
|
+
|
|
180
|
+
```json
|
|
181
|
+
{
|
|
182
|
+
"id": "key-light",
|
|
183
|
+
"transform": {
|
|
184
|
+
"position": [2, 4, 3],
|
|
185
|
+
"rotationDeg": [55, -45, 0]
|
|
186
|
+
},
|
|
187
|
+
"components": {
|
|
188
|
+
"com.iwsdk.components.DirectionalLight": {
|
|
189
|
+
"color": [1, 0.897, 0.738, 1],
|
|
190
|
+
"intensity": 2.2,
|
|
191
|
+
"castShadow": true,
|
|
192
|
+
"shadowMapSize": "1024"
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The built-in component IDs are `AmbientLight`, `HemisphereLight`,
|
|
199
|
+
`DirectionalLight`, `PointLight`, `SpotLight`, and `RectAreaLight`, each under
|
|
200
|
+
the `com.iwsdk.components` namespace. Component colors are linear RGBA arrays.
|
|
201
|
+
Use root IBL for general PBR response and authored lights for composition.
|
|
202
|
+
|
|
203
|
+
Structural objects are closed, so an unknown field fails validation. The exact
|
|
204
|
+
fields are:
|
|
205
|
+
|
|
206
|
+
| Component | Fields |
|
|
207
|
+
| --- | --- |
|
|
208
|
+
| `AmbientLight` | `color`, `intensity` |
|
|
209
|
+
| `HemisphereLight` | `skyColor`, `groundColor`, `intensity` |
|
|
210
|
+
| `DirectionalLight` | `color`, `intensity`, `shadowCameraSize`, + shadow set |
|
|
211
|
+
| `PointLight` | `color`, `intensity` (candela), `distance`, `decay`, + shadow set |
|
|
212
|
+
| `SpotLight` | `color`, `intensity` (candela), `distance`, `decay`, `angleDeg`, `penumbra`, + shadow set |
|
|
213
|
+
| `RectAreaLight` | `color`, `intensity` (nit), `width`, `height` — no shadows |
|
|
214
|
+
|
|
215
|
+
The shadow set is `castShadow`, `shadowMapSize` (enum string `"256"`, `"512"`,
|
|
216
|
+
`"1024"`, `"2048"`), `shadowBias`, `shadowNormalBias`, `shadowRadius`,
|
|
217
|
+
`shadowCameraNear`, `shadowCameraFar`. `AmbientLight` and `HemisphereLight`
|
|
218
|
+
ignore the node transform.
|
|
219
|
+
|
|
220
|
+
## Prefabs And Patterns
|
|
221
|
+
|
|
222
|
+
Prefabs are the only scene-local resource:
|
|
223
|
+
|
|
224
|
+
```json
|
|
225
|
+
{
|
|
226
|
+
"resources": {
|
|
227
|
+
"prefabs": [
|
|
228
|
+
{
|
|
229
|
+
"id": "book",
|
|
230
|
+
"root": {
|
|
231
|
+
"id": "book-root",
|
|
232
|
+
"content": { "type": "asset", "asset": "hardcover-book" }
|
|
233
|
+
}
|
|
234
|
+
},
|
|
235
|
+
{
|
|
236
|
+
"id": "chair-with-cushion",
|
|
237
|
+
"root": {
|
|
238
|
+
"id": "chair-root",
|
|
239
|
+
"content": { "type": "asset", "asset": "reading-chair" },
|
|
240
|
+
"children": [
|
|
241
|
+
{
|
|
242
|
+
"id": "cushion",
|
|
243
|
+
"content": { "type": "asset", "asset": "chair-cushion" }
|
|
244
|
+
}
|
|
245
|
+
]
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
]
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Prefab node IDs are local until instantiated. Runtime IDs are derived
|
|
254
|
+
deterministically. Do not author IDs that collide with derived paths such as
|
|
255
|
+
`chairs/0000/book-root`.
|
|
256
|
+
|
|
257
|
+
A pattern may become one `InstancedMesh` when its prefab resolves to one eligible
|
|
258
|
+
mesh. Component-bearing or compound prefabs expand to distinct cloned hierarchies.
|
|
259
|
+
|
|
260
|
+
## Authoring-Only Imports
|
|
261
|
+
|
|
262
|
+
```json
|
|
263
|
+
{
|
|
264
|
+
"imports": [
|
|
265
|
+
{
|
|
266
|
+
"id": "nook",
|
|
267
|
+
"src": "./modules/nook.iwsdk.scene.json",
|
|
268
|
+
"transform": { "position": [2, 0, -1] }
|
|
269
|
+
}
|
|
270
|
+
]
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Each imported file must be a valid standalone v1 scene. Imports are permitted only in
|
|
275
|
+
scratch composition documents rendered by authoring tools; the editable final scene
|
|
276
|
+
and application runtime reject them. Imports resolve recursively in declaration order.
|
|
277
|
+
Node and prefab IDs are namespaced as
|
|
278
|
+
`<import-id>/<local-id>`. Asset and component IDs remain unchanged and
|
|
279
|
+
application-global.
|
|
280
|
+
|
|
281
|
+
The import entry becomes a group wrapper carrying the import transform. The root owns
|
|
282
|
+
top-level components, environment, metadata, and authoring globals; module globals do
|
|
283
|
+
not override them. Once the composition passes, flatten and make the generated
|
|
284
|
+
import-free document the sole source of truth. Never re-flatten over later editor
|
|
285
|
+
changes.
|
|
286
|
+
|
|
287
|
+
Use `scene_flatten_file` or `npx iwsdk scene flatten` to materialize the final
|
|
288
|
+
document. The command resolves the import graph, preserves wrapper transforms,
|
|
289
|
+
validates the flat output, writes atomically, and refuses the write if flattening
|
|
290
|
+
changes runtime semantics.
|
|
291
|
+
|
|
292
|
+
Verify the flatten preserved semantics by comparing `runtimeHash` before and
|
|
293
|
+
after — they must be identical. Note that only `authoring` and `imports` are
|
|
294
|
+
stripped from the runtime projection, so writing provenance into `metadata`
|
|
295
|
+
changes the hash and defeats this check.
|
|
296
|
+
|
|
297
|
+
## Components And Constraints
|
|
298
|
+
|
|
299
|
+
Component keys use their registered IWSDK IDs. Values are the component's raw props:
|
|
300
|
+
|
|
301
|
+
```json
|
|
302
|
+
{
|
|
303
|
+
"components": {
|
|
304
|
+
"com.iwsdk.components.Visibility": {
|
|
305
|
+
"isVisible": true
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Scene files never embed component schemas. Declare application components in a
|
|
312
|
+
system-free module, export a manifest with `defineComponents`, and give that same
|
|
313
|
+
manifest to the runtime and Vite plugin:
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
// src/components.ts
|
|
317
|
+
import { defineComponents } from '@iwsdk/core';
|
|
318
|
+
import { ReadingState } from './components/reading-state.js';
|
|
319
|
+
|
|
320
|
+
export default defineComponents([ReadingState]);
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
```ts
|
|
324
|
+
// iwsdk.config.json points components.module at ./src/components
|
|
325
|
+
// runtime and editor both consume virtual:iwsdk-project
|
|
326
|
+
import projectOptions from 'virtual:iwsdk-project';
|
|
327
|
+
World.create(container, projectOptions);
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
The editor and runtime independently import the same manifest and derive validation
|
|
331
|
+
and inspector metadata from the executable component declarations. Component IDs must
|
|
332
|
+
be unique across IWSDK and the application. Keep declaration modules free of system,
|
|
333
|
+
DOM, renderer, and world side effects; systems may import those declarations.
|
|
334
|
+
|
|
335
|
+
Transforms use `[x, y, z]` tuples, degrees, and positive scalar or vector scale.
|
|
336
|
+
The optional `lookAt` constraint resolves yaw deterministically during lowering:
|
|
337
|
+
|
|
338
|
+
```json
|
|
339
|
+
{
|
|
340
|
+
"constraints": {
|
|
341
|
+
"lookAt": { "mode": "yaw-v1", "target": [0, 1.2, 0] }
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Author spatial relationships directly through node transforms. The schema does not
|
|
347
|
+
infer support, floor contact, or other physical-placement semantics.
|
|
348
|
+
|
|
349
|
+
## Authoring And Review
|
|
350
|
+
|
|
351
|
+
Use `authoring.composition` as a fixed brief, not a process transcript:
|
|
352
|
+
|
|
353
|
+
```json
|
|
354
|
+
{
|
|
355
|
+
"authoring": {
|
|
356
|
+
"composition": {
|
|
357
|
+
"mode": "static",
|
|
358
|
+
"input": {
|
|
359
|
+
"kind": "hybrid",
|
|
360
|
+
"prompt": "A courtyard reading nook",
|
|
361
|
+
"references": []
|
|
362
|
+
},
|
|
363
|
+
"target": {
|
|
364
|
+
"surfaces": ["browser", "vr"],
|
|
365
|
+
"style": "stylized-pbr",
|
|
366
|
+
"assetPolicy": "manifest-assets"
|
|
367
|
+
},
|
|
368
|
+
"feasibility": { "status": "supported" },
|
|
369
|
+
"provenance": {
|
|
370
|
+
"adapter": { "id": "hybrid-intake", "version": "1.0.0" },
|
|
371
|
+
"skill": { "id": "iwsdk-scene-composer", "version": "1.0.0" },
|
|
372
|
+
"capabilityHash": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
|
|
373
|
+
"inputHashes": []
|
|
374
|
+
},
|
|
375
|
+
"representationPolicy": {
|
|
376
|
+
"fidelityCeiling": "stylized-static",
|
|
377
|
+
"allowed": ["asset", "prefab", "pattern"]
|
|
378
|
+
},
|
|
379
|
+
"features": [],
|
|
380
|
+
"assumptions": [],
|
|
381
|
+
"review": {
|
|
382
|
+
"heroView": "hero",
|
|
383
|
+
"requiredViews": ["hero", "top", "quarter"],
|
|
384
|
+
"lenses": ["layout", "geometry", "final"],
|
|
385
|
+
"maxCorrectionRounds": 2
|
|
386
|
+
}
|
|
387
|
+
},
|
|
388
|
+
"views": []
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
`inputHashes` is the exact unique set of the prompt SHA-256, when present, plus every
|
|
394
|
+
declared reference digest with a `sha256:` prefix. Changing prompt whitespace changes
|
|
395
|
+
identity.
|
|
396
|
+
|
|
397
|
+
Every required feature needs implementation node bindings and immutable acceptance
|
|
398
|
+
criteria. Supported kinds normally include presence, count, projected-region,
|
|
399
|
+
spatial-relation, and visual-judgment.
|
|
400
|
+
|
|
401
|
+
Use `capture-node-mask-bounds-v1` for projected region evidence of manifest assets.
|
|
402
|
+
Their arbitrary external geometry cannot be proven from a JSON world-AABB assumption.
|
|
403
|
+
|
|
404
|
+
Authoring views contain exact projection parameters. Perspective views use position,
|
|
405
|
+
target, and FOV. Orthographic views use position, target, and height. Pass a saved
|
|
406
|
+
`viewId` to camera or screenshot tools rather than approximating it with a preset.
|
|
407
|
+
The separate `view` field accepts only built-in preset names. The runtime applies the
|
|
408
|
+
scene's hero view after level initialization, so adjust that authored view when editor
|
|
409
|
+
and runtime framing need to stay in parity; an initial `World.create` camera is not an
|
|
410
|
+
override for a scene-owned camera.
|
|
411
|
+
|
|
412
|
+
```json
|
|
413
|
+
{
|
|
414
|
+
"authoring": {
|
|
415
|
+
"views": [
|
|
416
|
+
{
|
|
417
|
+
"id": "hero",
|
|
418
|
+
"role": "hero",
|
|
419
|
+
"projection": "perspective",
|
|
420
|
+
"position": [0, 1.6, 4.5],
|
|
421
|
+
"target": [0, 1.4, 0],
|
|
422
|
+
"fov": 42
|
|
423
|
+
},
|
|
424
|
+
{
|
|
425
|
+
"id": "top",
|
|
426
|
+
"role": "diagnostic",
|
|
427
|
+
"projection": "orthographic",
|
|
428
|
+
"position": [0, 8, 0],
|
|
429
|
+
"target": [0, 0, 0],
|
|
430
|
+
"height": 8
|
|
431
|
+
}
|
|
432
|
+
]
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
`nodeAnnotations` bind actual nodes to layout, geometry, or final review layers.
|
|
438
|
+
Unannotated renderables default to layout; descendants inherit the nearest annotation.
|
|
439
|
+
|
|
440
|
+
Every node may set `framingRole` to `content` or `support`. Use support only for
|
|
441
|
+
rendered infrastructure such as an oversized floor or backdrop. Requested subjects
|
|
442
|
+
must remain content.
|
|
443
|
+
|
|
444
|
+
## Validation Traps
|
|
445
|
+
|
|
446
|
+
- Do not put `assets` or `materials` under `resources`.
|
|
447
|
+
- Do not emit model, primitive, geometry, material, or material override fields.
|
|
448
|
+
- Do not assume that a file in `public/` is registered; check `src/assets.ts`.
|
|
449
|
+
- Do not use a group as the only binding for a required visible feature.
|
|
450
|
+
- Do not namespace manifest asset IDs inside imported modules.
|
|
451
|
+
- Do not open or load an import-bearing composition as the editable/runtime scene;
|
|
452
|
+
flatten it first.
|
|
453
|
+
- Do not author duplicate or derived runtime IDs.
|
|
454
|
+
- Do not use non-finite transforms, unsafe paths, or unknown
|
|
455
|
+
component fields.
|
|
456
|
+
- Do not claim projected AABB silhouette evidence for arbitrary manifest assets; use
|
|
457
|
+
trusted capture node masks.
|
|
458
|
+
- Do not save over unsaved human editor changes. Resolve the reported conflict first.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Text Intake
|
|
2
|
+
|
|
3
|
+
Use this adapter when the user supplies no visual reference. Text defines design
|
|
4
|
+
intent; do not invent a source-fidelity target or camera-confidence score.
|
|
5
|
+
|
|
6
|
+
## Extract The Brief
|
|
7
|
+
|
|
8
|
+
Record:
|
|
9
|
+
|
|
10
|
+
- required objects and recognizable systems;
|
|
11
|
+
- spatial relations: beside, behind, centered, crossing, enclosing, supporting;
|
|
12
|
+
- counts, approximate scale, and one scale anchor;
|
|
13
|
+
- target surface: browser, VR, AR, or shared;
|
|
14
|
+
- style, palette, and material intent;
|
|
15
|
+
- desired hero view or application view when stated;
|
|
16
|
+
- existing glTF/procedural assets versus new asset-authoring needs;
|
|
17
|
+
- exclusions and non-goals;
|
|
18
|
+
- performance constraints stated by the user or calibrated target profile.
|
|
19
|
+
|
|
20
|
+
Performance constraints are not a first-class authoring branch in the scene format. Put user
|
|
21
|
+
constraints in `metadata["iwsdk.composer.performanceLimits"]` as JSON, or retain them
|
|
22
|
+
in the external cost report. Never present an uncalibrated desktop threshold as a
|
|
23
|
+
device profile.
|
|
24
|
+
|
|
25
|
+
Convert ambiguous but nonblocking choices into explicit assumptions with
|
|
26
|
+
`high | medium | low` certainty. Ask only when different interpretations would change
|
|
27
|
+
a required feature or make the request unsupported.
|
|
28
|
+
|
|
29
|
+
## Define Features
|
|
30
|
+
|
|
31
|
+
Create 3-8 required or important features that make the request recognizably correct.
|
|
32
|
+
Prefer observable results:
|
|
33
|
+
|
|
34
|
+
- `crossroads`: two roads intersect at right angles with four pedestrian crossings;
|
|
35
|
+
- `relative-height`: apartment building is at least twice the house height;
|
|
36
|
+
- `reading-cluster`: chair, lamp, and side table form one reachable cluster;
|
|
37
|
+
- `arch-opening`: path passes visibly through the stone arch;
|
|
38
|
+
- `vehicle-heading`: car points along the east-west road.
|
|
39
|
+
|
|
40
|
+
Bind each feature to planned node IDs and typed acceptance criteria. Avoid vague
|
|
41
|
+
criteria such as "looks good" or "high quality."
|
|
42
|
+
|
|
43
|
+
## Select A Representation
|
|
44
|
+
|
|
45
|
+
Call `scene_get_capabilities`, inspect the configured asset manifest, then choose in
|
|
46
|
+
this order:
|
|
47
|
+
|
|
48
|
+
1. reuse a registered glTF or procedural asset when it satisfies the required form;
|
|
49
|
+
2. author a new manifest asset when identity, geometry, or material response is
|
|
50
|
+
missing;
|
|
51
|
+
3. assemble registered assets in a scene prefab for a reusable semantic object;
|
|
52
|
+
4. use a deterministic pattern for repeated compatible prefabs;
|
|
53
|
+
5. accept an approximation with a named fidelity ceiling;
|
|
54
|
+
6. block when a required feature has no supportable representation.
|
|
55
|
+
|
|
56
|
+
Do not fabricate catalog IDs. Procedural code is an explicit asset-authoring surface,
|
|
57
|
+
not a hidden scene escape hatch: keep it deterministic in a dedicated asset module,
|
|
58
|
+
register its parentless `Object3D` in the manifest, and reference that ID from JSON.
|
|
59
|
+
|
|
60
|
+
## Establish Scale And Coordinates
|
|
61
|
+
|
|
62
|
+
Use `+Y` up. Choose a semantic origin such as scene center, floor center, or crossing
|
|
63
|
+
center. Put group origins where later editing is natural. Use conventional dimensions
|
|
64
|
+
only when the prompt supplies no evidence; record those values as assumptions.
|
|
65
|
+
|
|
66
|
+
The persistent player origin materializes at `[0, 0, 0]` unless the top-level
|
|
67
|
+
`player.transform` deliberately moves it. A semantic scene center is therefore not
|
|
68
|
+
automatically a safe object center: keep a standing capsule around the authored
|
|
69
|
+
player origin clear, or move the player to a deliberate spawn. Include an exact
|
|
70
|
+
spawn review view at player eye height (about 1.6 m above the origin) looking into
|
|
71
|
+
the composition; hero cameras do not substitute for this check.
|
|
72
|
+
|
|
73
|
+
Text-only scenes need at least one hero view plus diagnostic top, quarter, and player
|
|
74
|
+
spawn views.
|
|
75
|
+
The hero view is a design choice, not a match to an imaginary source image.
|
|
76
|
+
|
|
77
|
+
## Review Text-Only Output
|
|
78
|
+
|
|
79
|
+
Use deterministic hierarchy, count, support, relation, bounds, and runtime checks.
|
|
80
|
+
Agent visual judgment evaluates composition and legibility against the written
|
|
81
|
+
criteria, not similarity to an absent reference. Do not use IoU, SSIM, pHash, or
|
|
82
|
+
camera-fit metrics.
|