@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
package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
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.
|
package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# Composition Patterns
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
1. Representation Ladder
|
|
6
|
+
2. Object Reconstruction
|
|
7
|
+
3. Environment Composition
|
|
8
|
+
4. Repetition
|
|
9
|
+
5. Camera And Lighting
|
|
10
|
+
6. Cost Control
|
|
11
|
+
|
|
12
|
+
## Representation Ladder
|
|
13
|
+
|
|
14
|
+
Match silhouette and proportions before surface detail. All visible scene content is
|
|
15
|
+
an `asset` reference, but the registered asset may be a glTF or a procedural
|
|
16
|
+
`Object3D`. Choose the lowest-complexity asset implementation that preserves every
|
|
17
|
+
required feature:
|
|
18
|
+
|
|
19
|
+
| Form | Asset implementation |
|
|
20
|
+
| --------------------------------------- | -------------------------- |
|
|
21
|
+
| Rectilinear mass, panel, slab | Box geometry |
|
|
22
|
+
| Soft-edged block, cushion, casing | Rounded-box geometry |
|
|
23
|
+
| Rounded mass, joint, crown | Scaled sphere geometry |
|
|
24
|
+
| Pole or simple column | Cylinder or cone geometry |
|
|
25
|
+
| Rotational vessel, turned seat, shade | Lathe geometry |
|
|
26
|
+
| Wheel, ring, circular handle | Torus geometry |
|
|
27
|
+
| Limb, padded rail, soft elongated body | Capsule geometry |
|
|
28
|
+
| Flat profile with meaningful outline | Shape/extrude geometry |
|
|
29
|
+
| Branch, pipe, cable, bicycle frame | Tube along explicit points |
|
|
30
|
+
| Reusable part hierarchy | Procedural asset or prefab |
|
|
31
|
+
| Repeated compatible detail | Deterministic pattern |
|
|
32
|
+
| Identity-critical asset already present | Registered glTF asset |
|
|
33
|
+
|
|
34
|
+
Create geometry and materials in an asset module and register its parentless root in
|
|
35
|
+
the manifest. Keep composition and repetition in scene JSON. Do not force an organic
|
|
36
|
+
continuous form into a single box, and do not import an opaque glTF solely to avoid a
|
|
37
|
+
small deterministic procedural asset.
|
|
38
|
+
|
|
39
|
+
## Object Reconstruction
|
|
40
|
+
|
|
41
|
+
Build one semantic hierarchy in this order:
|
|
42
|
+
|
|
43
|
+
1. root at a stable support/pivot point;
|
|
44
|
+
2. primary masses and bounding proportions;
|
|
45
|
+
3. structural connectors and negative spaces;
|
|
46
|
+
4. silhouette-defining secondary forms;
|
|
47
|
+
5. repeated identity details;
|
|
48
|
+
6. shared material families and small accents in asset code.
|
|
49
|
+
|
|
50
|
+
Keep parts separate when their boundary, material, or transform matters. Merge visual
|
|
51
|
+
noise into a larger form when it cannot affect a required view.
|
|
52
|
+
|
|
53
|
+
Every layout-critical semantic group must contain actual coarse renderables for its
|
|
54
|
+
primary masses. Keep those assets, instances, or patterns visible in the `layout`
|
|
55
|
+
lens. An empty group is a useful transform root and feature binding, but it
|
|
56
|
+
has no bounds, pixels, support contact, or silhouette and therefore cannot be the
|
|
57
|
+
group's layout proxy.
|
|
58
|
+
|
|
59
|
+
### Stool Or Small Furniture
|
|
60
|
+
|
|
61
|
+
- seat: lathe, cylinder, extruded outline, or shallow rounded box;
|
|
62
|
+
- legs: tapered cylinders or capsules, parented under the root;
|
|
63
|
+
- braces: tubes/cylinders between measured endpoints;
|
|
64
|
+
- upholstery: scaled capsule/sphere or layered rounded masses;
|
|
65
|
+
- seams/buttons: sparse repeated small geometry only when identity-critical.
|
|
66
|
+
|
|
67
|
+
Place the root on the floor. Check seat height and leg spread in front and side views.
|
|
68
|
+
Preserve negative space between legs.
|
|
69
|
+
|
|
70
|
+
### Armchair And Reading Furniture
|
|
71
|
+
|
|
72
|
+
Compose seat cushion, back cushion, arms, frame, and legs as independent parts. Use
|
|
73
|
+
rounded boxes, scaled capsules/spheres for soft cushions, and boxes/tubes for the
|
|
74
|
+
frame. Overlap soft parts slightly to avoid visible gaps. Match the outer silhouette
|
|
75
|
+
and seat/back angle before seams or buttons.
|
|
76
|
+
|
|
77
|
+
### Mechanical Prop Or Generator
|
|
78
|
+
|
|
79
|
+
Start with chassis and major cylindrical/box volumes. Add one hierarchy per visible
|
|
80
|
+
system: frame, tank, vents, control panel, handles, cables, fasteners. Use exact
|
|
81
|
+
patterns for manufactured vents/bolts. Use tubes for cables and pipes. Keep painted
|
|
82
|
+
metal dielectric; reserve high metalness for exposed metal.
|
|
83
|
+
|
|
84
|
+
### Bicycle Or Thin Frame
|
|
85
|
+
|
|
86
|
+
Use two wheel cylinders/tori in a procedural asset, or use a registered glTF when
|
|
87
|
+
silhouette fidelity requires it. Build a procedural frame from tubes between stable
|
|
88
|
+
joint points. Use separate
|
|
89
|
+
fork, handlebar, crank, saddle, and pedal groups. Verify wheel coplanarity, contact
|
|
90
|
+
with ground, and frame negative spaces from a side view, then check real volume from a
|
|
91
|
+
quarter view.
|
|
92
|
+
|
|
93
|
+
### Animal Or Organic Character Blockout
|
|
94
|
+
|
|
95
|
+
Use a root at ground contact, capsules/ellipsoids for torso and limbs, spheres for
|
|
96
|
+
joints/head, cones or extrudes for ears/tail accents, and tubes for curved tails.
|
|
97
|
+
Preserve pose, body proportions, leg contacts, head direction, and silhouette before
|
|
98
|
+
facial detail. A procedural animal assembled from simple geometry is a stylized
|
|
99
|
+
blockout; state the ceiling when fur, anatomy, or likeness is required.
|
|
100
|
+
|
|
101
|
+
### Tree, Stump, Or Plant
|
|
102
|
+
|
|
103
|
+
Use a tapered cylinder/extrude for the trunk, tubes for branches/roots/stems, scaled
|
|
104
|
+
spheres/cones or extruded leaves for foliage. Model major silhouette branches
|
|
105
|
+
explicitly. Use deterministic seeded patterns for compatible smaller branches/leaves,
|
|
106
|
+
with bounded count and variation. Avoid a uniform sphere when the reference depends on
|
|
107
|
+
an irregular crown or gnarled outline.
|
|
108
|
+
|
|
109
|
+
### Tent Or Fabric Shelter
|
|
110
|
+
|
|
111
|
+
Use an extruded triangular/arched profile or thin planes for fabric panels, tubes for
|
|
112
|
+
poles, and cylinders/tubes for guy lines. Keep planes double-sided only where needed.
|
|
113
|
+
Offset layered flaps to avoid z-fighting. Verify support points and interior opening
|
|
114
|
+
from front and quarter views.
|
|
115
|
+
|
|
116
|
+
### Lantern Or Transparent Vessel
|
|
117
|
+
|
|
118
|
+
Build the metal frame first, then a low-opacity double-sided glazing proxy when
|
|
119
|
+
supported. Use cylinders/extrudes for body and cap, tubes for cage/handle, and a small
|
|
120
|
+
emissive interior source plus actual light when required. Scalar opacity does not
|
|
121
|
+
provide refraction; record that limitation.
|
|
122
|
+
|
|
123
|
+
### Arch Or Masonry Opening
|
|
124
|
+
|
|
125
|
+
Prefer one extrude with an explicit opening hole for a clean arch silhouette. Otherwise
|
|
126
|
+
compose two pillars and a ring of wedge-like repeated blocks, keeping the opening
|
|
127
|
+
unobstructed. Model the void, not a painted arch on a solid wall. Use irregular but
|
|
128
|
+
bounded variation only after the main curve and support contact are correct.
|
|
129
|
+
|
|
130
|
+
## Environment Composition
|
|
131
|
+
|
|
132
|
+
Use a shallow semantic hierarchy:
|
|
133
|
+
|
|
134
|
+
```text
|
|
135
|
+
scene
|
|
136
|
+
ground-and-paths
|
|
137
|
+
architecture
|
|
138
|
+
focal-cluster
|
|
139
|
+
furniture-and-props
|
|
140
|
+
vegetation
|
|
141
|
+
lights
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Architecture
|
|
145
|
+
|
|
146
|
+
Create one group per building. Start with body, roof, foundation, primary openings,
|
|
147
|
+
and large facade bands. Add window/balcony prefabs only after one module is correct.
|
|
148
|
+
Use a consistent facade offset of roughly `0.01..0.04` meters to prevent z-fighting.
|
|
149
|
+
Infer floor height from doors or people when visible; otherwise record a conventional
|
|
150
|
+
scale assumption.
|
|
151
|
+
|
|
152
|
+
### Roads, Paths, And Ground
|
|
153
|
+
|
|
154
|
+
Use thin boxes for surfaces needing reliable support bounds. Use polygon/extrude for
|
|
155
|
+
irregular patios or paths. Put lane/edge markings slightly above the surface. Avoid
|
|
156
|
+
overlapping coplanar planes. Validate layout from top and vertical contact from front.
|
|
157
|
+
|
|
158
|
+
For a studio floor or seamless background support, use one surface large enough to
|
|
159
|
+
cover the scene footprint and every required, alternate, and diagnostic camera
|
|
160
|
+
frustum. Match its base value to the environment background when continuity is
|
|
161
|
+
intended, while preserving enough lighting response to show contact shadows. Inspect
|
|
162
|
+
every exact saved view for a horizon, diagonal plane edge, corner, or value seam; a
|
|
163
|
+
hero-only edge check is insufficient. Mark oversized infrastructure nodes
|
|
164
|
+
`framingRole: "support"` and fit the camera to `framingBounds`; use raw `worldBounds`
|
|
165
|
+
and exact-view captures to verify support coverage, so the oversized support neither
|
|
166
|
+
clips nor inflates subject framing.
|
|
167
|
+
|
|
168
|
+
### Furniture Clusters
|
|
169
|
+
|
|
170
|
+
Preserve reachability and conversational orientation: chairs face the focal center,
|
|
171
|
+
tables sit at usable height, lamps stand beside rather than inside furniture, and
|
|
172
|
+
objects share the same support surface. Bind the cluster and each identity-critical
|
|
173
|
+
object to feature criteria.
|
|
174
|
+
|
|
175
|
+
### Vegetation Borders
|
|
176
|
+
|
|
177
|
+
Model prominent plants explicitly. Use prefabs and deterministic scatter/along-path
|
|
178
|
+
patterns for background beds. Separate trunk/stem and crown/leaf material families.
|
|
179
|
+
Vary scale/yaw within a narrow range and keep the distribution reproducible.
|
|
180
|
+
|
|
181
|
+
### Vehicles And People
|
|
182
|
+
|
|
183
|
+
Use a group origin at ground contact. For vehicles, compose body/cabin/wheels and
|
|
184
|
+
orient the group along the path. For distant people, register simplified procedural
|
|
185
|
+
assets with torso/head/limb geometry and preserve height/stance. Avoid identical
|
|
186
|
+
prominent poses.
|
|
187
|
+
|
|
188
|
+
## Repetition
|
|
189
|
+
|
|
190
|
+
Use exact grid/linear/radial/along-path patterns for manufactured structures and
|
|
191
|
+
seeded scatter for organic distribution. Name the algorithm/version and seed.
|
|
192
|
+
|
|
193
|
+
Build and validate one prefab before instancing. Keep local IDs semantic. Use explicit
|
|
194
|
+
instances when individual components or unique transforms are required. Material
|
|
195
|
+
variants are separate manifest assets, not scene overrides.
|
|
196
|
+
Use a pattern only when all instances can share compatible render content.
|
|
197
|
+
|
|
198
|
+
Do not add hundreds of explicit nodes when a bounded pattern expresses the same
|
|
199
|
+
authoring intent. Do not use a pattern to hide meaningful per-instance differences.
|
|
200
|
+
|
|
201
|
+
## Camera And Lighting
|
|
202
|
+
|
|
203
|
+
Treat the player spawn as a required application camera, not an incidental origin.
|
|
204
|
+
Unless `player.transform` says otherwise, the player's feet are at `[0, 0, 0]` and
|
|
205
|
+
their first-person view is approximately `[0, 1.6, 0]`. Keep that standing volume
|
|
206
|
+
clear and inspect a saved spawn view before accepting the composition.
|
|
207
|
+
|
|
208
|
+
Tune a reference camera in this order:
|
|
209
|
+
|
|
210
|
+
1. target at the composition/object center;
|
|
211
|
+
2. projection type;
|
|
212
|
+
3. azimuth for visible side proportions;
|
|
213
|
+
4. elevation for visible top area;
|
|
214
|
+
5. distance/FOV or orthographic height for framing;
|
|
215
|
+
6. geometry/placement for remaining overlap differences.
|
|
216
|
+
|
|
217
|
+
Never distort support or obvious volume solely to match one view. Validate a
|
|
218
|
+
non-planar form from at least one alternate angle.
|
|
219
|
+
|
|
220
|
+
Use lights to reveal authored form rather than paint lighting into base color. For a
|
|
221
|
+
studio or product scene, prefer Room IBL plus one or two rectangular area lights and
|
|
222
|
+
a low-intensity shadow-casting directional light when contact shadows matter. For a
|
|
223
|
+
broad environment, ambient/hemisphere fill plus a directional key remains useful.
|
|
224
|
+
Author lights as ECS components. Directional, spot, and rectangular area lights emit
|
|
225
|
+
along their node's local `-Z` axis, so aim them with the node rotation. Keep review
|
|
226
|
+
geometry lighting neutral and separate from final-look lighting.
|
|
227
|
+
|
|
228
|
+
## Cost Control
|
|
229
|
+
|
|
230
|
+
- Use low segment counts for small/distant curved parts and increase only when a
|
|
231
|
+
required silhouette visibly benefits.
|
|
232
|
+
- Instance compatible repetition. Record the expanded count and draw-call lowering.
|
|
233
|
+
- Disable shadow casting on tiny repeated trim, leaves, fasteners, and markings unless
|
|
234
|
+
their shadows carry a required feature.
|
|
235
|
+
- Begin with `castShadow: false` on assets, then opt in focal grounded
|
|
236
|
+
masses deliberately. Treat more than one shadow caster per four visible meshes as
|
|
237
|
+
a review trigger, not as physical-device performance proof; retain a feature-based
|
|
238
|
+
justification for any exception.
|
|
239
|
+
- Avoid hidden back-side detail that cannot affect any required or application view.
|
|
240
|
+
- Reuse material instances inside asset modules instead of gratuitous one-off values.
|
|
241
|
+
- Keep transparent surfaces sparse and inspect sorting from required views.
|
|
242
|
+
- Record raw calls, triangles, programs, textures, shadow casters, and frame samples;
|
|
243
|
+
do not substitute node count for measured renderer cost.
|