@iwsdk/create 0.4.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -41
- package/dist/cli.js +1003 -3418
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
- package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
- package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
- package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
- package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
- package/dist/guidance/claude/.claude/settings.json +19 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/CLAUDE.md +142 -0
- package/dist/guidance/codex/.codex/config.toml +2 -0
- package/dist/guidance/common/AGENTS.md +151 -0
- package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
- package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
- package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
- package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
- package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
- package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
- package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
- package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/gitignore.template +45 -0
- package/dist/template/common/index.html +16 -0
- package/dist/template/common/nvmrc.template +1 -0
- package/dist/template/common/public/audio/chime.mp3 +0 -0
- package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common/public/textures/webxr.png +0 -0
- package/dist/template/common/public/ui/welcome.uikitml +98 -0
- package/dist/template/common/src/assets.ts +54 -0
- package/dist/template/common/src/components.ts +11 -0
- package/dist/template/common/src/index.ts +19 -0
- package/dist/template/common/src/panel.ts +38 -0
- package/dist/template/common/src/robot-component.ts +10 -0
- package/dist/template/common/src/robot.ts +38 -0
- package/dist/template/common/src/vite-env.d.ts +2 -0
- package/dist/template/common/tsconfig.json +15 -0
- package/dist/template/common/vite.config.ts +27 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/gitignore.template +45 -0
- package/dist/template/common-js/index.html +16 -0
- package/dist/template/common-js/nvmrc.template +1 -0
- package/dist/template/common-js/public/audio/chime.mp3 +0 -0
- package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common-js/public/textures/webxr.png +0 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
- package/dist/template/common-js/src/assets.js +45 -0
- package/dist/template/common-js/src/components.js +9 -0
- package/dist/template/common-js/src/index.js +14 -0
- package/dist/template/common-js/src/panel.js +31 -0
- package/dist/template/common-js/src/robot-component.js +8 -0
- package/dist/template/common-js/src/robot.js +37 -0
- package/dist/template/common-js/vite.config.js +25 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
- package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
- package/package.json +23 -17
- package/scripts/verify-release-ready.mjs +76 -0
- package/LICENSE +0 -21
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-ui
|
|
3
|
+
description: Create, place, preview, debug, and connect manifest-backed IWSDK UIKitML assets. Use for spatial panels, browser HUDs, UIKitML layout, fonts, editor previews, or runtime element behavior.
|
|
4
|
+
argument-hint: '[panel-name or description of changes]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# UIKitML Asset Workflow
|
|
8
|
+
|
|
9
|
+
Treat UIKitML as a first-class renderable asset. Use the managed editor's isolated
|
|
10
|
+
renderer for layout, the scene editor for placement, and the application runtime for
|
|
11
|
+
behavior. Do not change the scene, camera, or component model merely to inspect a
|
|
12
|
+
panel.
|
|
13
|
+
|
|
14
|
+
User request is in `$ARGUMENTS`.
|
|
15
|
+
|
|
16
|
+
## 1. Find the three stable identities
|
|
17
|
+
|
|
18
|
+
Every scene-authored panel has three different identities:
|
|
19
|
+
|
|
20
|
+
1. the manifest asset ID, which names the reusable UIKitML definition;
|
|
21
|
+
2. the scene node ID, which names one placed instance;
|
|
22
|
+
3. element `id` attributes, which name fields and controls inside the document.
|
|
23
|
+
|
|
24
|
+
Find or add the manifest entry in `src/assets.ts` and keep the source under
|
|
25
|
+
`public/ui/`:
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { AssetType, defineAssets } from '@iwsdk/core';
|
|
29
|
+
|
|
30
|
+
const publicAssetUrl = (path: string) =>
|
|
31
|
+
`${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
|
|
32
|
+
|
|
33
|
+
export default defineAssets({
|
|
34
|
+
'welcome-panel': {
|
|
35
|
+
name: 'Welcome panel',
|
|
36
|
+
type: AssetType.UIKitML,
|
|
37
|
+
url: publicAssetUrl('ui/welcome.uikitml'),
|
|
38
|
+
},
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
A file under `public/ui/` is not placeable until it is registered. The `.uikitml`
|
|
43
|
+
file is the runtime source of truth; never generate an intermediate JSON file.
|
|
44
|
+
|
|
45
|
+
## 2. Reuse the managed editor
|
|
46
|
+
|
|
47
|
+
Run commands from the application directory. Reuse a command-ready session instead
|
|
48
|
+
of starting a second server or browser:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npx iwsdk dev status
|
|
52
|
+
npx iwsdk dev up --timeout 60000
|
|
53
|
+
npx iwsdk ui assets --raw
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`dev up` owns the managed headed browser. Do not launch a second Playwright browser,
|
|
57
|
+
enable Vite's independent opener, or implement a custom UIKit renderer.
|
|
58
|
+
|
|
59
|
+
## 3. Render the panel in isolation
|
|
60
|
+
|
|
61
|
+
Use the editor-backed isolated renderer before debugging scene placement:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npx iwsdk ui render-preview \
|
|
65
|
+
--input-json '{"assetId":"welcome-panel","width":800,"height":600}' \
|
|
66
|
+
--output-file artifacts/welcome-panel.png
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
This renders the real manifest entry through the real UIKitML parser, fonts, layout,
|
|
70
|
+
and WebGL path on a neutral background. It waits for UIKit render and resource
|
|
71
|
+
signals; do not add fixed frame delays. Re-run the command after every layout change.
|
|
72
|
+
Same-URL sources are reloaded without restarting the server.
|
|
73
|
+
|
|
74
|
+
## 4. Place and inspect it in the scene editor
|
|
75
|
+
|
|
76
|
+
For a human-authored placement, open the scene and add the UIKitML asset from the
|
|
77
|
+
asset drawer. For file authoring, use the same asset-only node contract:
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"id": "welcome-panel-instance",
|
|
82
|
+
"name": "Welcome panel",
|
|
83
|
+
"content": { "type": "asset", "asset": "welcome-panel" },
|
|
84
|
+
"transform": {
|
|
85
|
+
"position": [0, 1.4, -1.5],
|
|
86
|
+
"rotationDeg": [0, 180, 0],
|
|
87
|
+
"scale": 0.5
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npx iwsdk scene render-file \
|
|
94
|
+
--input-json '{"path":"public/scenes/main.iwsdk.scene.json","view":"quarter"}' \
|
|
95
|
+
--output-file artifacts/main-editor.png
|
|
96
|
+
npx iwsdk scene open \
|
|
97
|
+
--input-json '{"path":"public/scenes/main.iwsdk.scene.json"}' --raw
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
UIKitML surfaces are single-sided. If the isolated preview works but the placed panel
|
|
101
|
+
is invisible, inspect its rotation first. Size a world-space panel with its ordinary
|
|
102
|
+
entity transform scale. There is no `maxWidth`/`maxHeight` fitting layer and no
|
|
103
|
+
editor-visible legacy `PanelUI` component to configure.
|
|
104
|
+
|
|
105
|
+
Use `scene screenshot` for editor/scene evidence. `browser screenshot` is intentionally
|
|
106
|
+
runtime-only and switches the managed workspace to runtime before capturing.
|
|
107
|
+
|
|
108
|
+
## 5. Edit UIKitML
|
|
109
|
+
|
|
110
|
+
UIKitML is HTML/CSS-shaped, but it is not a browser engine. Before assuming browser
|
|
111
|
+
behavior, use `npx iwsdk reference search` or the connected IWSDK reference tools to
|
|
112
|
+
confirm supported elements and properties.
|
|
113
|
+
|
|
114
|
+
Key rules:
|
|
115
|
+
|
|
116
|
+
- numeric UIKit sizes are centimeters (`100` = 100 cm = 1 m);
|
|
117
|
+
- use stable `id` attributes for elements application code must manipulate;
|
|
118
|
+
- prefer explicit supported declarations over CSS shorthand;
|
|
119
|
+
- parser errors include source locations;
|
|
120
|
+
- relative and remote font URLs are supported, but font completion can change layout;
|
|
121
|
+
- the managed preview settles from UIKit render/font/texture signals, so inspect logs
|
|
122
|
+
instead of compensating with arbitrary waits.
|
|
123
|
+
|
|
124
|
+
### Reuse built-in kits, icons, and remote fonts
|
|
125
|
+
|
|
126
|
+
IWSDK bundles the UIKitML Horizon component kit and Lucide icon set. Select the
|
|
127
|
+
Horizon kit explicitly in `iwsdk.config.json` so the choice is visible to both the
|
|
128
|
+
runtime and editor:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"world": {
|
|
133
|
+
"features": {
|
|
134
|
+
"spatialUI": { "kit": "horizon" }
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Horizon tags such as `<Panel>`, `<Button>`, `<ButtonIcon>`, and `<ButtonLabel>`
|
|
141
|
+
can then be combined directly with Lucide tags such as `<RectangleGoggles>` or
|
|
142
|
+
`<LogIn>`. Do not install or register either component set in application code.
|
|
143
|
+
|
|
144
|
+
UIKitML also accepts remote TTF declarations. The starter's
|
|
145
|
+
`public/ui/welcome.uikitml` demonstrates multiple DM Sans weights loaded from
|
|
146
|
+
`fonts.gstatic.com` with `@font-face`; apply the declared family to a root class so
|
|
147
|
+
all descendants inherit it. Keep a local font under `public/` when offline or
|
|
148
|
+
cross-origin availability is a product requirement.
|
|
149
|
+
|
|
150
|
+
After each edit:
|
|
151
|
+
|
|
152
|
+
1. rerender with `ui render-preview` and inspect the image;
|
|
153
|
+
2. rerender the scene when placement or scale matters;
|
|
154
|
+
3. inspect `browser logs` for parser, font, texture, or runtime failures.
|
|
155
|
+
|
|
156
|
+
## 6. Connect runtime behavior
|
|
157
|
+
|
|
158
|
+
For a code-owned instance, keep the `UIKitMLAsset` returned by the asset manager:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
import { UIKitMLAsset } from '@iwsdk/core';
|
|
162
|
+
|
|
163
|
+
const panel = await world.assets.instantiate<UIKitMLAsset>('welcome-panel');
|
|
164
|
+
const entity = world.createTransformEntity(panel);
|
|
165
|
+
const button = panel.requireElementById('xr-button');
|
|
166
|
+
button.addEventListener('click', () => world.launchXR());
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
For a scene-authored instance, resolve it by stable scene node ID after the level has
|
|
170
|
+
loaded:
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
const panel = world.requireSceneObject<UIKitMLAsset>('welcome-panel-instance');
|
|
174
|
+
const button = panel.requireElementById('xr-button');
|
|
175
|
+
button.setProperties({ display: 'none' });
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Do not locate a panel by transient ECS index, manifest URL, or a scan for an internal
|
|
179
|
+
`PanelDocument`. Use the scene node ID and element IDs.
|
|
180
|
+
|
|
181
|
+
## ScreenSpace is product behavior
|
|
182
|
+
|
|
183
|
+
Add `ScreenSpace` only when the experience genuinely needs a browser-camera HUD:
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
entity.addComponent(ScreenSpace, {
|
|
187
|
+
width: '420px',
|
|
188
|
+
height: '240px',
|
|
189
|
+
top: '20px',
|
|
190
|
+
right: '20px',
|
|
191
|
+
zOffset: 0.2,
|
|
192
|
+
});
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Position and size values are CSS strings. In immersive mode the document returns to
|
|
196
|
+
its authored world transform. Do not add `ScreenSpace`, a backdrop, or a temporary
|
|
197
|
+
camera pose merely to make a panel easier to inspect—the editor already provides the
|
|
198
|
+
correct isolated and in-scene render paths.
|
|
199
|
+
|
|
200
|
+
## Completion checklist
|
|
201
|
+
|
|
202
|
+
- Manifest ID resolves and `ui assets` lists it.
|
|
203
|
+
- Isolated preview is nonblank, correctly laid out, and uses the intended fonts.
|
|
204
|
+
- Scene preview has correct facing, transform scale, and lighting-independent color.
|
|
205
|
+
- Runtime behavior resolves the placed node and required element IDs.
|
|
206
|
+
- Browser logs contain no UIKitML parser, resource, or font errors.
|
|
207
|
+
- No generated UI JSON, temporary ScreenSpace component, backdrop, or camera hack
|
|
208
|
+
remains.
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# IWSDK project
|
|
2
|
+
|
|
3
|
+
A Vite + TypeScript or JavaScript app, but several things do **not** work the way
|
|
4
|
+
a normal Vite project works. Read this section before assuming anything.
|
|
5
|
+
|
|
6
|
+
Deeper material is path-scoped in `.claude/rules/` and loads automatically when
|
|
7
|
+
you touch the matching files. `AGENTS.md` is the vendor-neutral copy for other
|
|
8
|
+
agents; this file is the one Claude Code reads.
|
|
9
|
+
|
|
10
|
+
## What is not standard Vite
|
|
11
|
+
|
|
12
|
+
**`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
|
|
13
|
+
the active scene, the asset module, the component module, and all XR/world
|
|
14
|
+
features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
|
|
15
|
+
restarts Vite in place; the managed window remains open and its command bridges
|
|
16
|
+
reconnect automatically. Wait for `npx iwsdk dev status` to report
|
|
17
|
+
`browserCommandReady: true` before issuing browser-backed commands.
|
|
18
|
+
|
|
19
|
+
**`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
|
|
20
|
+
`src/index.js` imports it and passes it whole to `World.create()`. Do not
|
|
21
|
+
hand-build that options object.
|
|
22
|
+
|
|
23
|
+
**The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
|
|
24
|
+
`vite`. It launches a managed browser that hosts the MCP command bridge.
|
|
25
|
+
`--no-open` intentionally starts only the server: status reports
|
|
26
|
+
`browser.status: "not_launched"`, and browser-backed commands fail immediately
|
|
27
|
+
with `browser_not_launched` plus restart guidance. One managed window hosts two
|
|
28
|
+
roles, editor and runtime.
|
|
29
|
+
|
|
30
|
+
**`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
|
|
31
|
+
realms** — once by the app runtime, once by the editor. It must be deterministic
|
|
32
|
+
and side-effect free: no `World`, no DOM, no timers, no reliance on shared object
|
|
33
|
+
identity.
|
|
34
|
+
|
|
35
|
+
**Static geometry lives in TypeScript, composition lives in JSON.** Scene JSON
|
|
36
|
+
never declares URLs, geometry or materials — only manifest IDs.
|
|
37
|
+
|
|
38
|
+
**Components must be declared in a system-free module** and exported from
|
|
39
|
+
`src/components.ts`/`src/components.js` via `defineComponents()`. The editor
|
|
40
|
+
imports that same manifest to build its inspector, so a component that is not in
|
|
41
|
+
it cannot be authored in scenes.
|
|
42
|
+
|
|
43
|
+
**Import Three.js from `@iwsdk/core`, never from `three`.** `@iwsdk/core`
|
|
44
|
+
re-exports all of Three; importing `three` directly creates a duplicate instance
|
|
45
|
+
and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
|
|
46
|
+
|
|
47
|
+
## Traps that produce silent failures
|
|
48
|
+
|
|
49
|
+
| Trap | Symptom | Fix |
|
|
50
|
+
| ------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
|
|
52
|
+
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
|
|
53
|
+
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx iwsdk scene flatten` once, then edit the flat output (see `.claude/rules/scene-json.md`) |
|
|
54
|
+
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
|
|
55
|
+
| `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
|
|
56
|
+
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
|
|
57
|
+
| Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
|
|
58
|
+
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
|
|
59
|
+
| `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx iwsdk reference warmup`; fresh installed scaffolds do this during creation |
|
|
60
|
+
|
|
61
|
+
## Verify before you claim it works
|
|
62
|
+
|
|
63
|
+
**Always `npx tsc --noEmit` before testing.** Type errors stop systems
|
|
64
|
+
initialising without necessarily logging anything in the browser.
|
|
65
|
+
|
|
66
|
+
Then check the right status for the task — these are not interchangeable:
|
|
67
|
+
|
|
68
|
+
- scene/editor work → `scene_get_state`
|
|
69
|
+
- XR device or session actions → `xr_get_session_status`
|
|
70
|
+
- server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
|
|
71
|
+
|
|
72
|
+
When something is missing but the console is clean: call
|
|
73
|
+
`browser_get_console_logs` with only `count` (a `level` filter hides errors), then
|
|
74
|
+
`ecs_find_entities` to confirm the entity exists and carries the components you
|
|
75
|
+
expect.
|
|
76
|
+
|
|
77
|
+
The non-obvious part is which observation proves what: the **editor** render does
|
|
78
|
+
not run application systems, so anything driven by a system must be verified with
|
|
79
|
+
`browser_screenshot` (runtime), not `scene_screenshot` (editor).
|
|
80
|
+
|
|
81
|
+
## MCP and CLI are one surface, not two
|
|
82
|
+
|
|
83
|
+
Nearly every capability exists both ways — `scene_render_file` and
|
|
84
|
+
`npx iwsdk scene render-file`, `ecs_find_entities` and `npx iwsdk ecs find`.
|
|
85
|
+
Discover CLI actions with the bare domain or domain help (`npx iwsdk scene` or
|
|
86
|
+
`npx iwsdk scene --help`); both list that domain's actions.
|
|
87
|
+
|
|
88
|
+
**The CLI is not a fallback for a dead bridge.** Both routes drive the same
|
|
89
|
+
managed browser, so when `dev status` reports `browserConnected: false`,
|
|
90
|
+
every scene/ecs/xr/browser/ui command fails either way. Only `dev status`,
|
|
91
|
+
`dev logs` and `reference status` work without a browser.
|
|
92
|
+
|
|
93
|
+
Choose by the shape of the call, not by availability:
|
|
94
|
+
|
|
95
|
+
- **MCP** for one-off calls, and whenever you want the image returned inline.
|
|
96
|
+
- **CLI** when you need to loop or script — rendering six views, or sampling a
|
|
97
|
+
value twice to measure a rate — or when the response is big enough to be worth
|
|
98
|
+
filtering before it reaches context. A render of a scene containing an
|
|
99
|
+
instanced pattern returns an id for every expanded instance.
|
|
100
|
+
|
|
101
|
+
CLI `--output-file` returns a **different payload shape** from the plain call:
|
|
102
|
+
the result nests under `data.result` instead of `data`, and `renderStats` and the
|
|
103
|
+
hashes are dropped. If you need a hash or triangle count, omit `--output-file`
|
|
104
|
+
and filter the JSON instead.
|
|
105
|
+
|
|
106
|
+
## Skills
|
|
107
|
+
|
|
108
|
+
Scene composition, UI authoring, physics, depth occlusion, grab and ray
|
|
109
|
+
interaction testing, ECS frame-stepping, and end-to-end planning each have a
|
|
110
|
+
skill under `.claude/skills/`. Their descriptions handle routing, so they are not
|
|
111
|
+
restated here.
|
|
112
|
+
|
|
113
|
+
The failure worth guarding against is improvising a domain that already has a
|
|
114
|
+
skill because the naive approach looks tractable. Before hand-authoring scene
|
|
115
|
+
JSON, a UIKitML panel, or a physics body, invoke the skill.
|
|
116
|
+
|
|
117
|
+
## Layout
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
iwsdk.config.json project authority: scene, assets, components, world, dev
|
|
121
|
+
src/index.ts|js World.create() + explicit system registration
|
|
122
|
+
src/assets.ts|js defineAssets() — shared runtime/editor catalog
|
|
123
|
+
src/components.ts|js defineComponents() — shared runtime/editor catalog
|
|
124
|
+
src/scene-assets/ *.scene-asset.ts|js — parentless Object3D prototypes
|
|
125
|
+
public/scenes/ *.iwsdk.scene.json — composition only
|
|
126
|
+
public/ui/ *.uikitml — runtime-loaded panels
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
No barrel `index.ts` files. Keep component declarations free of system, DOM and
|
|
130
|
+
renderer imports; systems import the declarations, never the reverse.
|
|
131
|
+
|
|
132
|
+
## Conventions
|
|
133
|
+
|
|
134
|
+
- Systems use queries, never manually tracked entity arrays.
|
|
135
|
+
- Never allocate in `update()`. Allocate in `init()` as class properties.
|
|
136
|
+
- Prefer `queries.x.subscribe('qualify', ...)` over polling state each frame.
|
|
137
|
+
- Register every subscription teardown in `this.cleanupFuncs`.
|
|
138
|
+
- Use `signal.peek()` in `update()`; `.value` adds per-frame subscription overhead.
|
|
139
|
+
- Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
|
|
140
|
+
- Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
|
|
141
|
+
- Use the `RayInteractable` component, never a manual `Raycaster`.
|
|
142
|
+
- VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# IWSDK project
|
|
2
|
+
|
|
3
|
+
A Vite + TypeScript or JavaScript app, but several things do **not** work the way
|
|
4
|
+
a normal Vite project works. Read this section before assuming anything.
|
|
5
|
+
|
|
6
|
+
Deeper material is installed in each selected harness's native path-scoped rule
|
|
7
|
+
format. Harnesses that use `AGENTS.md` also receive equivalent nested files near
|
|
8
|
+
the code they govern. Read the applicable scoped instructions before working in
|
|
9
|
+
that area.
|
|
10
|
+
|
|
11
|
+
## What is not standard Vite
|
|
12
|
+
|
|
13
|
+
**`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
|
|
14
|
+
the active scene, the asset module, the component module, and all XR/world
|
|
15
|
+
features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
|
|
16
|
+
restarts Vite in place; the managed window remains open and its command bridges
|
|
17
|
+
reconnect automatically. Wait for `npx iwsdk dev status` to report
|
|
18
|
+
`browserCommandReady: true` before issuing browser-backed commands.
|
|
19
|
+
|
|
20
|
+
**`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
|
|
21
|
+
`src/index.js` imports it and passes it whole to `World.create()`. Do not
|
|
22
|
+
hand-build that options object.
|
|
23
|
+
|
|
24
|
+
**The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
|
|
25
|
+
`vite`. It launches a managed browser that hosts the MCP command bridge.
|
|
26
|
+
`--no-open` intentionally starts only the server: status reports
|
|
27
|
+
`browser.status: "not_launched"`, and browser-backed commands fail immediately
|
|
28
|
+
with `browser_not_launched` plus restart guidance. One managed window hosts two
|
|
29
|
+
roles, editor and runtime.
|
|
30
|
+
|
|
31
|
+
**`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
|
|
32
|
+
realms** — once by the app runtime, once by the editor. It must be deterministic
|
|
33
|
+
and side-effect free: no `World`, no DOM, no timers, no reliance on shared object
|
|
34
|
+
identity.
|
|
35
|
+
|
|
36
|
+
**Static geometry lives in TypeScript, composition lives in JSON.** Scene JSON
|
|
37
|
+
never declares URLs, geometry or materials — only manifest IDs.
|
|
38
|
+
|
|
39
|
+
**Components must be declared in a system-free module** and exported from
|
|
40
|
+
`src/components.ts`/`src/components.js` via `defineComponents()`. The editor
|
|
41
|
+
imports that same manifest to build its inspector, so a component that is not in
|
|
42
|
+
it cannot be authored in scenes.
|
|
43
|
+
|
|
44
|
+
**Import Three.js from `@iwsdk/core`, never from `three`.** `@iwsdk/core`
|
|
45
|
+
re-exports all of Three; importing `three` directly creates a duplicate instance
|
|
46
|
+
and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
|
|
47
|
+
|
|
48
|
+
## Traps that produce silent failures
|
|
49
|
+
|
|
50
|
+
| Trap | Symptom | Fix |
|
|
51
|
+
| ------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
|
|
52
|
+
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
|
|
53
|
+
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
|
|
54
|
+
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx iwsdk scene flatten` once, then edit the flat output |
|
|
55
|
+
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
|
|
56
|
+
| `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
|
|
57
|
+
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
|
|
58
|
+
| Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
|
|
59
|
+
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
|
|
60
|
+
| `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx iwsdk reference warmup`; fresh installed scaffolds do this during creation |
|
|
61
|
+
|
|
62
|
+
## Verify before you claim it works
|
|
63
|
+
|
|
64
|
+
**Always `npx tsc --noEmit` before testing.** Type errors stop systems
|
|
65
|
+
initialising without necessarily logging anything in the browser.
|
|
66
|
+
|
|
67
|
+
Then check the right status for the task — these are not interchangeable:
|
|
68
|
+
|
|
69
|
+
- scene/editor work → `scene_get_state`
|
|
70
|
+
- XR device or session actions → `xr_get_session_status`
|
|
71
|
+
- server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
|
|
72
|
+
|
|
73
|
+
When something is missing but the console is clean: call
|
|
74
|
+
`browser_get_console_logs` with only `count` (a `level` filter hides errors), then
|
|
75
|
+
`ecs_find_entities` to confirm the entity exists and carries the components you
|
|
76
|
+
expect.
|
|
77
|
+
|
|
78
|
+
The non-obvious part is which observation proves what: the **editor** render does
|
|
79
|
+
not run application systems, so anything driven by a system must be verified with
|
|
80
|
+
`browser_screenshot` (runtime), not `scene_screenshot` (editor).
|
|
81
|
+
|
|
82
|
+
## MCP and CLI are one surface, not two
|
|
83
|
+
|
|
84
|
+
Nearly every capability exists both ways — `scene_render_file` and
|
|
85
|
+
`npx iwsdk scene render-file`, `ecs_find_entities` and `npx iwsdk ecs find`.
|
|
86
|
+
Discover CLI actions with the bare domain or domain help (`npx iwsdk scene` or
|
|
87
|
+
`npx iwsdk scene --help`); both list that domain's actions.
|
|
88
|
+
|
|
89
|
+
**The CLI is not a fallback for a dead bridge.** Both routes drive the same
|
|
90
|
+
managed browser, so when `dev status` reports `browserConnected: false`,
|
|
91
|
+
every scene/ecs/xr/browser/ui command fails either way. Only `dev status`,
|
|
92
|
+
`dev logs` and `reference status` work without a browser.
|
|
93
|
+
|
|
94
|
+
Choose by the shape of the call, not by availability:
|
|
95
|
+
|
|
96
|
+
- **MCP** for one-off calls, and whenever you want the image returned inline.
|
|
97
|
+
- **CLI** when you need to loop or script — rendering six views, or sampling a
|
|
98
|
+
value twice to measure a rate — or when the response is big enough to be worth
|
|
99
|
+
filtering before it reaches context. A render of a scene containing an
|
|
100
|
+
instanced pattern returns an id for every expanded instance.
|
|
101
|
+
|
|
102
|
+
CLI `--output-file` returns a **different payload shape** from the plain call:
|
|
103
|
+
the result nests under `data.result` instead of `data`, and `renderStats` and the
|
|
104
|
+
hashes are dropped. If you need a hash or triangle count, omit `--output-file`
|
|
105
|
+
and filter the JSON instead.
|
|
106
|
+
|
|
107
|
+
## Skills
|
|
108
|
+
|
|
109
|
+
Scene composition, UI authoring, physics, depth occlusion, grab and ray
|
|
110
|
+
interaction testing, ECS frame-stepping, and end-to-end planning each have a
|
|
111
|
+
project skill in the selected harness's standard skill directory. Their
|
|
112
|
+
descriptions handle routing, so they are not restated here.
|
|
113
|
+
|
|
114
|
+
The failure worth guarding against is improvising a domain that already has a
|
|
115
|
+
skill because the naive approach looks tractable. Before hand-authoring scene
|
|
116
|
+
JSON, a UIKitML panel, or a physics body, invoke the skill.
|
|
117
|
+
|
|
118
|
+
## Layout
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
iwsdk.config.json project authority: scene, assets, components, world, dev
|
|
122
|
+
src/index.ts|js World.create() + explicit system registration
|
|
123
|
+
src/assets.ts|js defineAssets() — shared runtime/editor catalog
|
|
124
|
+
src/components.ts|js defineComponents() — shared runtime/editor catalog
|
|
125
|
+
src/scene-assets/ *.scene-asset.ts|js — parentless Object3D prototypes
|
|
126
|
+
public/scenes/ *.iwsdk.scene.json — composition only
|
|
127
|
+
public/ui/ *.uikitml — runtime-loaded panels
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
No barrel `index.ts` files. Keep component declarations free of system, DOM and
|
|
131
|
+
renderer imports; systems import the declarations, never the reverse.
|
|
132
|
+
|
|
133
|
+
## Conventions
|
|
134
|
+
|
|
135
|
+
- Systems use queries, never manually tracked entity arrays.
|
|
136
|
+
- Never allocate in `update()`. Allocate in `init()` as class properties.
|
|
137
|
+
- Prefer `queries.x.subscribe('qualify', ...)` over polling state each frame.
|
|
138
|
+
- Register every subscription teardown in `this.cleanupFuncs`.
|
|
139
|
+
- Use `signal.peek()` in `update()`; `.value` adds per-frame subscription overhead.
|
|
140
|
+
- Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
|
|
141
|
+
- Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
|
|
142
|
+
- Use the `RayInteractable` component, never a manual `Raycaster`.
|
|
143
|
+
- VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
|
|
144
|
+
|
|
145
|
+
## Deep reference
|
|
146
|
+
|
|
147
|
+
Harness-native scoped rules cover `public/scenes/**`, `public/ui/**`,
|
|
148
|
+
`src/assets.ts`, `src/scene-assets/**`, and `src/**/*.ts`. `AGENTS.md`-based
|
|
149
|
+
harnesses receive nested instruction files; Cursor and Copilot receive their
|
|
150
|
+
native rule formats. Skill procedures live in the selected harness's project
|
|
151
|
+
skill directory and state when they apply.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "src/assets.ts,src/assets.js,src/scene-assets/**"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Asset manifest contract
|
|
6
|
+
|
|
7
|
+
`src/assets.ts` is imported **independently by the app runtime and the editor**,
|
|
8
|
+
in separate JS realms. It must therefore be deterministic and self-contained:
|
|
9
|
+
|
|
10
|
+
- no `World`, scene, iframe, editor object or DOM access
|
|
11
|
+
- no timers, no fetching ambient state
|
|
12
|
+
- no reliance on singleton object identity across realms
|
|
13
|
+
- prototypes immutable after registration, and never parented
|
|
14
|
+
|
|
15
|
+
A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
|
|
16
|
+
or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
|
|
17
|
+
`HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
|
|
18
|
+
as scene content; audio/texture/HDR are for application systems.
|
|
19
|
+
|
|
20
|
+
Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
|
|
21
|
+
builds resolve identically. A file in `public/` is **not** available to a scene
|
|
22
|
+
until it is registered here.
|
|
23
|
+
|
|
24
|
+
## Procedural assets
|
|
25
|
+
|
|
26
|
+
Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
|
|
27
|
+
register it under a stable ID. The registry rejects an already-parented
|
|
28
|
+
prototype.
|
|
29
|
+
|
|
30
|
+
Every placement is a distinct hierarchy clone, but **geometry and materials stay
|
|
31
|
+
shared**. Never dispose them from a placed clone; world teardown owns their
|
|
32
|
+
lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
|
|
33
|
+
one instance — mutating the shared material in place changes every instance.
|
|
34
|
+
|
|
35
|
+
Bounds come from `Box3` over the instantiated asset and drive placement,
|
|
36
|
+
selection, framing and scatter collision. Put the origin where composition wants
|
|
37
|
+
it (usually floor contact, or the object's own pivot), keep transforms finite,
|
|
38
|
+
and don't let invisible helpers inflate bounds.
|
|
39
|
+
|
|
40
|
+
## Cost
|
|
41
|
+
|
|
42
|
+
Split tessellation by viewing distance rather than using one budget everywhere: a
|
|
43
|
+
close-range hero model and coarser display copies of the same form are two
|
|
44
|
+
prototypes from one factory function. Sphere/lathe segment counts dominate small
|
|
45
|
+
repeated detail more than people expect — check `renderStats.triangles` rather
|
|
46
|
+
than guessing.
|
|
47
|
+
|
|
48
|
+
Reuse material instances within a module. Prefer prefabs plus a deterministic
|
|
49
|
+
pattern for repetition; a pattern whose prefab resolves to a single component-free
|
|
50
|
+
mesh lowers to one `InstancedMesh`.
|
|
51
|
+
|
|
52
|
+
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "src/**/*.ts,src/**/*.js"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# ECS API reference
|
|
6
|
+
|
|
7
|
+
## Field types
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
|
|
11
|
+
Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
|
|
12
|
+
Types.Object // avoid — not optimised
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Component
|
|
16
|
+
|
|
17
|
+
Declare in a system-free module, then list it in `src/components.ts` via
|
|
18
|
+
`defineComponents()` or the editor cannot author it.
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
export const MyComponent = createComponent('MyComponent', {
|
|
22
|
+
speed: { type: Types.Float32, default: 1 },
|
|
23
|
+
tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
|
|
28
|
+
`widget` — drives the editor inspector.
|
|
29
|
+
|
|
30
|
+
## System
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
export class MySystem extends createSystem(
|
|
34
|
+
{
|
|
35
|
+
items: { required: [MyComponent] },
|
|
36
|
+
active: { required: [MyComponent], excluded: [Grabbed] },
|
|
37
|
+
},
|
|
38
|
+
{ speed: { type: Types.Float32, default: 1 } }, // optional config
|
|
39
|
+
) {
|
|
40
|
+
private temp!: Vector3;
|
|
41
|
+
|
|
42
|
+
init() {
|
|
43
|
+
this.temp = new Vector3();
|
|
44
|
+
this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
|
|
45
|
+
this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
update(delta: number, time: number) {
|
|
49
|
+
for (const entity of this.queries.active.entities) { /* no allocations */ }
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
|
|
55
|
+
`lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
|
|
56
|
+
entities in a transient state — e.g. excluding `Grabbed` so a held object is left
|
|
57
|
+
alone.
|
|
58
|
+
|
|
59
|
+
Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
|
|
60
|
+
|
|
61
|
+
Read fields with `entity.getValue(Component, 'field')`. For vector fields use
|
|
62
|
+
`entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
|
|
63
|
+
no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
|
|
64
|
+
|
|
65
|
+
## Interaction components
|
|
66
|
+
|
|
67
|
+
`RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
|
|
68
|
+
and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
|
|
69
|
+
proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
|
|
70
|
+
ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
|
|
71
|
+
`GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
|
|
72
|
+
defaults to **false**, so hand pinch does not grab unless you enable it.
|
|
73
|
+
|
|
74
|
+
`DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
|
|
75
|
+
`MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
|
|
76
|
+
`detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
|
|
77
|
+
`targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
|
|
78
|
+
no custom code.
|
|
79
|
+
|
|
80
|
+
For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
|
|
81
|
+
`getHolderHand(entity)` — never deep-import `Handle`.
|
|
82
|
+
|
|
83
|
+
## XR input
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const pad = this.input.xr.gamepads.right;
|
|
87
|
+
pad?.getButtonDown(InputComponent.Trigger); // just pressed
|
|
88
|
+
pad?.getAxesValues(InputComponent.Thumbstick);
|
|
89
|
+
this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
|
|
93
|
+
buttons. Browser controls live at `world.input.keyboard` and
|
|
94
|
+
`world.input.browserGamepads`.
|
|
95
|
+
|
|
96
|
+
## Lifecycle
|
|
97
|
+
|
|
98
|
+
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
99
|
+
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
100
|
+
`getWorldPosition()` when logic needs the true viewer position.
|