@iwsdk/create 0.4.2 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -41
- package/dist/cli.js +1003 -3418
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
- package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
- package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
- package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
- package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
- package/dist/guidance/claude/.claude/settings.json +19 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
- package/dist/guidance/claude/CLAUDE.md +142 -0
- package/dist/guidance/codex/.codex/config.toml +2 -0
- package/dist/guidance/common/AGENTS.md +151 -0
- package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
- package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
- package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
- package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
- package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
- package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
- package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
- package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/gitignore.template +45 -0
- package/dist/template/common/index.html +16 -0
- package/dist/template/common/nvmrc.template +1 -0
- package/dist/template/common/public/audio/chime.mp3 +0 -0
- package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common/public/textures/webxr.png +0 -0
- package/dist/template/common/public/ui/welcome.uikitml +98 -0
- package/dist/template/common/src/assets.ts +54 -0
- package/dist/template/common/src/components.ts +11 -0
- package/dist/template/common/src/index.ts +19 -0
- package/dist/template/common/src/panel.ts +38 -0
- package/dist/template/common/src/robot-component.ts +10 -0
- package/dist/template/common/src/robot.ts +38 -0
- package/dist/template/common/src/vite-env.d.ts +2 -0
- package/dist/template/common/tsconfig.json +15 -0
- package/dist/template/common/vite.config.ts +27 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/gitignore.template +45 -0
- package/dist/template/common-js/index.html +16 -0
- package/dist/template/common-js/nvmrc.template +1 -0
- package/dist/template/common-js/public/audio/chime.mp3 +0 -0
- package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
- package/dist/template/common-js/public/textures/webxr.png +0 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
- package/dist/template/common-js/src/assets.js +45 -0
- package/dist/template/common-js/src/components.js +9 -0
- package/dist/template/common-js/src/index.js +14 -0
- package/dist/template/common-js/src/panel.js +31 -0
- package/dist/template/common-js/src/robot-component.js +8 -0
- package/dist/template/common-js/src/robot.js +37 -0
- package/dist/template/common-js/vite.config.js +25 -0
- package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
- package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
- package/package.json +17 -12
- package/scripts/verify-release-ready.mjs +76 -0
|
@@ -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.
|