@iwsdk/create 0.5.3 → 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/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
|
@@ -1,101 +0,0 @@
|
|
|
1
|
-
# Phase 2 Playbook — Design Deck & Concept Art
|
|
2
|
-
|
|
3
|
-
Make the spec visible. The developer should be able to _look_ at the game
|
|
4
|
-
before any code exists — and veto the look, the layout, or the loop cheaply.
|
|
5
|
-
|
|
6
|
-
Inputs: `design/GAME_SPEC.md`. Outputs: `design/deck.html`,
|
|
7
|
-
`design/concept/*.svg` (or generated images), `design/concept/layout.svg`.
|
|
8
|
-
|
|
9
|
-
## Capability Ladder (from Phase 0 probe)
|
|
10
|
-
|
|
11
|
-
| Capability found | Concept art | Deck presentation |
|
|
12
|
-
| -------------------------- | ------------------------------ | ---------------------------------- |
|
|
13
|
-
| Image-generation tool | generate key art + mood images | embed images in deck |
|
|
14
|
-
| None (default) | hand-authored SVG | self-contained HTML file |
|
|
15
|
-
| HTML artifact/preview tool | — | publish deck for viewing |
|
|
16
|
-
| Terminal only | — | give file path + per-slide summary |
|
|
17
|
-
|
|
18
|
-
Never block on a missing capability — degrade and note it in `PIPELINE.md`.
|
|
19
|
-
|
|
20
|
-
## Deck: `design/deck.html`
|
|
21
|
-
|
|
22
|
-
Self-contained single file: inline CSS, no external fonts/scripts/CDNs, works
|
|
23
|
-
from `file://`. One `<section class="slide">` per slide, 16:9 layout,
|
|
24
|
-
arrow-key + click navigation via a small inline script, slide counter.
|
|
25
|
-
Dark background with the game's palette as accents (pull actual hex values
|
|
26
|
-
from the spec's art direction — the deck should _feel_ like the game).
|
|
27
|
-
|
|
28
|
-
Slide outline (adapt, don't pad):
|
|
29
|
-
|
|
30
|
-
1. **Title** — name, one-line pitch, platform badge (VR/AR/browser).
|
|
31
|
-
2. **Fantasy & pillars** — the 3 pillars, each with a one-line consequence
|
|
32
|
-
("Pillar: instant fun → no menus before the first throw").
|
|
33
|
-
3. **Core loop** — a diagram (inline SVG boxes/arrows), 3–5 beats, timed.
|
|
34
|
-
4. **Mechanics** — one row per mechanic: verb, input, response, feedback.
|
|
35
|
-
5. **The space** — embed `concept/layout.svg`; call out dimensions, player
|
|
36
|
-
start, interaction zones.
|
|
37
|
-
6. **Key moment** — embed the hero concept piece; caption the emotional beat.
|
|
38
|
-
7. **Interaction model** — controls per platform (VR controllers / hands /
|
|
39
|
-
keyboard+mouse), one table.
|
|
40
|
-
8. **Art & audio direction** — palette swatches (actual hexes), material
|
|
41
|
-
notes, audio moment list.
|
|
42
|
-
9. **Scope** — MVP / target / stretch as three columns; success criteria.
|
|
43
|
-
10. **Tech snapshot** — one slide only: session mode, feature flags,
|
|
44
|
-
known-custom systems (from spec; refined in Phase 3).
|
|
45
|
-
|
|
46
|
-
## Concept Art: hand-authored SVG that doesn't look programmer-made
|
|
47
|
-
|
|
48
|
-
SVG is the reliable fallback and can look genuinely good if you treat it as
|
|
49
|
-
illustration, not as a diagram:
|
|
50
|
-
|
|
51
|
-
- **Compose in layers**: sky/background gradient → far silhouettes → mid
|
|
52
|
-
shapes → subject → foreground accents → lighting effects.
|
|
53
|
-
- **Use the palette**: define 5–7 colors in `<defs>` as gradients; reuse
|
|
54
|
-
them everywhere. Consistent palette reads as intentional art.
|
|
55
|
-
- **Light**: one light direction; add a `radialGradient` glow, rim-light
|
|
56
|
-
strokes on the subject, and soft shadow ellipses under objects.
|
|
57
|
-
- **Atmosphere**: layered opacity (fog planes at 10–30%), stars/particles as
|
|
58
|
-
small circles with varying opacity, vignette via an inset radial gradient.
|
|
59
|
-
- **Silhouette over detail**: shapes with strong outlines beat fussy detail;
|
|
60
|
-
10–40 elements per piece is plenty.
|
|
61
|
-
- 1600×900 viewBox for scenes; embed via `<img>` or inline in the deck.
|
|
62
|
-
|
|
63
|
-
Standard set (2–4 pieces):
|
|
64
|
-
|
|
65
|
-
- `concept/key-moment.svg` — the hero shot: mid-action, player POV or
|
|
66
|
-
three-quarter view of the climax beat.
|
|
67
|
-
- `concept/environment.svg` — the space at rest; establishes mood/palette.
|
|
68
|
-
- `concept/ui-mock.svg` — main panel(s) at rough proportions with real
|
|
69
|
-
label text (this seeds the `.uikitml` work later).
|
|
70
|
-
|
|
71
|
-
## Layout Diagram: `design/concept/layout.svg`
|
|
72
|
-
|
|
73
|
-
Top-down, **meters as first-class**: draw a scale bar; label distances.
|
|
74
|
-
Include: play-space boundary, player start + facing arrow, every interactive
|
|
75
|
-
object (labeled with mechanic #), UI panel positions + heights, locomotion
|
|
76
|
-
destinations if any. XR is real scale — tables are ~0.75 m, standing eye
|
|
77
|
-
height ~1.6 m, comfortable reach ~0.6 m, comfortable UI distance 1.5–2.5 m.
|
|
78
|
-
This diagram becomes the entity placement table in Phase 4, so positions
|
|
79
|
-
drawn here should already be plausible `[x, y, z]` values.
|
|
80
|
-
|
|
81
|
-
## Sub-agent briefs (when fanning out)
|
|
82
|
-
|
|
83
|
-
Give each agent: the spec path, this file's path, the exact output path(s),
|
|
84
|
-
and "return a one-paragraph summary; the file is the deliverable". Deck,
|
|
85
|
-
concept set, and layout are independent — run them in parallel. Review all
|
|
86
|
-
outputs yourself against the spec before presenting: palette consistency,
|
|
87
|
-
mechanic names matching the spec, no placeholder lorem text.
|
|
88
|
-
|
|
89
|
-
## Presenting
|
|
90
|
-
|
|
91
|
-
- Artifact/preview tool available → publish the deck; link concept pieces.
|
|
92
|
-
If the tool wraps content in its own HTML skeleton (some artifact tools
|
|
93
|
-
do), keep `deck.html` standalone on disk and strip the
|
|
94
|
-
`<!doctype>/<html>/<head>/<body>` wrapper only in the published copy.
|
|
95
|
-
- Remote/cloud harness with a file-send mechanism → send `design/deck.html`
|
|
96
|
-
and the concept pieces to the user directly (rendered when supported).
|
|
97
|
-
- Otherwise → list file paths with one-line descriptions and tell the user
|
|
98
|
-
how to open them (`open design/deck.html` / drag into a browser).
|
|
99
|
-
- Interactive mode → ask 2–3 pointed reaction questions (look right? layout
|
|
100
|
-
right? anything to cut?). Autonomous → proceed; note in PIPELINE.md that
|
|
101
|
-
design is unreviewed.
|
|
@@ -1,176 +0,0 @@
|
|
|
1
|
-
# Phase 3 Playbook — Grounding the Spec to IWSDK
|
|
2
|
-
|
|
3
|
-
Every mechanic in `design/GAME_SPEC.md` gets classified before any code:
|
|
4
|
-
|
|
5
|
-
- **BUILT-IN** — a component/system ships in IWSDK; we just attach/configure.
|
|
6
|
-
- **CONFIGURE** — a feature flag or config object in `World.create` (plus
|
|
7
|
-
prerequisites, e.g. locomotion requires collision geometry).
|
|
8
|
-
- **CUSTOM** — needs a new component/system; sketch its queries and priority.
|
|
9
|
-
|
|
10
|
-
The output is `design/TECH_PLAN.md`. The audit rule: re-check every CUSTOM
|
|
11
|
-
item against the reinvention-risk table in `api-reference.md` — an agent
|
|
12
|
-
rebuilding a built-in (raycasting, grab logic, sky domes, teleport arcs,
|
|
13
|
-
spatial audio) is this pipeline's most common and most expensive failure.
|
|
14
|
-
|
|
15
|
-
## Source-of-truth ladder
|
|
16
|
-
|
|
17
|
-
1. **`iwsdk reference` CLI** (semantic search over the actual SDK source) —
|
|
18
|
-
best for "does X exist / how is Y used".
|
|
19
|
-
2. **`references/api-reference.md`** (ships with this skill) — curated
|
|
20
|
-
patterns, enums, gotchas; always available.
|
|
21
|
-
3. **Installed source** — `node_modules/@iwsdk/core/dist/**/*.d.ts` (grep
|
|
22
|
-
recursively — the dist root only has a re-export barrel; the real
|
|
23
|
-
declarations live in subdirectories like `dist/grab/*.d.ts`).
|
|
24
|
-
4. **Docs site** — https://iwsdk.dev (guides + concepts; also `llms.txt`).
|
|
25
|
-
|
|
26
|
-
Trust order for _signatures_: 3 > 1 > 2 > 4. Trust order for _patterns and
|
|
27
|
-
gotchas_: 2 > 1 > 4.
|
|
28
|
-
|
|
29
|
-
**Version drift is real**: curated docs (rung 2, plus the project CLAUDE.md)
|
|
30
|
-
may describe APIs newer or older than the installed package. Example: docs
|
|
31
|
-
describing `GrabSystem.forceRelease()` while the installed 0.4.2 has no such
|
|
32
|
-
method, and `entity.setValue()` throwing on vector fields in elics 3.4.x
|
|
33
|
-
while older docs show `setValue(Transform, 'position', [...])`. For every
|
|
34
|
-
API your plan depends on, confirm the signature at rung 3 (installed
|
|
35
|
-
`.d.ts`) or rung 1 before writing it into TECH_PLAN.
|
|
36
|
-
|
|
37
|
-
## Reference CLI protocol
|
|
38
|
-
|
|
39
|
-
Run from **inside the app directory** (the CLI resolves the nearest folder
|
|
40
|
-
with a `vite.config.*` and an `@iwsdk/*` dependency — it fails at a monorepo
|
|
41
|
-
root or empty dir). The package `@iwsdk/reference` must be installed
|
|
42
|
-
(generated apps include it; `npm i -D @iwsdk/reference` otherwise). Fresh
|
|
43
|
-
installed scaffolds perform the one-time ~210 MB corpus/model warmup during
|
|
44
|
-
creation; queries then run offline. `npx iwsdk reference status` tells you the
|
|
45
|
-
state. Run `npx iwsdk reference warmup` manually only for an older app, a
|
|
46
|
-
`--no-install` scaffold, or recovery from an interrupted initialization.
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
# Semantic search — start here for each mechanic
|
|
50
|
-
npx iwsdk reference search --input-json '{"query":"throw object with physics velocity","limit":5,"verbosity":1}'
|
|
51
|
-
|
|
52
|
-
# Exact API card once you have a name
|
|
53
|
-
npx iwsdk reference api --input-json '{"name":"PhysicsManipulation"}'
|
|
54
|
-
|
|
55
|
-
# Enumerate what exists (great first call of the phase — cache the output)
|
|
56
|
-
npx iwsdk reference components --input-json '{}'
|
|
57
|
-
npx iwsdk reference systems --input-json '{}'
|
|
58
|
-
|
|
59
|
-
# Real usage examples from the SDK/examples
|
|
60
|
-
npx iwsdk reference examples --input-json '{"api_name":"DistanceGrabbable"}'
|
|
61
|
-
|
|
62
|
-
# Who depends on / extends a thing
|
|
63
|
-
npx iwsdk reference dependents --input-json '{"api_name":"GrabSystem"}'
|
|
64
|
-
npx iwsdk reference relationship --input-json '{"type":"extends","target":"System"}'
|
|
65
|
-
|
|
66
|
-
# Pull exact source when the docs disagree
|
|
67
|
-
npx iwsdk reference file --input-json '{"file_path":"packages/core/src/grab/grab-system.ts","source":"iwsdk"}'
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
Tips: `verbosity` 0–3 controls how much code comes back (default 3 is
|
|
71
|
-
verbose — use 1 for surveys, 3 for the one API you're implementing against).
|
|
72
|
-
Output is a JSON envelope `{ok, data:{result:{results:[…]}}}`; parse stdout
|
|
73
|
-
only. The first query after warmup pays model-load latency (~10–30 s).
|
|
74
|
-
|
|
75
|
-
If reference is unavailable (no network / install failed): use ladder rungs
|
|
76
|
-
2–4 and say so in TECH_PLAN's risk list — grounding confidence is lower.
|
|
77
|
-
Known install failure: `@iwsdk/reference` depends on `onnxruntime-node`,
|
|
78
|
-
whose postinstall downloads CUDA binaries; behind restrictive proxies it
|
|
79
|
-
403s and kills `npm install`. Retry with
|
|
80
|
-
`npm_config_onnxruntime_node_install_cuda=skip npm install`.
|
|
81
|
-
|
|
82
|
-
## Domain → API starting points
|
|
83
|
-
|
|
84
|
-
Survey `components`/`systems` output first, then dig per domain. Common
|
|
85
|
-
mappings (details in `api-reference.md`):
|
|
86
|
-
|
|
87
|
-
| Spec language | Look at |
|
|
88
|
-
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
89
|
-
| pick up, hold, wield (near) | `OneHandGrabbable`, `TwoHandsGrabbable`, `grabbing` flag |
|
|
90
|
-
| pull from afar, force-grab | `DistanceGrabbable` + `MovementMode` |
|
|
91
|
-
| throw, bounce, stack, knock over | `physics` flag, `PhysicsBody`+`PhysicsShape`, `PhysicsManipulation` (impulses/velocity) |
|
|
92
|
-
| point, click, hover, poke | `Interactable` (+ `Hovered`/`Pressed` tags), built-in RayPointer |
|
|
93
|
-
| buttons, menus, score display | `spatialUI` flag, manifest `AssetType.UIKitML`, placed scene node + stable element IDs; `ScreenSpace` (intentional browser HUD); `Follower` (head-locked) |
|
|
94
|
-
| walk, teleport, turn, jump | `locomotion` flag (+ `browserControls` for keyboard), `LocomotionEnvironment` on collision geometry |
|
|
95
|
-
| sky, mood, lighting | `DomeGradient`/`DomeTexture` + `IBLGradient`/`IBLTexture` **on the level root** |
|
|
96
|
-
| sounds, music | `AudioSource` + `AudioUtils.play()`, `PlaybackMode` |
|
|
97
|
-
| spawn/despawn, levels | `createTransformEntity`, `LevelTag`/`LevelRoot`, `world.loadLevel()` |
|
|
98
|
-
| AR: real tables/walls | `sceneUnderstanding` flag, `XRPlane`/`XRMesh` |
|
|
99
|
-
| AR: place on surfaces | `environmentRaycast` flag, `EnvironmentRaycastTarget` + `RaycastSpace` |
|
|
100
|
-
| AR: hide behind real things | `DepthOccludable` (see the iwsdk-depth-occlusion skill) |
|
|
101
|
-
| camera feed, selfie, MR capture | `camera` flag, `CameraSource`, `CameraUtils` |
|
|
102
|
-
| game state, pause, score | signals in `world.globals`, system `config` signals |
|
|
103
|
-
|
|
104
|
-
## Levels & scenes note
|
|
105
|
-
|
|
106
|
-
Scenes can be **built in code** (manifest assets + `createTransformEntity`) or loaded
|
|
107
|
-
from native IWSDK scene JSON selected by `iwsdk.config.json`. Use scene JSON for static
|
|
108
|
-
composition and runtime code for procedural or state-dependent entities. Scene JSON is
|
|
109
|
-
authored source, not generated editor state: agents may edit files under
|
|
110
|
-
`public/scenes/` directly, while humans may use the managed workspace editor for
|
|
111
|
-
hierarchy, transforms, components, and assets. Validate and render through
|
|
112
|
-
`scene render-file`, then use `scene open` for live editor collaboration.
|
|
113
|
-
|
|
114
|
-
## TECH_PLAN.md template
|
|
115
|
-
|
|
116
|
-
```markdown
|
|
117
|
-
# <Title> — Tech Plan
|
|
118
|
-
|
|
119
|
-
## iwsdk.config.json world block (decided)
|
|
120
|
-
|
|
121
|
-
\`\`\`jsonc
|
|
122
|
-
{
|
|
123
|
-
"world": {
|
|
124
|
-
"xr": { "mode": "vr", "offer": "once" },
|
|
125
|
-
"features": { "physics": true, "grabbing": true, "locomotion": false }
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
\`\`\`
|
|
129
|
-
Prerequisite checks: <locomotion→collision geometry? spatialUI→ui configs? …>
|
|
130
|
-
|
|
131
|
-
## Mechanics grounding
|
|
132
|
-
|
|
133
|
-
| Mechanic | Class | IWSDK pieces | Custom work | Risk |
|
|
134
|
-
| ------------- | --------------- | ------------------------------------ | ----------------------------------------- | --------------------- |
|
|
135
|
-
| M1 throw ball | BUILT-IN+CUSTOM | DistanceGrabbable, PhysicsBody/Shape | ThrowVelocitySystem (velocity on release) | release-velocity feel |
|
|
136
|
-
|
|
137
|
-
## Custom systems
|
|
138
|
-
|
|
139
|
-
### <SystemName> (priority <n> — band <input|sim|sync|ui>)
|
|
140
|
-
|
|
141
|
-
- Queries: `{ name: { required: [A, B], where: [...] } }`
|
|
142
|
-
- Reacts to: <qualify/disqualify/signal/frame>
|
|
143
|
-
- Writes: <components/signals>
|
|
144
|
-
- Sketch: <3–6 lines>
|
|
145
|
-
|
|
146
|
-
## Custom components
|
|
147
|
-
|
|
148
|
-
| Component | Fields (Type, default) | On which entities |
|
|
149
|
-
|
|
150
|
-
## Asset manifest
|
|
151
|
-
|
|
152
|
-
| Asset | Type | Source (code-built / user file / to-source) | Path |
|
|
153
|
-
|
|
154
|
-
## Globals & signals
|
|
155
|
-
|
|
156
|
-
| Key | Type | Writers | Readers |
|
|
157
|
-
|
|
158
|
-
## Risks & mitigations
|
|
159
|
-
|
|
160
|
-
| Risk | Impact | Mitigation |
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
## Fan-out guidance
|
|
164
|
-
|
|
165
|
-
Preconditions: reference warmup must already be **complete** before fanning
|
|
166
|
-
out (parallel agents must not each trigger a concurrent warmup or the
|
|
167
|
-
10–30 s model load; run one cheap query first to pay the load once).
|
|
168
|
-
|
|
169
|
-
One research agent per domain actually present in the spec. Each gets: spec
|
|
170
|
-
path, this file's path, the **absolute app-root path** (all `npx iwsdk`
|
|
171
|
-
commands run from there — sub-agent working directories often reset between
|
|
172
|
-
calls), its domain, and the instruction to _return only_ filled table rows +
|
|
173
|
-
custom-system sketches + citations (file paths / CLI output it based claims
|
|
174
|
-
on). Merge, dedupe (several domains will touch
|
|
175
|
-
`Interactable`), then do the reinvention audit yourself with
|
|
176
|
-
`api-reference.md` open.
|
|
@@ -1,156 +0,0 @@
|
|
|
1
|
-
# Phase 1 Playbook — Ideation
|
|
2
|
-
|
|
3
|
-
Turn an idea into `design/GAME_SPEC.md`. The spec is the contract for every
|
|
4
|
-
later phase: design renders it, grounding maps it, milestones implement it,
|
|
5
|
-
verification asserts it. Vague spec = expensive rework.
|
|
6
|
-
|
|
7
|
-
## How to Ask
|
|
8
|
-
|
|
9
|
-
- **Batch** 3–4 questions per round; never one-at-a-time drip. Structured
|
|
10
|
-
question tools typically cap a call at 4 questions with 2–4 options each
|
|
11
|
-
(AskUserQuestion allows at most 4) — split an oversized round into two
|
|
12
|
-
consecutive calls rather than dropping questions.
|
|
13
|
-
- Every question offers 2–4 **opinionated options** with a recommended
|
|
14
|
-
default and one-line trade-offs. Developers react better than they invent.
|
|
15
|
-
- Use the harness's structured question tool (e.g. AskUserQuestion) when
|
|
16
|
-
available; otherwise a compact markdown list.
|
|
17
|
-
- 2 rounds is the target, 3 the max. If answers open a genuinely new axis
|
|
18
|
-
(e.g. "actually it's multiplayer"), that justifies a round; taste
|
|
19
|
-
refinements do not.
|
|
20
|
-
- **Autonomous mode:** answer every question yourself with the most
|
|
21
|
-
defensible default, mark each `[ASSUMED]`, and add a "Questions I would
|
|
22
|
-
have asked" appendix to the spec so the developer can revisit them later.
|
|
23
|
-
|
|
24
|
-
## Question Bank
|
|
25
|
-
|
|
26
|
-
Pick what's undetermined by the user's idea — skip what's already clear.
|
|
27
|
-
|
|
28
|
-
**Platform & mode (round 1, always)**
|
|
29
|
-
|
|
30
|
-
- VR (`ImmersiveVR`), AR/passthrough (`ImmersiveAR`), browser-first
|
|
31
|
-
(`xr: false`), or dual (XR + browser fallback)? Dual costs extra input
|
|
32
|
-
work but makes the app testable anywhere.
|
|
33
|
-
- Target device (Quest-class headset? phone AR? desktop browser?).
|
|
34
|
-
- Play space: seated / standing / room-scale? → drives locomotion + comfort.
|
|
35
|
-
|
|
36
|
-
**Core loop (round 1, always)**
|
|
37
|
-
|
|
38
|
-
- What does the player _do_ every 30 seconds? (verbs: grab, throw, aim,
|
|
39
|
-
place, dodge, build, inspect…)
|
|
40
|
-
- What's the objective and the failure state? Score, timer, lives, zen?
|
|
41
|
-
- Session length target (2-minute toy vs 20-minute session).
|
|
42
|
-
|
|
43
|
-
**Mechanics detail (round 2)**
|
|
44
|
-
|
|
45
|
-
- For each verb: which hand(s)? near grab or distance grab? snap or free?
|
|
46
|
-
- Physics-driven or scripted outcomes? (bouncing/stacking/throwing → physics)
|
|
47
|
-
- Movement: none / teleport / smooth slide / both? Jumping?
|
|
48
|
-
- Win/lose feedback: what does the player see/hear on success and failure?
|
|
49
|
-
|
|
50
|
-
**Presentation (round 2)**
|
|
51
|
-
|
|
52
|
-
- Art direction: 2–3 adjectives + a palette hint (e.g. "neon arcade night",
|
|
53
|
-
"warm wooden workshop"). Realistic assets need sourcing; stylized
|
|
54
|
-
primitives can be built in code.
|
|
55
|
-
- Environment: skybox gradient? textured dome? modeled room?
|
|
56
|
-
- Audio moments: ambient loop? per-interaction SFX? music?
|
|
57
|
-
|
|
58
|
-
**Scope & success (round 2, always)**
|
|
59
|
-
|
|
60
|
-
- MVP in one sentence — the smallest thing that demonstrates the fantasy.
|
|
61
|
-
- Stretch list — what's explicitly _not_ MVP.
|
|
62
|
-
- 3–6 success criteria, each observable at runtime (see below).
|
|
63
|
-
|
|
64
|
-
**AR-specific (when applicable)**
|
|
65
|
-
|
|
66
|
-
- Does virtual content interact with real surfaces (tables/walls/floor)?
|
|
67
|
-
- Placement: tap-to-place, controller ray, auto-anchor?
|
|
68
|
-
- Occlusion by real objects needed?
|
|
69
|
-
|
|
70
|
-
## Success Criteria Must Be Observable
|
|
71
|
-
|
|
72
|
-
Phase 6 will assert every criterion with the runtime CLI. Good criteria name
|
|
73
|
-
an action and a checkable outcome:
|
|
74
|
-
|
|
75
|
-
- ✅ "Grabbing a ball and releasing it toward the pins knocks at least one
|
|
76
|
-
pin over (pin rotation changes >45°)."
|
|
77
|
-
- ✅ "Score panel increments within 1s of a target being hit."
|
|
78
|
-
- ❌ "The game feels satisfying." (not assertable — turn it into proxies:
|
|
79
|
-
SFX plays on hit, hit target flashes, etc.)
|
|
80
|
-
|
|
81
|
-
## GAME_SPEC.md Template
|
|
82
|
-
|
|
83
|
-
```markdown
|
|
84
|
-
# <Title> — Game Spec
|
|
85
|
-
|
|
86
|
-
**Pitch.** <2–3 sentences: fantasy + loop + platform.>
|
|
87
|
-
|
|
88
|
-
**Pillars.** <3 bullets that arbitrate future trade-offs.>
|
|
89
|
-
|
|
90
|
-
## Platform & Mode
|
|
91
|
-
|
|
92
|
-
- Session: ImmersiveVR | ImmersiveAR | browser-first | dual (XR + browser)
|
|
93
|
-
- Device target: <…> · Play space: seated|standing|room-scale
|
|
94
|
-
- Comfort: <teleport-only / vignette / stationary — and why>
|
|
95
|
-
|
|
96
|
-
## Core Loop
|
|
97
|
-
|
|
98
|
-
<One paragraph: the 30-second loop. Then:>
|
|
99
|
-
|
|
100
|
-
1. <beat> → 2. <beat> → 3. <beat> → repeat/escalate.
|
|
101
|
-
|
|
102
|
-
## Mechanics
|
|
103
|
-
|
|
104
|
-
| # | Mechanic | Player verb | Notes |
|
|
105
|
-
| --- | -------- | ------------ | -------------------------- |
|
|
106
|
-
| M1 | <name> | grab/throw/… | <hand, distance, physics?> |
|
|
107
|
-
|
|
108
|
-
## Space & Locomotion
|
|
109
|
-
|
|
110
|
-
- World size: <e.g. 4×4 m room> · Locomotion: none|teleport|slide|both
|
|
111
|
-
- Collision geometry source: <floor plane / modeled room / native scene document>
|
|
112
|
-
|
|
113
|
-
## UI Surfaces
|
|
114
|
-
|
|
115
|
-
- <e.g. floating score panel (world-space, follows player), main menu panel,
|
|
116
|
-
browser-mode HUD>
|
|
117
|
-
|
|
118
|
-
## Audio
|
|
119
|
-
|
|
120
|
-
- <ambient loop? SFX list keyed to mechanics: grab, hit, win…>
|
|
121
|
-
|
|
122
|
-
## Art Direction
|
|
123
|
-
|
|
124
|
-
- <adjectives, palette, asset approach: code-built primitives / GLTF assets>
|
|
125
|
-
|
|
126
|
-
## Scope
|
|
127
|
-
|
|
128
|
-
- **MVP:** <one sentence + the mechanics included>
|
|
129
|
-
- **Target:** <MVP + …>
|
|
130
|
-
- **Stretch (non-goals for now):** <list>
|
|
131
|
-
|
|
132
|
-
## Success Criteria (asserted in Phase 6)
|
|
133
|
-
|
|
134
|
-
| # | Criterion (observable) | How it will be checked |
|
|
135
|
-
| --- | ---------------------- | ----------------------------------- |
|
|
136
|
-
| S1 | <…> | ecs diff / screenshot / log pattern |
|
|
137
|
-
|
|
138
|
-
## Decisions & Assumptions
|
|
139
|
-
|
|
140
|
-
| Decision | Chosen | Why | Source |
|
|
141
|
-
| -------- | -------- | -------- | ---------------- |
|
|
142
|
-
| <axis> | <choice> | <reason> | user / [ASSUMED] |
|
|
143
|
-
|
|
144
|
-
## Questions I would have asked (autonomous mode only)
|
|
145
|
-
|
|
146
|
-
- <question — chosen default — what would change if answered differently>
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
## Sizing Guidance
|
|
150
|
-
|
|
151
|
-
Right-size the MVP to what one agent session can build _and verify_: 2–4
|
|
152
|
-
mechanics, 1 environment, 1–2 UI panels, 3–8 custom components, 2–5 custom
|
|
153
|
-
systems. Physics, grabbing, spatial UI, audio, and environment theming are
|
|
154
|
-
nearly free (built-ins); multiplayer, persistence, custom shaders, and
|
|
155
|
-
skeletal animation are expensive (custom). If the idea is big, put the
|
|
156
|
-
expensive parts in Stretch and say so in the pitch summary.
|
|
@@ -1,199 +0,0 @@
|
|
|
1
|
-
# Phases 5–7 Playbook — Runtime Verification
|
|
2
|
-
|
|
3
|
-
Everything here uses the `iwsdk` CLI (works in every harness). MCP
|
|
4
|
-
equivalents exist for every command but several names differ: `xr enter` =
|
|
5
|
-
`xr_accept_session`, `xr status` = `xr_get_session_status`, `ecs find` =
|
|
6
|
-
`ecs_find_entities`, `ecs query` = `ecs_query_entity`, `browser logs` =
|
|
7
|
-
`browser_get_console_logs`, `browser reload` = `browser_reload_page`,
|
|
8
|
-
`scene state` = `scene_get_state`, and `scene render-file` =
|
|
9
|
-
`scene_render_file`; the rest map 1:1
|
|
10
|
-
(`xr_select` → `xr select`, `ecs_pause` → `ecs pause`, …). Use MCP tools only
|
|
11
|
-
if your harness clearly has them connected. The sibling `iwsdk-grab` /
|
|
12
|
-
`iwsdk-ray` / `iwsdk-debug` / `iwsdk-ui` skills cover the same runtime
|
|
13
|
-
operations as focused per-interaction recipes — consistent with this file.
|
|
14
|
-
|
|
15
|
-
**Ground rules.** Run every `npx iwsdk …` from **inside the app directory**
|
|
16
|
-
(the app must depend on `@iwsdk/cli`; a bare `npx iwsdk` elsewhere resolves
|
|
17
|
-
to an unrelated npm package). One CLI call per shell command — no `&&`
|
|
18
|
-
chains between CLI calls; use separate `sleep N` calls for waits. Every
|
|
19
|
-
command prints a JSON envelope `{ok, data|error}` on stdout — parse it and
|
|
20
|
-
check the assertion **before** the next command. Add `--timeout 20000` to
|
|
21
|
-
slow ops (reload, xr enter, animate-to, screenshot).
|
|
22
|
-
|
|
23
|
-
## The Standard Loop
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
npx tsc --noEmit # 0. types clean first — always
|
|
27
|
-
npx iwsdk dev status # 1. already running? if state.running AND
|
|
28
|
-
# state.browserCommandReady are true,
|
|
29
|
-
# REUSE it — never start a second server
|
|
30
|
-
npx iwsdk dev up --timeout 60000 # 2. only if not running: detached daemon;
|
|
31
|
-
# returns once the browser is command-ready.
|
|
32
|
-
# (`npm run dev` = `iwsdk dev up --open
|
|
33
|
-
# --foreground` — never returns; use it only
|
|
34
|
-
# where your harness manages background
|
|
35
|
-
# processes. NEVER a bare '&'.)
|
|
36
|
-
npx iwsdk ecs systems # 3. connectivity: returns system list
|
|
37
|
-
npx iwsdk browser reload --timeout 20000 # 4. fresh page state
|
|
38
|
-
sleep 3
|
|
39
|
-
npx iwsdk browser screenshot --output-file design/verify/base.png --timeout 20000
|
|
40
|
-
# 5. runtime renders? (not black/empty).
|
|
41
|
-
# Browser screenshots are runtime-only and
|
|
42
|
-
# auto-switch away from editor view. Without
|
|
43
|
-
# --output-file the PNG lands in the system
|
|
44
|
-
# temp dir (path in the JSON envelope)
|
|
45
|
-
npx iwsdk xr enter --timeout 20000 # 6. enter emulated XR session
|
|
46
|
-
sleep 2
|
|
47
|
-
npx iwsdk browser logs --input-json '{"count":30}'
|
|
48
|
-
# 7. console clean — scan ALL levels (a
|
|
49
|
-
# level filter can miss important errors);
|
|
50
|
-
# fail the gate on any error-looking line
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
If `dev up` times out, poll yourself: run `npx iwsdk dev status`, `sleep 5`,
|
|
54
|
-
repeat up to ~60 s (a shell `until` loop around the _single_ CLI call is fine
|
|
55
|
-
— the no-chaining rule is about chaining different CLI calls), then inspect
|
|
56
|
-
`npx iwsdk dev logs --tail 100`.
|
|
57
|
-
|
|
58
|
-
Then per-scenario: discover → simulate → assert. Finish with
|
|
59
|
-
`npx iwsdk dev down` when done for the session.
|
|
60
|
-
|
|
61
|
-
The dev server owns one managed headed Playwright Chromium window, with IWER enabled
|
|
62
|
-
for XR starters. It starts with the dev server; do not launch a second browser or turn
|
|
63
|
-
Vite's independent `server.open` back on. Use `scene screenshot` / `scene render-file`
|
|
64
|
-
for editor evidence and `browser screenshot` for the application runtime.
|
|
65
|
-
|
|
66
|
-
## Discover (after every reload — entity indices are NOT stable)
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
npx iwsdk ecs find --input-json '{"withComponents":["OneHandGrabbable"]}'
|
|
70
|
-
npx iwsdk ecs query --input-json '{"entityIndex":3}' # full entity dump
|
|
71
|
-
npx iwsdk scene state --raw # active scene/runtime state
|
|
72
|
-
npx iwsdk ecs components # component registry
|
|
73
|
-
npx iwsdk ecs systems # system registry
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
## Simulate input (XR emulation cheat sheet)
|
|
77
|
-
|
|
78
|
-
Devices: `headset`, `controller-left`, `controller-right`, `hand-left`,
|
|
79
|
-
`hand-right`.
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
# Aim/move devices
|
|
83
|
-
npx iwsdk xr set-transform --input-json '{"device":"headset","position":{"x":0,"y":1.6,"z":0}}'
|
|
84
|
-
npx iwsdk xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1,"z":-2}}'
|
|
85
|
-
npx iwsdk xr animate-to --input-json '{"device":"controller-right","position":{"x":0.2,"y":1.1,"z":-0.4},"duration":0.5}' --timeout 20000
|
|
86
|
-
|
|
87
|
-
# Buttons — WRONG BUTTON FAILS SILENTLY, know which mechanic uses which:
|
|
88
|
-
npx iwsdk xr set-select-value --input-json '{"device":"controller-right","value":1}' # press TRIGGER — UI pointerdown or distance-grab engage
|
|
89
|
-
npx iwsdk xr set-select-value --input-json '{"device":"controller-right","value":0}' # release TRIGGER — UI pointerup or distance-grab release
|
|
90
|
-
npx iwsdk xr set-gamepad-state --input-json '{"device":"controller-right","buttons":[{"index":1,"value":1}]}' # SQUEEZE — near grab (one/two-hand)
|
|
91
|
-
npx iwsdk xr set-gamepad-state --input-json '{"device":"controller-right","buttons":[{"index":3,"value":1}]}' # A/X button (jump default)
|
|
92
|
-
|
|
93
|
-
# Thumbsticks (axes index 0=X, 1=Y):
|
|
94
|
-
npx iwsdk xr set-gamepad-state --input-json '{"device":"controller-left","axes":[{"index":1,"value":-1}]}' # slide forward (0 to stop)
|
|
95
|
-
npx iwsdk xr set-gamepad-state --input-json '{"device":"controller-right","axes":[{"index":0,"value":1}]}' # snap turn — EDGE-TRIGGERED: return to 0 before turning again
|
|
96
|
-
npx iwsdk xr set-gamepad-state --input-json '{"device":"controller-right","axes":[{"index":1,"value":1}]}' # hold then release to 0 = teleport
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
Synthetic gamepad indices for `set-gamepad-state`: 0=trigger, 1=squeeze,
|
|
100
|
-
2=thumbstick-press, 3=A/X, 4=B/Y, 5=thumbrest. (App code uses
|
|
101
|
-
`InputComponent` enums; these raw indices are only for the emulator CLI.)
|
|
102
|
-
|
|
103
|
-
## Assert
|
|
104
|
-
|
|
105
|
-
Pick the right instrument per behavior:
|
|
106
|
-
|
|
107
|
-
| Behavior | Assertion |
|
|
108
|
-
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
-
| hover/click state | `ecs query` for `Hovered`/`Pressed` on the entity |
|
|
110
|
-
| object moved/scaled/spawned | `ecs snapshot` (label before) → act → `ecs snapshot` (after) → `ecs diff` |
|
|
111
|
-
| physics settled/fell/collided | snapshot/diff on Transform position, or pause+step deterministically |
|
|
112
|
-
| **locomotion** (player moved) | **screenshots before/after** — the XR origin moves, headset transform stays constant; never assert on headset transform |
|
|
113
|
-
| **near-field grab** | snapshot/diff — `Hovered`/`Pressed` are NOT applied on near grabs |
|
|
114
|
-
| UI reacted | `browser logs` with a pattern: instrument handlers with distinctive `console.log('[GAME] score=…')` and assert `{"pattern":"\\[GAME\\]"}` |
|
|
115
|
-
| game logic over time | `ecs pause` → `ecs step --input-json '{"count":N}'` → query → `ecs resume` |
|
|
116
|
-
| looks right | `browser screenshot` and actually look at the image |
|
|
117
|
-
|
|
118
|
-
```bash
|
|
119
|
-
npx iwsdk ecs snapshot --input-json '{"label":"before"}'
|
|
120
|
-
# …act…
|
|
121
|
-
npx iwsdk ecs snapshot --input-json '{"label":"after"}'
|
|
122
|
-
npx iwsdk ecs diff --input-json '{"from":"before","to":"after"}'
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Only the two most recent snapshot labels are retained.
|
|
126
|
-
|
|
127
|
-
## Known traps
|
|
128
|
-
|
|
129
|
-
- Entity indices change on every reload — re-run `ecs find`; never reuse.
|
|
130
|
-
- JSON values must be real types: `true` not `"true"`, numbers not strings
|
|
131
|
-
(`ecs set-component` silently no-ops on wrong types).
|
|
132
|
-
- Trigger vs squeeze mix-ups produce _no error and no effect_ — check the
|
|
133
|
-
mechanic's grab type first (`DistanceGrabbable` → trigger/select-value;
|
|
134
|
-
`OneHandGrabbable`/`TwoHandsGrabbable` → squeeze button 1).
|
|
135
|
-
- Teleport is blocked while the ray hovers an `Interactable`.
|
|
136
|
-
- Snap turn re-fires only after the stick returns to 0.
|
|
137
|
-
- `--input-json` takes one single-quoted JSON argument; malformed JSON errors
|
|
138
|
-
out — build it with a heredoc if it contains quotes.
|
|
139
|
-
- UIKitML files live under `public/ui`, are registered in the asset manifest with
|
|
140
|
-
`AssetType.UIKitML`, and are parsed directly at runtime. Scene JSON references the
|
|
141
|
-
manifest asset ID; application code uses the placed scene node ID and element IDs.
|
|
142
|
-
- After deploying: verify the live HTML references the newly built hashed
|
|
143
|
-
assets (stale-dist deploys are the classic ship failure).
|
|
144
|
-
|
|
145
|
-
## Managed-runtime hardening
|
|
146
|
-
|
|
147
|
-
- Prefer `xr set-select-value` 1→0 when a test needs observable press and release
|
|
148
|
-
phases. Use `xr set-gamepad-state` for explicit raw gamepad buttons. Application UI
|
|
149
|
-
should use its normal `click` handlers unless the product itself needs lower-level
|
|
150
|
-
pointer phases.
|
|
151
|
-
- **Physics steps on the raw frame delta.** Reloads, screenshots, and
|
|
152
|
-
`ecs snapshot` (full-state serialize) stall the tab for hundreds of ms to
|
|
153
|
-
seconds; a single huge step tunnels thin/falling bodies and pops stacked
|
|
154
|
-
contacts. Don't run heavy CLI commands mid-interaction; snapshot between
|
|
155
|
-
scenarios, not during them. Build apps defensively (see
|
|
156
|
-
build-milestones.md runtime-hitch hardening defaults).
|
|
157
|
-
- **Parse the right payload path**: `browser logs` returns the entries under
|
|
158
|
-
`data.result` (a LIST of {level, message}); `browser screenshot` returns
|
|
159
|
-
`data.screenshotPath` directly under `data`. Shapes vary per command —
|
|
160
|
-
check one real response before scripting assertions.
|
|
161
|
-
- **Log-window noise**: `[IWSDK-MCP-TRACE]` lines flood small `count`
|
|
162
|
-
windows; use `count` 60–100 or a `pattern` filter for game logs.
|
|
163
|
-
- **Queries and screenshots disagreeing** (state changes you can't explain)
|
|
164
|
-
usually means **two browser tabs** are connected — the relay is
|
|
165
|
-
first-response-wins. Check `dev status` → `connectedClientCount`; if >1,
|
|
166
|
-
`npx iwsdk dev restart` to converge on one tab.
|
|
167
|
-
|
|
168
|
-
## Recovery ladder (runtime unresponsive / weird)
|
|
169
|
-
|
|
170
|
-
1. `npx iwsdk xr status` and `npx iwsdk dev status` — what state is it in?
|
|
171
|
-
2. `npx iwsdk browser logs` — crashed app code shows here.
|
|
172
|
-
3. `npx iwsdk browser reload --timeout 20000` — clears bad page state.
|
|
173
|
-
4. `npx iwsdk dev restart` — bad transport/server state.
|
|
174
|
-
5. Re-enter XR (`xr enter`) and re-discover entities after any of the above.
|
|
175
|
-
6. Dev server won't start: check `npx iwsdk dev logs --tail 100`; commonest
|
|
176
|
-
causes are a missing `dev:runtime` script, port conflict from an orphaned
|
|
177
|
-
server (`iwsdk dev down` in that app dir), or Playwright browser revision
|
|
178
|
-
mismatch (`npx playwright@<pinned> install chromium`).
|
|
179
|
-
|
|
180
|
-
## VERIFICATION.md format (Phase 6 output)
|
|
181
|
-
|
|
182
|
-
```markdown
|
|
183
|
-
# <Title> — Verification Report (<date>, commit <sha>)
|
|
184
|
-
|
|
185
|
-
| # | Success criterion | Result | Evidence |
|
|
186
|
-
| --- | ----------------- | ------ | ------------------------------------------ |
|
|
187
|
-
| S1 | throw knocks pins | PASS | diff: pin-3 rot Δ87°; design/verify/s1.png |
|
|
188
|
-
|
|
189
|
-
## Scenario transcripts
|
|
190
|
-
|
|
191
|
-
### S1
|
|
192
|
-
|
|
193
|
-
<the exact commands run + the assertion output snippets>
|
|
194
|
-
|
|
195
|
-
## Deferred / known gaps
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
Keep screenshots in `design/verify/`. A criterion without evidence is not a
|
|
199
|
-
PASS.
|