@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# Publishing to an Existing Host
|
|
2
|
+
|
|
3
|
+
Use this when the developer already has hosting. **You prepare files and stop**
|
|
4
|
+
— they publish. Your job is to make the handoff precise: the exact local files,
|
|
5
|
+
the exact public URLs, the exact command or click path for their host, and then
|
|
6
|
+
verification once they confirm.
|
|
7
|
+
|
|
8
|
+
Everything the app needs is inside `dist/` after `npm run build` (Vite copies
|
|
9
|
+
`public/` verbatim, dotfolders included), so in most cases the handoff is simply
|
|
10
|
+
"publish `dist/`". The recipes below exist for the cases where it is not.
|
|
11
|
+
|
|
12
|
+
## The two moments that need a publish
|
|
13
|
+
|
|
14
|
+
1. **Manifest + icons** — before `bubblewrap update`, which fetches them over
|
|
15
|
+
the network.
|
|
16
|
+
2. **`.well-known/assetlinks.json`** — after the signing keystore exists. The
|
|
17
|
+
TWA will not launch until this is live. This is the one that gets forgotten,
|
|
18
|
+
and the one hosts most often break.
|
|
19
|
+
|
|
20
|
+
## Universal gotchas
|
|
21
|
+
|
|
22
|
+
**Dotfolders get stripped.** Several hosts and build pipelines ignore
|
|
23
|
+
`.`-prefixed paths, so `.well-known/` silently never ships. Symptom: everything
|
|
24
|
+
else is 200, `/.well-known/assetlinks.json` is 404, and the installed app opens
|
|
25
|
+
to "will not launch". The path is fixed by the TWA spec — fix the host, do not
|
|
26
|
+
relocate the file.
|
|
27
|
+
|
|
28
|
+
**`.webmanifest` has no MIME mapping.** Older servers serve it as `text/plain`
|
|
29
|
+
or `application/octet-stream`. Either add the mapping
|
|
30
|
+
(`application/manifest+json`) or rename to `manifest.json` and update both
|
|
31
|
+
`<link rel="manifest">` in `index.html` and `webManifestUrl` in
|
|
32
|
+
`twa-manifest.json`.
|
|
33
|
+
|
|
34
|
+
**Aggressive CDN caching.** After the asset-links publish, a cached 404 keeps
|
|
35
|
+
the TWA broken long after the file is live. Purge the cache, then verify.
|
|
36
|
+
|
|
37
|
+
**Subpath hosting.** `assetlinks.json` must be at the origin root even when the
|
|
38
|
+
app is at `/<path>/`. See §5 of `SKILL.md`.
|
|
39
|
+
|
|
40
|
+
## Per-host recipes
|
|
41
|
+
|
|
42
|
+
### Netlify
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm run build
|
|
46
|
+
npx -y netlify-cli deploy --prod --dir=dist
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Dotfolders in the publish directory are served as-is; no config needed. If a
|
|
50
|
+
build plugin or a `.gitignore` rule is dropping `.well-known/`, publish `dist/`
|
|
51
|
+
directly as above rather than letting Netlify build from source.
|
|
52
|
+
|
|
53
|
+
MIME types are inferred correctly. To force one, add to `netlify.toml`:
|
|
54
|
+
|
|
55
|
+
```toml
|
|
56
|
+
[[headers]]
|
|
57
|
+
for = "/manifest.webmanifest"
|
|
58
|
+
[headers.values]
|
|
59
|
+
Content-Type = "application/manifest+json"
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Cloudflare Pages
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npm run build
|
|
66
|
+
npx -y wrangler pages deploy dist --project-name <project>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Pages skips dot-prefixed files on upload but makes an explicit exception for
|
|
70
|
+
`.well-known/`, so asset links normally work with no configuration. Verify
|
|
71
|
+
rather than trust it — a custom build step or an `.assetsignore` entry can still
|
|
72
|
+
drop the directory:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/.well-known/assetlinks.json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
If that 404s, emit a second copy at `public/assetlinks.json` and rewrite the
|
|
79
|
+
dotted path to it with a `_redirects` rule (status `200` = rewrite, not
|
|
80
|
+
redirect — a 3xx does not satisfy asset-link verification):
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
# public/_redirects
|
|
84
|
+
/.well-known/assetlinks.json /assetlinks.json 200
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Re-verify that the dotted URL returns the JSON body itself.
|
|
88
|
+
|
|
89
|
+
### GitHub Pages
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm run build
|
|
93
|
+
npx -y gh-pages -d dist --dotfiles
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`--dotfiles` is **required** — without it `.well-known/` is silently omitted.
|
|
97
|
+
Also add an empty `public/.nojekyll` file, or Jekyll strips underscore- and
|
|
98
|
+
dot-prefixed paths during the Pages build.
|
|
99
|
+
|
|
100
|
+
Project sites (`https://<user>.github.io/<repo>/`) are a subpath deployment:
|
|
101
|
+
`start_url`/`scope` become `/<repo>/`, and `assetlinks.json` must live in the
|
|
102
|
+
`<user>.github.io` **user/organization** repository so it is served from the
|
|
103
|
+
origin root. If the developer does not control that repo, they cannot ship a TWA
|
|
104
|
+
from this origin — say so and offer Vercel.
|
|
105
|
+
|
|
106
|
+
### AWS S3 + CloudFront
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
npm run build
|
|
110
|
+
aws s3 sync dist/ s3://<bucket>/ --delete
|
|
111
|
+
aws s3 cp dist/manifest.webmanifest s3://<bucket>/manifest.webmanifest \
|
|
112
|
+
--content-type application/manifest+json
|
|
113
|
+
aws s3 cp dist/.well-known/assetlinks.json s3://<bucket>/.well-known/assetlinks.json \
|
|
114
|
+
--content-type application/json
|
|
115
|
+
aws cloudfront create-invalidation --distribution-id <id> --paths '/*'
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`aws s3 sync` guesses content types from the extension and gets `.webmanifest`
|
|
119
|
+
wrong, so re-upload those two files explicitly. The CloudFront invalidation is
|
|
120
|
+
not optional — a cached 404 on `assetlinks.json` keeps the TWA broken.
|
|
121
|
+
|
|
122
|
+
### Firebase Hosting
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npm run build
|
|
126
|
+
npx -y firebase-tools deploy --only hosting
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Set `"public": "dist"` in `firebase.json`. Firebase serves `.well-known/`
|
|
130
|
+
correctly, but an `"ignore"` entry containing `"**/.*"` — which is in the
|
|
131
|
+
default generated config — will drop it. Remove or narrow that pattern.
|
|
132
|
+
|
|
133
|
+
### nginx / Apache on a VPS
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
npm run build
|
|
137
|
+
rsync -av --delete dist/ <user>@<host>:/var/www/<site>/
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
nginx: add the manifest MIME type and make sure no `location ~ /\.` rule is
|
|
141
|
+
denying dotfolders — the common hardening snippet `location ~ /\. { deny all; }`
|
|
142
|
+
blocks `.well-known/`. Allow it explicitly:
|
|
143
|
+
|
|
144
|
+
```nginx
|
|
145
|
+
location ^~ /.well-known/ { allow all; }
|
|
146
|
+
types { application/manifest+json webmanifest; }
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Apache: the equivalent trap is `<FilesMatch "^\.">` or a `RedirectMatch` rule
|
|
150
|
+
denying dot paths.
|
|
151
|
+
|
|
152
|
+
```apache
|
|
153
|
+
AddType application/manifest+json .webmanifest
|
|
154
|
+
<Directory "/var/www/<site>/.well-known">
|
|
155
|
+
Require all granted
|
|
156
|
+
</Directory>
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Unknown or internal host
|
|
160
|
+
|
|
161
|
+
Do not guess. Ask two questions and adapt:
|
|
162
|
+
|
|
163
|
+
1. How do you normally publish a build — a CLI command, a CI pipeline, or a
|
|
164
|
+
dashboard upload?
|
|
165
|
+
2. Can the origin serve a path beginning with a dot (`/.well-known/...`)?
|
|
166
|
+
|
|
167
|
+
Then produce the handoff in the same shape as the recipes above: exact files,
|
|
168
|
+
exact URLs, their command, and the verification you will run afterwards.
|
|
169
|
+
|
|
170
|
+
## Verify after every publish
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
for u in / /manifest.webmanifest /icons/icon-512.png /.well-known/assetlinks.json; do
|
|
174
|
+
printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
|
|
175
|
+
done
|
|
176
|
+
curl -s -o /dev/null -w 'keystore %{http_code} (want 404)\n' "https://<DOMAIN>/android.keystore"
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Report the actual status codes back to the developer rather than a bare "looks
|
|
180
|
+
good" — a 200 on the keystore URL, or a 404 on asset links, is the whole
|
|
181
|
+
difference between a working app and a launch failure diagnosed hours later.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Vercel Deployment
|
|
2
|
+
|
|
3
|
+
The recommended host when the developer has not already chosen one. Vercel
|
|
4
|
+
auto-detects Vite, serves `dist/` over HTTPS on a stable public alias, preserves
|
|
5
|
+
`public/` dotfolders (`.well-known/`), serves `.webmanifest` with the right MIME
|
|
6
|
+
type, and redeploys in one command — which matters because Digital Asset Links
|
|
7
|
+
force a second publish after the APK is signed.
|
|
8
|
+
|
|
9
|
+
## Prerequisites
|
|
10
|
+
|
|
11
|
+
The scaffolded `vite.config.*` is already correct — `base: './'`,
|
|
12
|
+
`publicDir: 'public'`, `build.outDir: 'dist'`. Nothing to change.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm run build # → dist/
|
|
16
|
+
ls dist # sanity: index.html, assets/, icons/, manifest.webmanifest
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## First run: authentication
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx -y vercel@latest whoami
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
If this errors, the developer is not logged in. `vercel login` is interactive
|
|
26
|
+
(it prompts for an email/SSO choice and waits on a browser round trip), so an
|
|
27
|
+
agent cannot complete it — **hand it off**: ask them to run `npx vercel login`
|
|
28
|
+
in their terminal, or to paste `! npx vercel login` into this session, then
|
|
29
|
+
re-run `whoami`.
|
|
30
|
+
|
|
31
|
+
For CI or an unattended run, a token works instead and skips the prompt:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx -y vercel@latest deploy --prod --yes --token "$VERCEL_TOKEN"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Find the scope
|
|
38
|
+
|
|
39
|
+
Personal accounts need no `--scope`. Team accounts do — omitting it deploys to
|
|
40
|
+
the wrong place or fails outright:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npx -y vercel@latest teams ls
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Deploy
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
npx -y vercel@latest deploy --prod --yes --scope <team-slug>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`--yes` accepts the project-creation and link prompts, so the command is
|
|
53
|
+
non-interactive. Vite is auto-detected: Vercel runs `vite build` and serves
|
|
54
|
+
`dist/`.
|
|
55
|
+
|
|
56
|
+
## Two URLs come back — only one is usable
|
|
57
|
+
|
|
58
|
+
| URL | Behavior | Use as `<DOMAIN>`? |
|
|
59
|
+
| --- | -------- | ------------------ |
|
|
60
|
+
| Canonical alias `https://<project>.vercel.app` | public, 200 | **yes** |
|
|
61
|
+
| Hashed per-deploy `https://<project>-<hash>-<team>.vercel.app` | 401 under team deployment protection | no |
|
|
62
|
+
|
|
63
|
+
The hashed URL is what the CLI prints most prominently, which is exactly how it
|
|
64
|
+
ends up baked into a `twa-manifest.json` by mistake. The resulting APK fetches a
|
|
65
|
+
401 and the app shows a blank or error screen on the headset. Always confirm the
|
|
66
|
+
alias returns 200 before using it anywhere downstream:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
curl -s -o /dev/null -w '%{http_code}\n' https://<project>.vercel.app/
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
If the canonical alias is also 401, deployment protection is enabled for the
|
|
73
|
+
whole project. It must be turned off (Project → Settings → Deployment
|
|
74
|
+
Protection) — a TWA cannot authenticate through it. This is the developer's
|
|
75
|
+
call: pause and ask.
|
|
76
|
+
|
|
77
|
+
## Custom domain
|
|
78
|
+
|
|
79
|
+
If they want a real domain instead of `*.vercel.app`, add it before packaging —
|
|
80
|
+
the domain is baked into `twa-manifest.json` and the asset links, so changing it
|
|
81
|
+
later means a new APK and a new Store build:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
npx -y vercel@latest domains add <domain> --scope <team-slug>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Verify
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
for u in / /manifest.webmanifest /icons/icon-512.png; do
|
|
91
|
+
printf '%s ' "$u"
|
|
92
|
+
curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
|
|
93
|
+
done
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The manifest should be `application/manifest+json`. Vercel infers this from the
|
|
97
|
+
`.webmanifest` extension with no configuration.
|
|
98
|
+
|
|
99
|
+
## Redeploying
|
|
100
|
+
|
|
101
|
+
Re-run the same deploy command. The alias moves to the new deployment; the
|
|
102
|
+
installed TWA picks up the change on its next launch, with no rebuild and no
|
|
103
|
+
Store upload.
|
|
104
|
+
|
|
105
|
+
The second deploy in this pipeline is the asset-links one: after the keystore
|
|
106
|
+
exists, write `public/.well-known/assetlinks.json`, then `npm run build` and
|
|
107
|
+
deploy again. Vite copies dotfolders out of `public/`, and Vercel serves them —
|
|
108
|
+
no `vercel.json` needed.
|
|
109
|
+
|
|
110
|
+
## When not to use Vercel
|
|
111
|
+
|
|
112
|
+
If the app needs a backend, private networking, or an existing corporate CDN,
|
|
113
|
+
this is the wrong recommendation. Ask, and fall back to Route B (existing host)
|
|
114
|
+
in `SKILL.md`.
|
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-native-xr-test
|
|
3
|
+
description: Drive an IWSDK app in a real Quest immersive session while you control headset and controller poses through the IWSDK CLI. Use when you will automate, script-test, or debug an app on a connected Quest. Not for the user trying the app by hand; native control takes over their head pose and controllers, so give them a plain dev session instead.
|
|
4
|
+
argument-hint: '[test scenario]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Test on a physical Quest
|
|
8
|
+
|
|
9
|
+
Run the app through an ADB-reversed localhost connection, enter the browser's
|
|
10
|
+
real immersive session, and use the ordinary IWSDK XR, ECS, scene, and browser
|
|
11
|
+
commands to observe and control it. The native browser continues to own
|
|
12
|
+
`XRSession`, frame scheduling, rendering, and tracking; IWSDK/IWER selectively
|
|
13
|
+
override poses and input for the test.
|
|
14
|
+
|
|
15
|
+
The requested scenario is in `$ARGUMENTS`.
|
|
16
|
+
|
|
17
|
+
## Not for hands-on testing
|
|
18
|
+
|
|
19
|
+
Use this skill only when you drive the headset. If the user wants to put the
|
|
20
|
+
headset on and try the app themselves, do not start native control and do not
|
|
21
|
+
give them a pairing URL. A `--native-xr-control` session overrides the head pose
|
|
22
|
+
and controllers of every Quest Browser page it serves, even after the pairing
|
|
23
|
+
token is removed from the URL; the page shows an "Agent-controlled page"
|
|
24
|
+
notice saying so. Restart without the flag and hand over a plain URL as described in
|
|
25
|
+
AGENTS.md. If a native-control test is running when the user asks to try the
|
|
26
|
+
app, finish or stop it, clean up as in step 6, then do the same.
|
|
27
|
+
|
|
28
|
+
## Safety and scope
|
|
29
|
+
|
|
30
|
+
- Use only public Android platform tools and IWSDK commands. Do not depend on a
|
|
31
|
+
device-rental service, XRPilot, or internal Meta tooling.
|
|
32
|
+
- Always work with an explicit device serial. With exactly one authorized
|
|
33
|
+
device in `adb devices`, use its serial. With several connected devices,
|
|
34
|
+
require the user to name the serial to test; never choose one yourself. Pass
|
|
35
|
+
`-s <serial>` to every ADB command and use the same serial as the IWSDK
|
|
36
|
+
`headsetId`.
|
|
37
|
+
- Support Quest Browser only. Do not broaden the browser user-agent check.
|
|
38
|
+
- Keep the command bridge on loopback. Use `adb reverse`; never expose or
|
|
39
|
+
forward the bridge over a LAN.
|
|
40
|
+
- Native control replaces the headset's native controller input sources with
|
|
41
|
+
synthetic controllers for the duration of the test. Physical controller and
|
|
42
|
+
hand-action playback are unavailable while the override is installed.
|
|
43
|
+
- `xr set-transform` applies absolute test poses, not offsets from live
|
|
44
|
+
tracking.
|
|
45
|
+
- A first run may show an immersive-WebXR permission prompt in the headset.
|
|
46
|
+
Ask the user to approve it physically, then relaunch. Do not automate that
|
|
47
|
+
permission dialog.
|
|
48
|
+
- Always remove the ADB reverse and stop the dev session during cleanup,
|
|
49
|
+
including after a failed test.
|
|
50
|
+
|
|
51
|
+
## Target the headset explicitly
|
|
52
|
+
|
|
53
|
+
A command without `runtimeTarget` always routes to the managed host browser,
|
|
54
|
+
never to a headset, even when a paired headset page is the only connected page.
|
|
55
|
+
This workflow starts with `--no-open`, so such a command fails with
|
|
56
|
+
`browser_not_launched`. Do not restart with `--open` to fix a headset command;
|
|
57
|
+
the managed browser never forwards commands to the Quest.
|
|
58
|
+
|
|
59
|
+
- Discover connected targets with `npx @iwsdk/cli runtime targets --raw`. Each
|
|
60
|
+
entry in `targets` carries a nested `runtimeTarget` object and the `methods`
|
|
61
|
+
that page supports.
|
|
62
|
+
- A headset page qualifies only when its entry has `deviceClass: "physical"`,
|
|
63
|
+
`role: "app"`, `commandReady: true`, and a `headsetId` equal to the explicit
|
|
64
|
+
serial.
|
|
65
|
+
- Copy the qualifying entry's complete `runtimeTarget` unchanged: `deviceClass`,
|
|
66
|
+
`headsetId`, `pageId`, `tabGeneration`, and any returned `sessionId` or
|
|
67
|
+
`browserEpoch`. Never rebuild it from separate fields, drop or edit a field,
|
|
68
|
+
or pass the surrounding entry instead.
|
|
69
|
+
- Put it under the top-level `runtimeTarget` key of every headset command's
|
|
70
|
+
`--input-json`, next to that command's own parameters. It is unrelated to the
|
|
71
|
+
position-vector `target` parameter of commands such as `xr look-at`.
|
|
72
|
+
- Never select a headset page with `expectedTab` alone. It carries no
|
|
73
|
+
`deviceClass` or `headsetId`, so the command stays on the managed browser.
|
|
74
|
+
- Never guess between candidates. If these rules do not identify exactly one
|
|
75
|
+
page, or a command returns `ambiguous_target`, ask the user to close the extra
|
|
76
|
+
app tabs in the headset, then rediscover. Do not fall back to list order, the
|
|
77
|
+
newest entry, another headset, or an untargeted command.
|
|
78
|
+
- A reload or relaunch advances the page generation. After one, or after a
|
|
79
|
+
`stale_browser_tab` or `target_unavailable` error, run `runtime targets` again
|
|
80
|
+
and reselect with these rules. An old `runtimeTarget` stays fenced to its
|
|
81
|
+
generation.
|
|
82
|
+
- `outcome_unknown` means the command may have executed. Never replay it.
|
|
83
|
+
Rediscover the target, inspect state with read-only commands such as
|
|
84
|
+
`xr status`, `ecs query`, or `scene transform`, and only then decide whether a
|
|
85
|
+
new command is needed.
|
|
86
|
+
- Headset pages accept runtime commands only. Host-only browser tools, such as
|
|
87
|
+
screenshots, snapshots, interaction, profiling, and console capture, return
|
|
88
|
+
`unsupported_on_target`; check the entry's `methods` first.
|
|
89
|
+
|
|
90
|
+
To test several headsets in one dev session, set up each serial separately: one
|
|
91
|
+
`adb -s <serial> reverse` route and one `runtime pair-headset` call per device,
|
|
92
|
+
discovery by each device's own `headsetId`, and one recorded `runtimeTarget` per
|
|
93
|
+
headset. Send each command with the `runtimeTarget` of the headset it is meant
|
|
94
|
+
for; never reuse one headset's `runtimeTarget` for another.
|
|
95
|
+
|
|
96
|
+
## 1. Verify the app and device
|
|
97
|
+
|
|
98
|
+
Run `npm run --if-present typecheck` and fix type errors before device testing.
|
|
99
|
+
|
|
100
|
+
Run `adb devices` and settle the explicit serial as described above. Continue
|
|
101
|
+
only when that serial is in the `device` state. A `pending`, `offline`, or
|
|
102
|
+
`unauthorized` device is not ready.
|
|
103
|
+
|
|
104
|
+
This workflow expects a manifest-first app that imports
|
|
105
|
+
`virtual:iwsdk-project` and passes it to `World.create()`. For a hand-built
|
|
106
|
+
`WorldOptions` object, opt in explicitly with:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
xr: {
|
|
110
|
+
// existing XR options
|
|
111
|
+
launchOnSessionGranted: true,
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## 2. Start the native-control dev session
|
|
116
|
+
|
|
117
|
+
From the application root, run:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
npx @iwsdk/cli dev up --native-xr-control --no-open
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Inspect `npx @iwsdk/cli dev status` and record the numeric port from the
|
|
124
|
+
active runtime. Native-control sessions default to HTTP when the application
|
|
125
|
+
does not explicitly configure Vite HTTPS. The app is loaded from
|
|
126
|
+
headset-localhost through ADB reverse, so the default remains a trustworthy
|
|
127
|
+
WebXR origin. `--no-open` leaves the managed host browser unlaunched, so only
|
|
128
|
+
commands that carry the headset's `runtimeTarget` can run.
|
|
129
|
+
|
|
130
|
+
## 3. Install the ADB route and pair the headset
|
|
131
|
+
|
|
132
|
+
Replace `<serial>` and `<port>` with the values verified above:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
adb -s <serial> reverse tcp:<port> tcp:<port>
|
|
136
|
+
npx @iwsdk/cli runtime pair-headset --input-json '{"headsetId":"<serial>"}' --raw
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Record the returned `url`. It carries this headset's pairing token for the
|
|
140
|
+
current dev session; an unpaired headset page is refused and never becomes a
|
|
141
|
+
target. Continue only if the URL points at `localhost` or `127.0.0.1` on
|
|
142
|
+
`<port>`. Pair again after any dev-session restart.
|
|
143
|
+
|
|
144
|
+
## 4. Enter the real immersive session
|
|
145
|
+
|
|
146
|
+
Before each launch, run `npx @iwsdk/cli runtime targets --raw` and record the
|
|
147
|
+
`pageId` and `tabGeneration` of every physical target whose `headsetId` is
|
|
148
|
+
`<serial>`.
|
|
149
|
+
|
|
150
|
+
URL-encode the returned pairing URL without changing its host or dropping its
|
|
151
|
+
query, then launch:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
adb -s <serial> shell am broadcast \
|
|
155
|
+
-n com.oculus.vrshell/.ShellControlBroadcastReceiver \
|
|
156
|
+
-a com.oculus.vrshell.intent.action.LAUNCH \
|
|
157
|
+
-d apk://com.oculus.browser \
|
|
158
|
+
-e uri "ovrweb://vr?uri=<encoded-pairing-url>"
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Keep the nested URL encoded so `?`, `&`, and fragment characters cannot be
|
|
162
|
+
interpreted as parameters of the outer deep link.
|
|
163
|
+
|
|
164
|
+
Poll `npx @iwsdk/cli runtime targets --raw`. Select the qualifying target that
|
|
165
|
+
this launch created: its `pageId` was not recorded, or its `tabGeneration` is
|
|
166
|
+
higher than recorded. If exactly one target matches, record its complete
|
|
167
|
+
`runtimeTarget`. A physical target has this shape:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
{
|
|
171
|
+
"deviceClass": "physical",
|
|
172
|
+
"headsetId": "<serial>",
|
|
173
|
+
"pageId": "<pageId>",
|
|
174
|
+
"tabGeneration": 1,
|
|
175
|
+
"sessionId": "<sessionId>"
|
|
176
|
+
}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
If no target appears, check in the headset that the page loaded from the
|
|
180
|
+
pairing URL and did not redirect to a network hostname. If more than one
|
|
181
|
+
matches, ask the user to close the extra tabs and relaunch.
|
|
182
|
+
|
|
183
|
+
Replace `<runtimeTarget>` below with the recorded object, verbatim:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
npx @iwsdk/cli xr status --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
XR status must show an active `immersive-vr` or `immersive-ar` session. Its
|
|
190
|
+
`browserConnected` and `browserCommandReady` fields describe the managed host
|
|
191
|
+
browser, not the headset. If the session stays inactive, ask the user to accept
|
|
192
|
+
the one-time browser permission in the headset, then repeat this step from the
|
|
193
|
+
pre-launch record.
|
|
194
|
+
|
|
195
|
+
Do not use `iwsdk xr enter` for this step: that command accepts an emulated
|
|
196
|
+
offer, while this workflow must preserve the browser's native session.
|
|
197
|
+
|
|
198
|
+
## 5. Run the scenario
|
|
199
|
+
|
|
200
|
+
Discover the available command shapes before improvising:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
npx @iwsdk/cli xr --help
|
|
204
|
+
npx @iwsdk/cli ecs --help
|
|
205
|
+
npx @iwsdk/cli scene --help
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Add the recorded `runtimeTarget` to each command's `--input-json`, next to the
|
|
209
|
+
command's own parameters. Here `target` is the world position to aim at:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
npx @iwsdk/cli xr look-at --input-json \
|
|
213
|
+
'{"device":"controller-right","target":{"x":0,"y":1.2,"z":-1},"runtimeTarget":<runtimeTarget>}' --raw
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The exact `runtimeTarget` both selects the intended headset page and rejects
|
|
217
|
+
stale commands after a page reload.
|
|
218
|
+
|
|
219
|
+
Use the same commands as desktop automation. Typical controls are:
|
|
220
|
+
|
|
221
|
+
- `xr set-transform` for headset or controller position/orientation.
|
|
222
|
+
- `xr look-at` to aim a controller ray at a world position.
|
|
223
|
+
- `xr set-select-value` or `xr select` for trigger/pinch interaction.
|
|
224
|
+
- `xr set-gamepad-state` for squeeze and controller buttons.
|
|
225
|
+
- `ecs query`, `ecs snapshot`, and `ecs diff` for authoritative state.
|
|
226
|
+
- `scene runtime-hierarchy` and `scene transform` to locate and measure
|
|
227
|
+
rendered objects.
|
|
228
|
+
|
|
229
|
+
Prove behavior with state, not only screenshots. For an interaction test,
|
|
230
|
+
record the target transform or component state before the action, perform the
|
|
231
|
+
pose/input sequence, and show the corresponding state change afterward.
|
|
232
|
+
|
|
233
|
+
## 6. Exit and clean up
|
|
234
|
+
|
|
235
|
+
Run these cleanup actions individually even if an earlier assertion failed:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
npx @iwsdk/cli xr exit --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
|
|
239
|
+
adb -s <serial> reverse --remove tcp:<port>
|
|
240
|
+
npx @iwsdk/cli dev down
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Use the most recently discovered `runtimeTarget` for `xr exit`. If it returns
|
|
244
|
+
`stale_browser_tab` or `target_unavailable`, rediscover and exit with the fresh
|
|
245
|
+
object; if it returns `outcome_unknown`, check `xr status` instead of repeating
|
|
246
|
+
the exit. Remove the reverse route from every device you configured.
|
|
247
|
+
|
|
248
|
+
Report:
|
|
249
|
+
|
|
250
|
+
- device serial (`headsetId`) and app URL used;
|
|
251
|
+
- the exact `runtimeTarget` of the final command;
|
|
252
|
+
- native session mode and enabled features;
|
|
253
|
+
- the selected target's command-ready state;
|
|
254
|
+
- pose/input actions performed;
|
|
255
|
+
- before/after evidence for the requested behavior;
|
|
256
|
+
- console errors or capability notes;
|
|
257
|
+
- confirmation that the reverse route and dev session were removed.
|
|
258
|
+
|
|
259
|
+
If the user wants to try the app in the headset afterwards, start a plain
|
|
260
|
+
session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
|
|
261
|
+
`--native-xr-control`) and give them the plain URL from `dev status`.
|
|
262
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-physics
|
|
3
|
+
description: Add or repair IWSDK rigid-body simulation, collision shapes, forces, and physics-aware grabbing. Use for gravity, falling, collision, bouncing, kinematic motion, or physics tuning.
|
|
4
|
+
argument-hint: '(use the current request)'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# IWSDK Physics
|
|
8
|
+
|
|
9
|
+
Use the current request as the specification. Prefer the scaffold's project
|
|
10
|
+
manifest and native scene components over rebuilding physics in TypeScript.
|
|
11
|
+
|
|
12
|
+
## Implement the smallest complete physics path
|
|
13
|
+
|
|
14
|
+
1. Inspect `iwsdk.config.json`, the active scene, and only the source file that
|
|
15
|
+
owns any requested custom behavior.
|
|
16
|
+
Make the complete first config/asset/scene edit before starting the dev
|
|
17
|
+
server. The contracts below are sufficient for the common path: do not call
|
|
18
|
+
`scene capabilities`, CLI `--help`, search `node_modules`, or inspect
|
|
19
|
+
generated declarations unless a concrete build/runtime error remains after
|
|
20
|
+
that edit.
|
|
21
|
+
2. Set `world.features.physics` to `true`. The scaffold registers
|
|
22
|
+
`PhysicsSystem`, `PhysicsBody`, `PhysicsShape`, and `PhysicsManipulation`; do
|
|
23
|
+
not register them again unless the project deliberately replaced bootstrap.
|
|
24
|
+
3. Every colliding entity needs both `PhysicsBody` and `PhysicsShape`:
|
|
25
|
+
|
|
26
|
+
- moving under simulation: `PhysicsBody.state: "DYNAMIC"`;
|
|
27
|
+
- fixed floor or wall: `PhysicsBody.state: "STATIC"`;
|
|
28
|
+
- code-driven moving platform: `PhysicsBody.state: "KINEMATIC"`.
|
|
29
|
+
|
|
30
|
+
4. Match shapes to visible geometry. Use `Sphere`, `Box`, or `Cylinder` with
|
|
31
|
+
explicit dimensions for primitives. Use `ConvexHull` for a dynamic complex
|
|
32
|
+
mesh and reserve `TriMesh` for static geometry.
|
|
33
|
+
5. Add only requested material tuning. Start with low restitution and moderate
|
|
34
|
+
friction; avoid compensating for a missing collider with extreme damping.
|
|
35
|
+
6. For a throwable object, combine a dynamic body and shape with the requested
|
|
36
|
+
grab component. `OneHandGrabbable` is proximity squeeze; a distance grab
|
|
37
|
+
also requires `RayInteractable` and `DistanceGrabbable`.
|
|
38
|
+
7. Apply a one-shot force or velocity through `PhysicsManipulation`. For a
|
|
39
|
+
reset/teleport of an existing body, use `PhysicsSystem.setBodyTransform` so
|
|
40
|
+
Havok and the render transform remain synchronized.
|
|
41
|
+
|
|
42
|
+
For simple primitive assets, import `Mesh`, `SphereGeometry`, `BoxGeometry`,
|
|
43
|
+
and `MeshStandardMaterial` from `@iwsdk/core`, construct parentless meshes, and
|
|
44
|
+
add those mesh values directly to the existing `defineAssets({...})` map. Keep
|
|
45
|
+
the render geometry and collider dimensions identical: a sphere of radius `r`
|
|
46
|
+
uses `PhysicsShape: { shape: "Sphere", dimensions: [r, 0, 0] }`; a box sized
|
|
47
|
+
`[w, h, d]` uses `{ shape: "Box", dimensions: [w, h, d] }`.
|
|
48
|
+
|
|
49
|
+
Read one bundled reference only when needed; do not read the complete set:
|
|
50
|
+
|
|
51
|
+
- exact component fields and dimensions: `references/component-reference.md`;
|
|
52
|
+
- implementation patterns: `references/workflows.md`;
|
|
53
|
+
- material or system tuning: `references/tuning-and-config.md`.
|
|
54
|
+
|
|
55
|
+
## Verify behavior, not just source
|
|
56
|
+
|
|
57
|
+
Run the production build once. Start the app once and inspect the named live
|
|
58
|
+
entities. For falling, collision, force, or kinematic behavior, pause before the
|
|
59
|
+
interesting transition, take a `before` snapshot, step a small fixed number of
|
|
60
|
+
frames, take an `after` snapshot, and diff them. Query the final transform and
|
|
61
|
+
physics state. Capture one final runtime image when spatial layout matters.
|
|
62
|
+
|
|
63
|
+
Use the documented CLI shape directly; do not call help to rediscover it:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx @iwsdk/cli ecs pause --input-json '{}'
|
|
67
|
+
npx @iwsdk/cli ecs snapshot --input-json '{"label":"before"}'
|
|
68
|
+
npx @iwsdk/cli ecs step --input-json '{"count":8,"delta":0.016}'
|
|
69
|
+
npx @iwsdk/cli ecs snapshot --input-json '{"label":"after"}'
|
|
70
|
+
npx @iwsdk/cli ecs diff --input-json '{"from":"before","to":"after"}'
|
|
71
|
+
npx @iwsdk/cli ecs resume --input-json '{}'
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
If a gravity body has already settled by the time the bridge is ready, its
|
|
75
|
+
resting transform plus a zero-motion stepped diff is valid collision evidence.
|
|
76
|
+
Do not teleport the body solely to recreate the fall.
|
|
77
|
+
|
|
78
|
+
Use an options object when you need to select the execution mode or simulation rate. Worker execution is the default; `useWorker: false` runs the same physics runtime and protocol on the main thread for compatibility and diagnostics.
|
|
79
|
+
|
|
80
|
+
```jsonc
|
|
81
|
+
"physics": {
|
|
82
|
+
"useWorker": true,
|
|
83
|
+
"updateFrequency": 60,
|
|
84
|
+
"interpolation": true
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Only enable physics when needed.** If no objects require dynamic simulation, omit it to avoid overhead.
|
|
89
|
+
|
|
90
|
+
For a newly composed test fixture, run `scene render-file` on the authored hero
|
|
91
|
+
view once and inspect at most that one image. After a valid, readable hero,
|
|
92
|
+
do not call `scene open`, `scene state`, or `scene screenshot`, and do not create
|
|
93
|
+
alternate editor views. Save the final live browser screenshot to a file but do
|
|
94
|
+
not read it back when the ECS measurements already prove the requested motion.
|
|
95
|
+
|
|
96
|
+
Pure rigid-body verification does not require entering XR. The authored `hero`
|
|
97
|
+
view is composition evidence, while the live browser camera can differ. Do not
|
|
98
|
+
temporarily edit `iwsdk.config.json`, restart the runtime, or render extra camera
|
|
99
|
+
angles solely to make a screenshot match the hero view. Save the live capture
|
|
100
|
+
directly with `npx @iwsdk/cli browser screenshot --output-file <path>` and let the
|
|
101
|
+
authored render cover deliberate framing.
|
|
102
|
+
|
|
103
|
+
Make at most one focused correction, then replay the same observation. Stop
|
|
104
|
+
when the requested bodies, collisions, and final state are evidenced. Resume
|
|
105
|
+
ECS time and leave the app in a stable state.
|
|
106
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5d66b2f83041f75889735be1e18747b078f2df32025ba1039cb77efbea3c2cb3 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|