@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.
- package/dist/cli.js +8 -13
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +16 -2
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-format.md +6 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/api-reference.md +56 -33
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +24 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-glasses-test/SKILL.md +281 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +24 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +3 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +25 -2
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +73 -6
- package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +2 -0
- package/dist/guidance/claude/.claude/rules/ecs-api.md +1 -1
- package/dist/guidance/claude/.claude/rules/scene-json.md +3 -1
- package/dist/guidance/claude/.claude/rules/uikitml.md +5 -0
- package/dist/guidance/claude/.claude/settings.json +1 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +16 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-format.md +6 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/api-reference.md +56 -33
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +24 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-glasses-test/SKILL.md +281 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +24 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +3 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +25 -2
- package/dist/guidance/common/AGENTS.md +25 -12
- package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +2 -0
- package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +1 -1
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +3 -1
- package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +5 -0
- package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +2 -0
- package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +1 -1
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +3 -1
- package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +5 -0
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +3 -1
- package/dist/guidance/scoped-agents/public/ui/AGENTS.md +5 -0
- package/dist/guidance/scoped-agents/src/AGENTS.md +3 -1
- package/dist/template/common/README.md +19 -0
- package/dist/template/common/public/ui/label-grab.uikitml +57 -0
- package/dist/template/common/public/ui/label-select.uikitml +57 -0
- package/dist/template/common/public/ui/label-spin.uikitml +57 -0
- package/dist/template/common/public/ui/welcome.uikitml +33 -32
- package/dist/template/common/src/assets.ts +32 -23
- package/dist/template/common/src/scene-assets/decor.scene-asset.ts +781 -0
- package/dist/template/common/src/scene-assets/studio.scene-asset.ts +298 -0
- package/dist/template/common-js/README.md +19 -0
- package/dist/template/common-js/public/ui/label-grab.uikitml +57 -0
- package/dist/template/common-js/public/ui/label-select.uikitml +57 -0
- package/dist/template/common-js/public/ui/label-spin.uikitml +57 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +33 -32
- package/dist/template/common-js/src/assets.js +20 -23
- package/dist/template/common-js/src/scene-assets/decor.scene-asset.js +554 -0
- package/dist/template/common-js/src/scene-assets/studio.scene-asset.js +236 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +354 -58
- package/dist/template/scenes/immersive.iwsdk.scene.json +435 -54
- package/package.json +4 -4
- package/dist/template/common/public/gltf/webxr-banner/banner.gltf +0 -68
- package/dist/template/common/public/textures/webxr.png +0 -0
- package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +0 -68
- package/dist/template/common-js/public/textures/webxr.png +0 -0
package/dist/cli.js
CHANGED
|
@@ -18331,7 +18331,7 @@ function createProjectManifest(configuration) {
|
|
|
18331
18331
|
? {
|
|
18332
18332
|
useWorker: featureFlags.locomotionUseWorker !== false,
|
|
18333
18333
|
...(target === 'browser'
|
|
18334
|
-
? { initialPlayerPosition: [
|
|
18334
|
+
? { initialPlayerPosition: [0, 0, 1] }
|
|
18335
18335
|
: {}),
|
|
18336
18336
|
...(featureFlags.locomotionBrowserControls
|
|
18337
18337
|
? { browserControls: true }
|
|
@@ -18354,19 +18354,14 @@ function createProjectManifest(configuration) {
|
|
|
18354
18354
|
},
|
|
18355
18355
|
input: { canvasPointerEvents: true },
|
|
18356
18356
|
render: {
|
|
18357
|
+
fov: 70,
|
|
18357
18358
|
near: 0.001,
|
|
18358
18359
|
far: 200,
|
|
18360
|
+
// Camera poses are relative to the player rig. The browser player starts
|
|
18361
|
+
// 1 m back, so every target frames the starter from the same spot.
|
|
18359
18362
|
camera: target === 'browser'
|
|
18360
|
-
? {
|
|
18361
|
-
|
|
18362
|
-
lookAt: [4, 1.1, 4.2],
|
|
18363
|
-
}
|
|
18364
|
-
: target === 'ar'
|
|
18365
|
-
? { position: [0, 1, 0.5] }
|
|
18366
|
-
: {
|
|
18367
|
-
position: [-4, 1.5, -6],
|
|
18368
|
-
lookAt: [0, 1.1, -1.8],
|
|
18369
|
-
},
|
|
18363
|
+
? { position: [0, 1.6, 0], lookAt: [0, 0.95, -2.95] }
|
|
18364
|
+
: { position: [0, 1.6, 1], lookAt: [0, 0.95, -1.95] },
|
|
18370
18365
|
},
|
|
18371
18366
|
features: {
|
|
18372
18367
|
locomotion,
|
|
@@ -18374,7 +18369,7 @@ function createProjectManifest(configuration) {
|
|
|
18374
18369
|
physics: featureFlags.physicsEnabled,
|
|
18375
18370
|
sceneUnderstanding: featureFlags.sceneUnderstandingEnabled,
|
|
18376
18371
|
environmentRaycast: featureFlags.environmentRaycastEnabled,
|
|
18377
|
-
spatialUI: { kit: 'horizon' },
|
|
18372
|
+
spatialUI: { kit: 'horizon', preferredColorScheme: 'dark' },
|
|
18378
18373
|
},
|
|
18379
18374
|
},
|
|
18380
18375
|
dev: {
|
|
@@ -18386,7 +18381,7 @@ function createProjectManifest(configuration) {
|
|
|
18386
18381
|
};
|
|
18387
18382
|
}
|
|
18388
18383
|
|
|
18389
|
-
const VERSION = "1.1.0-rc.
|
|
18384
|
+
const VERSION = "1.1.0-rc.2";
|
|
18390
18385
|
const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
|
|
18391
18386
|
|
|
18392
18387
|
/**
|
|
@@ -242,12 +242,26 @@ Directional lights emit along local `-Z`. Start from the shown transform or anot
|
|
|
242
242
|
simple intentional angle and refine it from the render; do not write a look-at solver.
|
|
243
243
|
The common light payloads are `AmbientLight: {color, intensity}`,
|
|
244
244
|
`HemisphereLight: {skyColor, groundColor, intensity}` (there is no `color` field),
|
|
245
|
-
and `PointLight: {color, intensity, distance, decay, castShadow}`. A
|
|
245
|
+
and `PointLight: {color, intensity, distance, decay, castShadow}`. A floor that should
|
|
246
|
+
have no visible edge gets `"com.iwsdk.components.DomeFade": {"start": 4, "end": 10}`
|
|
247
|
+
on the floor node itself: it fades that node's meshes into the root `DomeGradient`
|
|
248
|
+
between those horizontal distances from the node origin, and does nothing without a
|
|
249
|
+
`DomeGradient`. Do not paste sky GLSL into an `onBeforeCompile`. A clean state after
|
|
246
250
|
the correction is the finish gate; do not query capabilities again merely to confirm
|
|
247
251
|
these established fields.
|
|
248
252
|
|
|
253
|
+
Ground props with node components, not blob or catcher assets. Add
|
|
254
|
+
`"com.iwsdk.components.ContactShadow": {"size": [0.9, 0.9]}` to each node that stands
|
|
255
|
+
on the floor (origin at floor contact, size a little wider than the footprint). For
|
|
256
|
+
AR, add one component-only node with `ShadowCatcher: {size, opacity}` at floor height;
|
|
257
|
+
it shows the shadows of `castShadow` content only when `environment.shadows` is true
|
|
258
|
+
and a light has `castShadow`. `ContactShadow` and `ShadowCatcher` are established
|
|
259
|
+
schema too. For a complete look to copy (the starter's tilted clay-studio sky
|
|
260
|
+
with a fading floor, a default sky, or AR passthrough grounding), use
|
|
261
|
+
[environment-recipes.md](references/environment-recipes.md).
|
|
262
|
+
|
|
249
263
|
For this common path, do not read the references or call
|
|
250
|
-
`scene_get_capabilities`: `DomeGradient`, `IBLGradient`, `AmbientLight`,
|
|
264
|
+
`scene_get_capabilities`: `DomeGradient`, `IBLGradient`, `DomeFade`, `AmbientLight`,
|
|
251
265
|
`HemisphereLight`, `DirectionalLight`, `PointLight`, asset nodes,
|
|
252
266
|
`player.transform`, and perspective/orthographic `authoring.views` are established
|
|
253
267
|
schema. Do not write a separate projection or light-aim solver. Choose the initial
|
package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md
ADDED
|
@@ -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
|
|
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.
|
|
589
|
-
root.setValue(
|
|
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:
|
|
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
|
|
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
|
|
1301
|
-
|
|
|
1302
|
-
| GLTF loading with GLTFLoader
|
|
1303
|
-
| Ray/line mesh for controller pointing
|
|
1304
|
-
| Hover/click interaction with Raycaster
|
|
1305
|
-
| Custom skybox sphere
|
|
1306
|
-
|
|
|
1307
|
-
|
|
|
1308
|
-
|
|
|
1309
|
-
|
|
|
1310
|
-
|
|
|
1311
|
-
|
|
|
1312
|
-
|
|
|
1313
|
-
|
|
|
1314
|
-
|
|
|
1315
|
-
|
|
|
1316
|
-
|
|
|
1317
|
-
|
|
|
1318
|
-
|
|
|
1319
|
-
|
|
|
1320
|
-
|
|
|
1321
|
-
|
|
|
1322
|
-
|
|
|
1323
|
-
| Manual
|
|
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
|
|
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
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
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
|