@iwsdk/create 0.4.2 → 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.
Files changed (107) hide show
  1. package/README.md +103 -41
  2. package/dist/cli.js +1003 -3418
  3. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  9. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  10. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
  11. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
  12. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
  13. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
  14. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
  15. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
  16. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
  19. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  24. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  25. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
  27. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
  28. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
  29. package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
  30. package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
  31. package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
  32. package/dist/guidance/claude/.claude/settings.json +19 -0
  33. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
  34. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  35. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
  36. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
  43. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
  44. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
  45. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
  46. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
  47. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
  48. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
  49. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  50. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  53. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
  57. package/dist/guidance/claude/CLAUDE.md +142 -0
  58. package/dist/guidance/codex/.codex/config.toml +2 -0
  59. package/dist/guidance/common/AGENTS.md +151 -0
  60. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
  61. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
  62. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
  63. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
  64. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
  65. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
  66. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
  67. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
  68. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
  69. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
  70. package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
  71. package/dist/template/common/README.md +13 -0
  72. package/dist/template/common/gitignore.template +45 -0
  73. package/dist/template/common/index.html +16 -0
  74. package/dist/template/common/nvmrc.template +1 -0
  75. package/dist/template/common/public/audio/chime.mp3 +0 -0
  76. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
  77. package/dist/template/common/public/textures/webxr.png +0 -0
  78. package/dist/template/common/public/ui/welcome.uikitml +98 -0
  79. package/dist/template/common/src/assets.ts +54 -0
  80. package/dist/template/common/src/components.ts +11 -0
  81. package/dist/template/common/src/index.ts +19 -0
  82. package/dist/template/common/src/panel.ts +38 -0
  83. package/dist/template/common/src/robot-component.ts +10 -0
  84. package/dist/template/common/src/robot.ts +38 -0
  85. package/dist/template/common/src/vite-env.d.ts +2 -0
  86. package/dist/template/common/tsconfig.json +15 -0
  87. package/dist/template/common/vite.config.ts +27 -0
  88. package/dist/template/common-js/README.md +13 -0
  89. package/dist/template/common-js/gitignore.template +45 -0
  90. package/dist/template/common-js/index.html +16 -0
  91. package/dist/template/common-js/nvmrc.template +1 -0
  92. package/dist/template/common-js/public/audio/chime.mp3 +0 -0
  93. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
  94. package/dist/template/common-js/public/textures/webxr.png +0 -0
  95. package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
  96. package/dist/template/common-js/src/assets.js +45 -0
  97. package/dist/template/common-js/src/components.js +9 -0
  98. package/dist/template/common-js/src/index.js +14 -0
  99. package/dist/template/common-js/src/panel.js +31 -0
  100. package/dist/template/common-js/src/robot-component.js +8 -0
  101. package/dist/template/common-js/src/robot.js +37 -0
  102. package/dist/template/common-js/vite.config.js +25 -0
  103. package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
  104. package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
  105. package/package.json +23 -17
  106. package/scripts/verify-release-ready.mjs +76 -0
  107. package/LICENSE +0 -21
@@ -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.
@@ -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.