@iwsdk/create 1.1.0 → 1.2.0-rc.1
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 +68 -16
- package/dist/cli.js +7917 -3404
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-compose-scene/SKILL.md +3 -2
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-debug/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-dev/references/api-reference.md +8 -1
- package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md +16 -7
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md +9 -5
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-grab/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/SKILL.md +3 -1
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
- package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ray/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-ui/SKILL.md +17 -7
- package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/guidance/{claude → files}/.claude/agents/iwsdk-project-code-reviewer.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/assets-and-manifest.md +3 -0
- package/dist/guidance/{claude → files}/.claude/rules/ecs-api.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/scene-json.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/uikitml.md +1 -0
- package/dist/guidance/{claude → files}/.claude/settings.json +9 -3
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-compose-scene/SKILL.md +3 -2
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-debug/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-dev/references/api-reference.md +8 -1
- package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md +16 -7
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/planner.md +9 -5
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-grab/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/SKILL.md +3 -1
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
- package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ray/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-ui/SKILL.md +17 -7
- package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/assets-and-manifest.mdc +3 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/ecs-api.mdc +1 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/scene-json.mdc +1 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/uikitml.mdc +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md +2 -1
- package/dist/guidance/{copilot → files}/.github/instructions/ecs-api.instructions.md +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/scene-json.instructions.md +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/uikitml.instructions.md +1 -0
- package/dist/guidance/{common → files}/AGENTS.md +107 -27
- package/dist/guidance/{scoped-agents → files}/public/scenes/AGENTS.md +2 -0
- package/dist/guidance/{scoped-agents → files}/public/ui/AGENTS.md +2 -0
- package/dist/guidance/{scoped-agents → files}/src/AGENTS.md +2 -0
- package/dist/guidance/manifest.json +954 -0
- package/dist/template/common/.codex/config.toml +2 -0
- package/package.json +5 -5
- package/scripts/verify-release-ready.mjs +1 -2
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/agents/openai.yaml +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/vercel.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/component-reference.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/agents/openai.yaml +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/vercel.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/component-reference.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
- /package/dist/guidance/{claude → files}/CLAUDE.md +0 -0
- /package/dist/{guidance/codex → template/common-js}/.codex/config.toml +0 -0
|
@@ -1,5 +1,14 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=bb25ffd600c99d3f30cdc95518bb89161659907c667de45adcb29315b669bc7f -->
|
|
1
2
|
# IWSDK project
|
|
2
3
|
|
|
4
|
+
IWSDK changes faster than model training data. GLXF scenes, the external 0.4
|
|
5
|
+
scene editor and its Vite plugin, and the UIKitML-compile and glTF-optimizer Vite
|
|
6
|
+
plugins were removed in 0.5: scenes are native `*.iwsdk.scene.json` files edited
|
|
7
|
+
in IWSDK's built-in editor, and `@iwsdk/vite-plugin-dev` is the only IWSDK Vite
|
|
8
|
+
plugin. Trust this file and the project skills over what you remember about
|
|
9
|
+
IWSDK. To upgrade IWSDK, run `npx @iwsdk/cli@latest upgrade` and follow the
|
|
10
|
+
migration guides it writes to `.iwsdk/migrations/`.
|
|
11
|
+
|
|
3
12
|
A Vite + TypeScript or JavaScript app, but several things do **not** work the way
|
|
4
13
|
a normal Vite project works. Read this section before assuming anything.
|
|
5
14
|
|
|
@@ -16,6 +25,12 @@ applicable IWSDK guide or concept page.
|
|
|
16
25
|
|
|
17
26
|
## What is not standard Vite
|
|
18
27
|
|
|
28
|
+
**No `iwsdk.config.json` in this project?** IWSDK was added by hand. Run
|
|
29
|
+
`npx @iwsdk/create@latest . --yes --target vr` (`ar` for mixed reality,
|
|
30
|
+
`browser` for desktop 3D) to add the project manifest, an empty scene, and a
|
|
31
|
+
`virtual:iwsdk-project` entry in `src/iwsdk/` without overwriting any file; the
|
|
32
|
+
rest of this file assumes them.
|
|
33
|
+
|
|
19
34
|
**`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
|
|
20
35
|
the active scene, the asset module, the component module, and all XR/world
|
|
21
36
|
features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
|
|
@@ -44,12 +59,29 @@ tabGeneration on every physical command. Reload is supported through the page
|
|
|
44
59
|
bridge; screenshot, snapshot, interaction, profiling, console capture, and the
|
|
45
60
|
managed editor are host-only. Rediscover after reload to get the new generation.
|
|
46
61
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
62
|
+
**Choose the session mode before the first `dev up`, and pass it explicitly**
|
|
63
|
+
(the CLI default is headed):
|
|
64
|
+
|
|
65
|
+
- `--ai-mode collaborate` (headed, draws every frame, Runtime/Editor toggle)
|
|
66
|
+
when the user wants to watch or steer the work as it happens: they ask to see
|
|
67
|
+
it, are pairing live, or will judge visuals or motion by eye.
|
|
68
|
+
- `--ai-mode agent` (headless, draws only when a tool needs pixels, fast without
|
|
69
|
+
a GPU) for everything else: autonomous or background work, CI, a remote host
|
|
70
|
+
or no display.
|
|
71
|
+
|
|
72
|
+
If the request does not say and the user is there, ask once whether they want to
|
|
73
|
+
watch in a browser window or let you work headless; if nobody can answer, use
|
|
74
|
+
agent. That one question is allowed even where a playbook avoids pausing; put it
|
|
75
|
+
in your first reply, and start agent mode if no answer has come by the time you
|
|
76
|
+
need the session. Reuse a healthy session in whatever mode it runs, and announce
|
|
77
|
+
any mode change before restarting. Headless screenshots always show a fresh
|
|
78
|
+
frame, but frame rate there means nothing; the iwsdk-dev skill's
|
|
79
|
+
`references/headless-rendering.md` covers exact frames, filmstrips and
|
|
80
|
+
`RuntimeSettings`. In a visible collaboration session, use the Runtime/Editor
|
|
81
|
+
toggle in the single managed Chromium window. Its expected unsupported-flag
|
|
82
|
+
banner comes from `--ignore-certificate-errors` for the local development
|
|
83
|
+
certificate. Playwright may add separate sandbox-related flags in constrained
|
|
84
|
+
environments.
|
|
53
85
|
|
|
54
86
|
**`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
|
|
55
87
|
realms** — once by the app runtime, once by the editor. It must be deterministic
|
|
@@ -70,18 +102,17 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
|
|
|
70
102
|
|
|
71
103
|
## Traps that produce silent failures
|
|
72
104
|
|
|
73
|
-
| Trap | Symptom | Fix
|
|
74
|
-
| -------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
75
|
-
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface
|
|
76
|
-
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform`
|
|
77
|
-
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output
|
|
78
|
-
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()`
|
|
79
|
-
| `setValue` on a Vec2/Vec3/Vec4
|
|
80
|
-
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only
|
|
81
|
-
| `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`)
|
|
82
|
-
| `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it
|
|
83
|
-
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'`
|
|
84
|
-
| `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
|
|
105
|
+
| Trap | Symptom | Fix |
|
|
106
|
+
| -------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
107
|
+
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
|
|
108
|
+
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
|
|
109
|
+
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
|
|
110
|
+
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
|
|
111
|
+
| `setValue` on a Vec2/Vec3/Vec4 field | throws in elics 3.4.x | use `entity.getVectorView(...)` (Color fields take `setValue` with hex or `Color`) |
|
|
112
|
+
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
|
|
113
|
+
| `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`) |
|
|
114
|
+
| `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it |
|
|
115
|
+
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
|
|
85
116
|
|
|
86
117
|
## Verify before you claim it works
|
|
87
118
|
|
|
@@ -112,11 +143,21 @@ active XR session (`npx @iwsdk/cli xr status`). A flat runtime screenshot taken
|
|
|
112
143
|
outside XR can prove that the app renders, but it cannot prove immersive pose or
|
|
113
144
|
interaction correctness.
|
|
114
145
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
146
|
+
**When the user wants to try the app in a headset themselves**, give them a
|
|
147
|
+
plain session, never a native-control one. A session started with
|
|
148
|
+
`--native-xr-control` hands the head pose and controllers of every Quest Browser
|
|
149
|
+
page it serves to the CLI, with or without a pairing token in the URL, so the
|
|
150
|
+
user's own movement does nothing. If this session was started with
|
|
151
|
+
`--native-xr-control`, or you cannot tell, first run
|
|
152
|
+
`npx @iwsdk/cli dev restart` with the session's own `--ai-mode` and without that
|
|
153
|
+
flag; say so before restarting. Then run `npx @iwsdk/cli dev status` and give the
|
|
154
|
+
user a plain URL, never a `runtime pair-headset` URL: on the same Wi-Fi network,
|
|
155
|
+
one from `data.runtimeUrls.network` (they accept the expected local certificate
|
|
156
|
+
warning); on a Quest connected over USB, run
|
|
157
|
+
`adb -s <serial> reverse tcp:<port> tcp:<port>` and give
|
|
158
|
+
`data.runtimeUrls.local`. Invoke `iwsdk-native-xr-test` only when you drive the
|
|
159
|
+
headset yourself: automating, scripting, or debugging the app on a USB Quest.
|
|
160
|
+
See [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
|
|
120
161
|
for the complete workflow.
|
|
121
162
|
|
|
122
163
|
**Meta VR Glasses are not a Quest.** Their view is much narrower (37° left and
|
|
@@ -175,11 +216,14 @@ The selected playbook routes work to the narrowest owning specialist:
|
|
|
175
216
|
- a model-local defect found during composition routes back to `iwsdk-build-model`;
|
|
176
217
|
a placement or lighting defect stays in `iwsdk-compose-scene`.
|
|
177
218
|
|
|
178
|
-
UI authoring, physics, depth occlusion, grab and ray interaction testing,
|
|
179
|
-
frame-stepping,
|
|
180
|
-
the selected `iwsdk-dev` playbook calls for
|
|
219
|
+
UI authoring, physics, depth occlusion, grab and ray interaction testing, and
|
|
220
|
+
debugging (including ECS frame-stepping, in `iwsdk-debug`) have their own
|
|
221
|
+
project skills. Use them only when the selected `iwsdk-dev` playbook calls for
|
|
222
|
+
the matching specialty.
|
|
223
|
+
Invoke `iwsdk-upgrade` whenever the user asks to upgrade or bump IWSDK.
|
|
181
224
|
Two device-testing skills are invoked directly: `iwsdk-native-xr-test` whenever
|
|
182
|
-
|
|
225
|
+
you will drive the app on a connected Quest yourself (automate, script-test, or
|
|
226
|
+
debug it), never when the user wants to put the headset on and try it, and
|
|
183
227
|
`iwsdk-glasses-test` whenever the user targets Meta VR Glasses or asks for gaze
|
|
184
228
|
input.
|
|
185
229
|
|
|
@@ -199,6 +243,10 @@ public/scenes/ *.iwsdk.scene.json — composition only
|
|
|
199
243
|
public/ui/ *.uikitml — runtime-loaded panels
|
|
200
244
|
```
|
|
201
245
|
|
|
246
|
+
An app that added IWSDK to an existing project keeps these modules in
|
|
247
|
+
`src/iwsdk/` instead. `iwsdk.config.json` names the modules either way; the
|
|
248
|
+
`src/...` paths in this guidance mean the modules it names.
|
|
249
|
+
|
|
202
250
|
No barrel `index.ts` files. Keep component declarations free of system, DOM and
|
|
203
251
|
renderer imports; systems import the declarations, never the reverse.
|
|
204
252
|
|
|
@@ -212,12 +260,44 @@ renderer imports; systems import the declarations, never the reverse.
|
|
|
212
260
|
- Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
|
|
213
261
|
- Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
|
|
214
262
|
- Use the `RayInteractable` component, never a manual `Raycaster`.
|
|
263
|
+
- Give a UI panel or button both `RayInteractable` and `PokeInteractable`.
|
|
264
|
+
Fingertip touches only reach entities with `PokeInteractable`, so a
|
|
265
|
+
ray-only panel ignores hand presses.
|
|
215
266
|
- VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
|
|
267
|
+
- Keep an Enter XR control on the flat page of every XR app: the starter's
|
|
268
|
+
welcome-panel button, or your own UIKit or DOM button that calls
|
|
269
|
+
`world.launchXR()`. If you remove the welcome panel, replace its button.
|
|
270
|
+
`xr.offer` alone only adds a small "Enter VR" pill to the Quest Browser
|
|
271
|
+
toolbar (labelled VR even for AR), which people miss, so the page looks like
|
|
272
|
+
it has no way into XR.
|
|
273
|
+
- Keep app and game state that a person or agent will want to read or change
|
|
274
|
+
(score, lives, gold, wave, phase, timers, debug switches) in ECS components,
|
|
275
|
+
not module-level objects. `ecs query` and `ecs set-component` then read it and
|
|
276
|
+
jump it to any state from the CLI or MCP, in the emulator and on a paired
|
|
277
|
+
headset, without editing code or scripting the page.
|
|
278
|
+
|
|
279
|
+
**Browser automation is a last resort.** `dev up --allow-browser-automation`
|
|
280
|
+
enables `browser run`, which runs your own Playwright script inside the managed
|
|
281
|
+
browser. Before you reach for it, or for a temporary source edit such as
|
|
282
|
+
lowering a start value, to reach a hard-to-reach state, check whether that state
|
|
283
|
+
belongs in ECS. If it does, move it into a component as part of the work and
|
|
284
|
+
drive it with `ecs set-component`. Use browser automation only for what ECS and
|
|
285
|
+
the built-in tools cannot express, and say why.
|
|
216
286
|
|
|
217
287
|
## Deep reference
|
|
218
288
|
|
|
289
|
+
Look up IWSDK APIs with `npx @iwsdk/cli reference <op> --input-json '{...}'`
|
|
290
|
+
(the same tools are on MCP) instead of reading `node_modules`: `api`
|
|
291
|
+
`{"name":"World"}` for a known name, `search` `{"query":"PokeInteractable hand"}`,
|
|
292
|
+
`components` and `systems` to list every ECS type, `examples`
|
|
293
|
+
`{"api_name":"createSystem"}` for usage. `search` is a keyword search: give
|
|
294
|
+
identifiers plus a few words, not questions. The corpus ships inside
|
|
295
|
+
`@iwsdk/reference`, matches the installed version and needs no network or
|
|
296
|
+
warmup.
|
|
297
|
+
|
|
219
298
|
Harness-native scoped rules cover `public/scenes/**`, `public/ui/**`,
|
|
220
299
|
`src/assets.ts`, `src/scene-assets/**`, and `src/**/*.ts`. `AGENTS.md`-based
|
|
221
300
|
harnesses receive nested instruction files; Cursor and Copilot receive their
|
|
222
301
|
native rule formats. Skill procedures live in the selected harness's project
|
|
223
302
|
skill directory and state when they apply.
|
|
303
|
+
<!-- END iwsdk-agent-guidance -->
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=4451a5b98ba38a835cca3fc49666cbe62ba77353f6b8d0ed7d46b691d35067c1 -->
|
|
1
2
|
# IWSDK scoped project guidance
|
|
2
3
|
|
|
3
4
|
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
@@ -68,3 +69,4 @@ back. Render each changed module before the root.
|
|
|
68
69
|
|
|
69
70
|
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
70
71
|
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
72
|
+
<!-- END iwsdk-agent-guidance -->
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=abe74e27fdcd33f9fbdfa6fef5b11cd1427fe15c66fec1a0b884f3a09b750266 -->
|
|
1
2
|
# IWSDK scoped project guidance
|
|
2
3
|
|
|
3
4
|
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
@@ -62,3 +63,4 @@ can.
|
|
|
62
63
|
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
63
64
|
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
64
65
|
than improvising. This file is the format reference it relies on.
|
|
66
|
+
<!-- END iwsdk-agent-guidance -->
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=b60c812e637c6f5bd8f4480f83d7c28a93e042abac20fee504238e8981fa2b6f -->
|
|
1
2
|
# IWSDK scoped project guidance
|
|
2
3
|
|
|
3
4
|
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
@@ -149,3 +150,4 @@ mesh lowers to one `InstancedMesh`.
|
|
|
149
150
|
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
150
151
|
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
151
152
|
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
153
|
+
<!-- END iwsdk-agent-guidance -->
|