@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-ui
|
|
3
|
+
description: Build or modify manifest-backed IWSDK UIKitML with bounded preview, placement, and runtime verification. Use for spatial panels, browser HUDs, UIKitML layout, fonts, editor previews, and runtime element behavior.
|
|
4
|
+
argument-hint: '(use the current request)'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# IWSDK UI
|
|
8
|
+
|
|
9
|
+
Deliver the requested UI as one verified vertical slice. Use the current request
|
|
10
|
+
from conversation context; do not ask the user to repeat it or create a separate
|
|
11
|
+
design document.
|
|
12
|
+
|
|
13
|
+
## Choose the required surface
|
|
14
|
+
|
|
15
|
+
Before editing, classify the request:
|
|
16
|
+
|
|
17
|
+
- **UIKitML only**: document layout, styling, fonts, or reusable controls;
|
|
18
|
+
- **spatial panel**: UIKitML plus manifest registration and a scene instance;
|
|
19
|
+
- **runtime UI**: either of the above plus element lookup, events, and state;
|
|
20
|
+
- **ScreenSpace HUD**: browser-camera UI that intentionally returns to its
|
|
21
|
+
authored world transform in immersive XR.
|
|
22
|
+
|
|
23
|
+
Do not add placement, ScreenSpace, runtime state, or camera changes when the
|
|
24
|
+
request does not require them.
|
|
25
|
+
|
|
26
|
+
## Fast path
|
|
27
|
+
|
|
28
|
+
Inspect the relevant UI, asset manifest, active scene, and direct runtime caller
|
|
29
|
+
with one shell command that prints those files; do not issue a separate Read
|
|
30
|
+
tool call for every file. Then make the first coherent edit before broad
|
|
31
|
+
reference or dependency discovery. Use focused IWSDK reference queries only for
|
|
32
|
+
a concrete unsupported element, property, or runtime API question. Do not open,
|
|
33
|
+
grep, or list `node_modules` at any point in this workflow.
|
|
34
|
+
|
|
35
|
+
Strict image budget: during implementation, do not open any PNG, JPEG, or WebP
|
|
36
|
+
with the Read tool. Finish the runtime checks first. At the final visual gate,
|
|
37
|
+
create and open exactly one compact `artifacts/ui-runtime-review.jpg` contact
|
|
38
|
+
sheet as described below.
|
|
39
|
+
|
|
40
|
+
Keep the three stable identities explicit:
|
|
41
|
+
|
|
42
|
+
1. manifest asset ID;
|
|
43
|
+
2. scene node ID for a placed instance;
|
|
44
|
+
3. UIKitML element IDs used by application code.
|
|
45
|
+
|
|
46
|
+
Register each file under `public/ui/` as `AssetType.UIKitML` in the configured
|
|
47
|
+
asset manifest. UIKitML is the source of truth; do not generate an intermediate
|
|
48
|
+
JSON representation.
|
|
49
|
+
|
|
50
|
+
## Author the complete first pass
|
|
51
|
+
|
|
52
|
+
- UIKit numeric dimensions are centimeters (`100` is one meter).
|
|
53
|
+
- Use stable `id` attributes for every element code must address.
|
|
54
|
+
- Prefer supported explicit properties over CSS shorthand.
|
|
55
|
+
- Reuse the configured Horizon kit and bundled Lucide icons instead of
|
|
56
|
+
registering replacements in application code.
|
|
57
|
+
- Production builds keep only the Lucide icons named in static
|
|
58
|
+
`public/**/*.uikitml` files. UIKitML built or fetched at runtime (a string in
|
|
59
|
+
`src/`, a file outside `public/`, a remote URL) works in `npm run dev` but
|
|
60
|
+
fails after `npm run build` with `Unknown component <Settings>` and a hint.
|
|
61
|
+
List those icons by component name in `vite.config.ts`:
|
|
62
|
+
`iwsdkDev({ bundle: { icons: ['Settings'] } })` (`'all'` keeps all ~1,600,
|
|
63
|
+
about 4 MB more). Check dynamic UIKitML in a production build.
|
|
64
|
+
- In the stock Horizon kit, `<Panel>` renders an opaque surface that follows
|
|
65
|
+
the color scheme: dark at runtime when `spatialUI.preferredColorScheme` is
|
|
66
|
+
`dark` (the scaffold default), white in editor previews. Give text a dark
|
|
67
|
+
color plus a light `:dark` variant, as `public/ui/welcome.uikitml` does.
|
|
68
|
+
- Remote fonts can reflow layout. Use a local font when offline availability is
|
|
69
|
+
a product requirement.
|
|
70
|
+
- Use plain ASCII punctuation in runtime status copy. Do not use em dashes,
|
|
71
|
+
smart quotes, or other typographic punctuation unless the chosen local font
|
|
72
|
+
has already rendered that exact glyph successfully.
|
|
73
|
+
|
|
74
|
+
For a scene-authored instance, use asset content and an explicit transform. In
|
|
75
|
+
the stock starter composition, a front-facing UIKitML panel at negative Z faces
|
|
76
|
+
the default player with identity rotation. Do not add `rotationDeg: [0, 180, 0]`
|
|
77
|
+
unless the existing app establishes that convention or a measured render proves
|
|
78
|
+
it necessary.
|
|
79
|
+
|
|
80
|
+
The default XR player and an authored non-XR `hero` camera can be on opposite
|
|
81
|
+
sides of a single-sided panel. Preserve the transform required by the requested
|
|
82
|
+
player viewpoint; if an authored evidence camera sees the back face, move or aim
|
|
83
|
+
that camera instead of rotating the product UI away from the player.
|
|
84
|
+
|
|
85
|
+
When adding UI to an established composition, preserve existing primary UI and
|
|
86
|
+
objects. Start from the app's scale and spacing. In the stock scaffold, use
|
|
87
|
+
roughly `0.25`-`0.32` scale for a secondary panel and keep a same-band panel at
|
|
88
|
+
least `0.75` world meters above the existing central panel, at the same or
|
|
89
|
+
greater depth. Prefer a centered safe region over fragile frame edges.
|
|
90
|
+
|
|
91
|
+
## Connect runtime behavior
|
|
92
|
+
|
|
93
|
+
Resolve a scene-authored panel by scene node ID:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
const panel = world.requireSceneObject<UIKitMLAsset>('PanelNode');
|
|
97
|
+
const status = panel.requireElementById<UIKit.Text>('StatusText');
|
|
98
|
+
const action = panel.requireElementById('Btn_Action');
|
|
99
|
+
status.name = 'StatusText';
|
|
100
|
+
action.name = 'Btn_Action';
|
|
101
|
+
action.addEventListener('click', onAction);
|
|
102
|
+
cleanupFuncs.push(() => action.removeEventListener('click', onAction));
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Assign exact runtime names when the request requires controls to be addressable.
|
|
106
|
+
Register listener cleanup. Do not locate panels by transient ECS index, manifest
|
|
107
|
+
URL, or internal document implementation details.
|
|
108
|
+
|
|
109
|
+
For a small scene-authored state machine, use the public ECS surface directly;
|
|
110
|
+
do not inspect `node_modules` to rediscover these contracts:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
export const PanelState = createComponent('PanelState', {
|
|
114
|
+
step: { type: Types.Int8, default: 0 },
|
|
115
|
+
complete: { type: Types.Boolean, default: false },
|
|
116
|
+
});
|
|
117
|
+
export default defineComponents([PanelState]);
|
|
118
|
+
|
|
119
|
+
class PanelSystem extends createSystem({
|
|
120
|
+
panel: { required: [PanelState] },
|
|
121
|
+
activated: { required: [ActionMarker, Pressed] },
|
|
122
|
+
}) {
|
|
123
|
+
init(): void {
|
|
124
|
+
this.queries.activated.subscribe('qualify', () => this.advance());
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
private advance(): void {
|
|
128
|
+
const panel = this.queries.panel.entities.values().next().value;
|
|
129
|
+
if (panel == null) return;
|
|
130
|
+
// Read and write scalar fields with getValue/setValue, then update UIKit.
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Query result `entities` is a `Set`; use iteration or
|
|
136
|
+
`entities.values().next().value`, never array indexing. `@iwsdk/core` re-exports
|
|
137
|
+
the Three.js types needed for visual feedback, and scene-authored systems may use
|
|
138
|
+
`Pressed` qualification plus the existing app's marker component. Clone shared
|
|
139
|
+
asset materials before per-instance color or emissive changes.
|
|
140
|
+
|
|
141
|
+
Imported models can use material arrays or emissive-capable material subclasses
|
|
142
|
+
that do not satisfy a narrow `instanceof MeshStandardMaterial` check. For an
|
|
143
|
+
explicit whole-body state tint, traverse every `Mesh`, normalize its material to
|
|
144
|
+
an array, clone each material with `emissive` and `emissiveIntensity`, assign the
|
|
145
|
+
clones back, and update all of them. If an existing `emissiveMap` masks the
|
|
146
|
+
requested solid diagnostic color, clear that map on the clones and set
|
|
147
|
+
`needsUpdate`; do not alter shared source materials.
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
object3D.traverse((child) => {
|
|
151
|
+
if (!(child instanceof Mesh)) return;
|
|
152
|
+
const source = Array.isArray(child.material) ? child.material : [child.material];
|
|
153
|
+
const clones = source.map((material) => material.clone());
|
|
154
|
+
child.material = Array.isArray(child.material) ? clones : clones[0];
|
|
155
|
+
for (const material of clones) {
|
|
156
|
+
if ('emissive' in material && 'emissiveIntensity' in material) {
|
|
157
|
+
const stateMaterial = material as MeshStandardMaterial;
|
|
158
|
+
stateMaterial.emissiveMap = null;
|
|
159
|
+
stateMaterial.needsUpdate = true;
|
|
160
|
+
stateMaterials.push(stateMaterial);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
});
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
These are known public top-level exports: `createComponent`, `createSystem`,
|
|
167
|
+
`defineComponents`, `Types`, `Entity`, `Pressed`, `UIKitMLAsset`, `UIKit`,
|
|
168
|
+
`Color`, `Mesh`, `MeshStandardMaterial`, and `Object3D`. Import them directly
|
|
169
|
+
from `@iwsdk/core`. Typecheck the implementation; if an import fails, use the
|
|
170
|
+
compiler error or one focused IWSDK reference query. Do not inspect package
|
|
171
|
+
source, declarations, exports, or directories to reconfirm the export chain.
|
|
172
|
+
|
|
173
|
+
For immersive XR, default to a world-space panel or attach contextual UI to the
|
|
174
|
+
object it controls. Use a thresholded `Follower` targeting `world.player.head`
|
|
175
|
+
only when compact global UI must remain discoverable. Do not head-lock menus,
|
|
176
|
+
reading surfaces, or persistent panels; reserve direct `world.playerHeadEntity`
|
|
177
|
+
parenting for tiny, transient, non-interactive markers that require exact view
|
|
178
|
+
alignment. Do not use `ScreenSpace` expecting it to remain camera-attached in
|
|
179
|
+
XR. See https://iwsdk.dev/concepts/spatial-ui/hud.html for the placement
|
|
180
|
+
guidance.
|
|
181
|
+
|
|
182
|
+
Use `ScreenSpace` only for a real HUD requirement. Its dimensions and offsets are
|
|
183
|
+
CSS strings. Preserve the authored immersive transform and verify browser and XR
|
|
184
|
+
views independently when both modes matter.
|
|
185
|
+
|
|
186
|
+
## Verify with a bounded loop
|
|
187
|
+
|
|
188
|
+
Typecheck after the complete first slice, then start or reuse one managed
|
|
189
|
+
session. If no command-ready session exists, run `npx @iwsdk/cli dev up` once,
|
|
190
|
+
with the `--ai-mode` that AGENTS.md's session rule picks. Do not call `dev --help`, separately call `dev open`, restart a healthy
|
|
191
|
+
session, start a second browser, or build a custom UIKit renderer.
|
|
192
|
+
|
|
193
|
+
1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
|
|
194
|
+
2. Render one isolated preview after the first complete layout:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
npx @iwsdk/cli ui render-preview \
|
|
198
|
+
--input-json '{"assetId":"panel-id","width":800,"height":600}' \
|
|
199
|
+
--output-file artifacts/panel-preview.png
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Always provide `--output-file`; do not accept a temporary screenshot path
|
|
203
|
+
and add a separate copy step.
|
|
204
|
+
|
|
205
|
+
3. If spatial placement matters, render the authored hero view once; use
|
|
206
|
+
`view` only for built-in presets:
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
npx @iwsdk/cli scene render-file \
|
|
210
|
+
--input-json '{"path":"public/scenes/main.iwsdk.scene.json","viewId":"hero"}' \
|
|
211
|
+
--output-file artifacts/scene-hero.png
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Keep the full render result from this call so `visibleNodeIds`, validity,
|
|
215
|
+
framing, and the PNG are checked together. Do not pipe it through
|
|
216
|
+
`head`/`tail`/`grep` and rerun only to recover discarded metadata.
|
|
217
|
+
|
|
218
|
+
4. Find the panel entity, then inspect its live UIKitML state before and after
|
|
219
|
+
exercising each required control through real pointer or XR input:
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
npx @iwsdk/cli ecs find --input-json '{"namePattern":"^Welcome Panel$"}'
|
|
223
|
+
npx @iwsdk/cli ui inspect --input-json '{"entityIndex":12,"selector":"#Btn_Action"}'
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
Replace the example pattern with the panel's authored scene/entity name, and
|
|
227
|
+
reuse the returned entity index rather than hard-coding the example value.
|
|
228
|
+
|
|
229
|
+
5. Capture one final runtime preview from the intended viewpoint. Reuse a
|
|
230
|
+
required completion-state capture when it already provides that evidence.
|
|
231
|
+
|
|
232
|
+
For common CLI verification, use these forms directly rather than discovery:
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
npx @iwsdk/cli xr status
|
|
236
|
+
npx @iwsdk/cli xr enter --input-json '{}'
|
|
237
|
+
npx @iwsdk/cli xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1.5,"z":-2}}'
|
|
238
|
+
npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
|
|
239
|
+
npx @iwsdk/cli ecs find --input-json '{"withComponents":["ComponentName"]}'
|
|
240
|
+
npx @iwsdk/cli ecs query --input-json '{"entityIndex":12}'
|
|
241
|
+
npx @iwsdk/cli ui inspect --input-json '{"entityIndex":12,"selector":"#Btn_Action"}'
|
|
242
|
+
npx @iwsdk/cli browser logs --input-json '{"count":30}'
|
|
243
|
+
npx @iwsdk/cli browser reload --input-json '{}'
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
For a file capture, use `npx @iwsdk/cli browser screenshot --output-file <path>`;
|
|
247
|
+
`browser_screenshot` does not accept an `outputPath` input field.
|
|
248
|
+
|
|
249
|
+
When a UI change requires a regression smoke for an existing
|
|
250
|
+
`DistanceGrabbable`, do not substitute a long `xr select` click. Aim at the
|
|
251
|
+
object, hold select with
|
|
252
|
+
`npx @iwsdk/cli xr set-select-value --input-json '{"device":"controller-right","value":1}'`,
|
|
253
|
+
query the entity while held to observe `Grabbed`, then release with the same
|
|
254
|
+
command and `"value":0`. Movement is unnecessary unless the request asks for
|
|
255
|
+
it.
|
|
256
|
+
|
|
257
|
+
When the request asks for a poke (near touch) on a control, press it with the
|
|
258
|
+
emulated hand's index fingertip by its element ID. The panel entity needs
|
|
259
|
+
`PokeInteractable`. Its `hand` field (`"both"`, the default, `"left"` or
|
|
260
|
+
`"right"`) limits which hand can poke it, for example a wrist menu that only
|
|
261
|
+
the other hand should press:
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
|
|
265
|
+
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
The press clicked when `presses[0].contactMs` is below 800; at 800 or more a
|
|
269
|
+
slow headless frame held the touch too long, so run the press once more. Confirm
|
|
270
|
+
the state change with `ui inspect`. `xr list-targets` lists the element IDs that
|
|
271
|
+
can be pressed.
|
|
272
|
+
|
|
273
|
+
The commands in this section are the supported path. Do not call broad
|
|
274
|
+
`iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
|
|
275
|
+
error output and the exact forms above to correct it instead of invoking
|
|
276
|
+
`--help`.
|
|
277
|
+
|
|
278
|
+
Batch layout fixes before rerendering. By default allow one isolated preview,
|
|
279
|
+
one authored-scene render, and one final runtime capture; add one replacement
|
|
280
|
+
preview only to verify a focused correction. Do not rerender after every small
|
|
281
|
+
edit, repeatedly restart the runtime, or use screenshots to debug input state.
|
|
282
|
+
Keep the whole task under roughly 80 tool calls by batching independent reads
|
|
283
|
+
and related state queries. Check console logs once after final behavior unless a
|
|
284
|
+
new edit creates a concrete reason to check again. Do not capture extra
|
|
285
|
+
diagnostic screenshots for states already proven by named queries.
|
|
286
|
+
For the final visual comparison, create one compact JPEG contact sheet with the
|
|
287
|
+
supplied baseline above the final live-runtime capture, then load only that one
|
|
288
|
+
image into model context. Do not load the full-size PNGs separately. On Windows,
|
|
289
|
+
substitute the two paths in this known command:
|
|
290
|
+
|
|
291
|
+
```powershell
|
|
292
|
+
powershell.exe -NoProfile -Command 'Add-Type -AssemblyName System.Drawing; $a=[Drawing.Image]::FromFile((Resolve-Path "BASELINE.png")); $b=[Drawing.Image]::FromFile((Resolve-Path "FINAL.png")); $w=600; $ha=[int]($a.Height*$w/$a.Width); $hb=[int]($b.Height*$w/$b.Width); $o=[Drawing.Bitmap]::new($w,$ha+$hb); $g=[Drawing.Graphics]::FromImage($o); $g.DrawImage($a,0,0,$w,$ha); $g.DrawImage($b,0,$ha,$w,$hb); $o.Save((Join-Path (Get-Location) "artifacts/ui-runtime-review.jpg"),[Drawing.Imaging.ImageFormat]::Jpeg); $g.Dispose(); $o.Dispose(); $a.Dispose(); $b.Dispose()'
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
`artifacts/ui-runtime-review.jpg` is the only image file to open with the Read
|
|
296
|
+
tool. Do not open isolated previews, hero renders, progress captures, completion
|
|
297
|
+
captures, the baseline PNG, or the final PNG separately.
|
|
298
|
+
|
|
299
|
+
Treat that contact sheet as a bounded layout sanity check, not a request to
|
|
300
|
+
visually prove every state detail. If it shows no blocking overlap, clipping,
|
|
301
|
+
unreadable primary UI, or accidental scene replacement, stop visual inspection.
|
|
302
|
+
Do not create follow-up zooms, crops, or object close-ups. Use the named ECS
|
|
303
|
+
state queries to prove interaction feedback; the evaluator will inspect the
|
|
304
|
+
saved progress and completion artifacts.
|
|
305
|
+
|
|
306
|
+
Render isolated, hero, progress, completion, and invalid-action files when the
|
|
307
|
+
task requires them, but do not open those files in model context; use render
|
|
308
|
+
metadata, named state queries, and file existence for those checks. After a
|
|
309
|
+
context compaction, continue from the measured state instead of rediscovering
|
|
310
|
+
package exports, CLI command families, or already accepted visual framing.
|
|
311
|
+
|
|
312
|
+
The final visual check must confirm:
|
|
313
|
+
|
|
314
|
+
- the complete panel is inside the expected frame;
|
|
315
|
+
- important text and controls remain readable at a compact preview size;
|
|
316
|
+
- primary text has clear contrast against the actual rendered surface;
|
|
317
|
+
- new UI does not touch or obscure existing primary UI or objects;
|
|
318
|
+
- required states differ through a coarse visible treatment, not only fine text.
|
|
319
|
+
When the task explicitly asks for visually distinct progress/completion or
|
|
320
|
+
success/error states, change at least a quarter of the panel surface (for
|
|
321
|
+
example a substantial header block or whole-surface tint) and/or a major
|
|
322
|
+
scene object's whole-body emissive treatment. A thin accent bar, small chips,
|
|
323
|
+
icons, and copy changes alone are not sufficient evidence.
|
|
324
|
+
|
|
325
|
+
Finish with a passing typecheck and production build, no UIKit parser/resource
|
|
326
|
+
errors, and concise runtime evidence. Remove temporary preview files or camera
|
|
327
|
+
workarounds that are not deliverables.
|
|
328
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f38cb22c3f17e583db46ecffe8ac78d5d58a1b990ebd485e00f1f5623b690332 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-upgrade
|
|
3
|
+
description: Upgrade an IWSDK app to a newer IWSDK release and prove it still works. Use when the user asks to upgrade, update or bump IWSDK or any @iwsdk/* package, when iwsdk dev up reports guidance updated from an older release, or when errors appear right after an IWSDK version change.
|
|
4
|
+
argument-hint: '[target version, default latest]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Upgrade IWSDK
|
|
8
|
+
|
|
9
|
+
An upgrade has three parts: move the packages, apply what changed between the
|
|
10
|
+
two releases, and show that the app behaves as it did before. Do them in that
|
|
11
|
+
order.
|
|
12
|
+
|
|
13
|
+
## 1. Record the baseline first
|
|
14
|
+
|
|
15
|
+
Before changing any version, check `git status`, make sure the user's work is
|
|
16
|
+
saved or committed (do not commit unless the user allowed it), and record how
|
|
17
|
+
the app behaves now: run its typecheck and build scripts with the project's
|
|
18
|
+
package manager (for example `npm run typecheck` and `npm run build`).
|
|
19
|
+
|
|
20
|
+
Write down every error, then start the dev server and save the browser log and
|
|
21
|
+
a runtime screenshot. Older apps often have errors that predate the upgrade;
|
|
22
|
+
without a baseline you cannot tell them from new ones, and proving it later
|
|
23
|
+
costs a full reinstall.
|
|
24
|
+
|
|
25
|
+
## 2. Move the packages
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx @iwsdk/cli@latest upgrade --dry-run
|
|
29
|
+
npx @iwsdk/cli@latest upgrade
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Always run it with `@latest`, even if the project has an older `@iwsdk/cli`:
|
|
33
|
+
the newest CLI carries every migration guide. For a specific release, add
|
|
34
|
+
`--to <version>` (`npx @iwsdk/cli@<version> upgrade` works only for releases
|
|
35
|
+
that include the `upgrade` command). It sets every `@iwsdk/*` package to the release, installs
|
|
36
|
+
with the project's package manager, aligns the `three` alias and an existing
|
|
37
|
+
`@types/three` with `@iwsdk/core`, refreshes this guidance, and writes to `.iwsdk/migrations/`:
|
|
38
|
+
|
|
39
|
+
- one `iwsdk-migrate-*/SKILL.md` for each release boundary that needs code
|
|
40
|
+
changes;
|
|
41
|
+
- `release-notes.md` with every change between the two versions.
|
|
42
|
+
|
|
43
|
+
It also checks `iwsdk.config.json` against the new release and lists settings
|
|
44
|
+
that no longer validate. Packages it reports as "not part of the IWSDK release"
|
|
45
|
+
were left as declared; remove one only if a migration guide says it was
|
|
46
|
+
retired. In a monorepo it installs with the workspace's package manager; if a
|
|
47
|
+
workspace-level override pins `three`, it tells you to change it.
|
|
48
|
+
|
|
49
|
+
If the user asked for a plain package-manager bump instead, do that, then run
|
|
50
|
+
`npx @iwsdk/cli@latest agents sync`; `iwsdk dev up` also refreshes unedited
|
|
51
|
+
guidance.
|
|
52
|
+
|
|
53
|
+
## 3. Apply what changed
|
|
54
|
+
|
|
55
|
+
1. Follow each migration guide in `.iwsdk/migrations/`, oldest first, before
|
|
56
|
+
other work.
|
|
57
|
+
2. Read the major and minor entries in `release-notes.md` and check whether
|
|
58
|
+
the app uses what they change (renamed settings, new required versions,
|
|
59
|
+
changed defaults).
|
|
60
|
+
3. Fix each `iwsdk.config.json` issue the upgrade listed.
|
|
61
|
+
4. Re-read the `iwsdk-agent-guidance` block in `AGENTS.md`: it now describes
|
|
62
|
+
the new release. Do not hand-edit guidance files; an edited file stops
|
|
63
|
+
receiving updates.
|
|
64
|
+
|
|
65
|
+
## 4. Prove it
|
|
66
|
+
|
|
67
|
+
Run the same checks as the baseline and compare. Report new errors and fix
|
|
68
|
+
them; report baseline errors separately as existing. A clean typecheck and
|
|
69
|
+
build do not show that the app renders: confirm the runtime screenshot and an
|
|
70
|
+
error-free browser log, and enter XR when the app is an XR app.
|
|
71
|
+
|
|
72
|
+
The upgrade is done when every migration guide is applied, the comparison
|
|
73
|
+
shows no new errors, and the user knows which existing errors remain.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Asset manifest contract"
|
|
3
|
+
globs:
|
|
4
|
+
- "src/assets.ts"
|
|
5
|
+
- "src/assets.js"
|
|
6
|
+
- "src/iwsdk/assets.ts"
|
|
7
|
+
- "src/iwsdk/assets.js"
|
|
8
|
+
- "src/scene-assets/**"
|
|
9
|
+
alwaysApply: false
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Asset manifest contract
|
|
13
|
+
|
|
14
|
+
`src/assets.ts` is imported **independently by the app runtime and the editor**,
|
|
15
|
+
in separate JS realms. It must therefore be deterministic and self-contained:
|
|
16
|
+
|
|
17
|
+
- no `World`, scene, iframe, editor object or DOM access
|
|
18
|
+
- no timers, no fetching ambient state
|
|
19
|
+
- no reliance on singleton object identity across realms
|
|
20
|
+
- prototypes immutable after registration, and never parented
|
|
21
|
+
|
|
22
|
+
A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
|
|
23
|
+
or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
|
|
24
|
+
`HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
|
|
25
|
+
as scene content; audio/texture/HDR are for application systems.
|
|
26
|
+
|
|
27
|
+
Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
|
|
28
|
+
builds resolve identically. A file in `public/` is **not** available to a scene
|
|
29
|
+
until it is registered here.
|
|
30
|
+
|
|
31
|
+
## Procedural assets
|
|
32
|
+
|
|
33
|
+
Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
|
|
34
|
+
register it under a stable ID. The registry rejects an already-parented
|
|
35
|
+
prototype.
|
|
36
|
+
|
|
37
|
+
Every placement is a distinct hierarchy clone, but **geometry and materials stay
|
|
38
|
+
shared**. Never dispose them from a placed clone; world teardown owns their
|
|
39
|
+
lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
|
|
40
|
+
one instance — mutating the shared material in place changes every instance.
|
|
41
|
+
|
|
42
|
+
Bounds come from `Box3` over the instantiated asset and drive placement,
|
|
43
|
+
selection, framing and scatter collision. Put the origin where composition wants
|
|
44
|
+
it (usually floor contact, or the object's own pivot), keep transforms finite,
|
|
45
|
+
and don't let invisible helpers inflate bounds.
|
|
46
|
+
|
|
47
|
+
## Cost
|
|
48
|
+
|
|
49
|
+
Split tessellation by viewing distance rather than using one budget everywhere: a
|
|
50
|
+
close-range hero model and coarser display copies of the same form are two
|
|
51
|
+
prototypes from one factory function. Sphere/lathe segment counts dominate small
|
|
52
|
+
repeated detail more than people expect — check `renderStats.triangles` rather
|
|
53
|
+
than guessing.
|
|
54
|
+
|
|
55
|
+
Reuse material instances within a module. Prefer prefabs plus a deterministic
|
|
56
|
+
pattern for repetition; a pattern whose prefab resolves to a single component-free
|
|
57
|
+
mesh lowers to one `InstancedMesh`.
|
|
58
|
+
|
|
59
|
+
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
60
|
+
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
61
|
+
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
62
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e6b8d299d9f7590043801fae63d23de387e937bcb87bafe59b9b70f6e0622db3 name=assets-and-manifest.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "ECS API reference"
|
|
3
|
+
globs:
|
|
4
|
+
- "src/**/*.ts"
|
|
5
|
+
- "src/**/*.js"
|
|
6
|
+
alwaysApply: false
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# ECS API reference
|
|
10
|
+
|
|
11
|
+
## Field types
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
|
|
15
|
+
Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
|
|
16
|
+
Types.Object // avoid — not optimised
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Component
|
|
20
|
+
|
|
21
|
+
Declare in a system-free module, then list it in `src/components.ts` via
|
|
22
|
+
`defineComponents()` or the editor cannot author it.
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
export const MyComponent = createComponent('MyComponent', {
|
|
26
|
+
speed: { type: Types.Float32, default: 1 },
|
|
27
|
+
tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
|
|
32
|
+
`widget` — drives the editor inspector.
|
|
33
|
+
|
|
34
|
+
## System
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
export class MySystem extends createSystem(
|
|
38
|
+
{
|
|
39
|
+
items: { required: [MyComponent] },
|
|
40
|
+
active: { required: [MyComponent], excluded: [Grabbed] },
|
|
41
|
+
},
|
|
42
|
+
{ speed: { type: Types.Float32, default: 1 } }, // optional config
|
|
43
|
+
) {
|
|
44
|
+
private temp!: Vector3;
|
|
45
|
+
|
|
46
|
+
init() {
|
|
47
|
+
this.temp = new Vector3();
|
|
48
|
+
this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
|
|
49
|
+
this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
update(delta: number, time: number) {
|
|
53
|
+
for (const entity of this.queries.active.entities) { /* no allocations */ }
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
|
|
59
|
+
`lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
|
|
60
|
+
entities in a transient state — e.g. excluding `Grabbed` so a held object is left
|
|
61
|
+
alone.
|
|
62
|
+
|
|
63
|
+
Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
|
|
64
|
+
|
|
65
|
+
Read fields with `entity.getValue(Component, 'field')`. For vector fields use
|
|
66
|
+
`entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
|
|
67
|
+
no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
|
|
68
|
+
|
|
69
|
+
## Interaction components
|
|
70
|
+
|
|
71
|
+
`RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
|
|
72
|
+
and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
|
|
73
|
+
proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
|
|
74
|
+
ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
|
|
75
|
+
`GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
|
|
76
|
+
defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
|
|
77
|
+
|
|
78
|
+
`DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
|
|
79
|
+
`MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
|
|
80
|
+
`detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
|
|
81
|
+
`targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
|
|
82
|
+
no custom code.
|
|
83
|
+
|
|
84
|
+
For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
|
|
85
|
+
`getHolderHand(entity)` — never deep-import `Handle`.
|
|
86
|
+
|
|
87
|
+
## XR input
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
const pad = this.input.xr.gamepads.right;
|
|
91
|
+
pad?.getButtonDown(InputComponent.Trigger); // just pressed
|
|
92
|
+
pad?.getAxesValues(InputComponent.Thumbstick);
|
|
93
|
+
this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
|
|
97
|
+
buttons. Browser controls live at `world.input.keyboard` and
|
|
98
|
+
`world.input.browserGamepads`.
|
|
99
|
+
|
|
100
|
+
## Lifecycle
|
|
101
|
+
|
|
102
|
+
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
103
|
+
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
104
|
+
`getWorldPosition()` when logic needs the true viewer position.
|
|
105
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f09a86b27ce781f8e69b6471051167bee392ac2f503526df33ded757940268f6 name=ecs-api.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Scene JSON — things that fail silently"
|
|
3
|
+
globs:
|
|
4
|
+
- "public/scenes/**"
|
|
5
|
+
alwaysApply: false
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Scene JSON — things that fail silently
|
|
9
|
+
|
|
10
|
+
Format reference lives in
|
|
11
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
12
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
13
|
+
it for imports, prefabs, patterns, or a schema detail not covered by active
|
|
14
|
+
guidance. For ordinary flat node, component, and authored-view edits, this rule,
|
|
15
|
+
the existing scene, and the active specialist are sufficient. This file is only
|
|
16
|
+
the short list of behaviours that produce no error when you get them wrong.
|
|
17
|
+
|
|
18
|
+
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
19
|
+
closed — an unknown field fails validation.
|
|
20
|
+
|
|
21
|
+
## Imports stop at the authoring boundary
|
|
22
|
+
|
|
23
|
+
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
24
|
+
scenes remain useful for composition. The editable scene session and application
|
|
25
|
+
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
26
|
+
`npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
|
|
27
|
+
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
28
|
+
later human editor changes.
|
|
29
|
+
|
|
30
|
+
## The player materialises at the scene origin
|
|
31
|
+
|
|
32
|
+
`0,0,0` unless the document authors `player.transform`. Nothing warns you. A
|
|
33
|
+
scene can pass every authored camera view and still spawn the player inside the
|
|
34
|
+
geometry, because review cameras are not the viewpoint that ships. Keep that
|
|
35
|
+
volume clear or place the player deliberately, and author a diagnostic view at
|
|
36
|
+
player eye height to prove it.
|
|
37
|
+
|
|
38
|
+
## `visibleNodeIds` is the silent-failure detector
|
|
39
|
+
|
|
40
|
+
`renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
|
|
41
|
+
did not appear — even when the image looks plausible and `valid` is `true`. Check
|
|
42
|
+
it against what you expect rather than trusting the picture. Single-sided
|
|
43
|
+
surfaces facing away from the camera are the usual cause, and they report nothing.
|
|
44
|
+
`ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
|
|
45
|
+
content is one of them is never listed; check the object it grounds instead.
|
|
46
|
+
|
|
47
|
+
## Component keys come in two forms
|
|
48
|
+
|
|
49
|
+
Root-level components use the namespaced form
|
|
50
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
51
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
52
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
53
|
+
node already uses instead of normalising.
|
|
54
|
+
|
|
55
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
56
|
+
|
|
57
|
+
## Browser hero views and XR spawn framing are distinct
|
|
58
|
+
|
|
59
|
+
Outside immersive XR, the hero authoring view supersedes `world.render.camera`
|
|
60
|
+
from `iwsdk.config.json` once the level initialises. While XR is presenting,
|
|
61
|
+
the tracked player rig owns the camera and the hero view is intentionally not
|
|
62
|
+
applied. Use the hero view for editor/browser framing, and validate important
|
|
63
|
+
content from the authored `player.transform` spawn (or the default standing
|
|
64
|
+
view near `[0, 1.6, 0]`) before accepting XR framing.
|
|
65
|
+
|
|
66
|
+
## Validation
|
|
67
|
+
|
|
68
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
69
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
70
|
+
back. Render each changed module before the root.
|
|
71
|
+
|
|
72
|
+
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
73
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f32c3e7d4024f56a3ff5ae32b42c236377551cbd3b2b231e84ada68362b68266 name=scene-json.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|