@iwsdk/create 0.4.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/README.md +103 -41
  2. package/dist/cli.js +1003 -3418
  3. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  9. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  10. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
  11. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
  12. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
  13. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
  14. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
  15. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
  16. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
  19. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  24. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  25. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
  27. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
  28. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
  29. package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
  30. package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
  31. package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
  32. package/dist/guidance/claude/.claude/settings.json +19 -0
  33. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
  34. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  35. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
  36. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
  43. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
  44. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
  45. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
  46. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
  47. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
  48. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
  49. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  50. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  53. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
  57. package/dist/guidance/claude/CLAUDE.md +142 -0
  58. package/dist/guidance/codex/.codex/config.toml +2 -0
  59. package/dist/guidance/common/AGENTS.md +151 -0
  60. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
  61. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
  62. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
  63. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
  64. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
  65. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
  66. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
  67. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
  68. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
  69. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
  70. package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
  71. package/dist/template/common/README.md +13 -0
  72. package/dist/template/common/gitignore.template +45 -0
  73. package/dist/template/common/index.html +16 -0
  74. package/dist/template/common/nvmrc.template +1 -0
  75. package/dist/template/common/public/audio/chime.mp3 +0 -0
  76. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
  77. package/dist/template/common/public/textures/webxr.png +0 -0
  78. package/dist/template/common/public/ui/welcome.uikitml +98 -0
  79. package/dist/template/common/src/assets.ts +54 -0
  80. package/dist/template/common/src/components.ts +11 -0
  81. package/dist/template/common/src/index.ts +19 -0
  82. package/dist/template/common/src/panel.ts +38 -0
  83. package/dist/template/common/src/robot-component.ts +10 -0
  84. package/dist/template/common/src/robot.ts +38 -0
  85. package/dist/template/common/src/vite-env.d.ts +2 -0
  86. package/dist/template/common/tsconfig.json +15 -0
  87. package/dist/template/common/vite.config.ts +27 -0
  88. package/dist/template/common-js/README.md +13 -0
  89. package/dist/template/common-js/gitignore.template +45 -0
  90. package/dist/template/common-js/index.html +16 -0
  91. package/dist/template/common-js/nvmrc.template +1 -0
  92. package/dist/template/common-js/public/audio/chime.mp3 +0 -0
  93. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
  94. package/dist/template/common-js/public/textures/webxr.png +0 -0
  95. package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
  96. package/dist/template/common-js/src/assets.js +45 -0
  97. package/dist/template/common-js/src/components.js +9 -0
  98. package/dist/template/common-js/src/index.js +14 -0
  99. package/dist/template/common-js/src/panel.js +31 -0
  100. package/dist/template/common-js/src/robot-component.js +8 -0
  101. package/dist/template/common-js/src/robot.js +37 -0
  102. package/dist/template/common-js/vite.config.js +25 -0
  103. package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
  104. package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
  105. package/package.json +23 -17
  106. package/scripts/verify-release-ready.mjs +76 -0
  107. package/LICENSE +0 -21
@@ -0,0 +1,241 @@
1
+ # Phases 4–5 Playbook — Architecture & Milestone Build
2
+
3
+ ## Scaffolding (new apps)
4
+
5
+ Use `@iwsdk/create` — never hand-roll project structure. Infer flags from the
6
+ TECH_PLAN, don't hardcode.
7
+
8
+ Flag menu (choose one per pair — this is NOT a runnable command):
9
+
10
+ ```text
11
+ --mode vr | --mode ar # XR apps; or --no-xr for browser-first
12
+ --physics | --no-physics
13
+ --grabbing | --no-grabbing
14
+ --locomotion | --no-locomotion
15
+ --scene-understanding | --no-scene-understanding # AR only
16
+ --yes # ALWAYS for agents — without it, interactive
17
+ # prompts hang AND the feature flags are ignored
18
+ ```
19
+
20
+ Runnable example (VR game, physics + grabbing, stationary):
21
+
22
+ ```bash
23
+ npx @iwsdk/create@latest bowling-vr --yes --mode vr --physics --grabbing --no-locomotion
24
+ ```
25
+
26
+ If `@latest` misbehaves, fall back to the version pinned by the project or the
27
+ current release documented on iwsdk.dev.
28
+
29
+ Notes:
30
+
31
+ - `--no-xr` scaffolds `xr: false` but does **not** wire browser locomotion,
32
+ mouselook, or browser grabbing — add `features.locomotion.browserControls`
33
+ and app-owned camera controls in code.
34
+ - Dual-runtime (VR + browser testable): scaffold `--mode vr`, then set
35
+ `xr: { offer: 'once' }`, `input: { canvasPointerEvents: true }`,
36
+ `locomotion: { browserControls: true }`.
37
+ - Generated apps come with: `npm run dev` (= `iwsdk dev up --open
38
+ --foreground`), a `dev:runtime` script (required by the CLI — never remove
39
+ it), the Vite dev plugin, starter src (`index.ts`, `panel.ts`, `robot.ts`),
40
+ `public/ui/welcome.uikitml`, and AI configs (CLAUDE.md, skills, MCP
41
+ adapters). Delete starter content you don't use (robot etc.) at M1, not M0
42
+ — M0 verifies the untouched baseline.
43
+ - Existing app instead of scaffold: write an "existing-app delta" section —
44
+ current feature flags vs needed, files to add/change.
45
+
46
+ ## Asset Strategy
47
+
48
+ In priority order:
49
+
50
+ 1. **Code-built primitives** (default for MVP): Box/Sphere/Cylinder/Cone/
51
+ Torus geometries + `MeshStandardMaterial` from `@iwsdk/core` — zero
52
+ sourcing risk, fine for stylized art directions. Compose "models" from
53
+ grouped primitives under one `createTransformEntity`.
54
+ 2. **Assets already in the project** (`public/gltf/…` from the starter, or
55
+ user-provided). List them in the manifest with paths.
56
+ 3. **Asset search tooling, if present** — if the environment has an asset
57
+ MCP (e.g. a `meta_assets_search`-style tool) or the user offers a source,
58
+ download GLB/GLTF into `public/gltf/<name>/` and record license/origin.
59
+ 4. **Ask the user** (interactive mode) for must-have hero assets.
60
+
61
+ Never invent asset paths; never reference files you haven't created or
62
+ verified. All runtime loading goes through `AssetManager` (manifest in
63
+ `World.create` for preload, `AssetManager.loadGLTF` for on-demand) — never
64
+ raw loaders. Audio: short mp3s; the starter ships `public/audio/chime.mp3`
65
+ you can reuse for MVP feedback.
66
+
67
+ ## ARCHITECTURE.md template
68
+
69
+ ```markdown
70
+ # <Title> — Architecture
71
+
72
+ ## Scaffold
73
+
74
+ Command: <exact @iwsdk/create line, or existing-app delta>
75
+
76
+ ## File tree (one system per file; no barrel index)
77
+
78
+ src/
79
+ index.ts # World.create + registrations + scene setup only
80
+ components/<x>.ts # createComponent defs (group related)
81
+ systems/<x>.ts # one system per file
82
+ public/ui/<panel>.uikitml
83
+ public/{gltf,audio,textures}/…
84
+
85
+ ## Components
86
+
87
+ | Component | Field | Type | Default | Notes |
88
+
89
+ ## Systems
90
+
91
+ | System | Priority | Queries | Purpose |
92
+ <band rule: 0–9 input · 10–19 simulation · 20–29 visual sync · 30+ UI/ambient>
93
+
94
+ ## Entity placement (from design/concept/layout.svg)
95
+
96
+ | Entity | Components | Position [x,y,z] | Notes |
97
+
98
+ ## Globals
99
+
100
+ | Key | Type | Purpose |
101
+
102
+ ## Milestones
103
+
104
+ ### M0 — scaffold renders
105
+
106
+ Demo: app serves; scene renders; XR session enters.
107
+ Assertions: screenshot non-black; `xr enter` ok; console clean.
108
+
109
+ ### M1 — <core mechanic vertical slice>
110
+
111
+ Demo: <observable behavior>
112
+ Assertions: <specific ecs/screenshot/log checks>
113
+
114
+ ### M2…Mn — <one mechanic or surface each>
115
+
116
+ ### M-final — all MVP success criteria pass (Phase 6 full run)
117
+ ```
118
+
119
+ Milestone rules: 3–6 milestones; each independently demoable; core-loop
120
+ mechanic first (riskiest feel-work earliest); UI and audio get their own
121
+ milestone unless trivial; every spec success criterion mapped to exactly one
122
+ milestone's assertions.
123
+
124
+ ## Runtime-hitch hardening defaults (build these in from M1)
125
+
126
+ The managed dev runtime steps physics on the raw frame delta. Reloads, screenshots,
127
+ debug snapshots, backgrounded windows, and CI can all hitch; a single multi-second
128
+ step tunnels thin colliders and pops stacked contacts. Defaults that avoid a day of
129
+ debugging:
130
+
131
+ - **Solid-block static colliders** (0.3 m+ thick), never thin plates; extend
132
+ the floor under/behind every play area as a catch surface; add invisible
133
+ containment walls so nothing rolls out of the world.
134
+ - **Spawn-gate dynamic bodies**: hold spawns until N consecutive stable
135
+ frames (e.g. 5 frames under 50 ms) so first steps can't tunnel them.
136
+ - **Physics-on-demand for precarious arrangements** (stacks, pyramids,
137
+ dominoes): keep them body-less until the moment gameplay needs them
138
+ knockable; re-park body-less on reset.
139
+ - **Self-healing bounds recovery**: a system that returns escaped dynamics
140
+ to their spawn poses.
141
+ - **Check physical support when translating design layouts**: a layout
142
+ drawn for looks (e.g. cans spaced wide apart) may leave upper items
143
+ unsupported — stacking needs contact (can spacing ≈ 2·radius).
144
+
145
+ ## The Milestone Loop (Phase 5)
146
+
147
+ For each milestone:
148
+
149
+ 1. **Brief** — restate demo criterion + assertions (from ARCHITECTURE.md).
150
+ 2. **Implement** — following `api-reference.md` best practices. Key habits:
151
+ imports from `@iwsdk/core` (never `three` for standard classes — one
152
+ Three instance only), `createTransformEntity` (never `scene.add`),
153
+ queries + qualify/disqualify subscriptions (never entity arrays), config
154
+ signals + `.peek()` in `update()`, `cleanupFuncs` for every subscription,
155
+ module-scope scratch vectors (no per-frame allocations).
156
+ 3. **Typecheck** — `npx tsc --noEmit`. Fix everything; zero-error baseline
157
+ makes later breakage attributable.
158
+ 4. **Verify** — run this milestone's assertions live (`verification.md` has
159
+ the loop). First milestone verifies the _scaffold before edits_.
160
+ 5. **Record** — Milestone Log entry in `design/PIPELINE.md` with evidence
161
+ paths. Per-milestone commits (message: `M<n>: <demo criterion>`) are this
162
+ pipeline's intended checkpointing — confirm once with the user at Phase 5
163
+ start, or record `[ASSUMED] auto-commit milestones` in autonomous mode.
164
+ If your harness forbids unrequested commits, skip them and note in
165
+ PIPELINE.md that the "revert to last green commit" recovery rung is
166
+ unavailable.
167
+ 6. Broken? Debug with runtime tools (`ecs pause/step/snapshot/diff`,
168
+ `browser logs`) before touching code. Revert to last green commit if a
169
+ milestone turns into a swamp; re-plan the milestone instead of thrashing.
170
+
171
+ ## Sub-agent rules for build fan-out
172
+
173
+ - Parallelize only **genuinely independent modules** (e.g. audio system vs
174
+ UI panel vs environment theming). Core-loop code is usually sequential.
175
+ - Each sub-agent owns a **disjoint file set**, stated explicitly in its
176
+ brief. Nobody but the main agent touches `src/index.ts`, `package.json`,
177
+ or `vite.config.ts`.
178
+ - Sub-agent brief = paths to GAME_SPEC/TECH_PLAN/ARCHITECTURE + the
179
+ **absolute app-root path** (run all commands from there — sub-agent
180
+ working directories often reset between calls) + the path to
181
+ `references/api-reference.md` with the
182
+ instruction to follow its best practices and anti-pattern list + owned
183
+ files + its milestone's assertions + "run `npx tsc --noEmit` before
184
+ returning; do NOT start dev servers or install packages".
185
+ - Sub-agents cannot keep background processes alive — the **main agent owns
186
+ the dev server** (`iwsdk dev up/down`), does all runtime verification, and
187
+ integrates results.
188
+ - After integrating parallel work: typecheck + verify loop before the next
189
+ fan-out. Two unverified fan-outs deep is how projects sink.
190
+
191
+ ## Common `iwsdk.config.json` world shapes
192
+
193
+ ```jsonc
194
+ // VR game (stationary or room-scale)
195
+ {
196
+ "world": {
197
+ "xr": { "mode": "vr", "offer": "once" },
198
+ "features": {
199
+ "physics": true,
200
+ "grabbing": true,
201
+ "locomotion": false,
202
+ "spatialUI": true
203
+ }
204
+ }
205
+ }
206
+
207
+ // Dual-runtime VR + browser-testable (recommended for agent-built apps —
208
+ // lets you and CI verify in a plain browser tab too)
209
+ {
210
+ "world": {
211
+ "xr": { "mode": "vr", "offer": "once" },
212
+ "input": { "canvasPointerEvents": true },
213
+ "features": {
214
+ "physics": true,
215
+ "grabbing": true,
216
+ "spatialUI": true,
217
+ "locomotion": { "browserControls": true }
218
+ }
219
+ }
220
+ }
221
+
222
+ // AR placement app
223
+ {
224
+ "world": {
225
+ "xr": {
226
+ "mode": "ar",
227
+ "features": { "planeDetection": true, "hitTest": true }
228
+ },
229
+ "features": {
230
+ "locomotion": false,
231
+ "sceneUnderstanding": true,
232
+ "environmentRaycast": true,
233
+ "grabbing": true
234
+ }
235
+ }
236
+ }
237
+ ```
238
+
239
+ Only enable what the TECH_PLAN grounded — every stray flag is overhead and a
240
+ prerequisite trap (locomotion without collision geometry = player falls
241
+ through the world). Full option reference: `api-reference.md` §18–19.
@@ -0,0 +1,101 @@
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.
@@ -0,0 +1,176 @@
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.
@@ -0,0 +1,156 @@
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.