@iwsdk/create 0.5.2 → 1.0.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/dist/cli.js +7223 -215
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
- package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
- package/dist/guidance/claude/.claude/settings.json +6 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/CLAUDE.md +2 -141
- package/dist/guidance/codex/.codex/config.toml +1 -1
- package/dist/guidance/common/AGENTS.md +96 -37
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/public/ui/welcome.uikitml +0 -19
- package/dist/template/common/src/robot.ts +5 -0
- package/dist/template/common/vite.config.ts +18 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
- package/dist/template/common-js/src/robot.js +5 -0
- package/dist/template/common-js/vite.config.js +18 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
- package/package.json +8 -7
- package/scripts/verify-release-ready.mjs +25 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
- /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
|
@@ -8,25 +8,48 @@ format. Harnesses that use `AGENTS.md` also receive equivalent nested files near
|
|
|
8
8
|
the code they govern. Read the applicable scoped instructions before working in
|
|
9
9
|
that area.
|
|
10
10
|
|
|
11
|
+
Explain immersive terms in plain language when they first matter instead of
|
|
12
|
+
assuming the reader knows them. In particular, introduce XR (an immersive
|
|
13
|
+
session), IWER (IWSDK's browser-based XR emulator), ECS (entity-component
|
|
14
|
+
system), and controller target-ray versus grip poses with a link to the
|
|
15
|
+
applicable IWSDK guide or concept page.
|
|
16
|
+
|
|
11
17
|
## What is not standard Vite
|
|
12
18
|
|
|
13
19
|
**`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
|
|
14
20
|
the active scene, the asset module, the component module, and all XR/world
|
|
15
21
|
features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
|
|
16
22
|
restarts Vite in place; the managed window remains open and its command bridges
|
|
17
|
-
reconnect automatically. Wait for `npx iwsdk dev status` to report
|
|
23
|
+
reconnect automatically. Wait for `npx @iwsdk/cli dev status` to report
|
|
18
24
|
`browserCommandReady: true` before issuing browser-backed commands.
|
|
19
25
|
|
|
20
26
|
**`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
|
|
21
27
|
`src/index.js` imports it and passes it whole to `World.create()`. Do not
|
|
22
28
|
hand-build that options object.
|
|
23
29
|
|
|
24
|
-
**The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
|
|
30
|
+
**The dev server is CLI-managed.** Use `npx @iwsdk/cli dev up` (or `npm run dev`), not
|
|
25
31
|
`vite`. It launches a managed browser that hosts the MCP command bridge.
|
|
26
|
-
`--no-open`
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
32
|
+
`--no-open` starts the server with managed-browser launch disabled. Server status
|
|
33
|
+
and explicitly paired physical targets remain available. A targetless managed
|
|
34
|
+
browser command then fails with `browser_not_launched`; it never falls through
|
|
35
|
+
to a physical page. Commands default to the managed browser. One managed
|
|
36
|
+
window hosts the editor and application roles. Browser failure leaves Vite and
|
|
37
|
+
HMR running. `runtime status`, `runtime targets`, and `runtime wait` do not recover
|
|
38
|
+
or launch a browser; `runtime recover` explicitly retries after a failure.
|
|
39
|
+
|
|
40
|
+
Pair a headset using `runtime pair-headset --input-json '{"headsetId":"ADB_SERIAL"}'`,
|
|
41
|
+
open the returned URL on that exact device through ADB reverse, then copy its
|
|
42
|
+
`runtimeTarget` from `runtime targets`. Include deviceClass, headsetId, pageId, and
|
|
43
|
+
tabGeneration on every physical command. Reload is supported through the page
|
|
44
|
+
bridge; screenshot, snapshot, interaction, profiling, console capture, and the
|
|
45
|
+
managed editor are host-only. Rediscover after reload to get the new generation.
|
|
46
|
+
|
|
47
|
+
The developer owns whether that managed window is headed or headless. Do not
|
|
48
|
+
change modes silently: announce the change before restarting. In a visible
|
|
49
|
+
collaboration session, use the Runtime/Editor toggle in the single managed
|
|
50
|
+
Chromium window. Its expected unsupported-flag banner comes from
|
|
51
|
+
`--ignore-certificate-errors` for the local development certificate. Playwright
|
|
52
|
+
may add separate sandbox-related flags in constrained environments.
|
|
30
53
|
|
|
31
54
|
**`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
|
|
32
55
|
realms** — once by the app runtime, once by the editor. It must be deterministic
|
|
@@ -47,28 +70,32 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
|
|
|
47
70
|
|
|
48
71
|
## Traps that produce silent failures
|
|
49
72
|
|
|
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 |
|
|
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/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
|
|
80
|
+
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
|
|
81
|
+
| Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
|
|
82
|
+
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
|
|
83
|
+
| `@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 |
|
|
61
84
|
|
|
62
85
|
## Verify before you claim it works
|
|
63
86
|
|
|
64
|
-
**Always `
|
|
87
|
+
**Always `npm run --if-present typecheck` before testing.** Type errors stop systems
|
|
65
88
|
initialising without necessarily logging anything in the browser.
|
|
66
89
|
|
|
90
|
+
For a new multi-file procedural model, finish the initial asset module and manifest
|
|
91
|
+
registration before `npx @iwsdk/cli dev up`; do not keep the browser live while its import
|
|
92
|
+
graph is half-written. Typecheck first, then launch the managed editor for inspection.
|
|
93
|
+
|
|
67
94
|
Then check the right status for the task — these are not interchangeable:
|
|
68
95
|
|
|
69
96
|
- scene/editor work → `scene_get_state`
|
|
70
97
|
- XR device or session actions → `xr_get_session_status`
|
|
71
|
-
- server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
|
|
98
|
+
- server readiness → `npx @iwsdk/cli dev status` (XR availability is not a server signal)
|
|
72
99
|
|
|
73
100
|
When something is missing but the console is clean: call
|
|
74
101
|
`browser_get_console_logs` with only `count` (a `level` filter hides errors), then
|
|
@@ -79,41 +106,73 @@ The non-obvious part is which observation proves what: the **editor** render doe
|
|
|
79
106
|
not run application systems, so anything driven by a system must be verified with
|
|
80
107
|
`browser_screenshot` (runtime), not `scene_screenshot` (editor).
|
|
81
108
|
|
|
109
|
+
Pose, controller/hand alignment, and immersive interaction claims require an
|
|
110
|
+
active XR session (`npx @iwsdk/cli xr status`). A flat runtime screenshot taken
|
|
111
|
+
outside XR can prove that the app renders, but it cannot prove immersive pose or
|
|
112
|
+
interaction correctness.
|
|
113
|
+
|
|
114
|
+
For a physical headset smoke test, run `npx @iwsdk/cli dev status`, open a URL from
|
|
115
|
+
`data.runtimeUrls.network` on a headset connected to the same Wi-Fi network,
|
|
116
|
+
and accept the expected local certificate warning. See
|
|
117
|
+
[Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
|
|
118
|
+
for the complete workflow.
|
|
119
|
+
|
|
82
120
|
## MCP and CLI are one surface, not two
|
|
83
121
|
|
|
84
122
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
`
|
|
123
|
+
`npx @iwsdk/cli scene render-file`, `ecs_find_entities` and `npx @iwsdk/cli ecs find`,
|
|
124
|
+
or `ui_inspect` and `npx @iwsdk/cli ui inspect`.
|
|
125
|
+
Discover CLI actions with the bare domain or domain help (`npx @iwsdk/cli scene` or
|
|
126
|
+
`npx @iwsdk/cli scene --help`); both list that domain's actions.
|
|
127
|
+
|
|
128
|
+
**CLI and MCP share the same target resolver and recovery policy.** A managed
|
|
129
|
+
command can recover a missing managed browser; it then returns
|
|
130
|
+
`browser_relaunched` with `outcome: "not_executed"`. Inspect the new state and issue
|
|
131
|
+
a fresh command. `outcome_unknown` means a dispatched mutation may have executed;
|
|
132
|
+
inspect state before retrying. Requests are never broadcast or replayed on
|
|
133
|
+
reconnect. Host browser tools can remain usable while a runtime bridge is loading.
|
|
93
134
|
|
|
94
135
|
Choose by the shape of the call, not by availability:
|
|
95
136
|
|
|
96
|
-
- **MCP** for one-off calls
|
|
137
|
+
- **MCP** for one-off calls. Screenshot tools persist the PNG locally and return
|
|
138
|
+
`screenshotPath`; read that file only when visual inspection is needed.
|
|
97
139
|
- **CLI** when you need to loop or script — rendering six views, or sampling a
|
|
98
140
|
value twice to measure a rate — or when the response is big enough to be worth
|
|
99
141
|
filtering before it reaches context. A render of a scene containing an
|
|
100
142
|
instanced pattern returns an id for every expanded instance.
|
|
101
143
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
and
|
|
144
|
+
For screenshot-producing CLI commands, the default response writes the image to a
|
|
145
|
+
temporary file and returns a normal envelope with metadata under `data.result` and
|
|
146
|
+
the path at `data.screenshotPath`. `--output-file <path>` selects the destination and
|
|
147
|
+
keeps that same metadata, including hashes and render statistics. `--raw` instead
|
|
148
|
+
prints the raw runtime result, including base64 `imageData`; when both flags are
|
|
149
|
+
present, `--output-file` takes precedence and image bytes are omitted.
|
|
106
150
|
|
|
107
151
|
## Skills
|
|
108
152
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
153
|
+
Invoke `iwsdk-dev` first for any request that builds, extends, fixes, tunes,
|
|
154
|
+
or polishes the app. It privately selects the greenfield planner path or the
|
|
155
|
+
bounded established-app iteration path; do not look for those paths as separate
|
|
156
|
+
public skills.
|
|
157
|
+
|
|
158
|
+
The selected playbook routes work to the narrowest owning specialist:
|
|
159
|
+
|
|
160
|
+
- creating or materially changing one glTF or procedural 3D asset →
|
|
161
|
+
`iwsdk-build-model`;
|
|
162
|
+
- arranging existing assets, scene JSON, cross-asset contacts, lighting,
|
|
163
|
+
environment, or cameras → `iwsdk-compose-scene`;
|
|
164
|
+
- a mixed build → finish every new or changed model, including support and set assets,
|
|
165
|
+
with `iwsdk-build-model`, then compose the scene with `iwsdk-compose-scene`;
|
|
166
|
+
- a model-local defect found during composition routes back to `iwsdk-build-model`;
|
|
167
|
+
a placement or lighting defect stays in `iwsdk-compose-scene`.
|
|
168
|
+
|
|
169
|
+
UI authoring, physics, depth occlusion, grab and ray interaction testing, ECS
|
|
170
|
+
frame-stepping, and debugging have their own project skills. Use them only when
|
|
171
|
+
the selected `iwsdk-dev` playbook calls for the matching specialty.
|
|
113
172
|
|
|
114
173
|
The failure worth guarding against is improvising a domain that already has a
|
|
115
174
|
skill because the naive approach looks tractable. Before hand-authoring scene
|
|
116
|
-
JSON, a UIKitML panel, or a physics body, invoke the skill.
|
|
175
|
+
JSON, a 3D model, a UIKitML panel, or a physics body, invoke the owning skill.
|
|
117
176
|
|
|
118
177
|
## Layout
|
|
119
178
|
|
|
@@ -5,10 +5,12 @@ applyTo: "public/scenes/**"
|
|
|
5
5
|
# Scene JSON — things that fail silently
|
|
6
6
|
|
|
7
7
|
Format reference lives in
|
|
8
|
-
`.agents/skills/iwsdk-scene
|
|
8
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
9
9
|
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
10
|
-
it
|
|
11
|
-
|
|
10
|
+
it for imports, prefabs, patterns, or a schema detail not covered by active
|
|
11
|
+
guidance. For ordinary flat node, component, and authored-view edits, this rule,
|
|
12
|
+
the existing scene, and the active specialist are sufficient. This file is only
|
|
13
|
+
the short list of behaviours that produce no error when you get them wrong.
|
|
12
14
|
|
|
13
15
|
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
14
16
|
closed — an unknown field fails validation.
|
|
@@ -18,7 +20,7 @@ closed — an unknown field fails validation.
|
|
|
18
20
|
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
19
21
|
scenes remain useful for composition. The editable scene session and application
|
|
20
22
|
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
21
|
-
`npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
|
|
23
|
+
`npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
|
|
22
24
|
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
23
25
|
later human editor changes.
|
|
24
26
|
|
|
@@ -8,10 +8,12 @@ alwaysApply: false
|
|
|
8
8
|
# Scene JSON — things that fail silently
|
|
9
9
|
|
|
10
10
|
Format reference lives in
|
|
11
|
-
`.agents/skills/iwsdk-scene
|
|
11
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
12
12
|
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
13
|
-
it
|
|
14
|
-
|
|
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.
|
|
15
17
|
|
|
16
18
|
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
17
19
|
closed — an unknown field fails validation.
|
|
@@ -21,7 +23,7 @@ closed — an unknown field fails validation.
|
|
|
21
23
|
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
22
24
|
scenes remain useful for composition. The editable scene session and application
|
|
23
25
|
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
24
|
-
`npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
|
|
26
|
+
`npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
|
|
25
27
|
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
26
28
|
later human editor changes.
|
|
27
29
|
|
|
@@ -5,10 +5,12 @@ This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
|
5
5
|
# Scene JSON — things that fail silently
|
|
6
6
|
|
|
7
7
|
Format reference lives in
|
|
8
|
-
`.agents/skills/iwsdk-scene
|
|
8
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
9
9
|
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
10
|
-
it
|
|
11
|
-
|
|
10
|
+
it for imports, prefabs, patterns, or a schema detail not covered by active
|
|
11
|
+
guidance. For ordinary flat node, component, and authored-view edits, this rule,
|
|
12
|
+
the existing scene, and the active specialist are sufficient. This file is only
|
|
13
|
+
the short list of behaviours that produce no error when you get them wrong.
|
|
12
14
|
|
|
13
15
|
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
14
16
|
closed — an unknown field fails validation.
|
|
@@ -18,7 +20,7 @@ closed — an unknown field fails validation.
|
|
|
18
20
|
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
19
21
|
scenes remain useful for composition. The editable scene session and application
|
|
20
22
|
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
21
|
-
`npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
|
|
23
|
+
`npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
|
|
22
24
|
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
23
25
|
later human editor changes.
|
|
24
26
|
|
|
@@ -11,3 +11,16 @@ npm run dev
|
|
|
11
11
|
|
|
12
12
|
Use the Runtime and Editor controls in the managed browser to switch between
|
|
13
13
|
the running experience and its authored scene.
|
|
14
|
+
|
|
15
|
+
## Starter content
|
|
16
|
+
|
|
17
|
+
The robot and welcome panel are small examples of authored scene content plus
|
|
18
|
+
runtime systems. The robot turns toward the player's head and plays a sound
|
|
19
|
+
when pressed. To remove the robot, delete its scene node, its `RobotSystem`
|
|
20
|
+
registration from `src/index.ts` or `src/index.js`, and its `Robot` registration
|
|
21
|
+
from `src/components.ts` or `src/components.js`; you can then delete the unused
|
|
22
|
+
robot component and system files. To remove the welcome panel, delete its scene
|
|
23
|
+
node and its `PanelSystem` registration from the application entry point.
|
|
24
|
+
|
|
25
|
+
- Minimal scene walkthrough: https://iwsdk.dev/guides/01b-minimal-scene.html
|
|
26
|
+
- XR-enabled projects — IWER emulator controls: https://iwsdk.dev/guides/02-testing-experience.html#iwer-controls
|
|
@@ -3,27 +3,8 @@
|
|
|
3
3
|
Horizon kit. RectangleGoggles and LogIn are bundled Lucide icon components.
|
|
4
4
|
-->
|
|
5
5
|
<style>
|
|
6
|
-
@font-face {
|
|
7
|
-
font-family: "DM Sans";
|
|
8
|
-
src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAopxhTg.ttf");
|
|
9
|
-
font-weight: 400;
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
@font-face {
|
|
13
|
-
font-family: "DM Sans";
|
|
14
|
-
src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAkJxhTg.ttf");
|
|
15
|
-
font-weight: 500;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
@font-face {
|
|
19
|
-
font-family: "DM Sans";
|
|
20
|
-
src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwARZthTg.ttf");
|
|
21
|
-
font-weight: 700;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
6
|
.panel-root {
|
|
25
7
|
flex-direction: column;
|
|
26
|
-
font-family: "DM Sans";
|
|
27
8
|
width: 344px;
|
|
28
9
|
}
|
|
29
10
|
|
|
@@ -8,6 +8,11 @@
|
|
|
8
8
|
import { AudioUtils, createSystem, Pressed, Vector3 } from '@iwsdk/core';
|
|
9
9
|
import { Robot } from './robot-component.js';
|
|
10
10
|
|
|
11
|
+
/**
|
|
12
|
+
* Starter-only behavior for the sample robot: face the player and play its
|
|
13
|
+
* configured audio when pressed. It is safe to delete with the robot scene
|
|
14
|
+
* node, Robot component declaration, and registration in src/index.ts.
|
|
15
|
+
*/
|
|
11
16
|
export class RobotSystem extends createSystem({
|
|
12
17
|
robot: { required: [Robot] },
|
|
13
18
|
robotClicked: { required: [Robot, Pressed] },
|
|
@@ -18,8 +18,26 @@ export default defineConfig({
|
|
|
18
18
|
rollupOptions: { input: './index.html' },
|
|
19
19
|
},
|
|
20
20
|
esbuild: { target: 'esnext' },
|
|
21
|
+
// @drawcall/uikitml otherwise pulls a second three/@pmndrs/uikit graph
|
|
22
|
+
// (three@0.185 vs app super-three@0.181). Duplicate Component classes break
|
|
23
|
+
// instanceof checks → "Only pmndrs/uikit components can be added as children".
|
|
24
|
+
resolve: {
|
|
25
|
+
dedupe: [
|
|
26
|
+
'three',
|
|
27
|
+
'@pmndrs/uikit',
|
|
28
|
+
'@pmndrs/uikit-horizon',
|
|
29
|
+
'@pmndrs/uikit-lucide',
|
|
30
|
+
],
|
|
31
|
+
},
|
|
21
32
|
optimizeDeps: {
|
|
22
33
|
exclude: ['@babylonjs/havok'],
|
|
34
|
+
include: [
|
|
35
|
+
'three',
|
|
36
|
+
'@pmndrs/uikit',
|
|
37
|
+
'@pmndrs/uikit-horizon',
|
|
38
|
+
'@pmndrs/uikit-lucide',
|
|
39
|
+
'@drawcall/uikitml',
|
|
40
|
+
],
|
|
23
41
|
esbuildOptions: { target: 'esnext' },
|
|
24
42
|
},
|
|
25
43
|
publicDir: 'public',
|
|
@@ -11,3 +11,16 @@ npm run dev
|
|
|
11
11
|
|
|
12
12
|
Use the Runtime and Editor controls in the managed browser to switch between
|
|
13
13
|
the running experience and its authored scene.
|
|
14
|
+
|
|
15
|
+
## Starter content
|
|
16
|
+
|
|
17
|
+
The robot and welcome panel are small examples of authored scene content plus
|
|
18
|
+
runtime systems. The robot turns toward the player's head and plays a sound
|
|
19
|
+
when pressed. To remove the robot, delete its scene node, its `RobotSystem`
|
|
20
|
+
registration from `src/index.ts` or `src/index.js`, and its `Robot` registration
|
|
21
|
+
from `src/components.ts` or `src/components.js`; you can then delete the unused
|
|
22
|
+
robot component and system files. To remove the welcome panel, delete its scene
|
|
23
|
+
node and its `PanelSystem` registration from the application entry point.
|
|
24
|
+
|
|
25
|
+
- Minimal scene walkthrough: https://iwsdk.dev/guides/01b-minimal-scene.html
|
|
26
|
+
- XR-enabled projects — IWER emulator controls: https://iwsdk.dev/guides/02-testing-experience.html#iwer-controls
|
|
@@ -3,27 +3,8 @@
|
|
|
3
3
|
Horizon kit. RectangleGoggles and LogIn are bundled Lucide icon components.
|
|
4
4
|
-->
|
|
5
5
|
<style>
|
|
6
|
-
@font-face {
|
|
7
|
-
font-family: "DM Sans";
|
|
8
|
-
src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAopxhTg.ttf");
|
|
9
|
-
font-weight: 400;
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
@font-face {
|
|
13
|
-
font-family: "DM Sans";
|
|
14
|
-
src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAkJxhTg.ttf");
|
|
15
|
-
font-weight: 500;
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
@font-face {
|
|
19
|
-
font-family: "DM Sans";
|
|
20
|
-
src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwARZthTg.ttf");
|
|
21
|
-
font-weight: 700;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
6
|
.panel-root {
|
|
25
7
|
flex-direction: column;
|
|
26
|
-
font-family: "DM Sans";
|
|
27
8
|
width: 344px;
|
|
28
9
|
}
|
|
29
10
|
|
|
@@ -6,6 +6,11 @@
|
|
|
6
6
|
*/
|
|
7
7
|
import { AudioUtils, createSystem, Pressed, Vector3 } from '@iwsdk/core';
|
|
8
8
|
import { Robot } from './robot-component.js';
|
|
9
|
+
/**
|
|
10
|
+
* Starter-only behavior for the sample robot: face the player and play its
|
|
11
|
+
* configured audio when pressed. It is safe to delete with the robot scene
|
|
12
|
+
* node, Robot component declaration, and registration in src/index.ts.
|
|
13
|
+
*/
|
|
9
14
|
export class RobotSystem extends createSystem({
|
|
10
15
|
robot: { required: [Robot] },
|
|
11
16
|
robotClicked: { required: [Robot, Pressed] },
|
|
@@ -16,8 +16,26 @@ export default defineConfig({
|
|
|
16
16
|
rollupOptions: { input: './index.html' },
|
|
17
17
|
},
|
|
18
18
|
esbuild: { target: 'esnext' },
|
|
19
|
+
// @drawcall/uikitml otherwise pulls a second three/@pmndrs/uikit graph
|
|
20
|
+
// (three@0.185 vs app super-three@0.181). Duplicate Component classes break
|
|
21
|
+
// instanceof checks → "Only pmndrs/uikit components can be added as children".
|
|
22
|
+
resolve: {
|
|
23
|
+
dedupe: [
|
|
24
|
+
'three',
|
|
25
|
+
'@pmndrs/uikit',
|
|
26
|
+
'@pmndrs/uikit-horizon',
|
|
27
|
+
'@pmndrs/uikit-lucide',
|
|
28
|
+
],
|
|
29
|
+
},
|
|
19
30
|
optimizeDeps: {
|
|
20
31
|
exclude: ['@babylonjs/havok'],
|
|
32
|
+
include: [
|
|
33
|
+
'three',
|
|
34
|
+
'@pmndrs/uikit',
|
|
35
|
+
'@pmndrs/uikit-horizon',
|
|
36
|
+
'@pmndrs/uikit-lucide',
|
|
37
|
+
'@drawcall/uikitml',
|
|
38
|
+
],
|
|
21
39
|
esbuildOptions: { target: 'esnext' },
|
|
22
40
|
},
|
|
23
41
|
publicDir: 'public',
|
|
@@ -1,7 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": "iwsdk.scene.v1",
|
|
3
3
|
"units": "meters",
|
|
4
|
-
"components": {
|
|
4
|
+
"components": {
|
|
5
|
+
"com.iwsdk.components.IBLGradient": {
|
|
6
|
+
"sky": [0.6902, 0.749, 0.7843, 1],
|
|
7
|
+
"equator": [0.6584, 0.7084, 0.7913, 1],
|
|
8
|
+
"ground": [0.807, 0.7758, 0.7454, 1],
|
|
9
|
+
"intensity": 1
|
|
10
|
+
}
|
|
11
|
+
},
|
|
5
12
|
"resources": {},
|
|
6
13
|
"nodes": [
|
|
7
14
|
{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@iwsdk/create",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0-rc.0",
|
|
4
4
|
"description": "Interactive CLI to scaffold Immersive Web SDK starter apps",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|
|
@@ -37,7 +37,8 @@
|
|
|
37
37
|
"cross-spawn": "^7.0.6",
|
|
38
38
|
"ora": "^8.2.0",
|
|
39
39
|
"prompts": "^2.4.2",
|
|
40
|
-
"semver": "^7.6.3"
|
|
40
|
+
"semver": "^7.6.3",
|
|
41
|
+
"yaml": "2.8.3"
|
|
41
42
|
},
|
|
42
43
|
"devDependencies": {
|
|
43
44
|
"@types/cross-spawn": "^6.0.6",
|
|
@@ -45,17 +46,17 @@
|
|
|
45
46
|
"@types/semver": "^7.5.8",
|
|
46
47
|
"typescript": "^5.8.3",
|
|
47
48
|
"vitest": "^4.1.10",
|
|
48
|
-
"@iwsdk/
|
|
49
|
-
"@iwsdk/scene-composition": "0.
|
|
50
|
-
"@iwsdk/
|
|
49
|
+
"@iwsdk/cli": "1.0.0-rc.0",
|
|
50
|
+
"@iwsdk/scene-composition": "1.0.0-rc.0",
|
|
51
|
+
"@iwsdk/core": "1.0.0-rc.0"
|
|
51
52
|
},
|
|
52
53
|
"scripts": {
|
|
53
54
|
"prebuild": "node scripts/gen-version.cjs && node scripts/build-template.mjs",
|
|
54
55
|
"build": "rollup -c",
|
|
55
|
-
"dev": "
|
|
56
|
+
"dev": "npm run --silent build && node dist/cli.js",
|
|
56
57
|
"watch": "rollup -c --watch",
|
|
57
58
|
"clean": "rm -rf dist",
|
|
58
|
-
"test": "
|
|
59
|
+
"test": "npm --prefix ../scene-composition run build && npm --prefix ../cli run build && npm run build && vitest run",
|
|
59
60
|
"test:watch": "vitest",
|
|
60
61
|
"test:coverage": "vitest run --coverage",
|
|
61
62
|
"verify:release-ready": "node scripts/verify-release-ready.mjs"
|
|
@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os';
|
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { promisify } from 'node:util';
|
|
14
|
+
import { parse } from 'yaml';
|
|
14
15
|
|
|
15
16
|
const execFileAsync = promisify(execFile);
|
|
16
17
|
|
|
@@ -45,6 +46,30 @@ try {
|
|
|
45
46
|
const packageJson = JSON.parse(
|
|
46
47
|
await readFile(path.join(appRoot, 'package.json'), 'utf8'),
|
|
47
48
|
);
|
|
49
|
+
const pnpmWorkspace = parse(
|
|
50
|
+
await readFile(path.join(appRoot, 'pnpm-workspace.yaml'), 'utf8'),
|
|
51
|
+
);
|
|
52
|
+
if (
|
|
53
|
+
packageJson.overrides?.sharp !== '0.35.4' ||
|
|
54
|
+
packageJson.overrides?.three !== 'npm:super-three@0.181.0'
|
|
55
|
+
) {
|
|
56
|
+
blockers.push(
|
|
57
|
+
'generated package.json is missing the npm Sharp/Three overrides',
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
if (
|
|
61
|
+
pnpmWorkspace.packages?.length !== 1 ||
|
|
62
|
+
pnpmWorkspace.packages[0] !== '.' ||
|
|
63
|
+
pnpmWorkspace.overrides?.sharp !== '0.35.4' ||
|
|
64
|
+
pnpmWorkspace.overrides?.three !== 'npm:super-three@0.181.0' ||
|
|
65
|
+
pnpmWorkspace.allowBuilds?.sharp !== true ||
|
|
66
|
+
pnpmWorkspace.allowBuilds?.['@meta-quest/metavr'] !== false ||
|
|
67
|
+
pnpmWorkspace.allowBuilds?.['onnxruntime-node'] !== false
|
|
68
|
+
) {
|
|
69
|
+
blockers.push(
|
|
70
|
+
'generated pnpm-workspace.yaml is missing the pnpm 10/11 override and build policy',
|
|
71
|
+
);
|
|
72
|
+
}
|
|
48
73
|
if (
|
|
49
74
|
packageJson.dependencies?.['@iwsdk/example-assets'] != null ||
|
|
50
75
|
packageJson.devDependencies?.['@iwsdk/example-assets'] != null
|