@iwsdk/create 1.1.0-rc.0 → 1.1.0-rc.2

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 (60) hide show
  1. package/dist/cli.js +8 -13
  2. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +16 -2
  3. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-format.md +6 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/api-reference.md +56 -33
  6. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +24 -5
  7. package/dist/guidance/agents/.agents/skills/iwsdk-glasses-test/SKILL.md +281 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +24 -1
  9. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +3 -1
  10. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +25 -2
  11. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +73 -6
  12. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +2 -0
  13. package/dist/guidance/claude/.claude/rules/ecs-api.md +1 -1
  14. package/dist/guidance/claude/.claude/rules/scene-json.md +3 -1
  15. package/dist/guidance/claude/.claude/rules/uikitml.md +5 -0
  16. package/dist/guidance/claude/.claude/settings.json +1 -0
  17. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +16 -2
  18. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  19. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-format.md +6 -0
  20. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/api-reference.md +56 -33
  21. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +24 -5
  22. package/dist/guidance/claude/.claude/skills/iwsdk-glasses-test/SKILL.md +281 -0
  23. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +24 -1
  24. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +3 -1
  25. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +25 -2
  26. package/dist/guidance/common/AGENTS.md +25 -12
  27. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +2 -0
  28. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +1 -1
  29. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +3 -1
  30. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +5 -0
  31. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +2 -0
  32. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +1 -1
  33. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +3 -1
  34. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +5 -0
  35. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +3 -1
  36. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +5 -0
  37. package/dist/guidance/scoped-agents/src/AGENTS.md +3 -1
  38. package/dist/template/common/README.md +19 -0
  39. package/dist/template/common/public/ui/label-grab.uikitml +57 -0
  40. package/dist/template/common/public/ui/label-select.uikitml +57 -0
  41. package/dist/template/common/public/ui/label-spin.uikitml +57 -0
  42. package/dist/template/common/public/ui/welcome.uikitml +33 -32
  43. package/dist/template/common/src/assets.ts +32 -23
  44. package/dist/template/common/src/scene-assets/decor.scene-asset.ts +781 -0
  45. package/dist/template/common/src/scene-assets/studio.scene-asset.ts +298 -0
  46. package/dist/template/common-js/README.md +19 -0
  47. package/dist/template/common-js/public/ui/label-grab.uikitml +57 -0
  48. package/dist/template/common-js/public/ui/label-select.uikitml +57 -0
  49. package/dist/template/common-js/public/ui/label-spin.uikitml +57 -0
  50. package/dist/template/common-js/public/ui/welcome.uikitml +33 -32
  51. package/dist/template/common-js/src/assets.js +20 -23
  52. package/dist/template/common-js/src/scene-assets/decor.scene-asset.js +554 -0
  53. package/dist/template/common-js/src/scene-assets/studio.scene-asset.js +236 -0
  54. package/dist/template/scenes/ar.iwsdk.scene.json +354 -58
  55. package/dist/template/scenes/immersive.iwsdk.scene.json +435 -54
  56. package/package.json +4 -4
  57. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +0 -68
  58. package/dist/template/common/public/textures/webxr.png +0 -0
  59. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +0 -68
  60. package/dist/template/common-js/public/textures/webxr.png +0 -0
@@ -0,0 +1,234 @@
1
+ # Environment Recipes
2
+
3
+ Copy-paste environment setups built only from built-in components. Merge the
4
+ root `components`, the `environment` block and the node `components` into the
5
+ scene; keep your own asset nodes. Every field, with its default and limits, is
6
+ in the `componentSchemas` of `scene_get_capabilities` with `full: true` (CLI:
7
+ `npx @iwsdk/cli scene capabilities --input-json '{"full":true}' --raw`), and the
8
+ editor shows each one with a label and limits.
9
+
10
+ ## Clay Studio
11
+
12
+ The VR and Desktop 3D starter's look: a pale lavender-to-bone sky tilted toward
13
+ the front left, a floor that fades into it with no visible edge, soft image-based
14
+ light and a warm key light with soft shadows.
15
+
16
+ ```json
17
+ {
18
+ "components": {
19
+ "com.iwsdk.components.DomeGradient": {
20
+ "sky": [0.843, 0.796, 0.882, 1],
21
+ "equator": [0.808, 0.855, 0.91, 1],
22
+ "ground": [0.902, 0.855, 0.82, 1],
23
+ "elevationDeg": 24,
24
+ "azimuthDeg": -31,
25
+ "dither": true
26
+ },
27
+ "com.iwsdk.components.IBLGradient": {
28
+ "sky": [0.72, 0.7, 0.8, 1],
29
+ "equator": [0.78, 0.78, 0.84, 1],
30
+ "ground": [0.5, 0.52, 0.58, 1],
31
+ "intensity": 0.2025
32
+ }
33
+ },
34
+ "environment": {
35
+ "toneMapping": "aces",
36
+ "exposure": 1.2,
37
+ "shadows": true,
38
+ "shadowMapType": "pcf"
39
+ },
40
+ "nodes": [
41
+ {
42
+ "id": "studio-floor",
43
+ "content": {
44
+ "type": "asset",
45
+ "asset": "studio-floor",
46
+ "receiveShadow": true
47
+ },
48
+ "components": {
49
+ "LocomotionEnvironment": {},
50
+ "DomeFade": { "start": 4, "end": 10 }
51
+ }
52
+ },
53
+ {
54
+ "id": "key-light",
55
+ "transform": {
56
+ "position": [-2.3541, 11.2763, 1.762],
57
+ "rotationDeg": [-73.3982, -11.3134, 0]
58
+ },
59
+ "components": {
60
+ "DirectionalLight": {
61
+ "color": [1, 0.945, 0.87, 1],
62
+ "intensity": 2.3,
63
+ "castShadow": true,
64
+ "shadowMapSize": "2048",
65
+ "shadowCameraSize": 8,
66
+ "shadowCameraNear": 2,
67
+ "shadowCameraFar": 24,
68
+ "shadowRadius": 7,
69
+ "shadowBias": -0.0004,
70
+ "shadowNormalBias": 0.02
71
+ }
72
+ }
73
+ },
74
+ {
75
+ "id": "fill-light",
76
+ "components": {
77
+ "HemisphereLight": {
78
+ "skyColor": [0.78, 0.83, 0.96, 1],
79
+ "groundColor": [0.592, 0.608, 0.651, 1],
80
+ "intensity": 1.15
81
+ }
82
+ }
83
+ }
84
+ ]
85
+ }
86
+ ```
87
+
88
+ - `elevationDeg` and `azimuthDeg` tilt the sky pole; `dither` removes banding in
89
+ the pale gradient, and the faded floor dithers with it.
90
+ - `DomeFade` goes on the floor node itself. Its meshes blend into the live sky
91
+ between 4 m and 10 m from the node origin; it does nothing without the
92
+ `DomeGradient`.
93
+ - Put a `ContactShadow` on each object that stands on the floor, or on a
94
+ component-only child node at its foot, sized a little wider than the
95
+ footprint.
96
+ - `IBLGradient` applies `intensity` once: 0.2025 here is 0.45 in a 1.0.x scene.
97
+
98
+ The starter grounds its pieces with these component-only child nodes, each
99
+ with just `transform.position` and `components.ContactShadow`: `size`, and
100
+ `height` where the blob sits lower than the 2 mm default. A round blob's
101
+ `height` is 2 mm times its width, so small blobs sit close to the surface and an
102
+ object's foot meets its blob without a gap.
103
+
104
+ | Node | Parent | `position` | `ContactShadow.size` | `ContactShadow.height` |
105
+ | ----------------------- | --------------- | ----------------------- | -------------------- | ---------------------- |
106
+ | `grab-plinth-contact` | `grab-plinth` | `[0, 0.002, 0]` | `[0.8, 0.8]` | `0.0016` |
107
+ | `select-plinth-contact` | `select-plinth` | `[0, 0.002, 0]` | `[0.8, 0.8]` | `0.0016` |
108
+ | `spin-plinth-contact` | `spin-plinth` | `[0, 0.002, 0]` | `[0.8, 0.8]` | `0.0016` |
109
+ | `graphite-cube-contact` | `grab-plinth` | `[-0.25, 0.921, -0.03]` | `[0.26, 0.26]` | `0.00052` |
110
+ | `graphite-gem-contact` | `grab-plinth` | `[0, 0.921, -0.03]` | `[0.24, 0.24]` | `0.00048` |
111
+ | `graphite-knot-contact` | `grab-plinth` | `[0.25, 0.921, -0.03]` | `[0.26, 0.26]` | `0.00052` |
112
+ | `robot-contact` | `select-plinth` | `[0, 0.921, -0.02]` | `[0.37, 0.37]` | `0.00074` |
113
+ | `graphite-ring-contact` | `spin-plinth` | `[0, 0.921, -0.02]` | `[0.4, 0.4]` | `0.0008` |
114
+ | `gallery-set-contact` | `gallery-set` | `[0, 0.002, 0]` | `[1.9, 1]` | default |
115
+ | `gallery-vase-contact` | `gallery-set` | `[-0.95, 0.002, -0.15]` | `[0.55, 0.55]` | `0.0011` |
116
+ | `sideboard-set-contact` | `sideboard-set` | `[0, 0.002, 0]` | `[2.3, 0.9]` | default |
117
+ | `floor-lamp-contact` | `sideboard-set` | `[1.1, 0.002, -0.08]` | `[0.45, 0.45]` | `0.0009` |
118
+
119
+ ## Default Sky
120
+
121
+ A neutral daylight sky and matching image-based light, as the components'
122
+ defaults. Add a `DomeFade` to the floor node so the floor has no visible edge.
123
+
124
+ ```json
125
+ {
126
+ "components": {
127
+ "com.iwsdk.components.DomeGradient": {
128
+ "sky": [0.2423, 0.6172, 0.8308, 1],
129
+ "equator": [0.6584, 0.7084, 0.7913, 1],
130
+ "ground": [0.807, 0.7758, 0.7454, 1],
131
+ "intensity": 1
132
+ },
133
+ "com.iwsdk.components.IBLGradient": {
134
+ "sky": [0.6902, 0.749, 0.7843, 1],
135
+ "equator": [0.6584, 0.7084, 0.7913, 1],
136
+ "ground": [0.807, 0.7758, 0.7454, 1],
137
+ "intensity": 1
138
+ }
139
+ }
140
+ }
141
+ ```
142
+
143
+ ## AR Passthrough
144
+
145
+ No sky, so passthrough stays visible; image-based light for the content, and a
146
+ shadow-only floor plus blobs to ground it. This is the AR starter's setup.
147
+
148
+ ```json
149
+ {
150
+ "components": {
151
+ "com.iwsdk.components.IBLGradient": {
152
+ "sky": [0.96, 0.94, 0.9, 1],
153
+ "equator": [0.8, 0.76, 0.7, 1],
154
+ "ground": [0.46, 0.42, 0.38, 1],
155
+ "intensity": 0.25
156
+ }
157
+ },
158
+ "environment": {
159
+ "toneMapping": "aces",
160
+ "exposure": 1,
161
+ "shadows": true,
162
+ "shadowMapType": "pcf"
163
+ },
164
+ "nodes": [
165
+ {
166
+ "id": "shadow-catcher",
167
+ "framingRole": "support",
168
+ "transform": { "position": [0, 0.001, -1.35] },
169
+ "components": { "ShadowCatcher": { "size": [6, 6], "opacity": 0.25 } }
170
+ },
171
+ {
172
+ "id": "plinth",
173
+ "content": { "type": "asset", "asset": "plinth", "castShadow": true },
174
+ "transform": { "position": [0, 0, -1.5] },
175
+ "components": {
176
+ "ContactShadow": {
177
+ "size": [0.8, 0.8],
178
+ "opacity": 0.4,
179
+ "color": [0, 0, 0, 1]
180
+ }
181
+ }
182
+ },
183
+ {
184
+ "id": "key-light",
185
+ "transform": {
186
+ "position": [-2.3541, 11.2763, 1.762],
187
+ "rotationDeg": [-73.3982, -11.3134, 0]
188
+ },
189
+ "components": {
190
+ "DirectionalLight": {
191
+ "color": [1, 0.945, 0.87, 1],
192
+ "intensity": 2,
193
+ "castShadow": true,
194
+ "shadowMapSize": "1024",
195
+ "shadowCameraSize": 6,
196
+ "shadowCameraNear": 2,
197
+ "shadowCameraFar": 24,
198
+ "shadowRadius": 5,
199
+ "shadowBias": -0.0004,
200
+ "shadowNormalBias": 0.02
201
+ }
202
+ }
203
+ },
204
+ {
205
+ "id": "fill-light",
206
+ "components": {
207
+ "HemisphereLight": {
208
+ "skyColor": [0.96, 0.94, 0.9, 1],
209
+ "groundColor": [0.55, 0.52, 0.48, 1],
210
+ "intensity": 1
211
+ }
212
+ }
213
+ }
214
+ ]
215
+ }
216
+ ```
217
+
218
+ The AR starter grounds its stations with the first eight contact nodes of the
219
+ Clay Studio table (the plinths and the pieces on them, with the same parents,
220
+ positions, sizes and heights), each tinted like the plinth above.
221
+
222
+ - Leave out `DomeGradient` and `DomeTexture` for AR. The runtime hides them in
223
+ an AR session anyway, so they only change the editor and desktop preview,
224
+ which then show a sky the headset never does.
225
+ - `ShadowCatcher` shows shadows only with `environment.shadows`, a light with
226
+ `castShadow` and `castShadow` content above it. A `ContactShadow` needs none
227
+ of that.
228
+ - Tint `ContactShadow` black for AR, at a lower opacity than the 0.72 default:
229
+ `"opacity": 0.4, "color": [0, 0, 0, 1]`. The default blue-grey lightens
230
+ anything darker than itself, so over a dark room, or the near-black page the
231
+ editor and the managed browser show behind the desktop preview, the blob
232
+ glows. Black only darkens, so it reads as a shadow on light floors, dark
233
+ floors and passthrough alike; at 0.4 it is about as dark on a light floor as
234
+ the default blob.
@@ -50,8 +50,14 @@ runtime projection strips `authoring` and hashes canonical JSON for runtime iden
50
50
 
51
51
  - `components` apply to the actual IWSDK level-root entity. `DomeGradient` and
52
52
  `IBLGradient` are normal removable components, not editor-only environment fields.
53
+ - `DomeFade` is a node component, not a root one: put
54
+ `"com.iwsdk.components.DomeFade": { "start": 4, "end": 10 }` on a floor or
55
+ terrain node to fade that node's own meshes into the root `DomeGradient` sky.
53
56
  - `LevelRoot`, `LevelTag`, and `Transform` are runtime-owned and must not appear in
54
57
  `components`.
58
+ - `ContactShadow` (a soft blob under a node) and `ShadowCatcher` (an invisible AR
59
+ floor that shows received shadows) are node components: put them on the grounded
60
+ node or a floor node, not in root `components`.
55
61
  - `resources` contains only reusable scene prefabs.
56
62
  - Use namespaced keys in opaque `metadata`. Do not hide structural fields there.
57
63
  - Structural objects are closed. Unknown fields fail validation.
@@ -540,12 +540,15 @@ import {
540
540
  IBLTexture,
541
541
  } from '@iwsdk/core';
542
542
 
543
- // Gradient sky dome (RGBA colors - 4 components)
543
+ // Gradient sky dome (RGBA display colors - 4 components)
544
544
  entity.addComponent(DomeGradient, {
545
545
  sky: [0.2423, 0.6172, 0.8308, 1.0], // RGBA
546
546
  equator: [0.6584, 0.7084, 0.7913, 1.0], // RGBA
547
547
  ground: [0.807, 0.7758, 0.7454, 1.0], // RGBA
548
- intensity: 1.0,
548
+ intensity: 1.0, // 0 = black
549
+ elevationDeg: 90, // sky pole height: 90 = straight up, lower tilts it
550
+ azimuthDeg: 0, // sky pole heading, node Y-rotation convention (90 = -X)
551
+ dither: false, // true adds ±0.5/255 noise against banding
549
552
  });
550
553
 
551
554
  // HDR texture sky
@@ -558,7 +561,7 @@ entity.addComponent(IBLGradient, {
558
561
  sky: [0.6902, 0.749, 0.7843, 1.0], // RGBA
559
562
  equator: [0.6584, 0.7084, 0.7913, 1.0], // RGBA
560
563
  ground: [0.807, 0.7758, 0.7454, 1.0], // RGBA
561
- intensity: 1.0,
564
+ intensity: 1.0, // applied once since 1.1.0 (square a 1.0.x value)
562
565
  });
563
566
 
564
567
  // IBL from texture
@@ -582,11 +585,14 @@ entity.addComponent(IBLTexture, {
582
585
  root.addComponent(DomeGradient, { sky: [0.24, 0.62, 0.83, 1.0], ... });
583
586
  ```
584
587
 
585
- 2. **After changing environment properties, MUST set `_needsUpdate: true`** — changes are silently ignored without it:
588
+ 2. **After changing `DomeTexture` or `IBLTexture`, MUST set `_needsUpdate: true`** — their changes are silently ignored without it. `DomeGradient` and `IBLGradient` apply edits on the next frame; `_needsUpdate` is optional for them:
586
589
 
587
590
  ```typescript
588
- root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]);
589
- root.setValue(DomeGradient, '_needsUpdate', true); // Required! (scalar — setValue OK)
591
+ root.setValue(DomeTexture, 'intensity', 0.6);
592
+ root.setValue(DomeTexture, '_needsUpdate', true); // Required for textures!
593
+
594
+ root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]); // applies next frame
595
+ root.setValue(DomeGradient, 'elevationDeg', 30); // applies next frame
590
596
  ```
591
597
 
592
598
  3. **Background vs IBL are separate**: `DomeTexture`/`DomeGradient` controls the visible sky. `IBLTexture`/`IBLGradient` controls scene lighting (reflections, ambient). You can mix them:
@@ -598,6 +604,18 @@ entity.addComponent(IBLTexture, {
598
604
 
599
605
  4. **In AR sessions**, backgrounds (dome) are automatically hidden but IBL remains active for realistic lighting on virtual objects.
600
606
 
607
+ 5. **`DomeFade` is a node component** that fades that node's own meshes into the root `DomeGradient` with horizontal distance from the node origin, so a floor has no visible edge. It does nothing without a `DomeGradient`, and its meshes hide with the dome in AR:
608
+
609
+ ```json
610
+ {
611
+ "id": "floor",
612
+ "content": { "type": "asset", "asset": "floor" },
613
+ "components": {
614
+ "com.iwsdk.components.DomeFade": { "start": 4, "end": 10 }
615
+ }
616
+ }
617
+ ```
618
+
601
619
  ### 14. Asset Loading
602
620
 
603
621
  ```typescript
@@ -864,7 +882,7 @@ const world = await World.create(container, {
864
882
  // enableJumping: true,
865
883
  // },
866
884
  grabbing: true, // Only if objects are grabbable
867
- // OR object form: grabbing: { useHandPinchForGrab: true },
885
+ // OR object form: grabbing: { useHandPinchForGrab: false }, // pinch grabs by default
868
886
  physics: true, // Only if using dynamic physics
869
887
  sceneUnderstanding: true, // OR: { showWireFrame: true }
870
888
  environmentRaycast: true, // AR hit-test against real-world surfaces
@@ -886,7 +904,9 @@ world.exitXR();
886
904
 
887
905
  Background and image-based lighting are authored explicitly with dome and IBL
888
906
  components on the level root. IWSDK does not synthesize missing environment
889
- components; starter scenes include gradient defaults.
907
+ components; the VR and Desktop 3D starter scene authors `DomeGradient` and
908
+ `IBLGradient`, and the AR starter authors only `IBLGradient` so no sky covers
909
+ passthrough.
890
910
 
891
911
  ### Post-Creation Initialization Sequence
892
912
 
@@ -1297,30 +1317,33 @@ Before writing custom code, check if IWSDK already provides the functionality. R
1297
1317
 
1298
1318
  ### Reinvention Risk Table
1299
1319
 
1300
- | What you might build from scratch | What IWSDK already provides |
1301
- | -------------------------------------- | ---------------------------------------------------------------------------- |
1302
- | GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
1303
- | Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
1304
- | Hover/click interaction with Raycaster | `RayInteractable` + `Hovered` + `Pressed` components |
1305
- | Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
1306
- | PBR environment lighting | `IBLGradient` or `IBLTexture` component |
1307
- | Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
1308
- | Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
1309
- | Controller 3D models | Auto-loaded from WebXR Input Profiles |
1310
- | Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
1311
- | Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
1312
- | Hit-test against real world | `EnvironmentRaycastTarget` component |
1313
- | Spatial audio | `AudioSource` component with pooling |
1314
- | Camera feed texture | `CameraSource` component |
1315
- | Depth occlusion shader | `DepthOccludable` component |
1316
- | HUD / screen-space UI | `ScreenSpace` component with CSS units |
1317
- | Follow-head billboard | `Follower` component |
1318
- | Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
1319
- | Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
1320
- | Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
1321
- | Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
1322
- | Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
1323
- | Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
1320
+ | What you might build from scratch | What IWSDK already provides |
1321
+ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
1322
+ | GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
1323
+ | Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
1324
+ | Hover/click interaction with Raycaster | `RayInteractable` + `Hovered` + `Pressed` components |
1325
+ | Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
1326
+ | Floor fading into the sky (`onBeforeCompile` with copied sky GLSL) | `DomeFade` on the floor node |
1327
+ | PBR environment lighting | `IBLGradient` or `IBLTexture` component |
1328
+ | Canvas or radial blob shadow card | `ContactShadow` node component |
1329
+ | ShadowMaterial plane for AR | `ShadowCatcher` node component |
1330
+ | Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
1331
+ | Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
1332
+ | Controller 3D models | Auto-loaded from WebXR Input Profiles |
1333
+ | Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
1334
+ | Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
1335
+ | Hit-test against real world | `EnvironmentRaycastTarget` component |
1336
+ | Spatial audio | `AudioSource` component with pooling |
1337
+ | Camera feed texture | `CameraSource` component |
1338
+ | Depth occlusion shader | `DepthOccludable` component |
1339
+ | HUD / screen-space UI | `ScreenSpace` component with CSS units |
1340
+ | Follow-head billboard | `Follower` component |
1341
+ | Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
1342
+ | Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
1343
+ | Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
1344
+ | Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
1345
+ | Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
1346
+ | Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
1324
1347
 
1325
1348
  ### Asset Loading (AssetManager)
1326
1349
 
@@ -1473,7 +1496,7 @@ These visuals are automatically created and managed by IWSDK systems:
1473
1496
  12. **DON'T** use `scene.add()` — use `createTransformEntity()` for proper ECS integration
1474
1497
  13. **DON'T** replace IWSDK pointer interaction with `new Raycaster()` — use `RayInteractable`; raw raycasters are valid for custom geometric queries, but the caller owns ECS entity mapping, target filtering, and pointer lifecycle
1475
1498
  14. **DON'T** add environment components (`DomeGradient`/`IBLTexture`/etc.) to arbitrary entities — must go on the level root (`world.activeLevel.value`)
1476
- 15. **DON'T** forget `_needsUpdate` after changing environment properties — changes are silently ignored without `entity.setValue(DomeGradient, '_needsUpdate', true)`
1499
+ 15. **DON'T** forget `_needsUpdate` after changing `DomeTexture` or `IBLTexture` properties — their changes are silently ignored without `entity.setValue(DomeTexture, '_needsUpdate', true)`. `DomeGradient` and `IBLGradient` apply edits without it
1477
1500
  16. **DON'T** use `entity.destroy()` for objects with GPU resources — use `entity.dispose()` which also cleans up geometry/materials/textures
1478
1501
  17. **DON'T** pass numbers to `ScreenSpace` — all position/size values are CSS strings like `'400px'` or `'50vw'`
1479
1502
 
@@ -136,6 +136,23 @@ object, run
136
136
  `npx @iwsdk/cli xr set-gamepad-state --input-json '{"device":"controller-right","buttons":[{"index":0,"value":1}]}'`,
137
137
  observe `Grabbed` or movement, then repeat with `value:0` to release.
138
138
 
139
+ For hand input (poke, pinch-grab, gestures), switch with
140
+ `xr set-input-mode` `{"mode":"hand"}` and drive the hand by target name with one
141
+ `xr run-sequence` per interaction (`--timeout 45000`). `xr list-targets` names
142
+ the interactable entities and their UIKitML element IDs. Press a button with
143
+ `press`, never a pinch; a near grab needs `grabbing.useHandPinchForGrab` (on by
144
+ default):
145
+
146
+ ```bash
147
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
148
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Requested Name","approach":{"distance":0.06},"pinch":{"value":1,"at":"arrival"}},{"position":{"x":0,"y":1,"z":-0.5},"depart":{"distance":0.08}}]}' --timeout 45000
149
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"pinch":0,"duration":0.15}]}'
150
+ ```
151
+
152
+ Query `Grabbed` between the grab and the release. A press result whose
153
+ `presses[0].contactMs` is 800 or more did not click. Slow headless frames can
154
+ stretch a press that far, so run that press once more before changing code.
155
+
139
156
  If a scene/source/UI edit happens after the managed runtime started and live
140
157
  state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
141
158
  loop on browser reload. Run one
@@ -187,11 +204,13 @@ largest empty region above or beside the preserved composition.
187
204
  Use an opaque or strongly contrasting panel surface. Primary copy must be dark
188
205
  on light or light on dark; white or pale text on translucent white, sky, or
189
206
  another bright background fails even when the glyphs are technically present.
190
- For the scaffold's Horizon `<Panel>`, assume the kit's opaque white surface
191
- wins over a custom root `background-color`; use dark primary and secondary text
192
- on the first attempt. Use light text only after a compact runtime preview proves
193
- the actual rendered panel surface is dark. Do not spend a restart discovering
194
- white-on-white text that the stock kit behavior already predicts.
207
+ For the scaffold's Horizon `<Panel>`, assume the kit's opaque surface wins
208
+ over a custom root `background-color`. That surface follows the color scheme:
209
+ the runtime renders it dark because `iwsdk.config.json` prefers `dark`, while
210
+ editor previews render it white. Give every text class a dark color plus a light
211
+ `:dark` variant, as `public/ui/welcome.uikitml` does, so copy reads on both.
212
+ Do not spend a restart discovering dark-on-dark or white-on-white text that the
213
+ stock kit behavior already predicts.
195
214
 
196
215
  Reuse the established app panel scale and spacing when available. In the stock
197
216
  starter-scale composition, a new front-facing UIKitML panel should begin at