@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.
Files changed (107) hide show
  1. package/dist/cli.js +7223 -215
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
  82. package/package.json +8 -7
  83. package/scripts/verify-release-ready.mjs +25 -0
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  89. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  94. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  100. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  105. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  106. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  107. /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.