@iwsdk/cli 1.1.0 → 1.2.0-rc.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 +106 -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 +1532 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +267 -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 +179 -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-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -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 +102 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +309 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +230 -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 +208 -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 +335 -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 +30 -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 +1532 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +267 -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 +179 -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-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -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 +102 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +309 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +230 -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 +208 -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 +335 -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 +954 -0
- package/dist/agent-guidance.d.ts +140 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3612 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +4010 -750
- 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 +138 -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 +53 -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 +6114 -508
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/metavr-telemetry.d.ts +6 -0
- package/dist/metavr-telemetry.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 +34 -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 +1506 -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,71 @@
|
|
|
1
|
+
# Build Step
|
|
2
|
+
|
|
3
|
+
`scripts/write-service-worker.mjs` (copied from
|
|
4
|
+
`assets/write-service-worker.mjs.template`) runs after `vite build`, once every
|
|
5
|
+
output file — `public/` included — is in `dist/`. It hashes each file, sorts it
|
|
6
|
+
into a list, names the release, and writes `dist/sw.js` from
|
|
7
|
+
`scripts/sw.js.template`.
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"scripts": {
|
|
12
|
+
"build": "vite build && node scripts/write-service-worker.mjs dist scripts/sw.js.template"
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It prints `sw.js: release <name>, <n> files, <m> on request`. Read that line
|
|
18
|
+
after every change to the rules.
|
|
19
|
+
|
|
20
|
+
## Rewrite the rules for the app
|
|
21
|
+
|
|
22
|
+
- **`LEFT_OUT`** — never listed. Keep the worker itself, source maps, crawler
|
|
23
|
+
and link-preview files, and `AGENTS.md`; add anything nothing requests.
|
|
24
|
+
- **`ON_REQUEST`** — listed with its hash, but copied only once the page fetches
|
|
25
|
+
it. Use it for files only some users need: copying them for everyone costs
|
|
26
|
+
every user for the benefit of a few. The kit's two rules
|
|
27
|
+
(`fonts/(ja|ko|zh)-`, `levels/extra-`) are examples; replace them.
|
|
28
|
+
|
|
29
|
+
## Three details that matter
|
|
30
|
+
|
|
31
|
+
- The paths are sorted before hashing, so the same output always gives the same
|
|
32
|
+
release name, and an unchanged build writes a byte-identical `sw.js`, which
|
|
33
|
+
browsers ignore.
|
|
34
|
+
- The placeholders are replaced through functions, because a replacement string
|
|
35
|
+
would read `$&` in a file name as a pattern.
|
|
36
|
+
- The script must run after every file exists: a file written later is missing
|
|
37
|
+
from the list, so it is never kept. That is why it runs after `vite build`
|
|
38
|
+
rather than from a plugin's `closeBundle` hook.
|
|
39
|
+
|
|
40
|
+
## Identify files by hash
|
|
41
|
+
|
|
42
|
+
Decide everything by the SHA-256 of a file's bytes, never by its name, date, or
|
|
43
|
+
version number. The one hash answers three questions: did the file change since
|
|
44
|
+
the last release, is a copy already on the device, and is the copy just
|
|
45
|
+
downloaded the right one.
|
|
46
|
+
|
|
47
|
+
| Signal | Decide by it? | Why |
|
|
48
|
+
| --- | --- | --- |
|
|
49
|
+
| SHA-256 of the bytes, computed at build | yes | the same bytes give the same hash on any machine |
|
|
50
|
+
| Hashed file names (`index-3f9a2c.js`) | only for Vite's own output | files copied from `public/` keep their names when their content changes |
|
|
51
|
+
| Modification time | no | a fresh checkout or a CI build gives every file a new time |
|
|
52
|
+
| `ETag` or `Last-Modified` | no | each server or CDN edge computes its own |
|
|
53
|
+
| One version number for the whole app | only as a label | a new number makes every file look changed, so every user downloads everything again |
|
|
54
|
+
|
|
55
|
+
## Duplicate files
|
|
56
|
+
|
|
57
|
+
Two paths with identical bytes share a hash but are stored twice, because the
|
|
58
|
+
Cache API keys entries by URL. To find them, group the list by hash inside
|
|
59
|
+
`writeServiceWorker()` (`Object.groupBy` needs Node.js 21 or later):
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
const byHash = Object.groupBy(Object.entries(files), ([, hash]) => hash);
|
|
63
|
+
for (const group of Object.values(byHash)) {
|
|
64
|
+
if (group.length > 1)
|
|
65
|
+
console.warn('same bytes:', group.map(([path]) => path).join(', '));
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
One duplicate is built in: the page loads `/`, but the list names `index.html`,
|
|
70
|
+
so a first visit fetches the entry page twice under two URLs. It is usually a
|
|
71
|
+
few kilobytes; list the entry page under its own URL if that matters.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Page Side
|
|
2
|
+
|
|
3
|
+
`src/offline.ts` (copied from `assets/offline.ts.template`) decides two moments:
|
|
4
|
+
when the copy is made, and when a new release may take over. It exports three
|
|
5
|
+
functions:
|
|
6
|
+
|
|
7
|
+
- **`startOffline(isIdle)`** — call first thing at startup. If a release
|
|
8
|
+
finished installing on an earlier visit, it takes over before anything
|
|
9
|
+
starts; otherwise it watches for one.
|
|
10
|
+
- **`keepOfflineCopy(isIdle)`** — call once the first screen is up. It registers
|
|
11
|
+
`./sw.js`, asks the browser to keep the copy with `navigator.storage.persist()`,
|
|
12
|
+
and reports what the page fetched before the worker existed.
|
|
13
|
+
- **`checkIdle()`** — call whenever the app becomes idle, such as when an XR
|
|
14
|
+
session ends. A release that installed while the app was busy takes over
|
|
15
|
+
then, instead of waiting for the next load.
|
|
16
|
+
|
|
17
|
+
In a JavaScript project, save it as `src/offline.js` and delete the type
|
|
18
|
+
annotations. In a TypeScript project it must be `.ts`: the scaffold's
|
|
19
|
+
`tsconfig.json` has no `allowJs`, so importing a `.js` module fails
|
|
20
|
+
`npm run typecheck`.
|
|
21
|
+
|
|
22
|
+
## Wiring in `src/index.ts`
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { VisibilityState, World } from '@iwsdk/core';
|
|
26
|
+
import projectOptions from 'virtual:iwsdk-project';
|
|
27
|
+
import { checkIdle, keepOfflineCopy, startOffline } from './offline.js';
|
|
28
|
+
|
|
29
|
+
let world: World | undefined;
|
|
30
|
+
const isIdle = () =>
|
|
31
|
+
world?.visibilityState.peek() === VisibilityState.NonImmersive;
|
|
32
|
+
startOffline(isIdle);
|
|
33
|
+
|
|
34
|
+
World.create(
|
|
35
|
+
document.getElementById('scene-container') as HTMLDivElement,
|
|
36
|
+
projectOptions,
|
|
37
|
+
).then((created) => {
|
|
38
|
+
world = created;
|
|
39
|
+
// ... register your systems ...
|
|
40
|
+
keepOfflineCopy(isIdle);
|
|
41
|
+
created.visibilityState.subscribe(() => checkIdle());
|
|
42
|
+
});
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Why each part is there
|
|
46
|
+
|
|
47
|
+
- **Register after the first screen, not at startup.** Registered at startup,
|
|
48
|
+
the worker downloads the release while the page is still downloading it, so
|
|
49
|
+
every file comes down twice. Registered later, the worker takes each file from
|
|
50
|
+
the HTTP cache instead.
|
|
51
|
+
- **Report what came before the worker.** Files the page fetched before the
|
|
52
|
+
worker existed never passed through it. The buffered `PerformanceObserver`
|
|
53
|
+
reports them, and the worker keeps the optional and pinned ones among them.
|
|
54
|
+
The browser buffers 250 resource entries by default; if the first load fetches
|
|
55
|
+
more, raise the limit early with `performance.setResourceTimingBufferSize()`.
|
|
56
|
+
- **Define idle for the app.** `isIdle()` must be `false` whenever a reload
|
|
57
|
+
could lose work or interrupt a session. No XR session is the IWSDK baseline;
|
|
58
|
+
add the app's own state, such as an unsaved edit or a game in progress, and
|
|
59
|
+
call `checkIdle()` when that state ends. When `isIdle()` is `true` and a new
|
|
60
|
+
release has installed, the page sends `'take-over'`, listens for
|
|
61
|
+
`controllerchange`, and reloads into the new release. The worker ignores the
|
|
62
|
+
request while another page of the app is open, so asking again later is safe.
|
|
63
|
+
- **Catch an install already under way.** The browser checks `sw.js` as the page
|
|
64
|
+
navigates, so an update can be installing before the page's script runs, its
|
|
65
|
+
`updatefound` already gone. `watch()` follows `registration.waiting`,
|
|
66
|
+
`registration.installing`, and the next `updatefound`, so none is missed.
|
|
67
|
+
- **Mirror the connection.** `navigator.onLine` and the `online` and `offline`
|
|
68
|
+
events say whether the device has a network, not whether the server answers.
|
|
69
|
+
Use them to disable or explain features that need a connection, and still
|
|
70
|
+
handle failed requests.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Service Worker
|
|
2
|
+
|
|
3
|
+
`scripts/sw.js.template` (copied from `assets/sw.js.template`) has three
|
|
4
|
+
placeholders — `RELEASE`, `FILES`, and `ON_REQUEST` — that the build step fills
|
|
5
|
+
in. It is plain JavaScript with no imports, so it is copied, not bundled. Install
|
|
6
|
+
copies the release, activate removes older releases, and fetch answers from the
|
|
7
|
+
copy.
|
|
8
|
+
|
|
9
|
+
## Request routing
|
|
10
|
+
|
|
11
|
+
| Request | Answered from |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| Anything but a GET | the network, untouched |
|
|
14
|
+
| A pinned third-party URL | its long-lived cache; else the network, and kept |
|
|
15
|
+
| A path in `FILES` | the release cache; the network only if the browser evicted it |
|
|
16
|
+
| A path in `ON_REQUEST` | the release cache once kept; until then the network, kept if its hash matches |
|
|
17
|
+
| A navigation to a folder, such as the site root | that folder's `index.html` from the release cache |
|
|
18
|
+
| Anything else | the network, untouched |
|
|
19
|
+
|
|
20
|
+
## What to change
|
|
21
|
+
|
|
22
|
+
- **`PREFIX`, `KEPT`, `HASH`** — rename for the app. `KEPT` must not start with
|
|
23
|
+
`PREFIX`, or the next activation deletes it.
|
|
24
|
+
- **`PINNED`** — covers IWSDK's controller models, the three.js decoders, and
|
|
25
|
+
the starter's stock models on jsDelivr. Match `three@` to the project's
|
|
26
|
+
three.js revision and `example-assets@` to `src/assets.ts`, and delete the
|
|
27
|
+
stock-model path if the app mirrors those files or never loads them. If the
|
|
28
|
+
app fetches nothing from other origins, delete `PINNED`, `PAIRED`,
|
|
29
|
+
`thirdParty()`, `keepPinned()`, and `keepPair()`.
|
|
30
|
+
|
|
31
|
+
Third-party files often come in families. IWSDK's controller models come as
|
|
32
|
+
`left.glb` and `right.glb` in the same profile folder, so `PAIRED` keeps the
|
|
33
|
+
other hand's model whenever one is kept: a user who only ever used one
|
|
34
|
+
controller online still has both offline. Add a rule like it for any other
|
|
35
|
+
family the app fetches piece by piece.
|
|
36
|
+
|
|
37
|
+
## Behaviour to keep
|
|
38
|
+
|
|
39
|
+
- **Cache-first, with no revalidation.** A page loaded from the copy is exactly
|
|
40
|
+
its release, and a new release arrives only through `sw.js`.
|
|
41
|
+
- **Query strings are ignored**, so a start URL such as `/?source=pwa` gets the
|
|
42
|
+
cached `index.html`.
|
|
43
|
+
- **No `skipWaiting()` of its own.** The worker calls it only on the page's
|
|
44
|
+
`'take-over'` message; the page decides when a release takes over.
|
|
45
|
+
- **A take-over needs the asking page to be alone.** `skipWaiting()` moves every
|
|
46
|
+
open page of the scope onto the new release, and activation deletes the old
|
|
47
|
+
release's cache under them: a second tab in the middle of an XR session would
|
|
48
|
+
load the new release's files, or none offline. So the worker grants
|
|
49
|
+
`'take-over'` only when one window of the scope is open; otherwise the release
|
|
50
|
+
waits until every page has closed, and the browser activates it then.
|
|
51
|
+
- **Only CORS responses are kept.** A `no-cors` request returns an opaque
|
|
52
|
+
response with status `0` and an unreadable body, which cannot be checked.
|
|
53
|
+
|
|
54
|
+
## Where the hash is compared
|
|
55
|
+
|
|
56
|
+
- **At build.** The release is named by a hash of its whole file list, so it
|
|
57
|
+
changes exactly when a listed file changes.
|
|
58
|
+
- **At install, file by file.** The worker looks in this release's own cache
|
|
59
|
+
first (an interrupted install resumes), then in earlier releases' caches, then
|
|
60
|
+
in the HTTP cache, and only then asks the server. Each cached copy carries its
|
|
61
|
+
hash in an `x-content-sha256` header, so an unchanged file is copied across,
|
|
62
|
+
never downloaded.
|
|
63
|
+
- **After every download.** The bytes are hashed before they are cached. A
|
|
64
|
+
mismatch is asked for again with `cache: 'no-cache'`, and a second mismatch
|
|
65
|
+
fails the install, which the browser retries on a later visit. This catches
|
|
66
|
+
stale CDN edges and a deploy that is still spreading.
|
|
67
|
+
- **On a first visit.** The page downloads its files before the worker exists,
|
|
68
|
+
and the worker takes them from the HTTP cache, so nothing crosses the wire
|
|
69
|
+
twice.
|
|
70
|
+
- **For optional files.** The same check runs when one is first fetched: a
|
|
71
|
+
stale copy is served that once and never kept.
|
|
72
|
+
- **For third-party files.** They have no hash in the list. The pinned URL is
|
|
73
|
+
their identity, and each is kept once per device.
|
|
74
|
+
|
|
75
|
+
## Updates
|
|
76
|
+
|
|
77
|
+
A new release installs beside the old one and waits. The page decides when it
|
|
78
|
+
takes over: at once if `isIdle()` is `true`, when the app next calls
|
|
79
|
+
`checkIdle()` while idle, or otherwise at the next load, before the app builds
|
|
80
|
+
anything — each time only if no other page of the app is open. Installing reuses every unchanged file from the old
|
|
81
|
+
release's cache by its hash, so an update downloads only what changed. Optional
|
|
82
|
+
files the old release kept come across while their hash is unchanged, and the
|
|
83
|
+
third-party cache is never touched. After `'take-over'`, activation deletes the
|
|
84
|
+
older release caches and claims the page, which sees `controllerchange` and
|
|
85
|
+
reloads from the new copy.
|
|
86
|
+
|
|
87
|
+
## Vercel headers
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"headers": [
|
|
92
|
+
{
|
|
93
|
+
"source": "/sw.js",
|
|
94
|
+
"headers": [{ "key": "Cache-Control", "value": "no-cache" }]
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"source": "/assets/(.*)",
|
|
98
|
+
"headers": [
|
|
99
|
+
{
|
|
100
|
+
"key": "Cache-Control",
|
|
101
|
+
"value": "public, max-age=31536000, immutable"
|
|
102
|
+
}
|
|
103
|
+
]
|
|
104
|
+
}
|
|
105
|
+
]
|
|
106
|
+
}
|
|
107
|
+
```
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Testing the Offline Copy
|
|
2
|
+
|
|
3
|
+
Six checks prove the design. Each is about what crosses the wire, so the test
|
|
4
|
+
watches the wire.
|
|
5
|
+
|
|
6
|
+
| # | Check | Pass when |
|
|
7
|
+
| - | ----- | --------- |
|
|
8
|
+
| 1 | First visit | the release cache holds every listed file; no file was sent in full twice; no optional file nobody asked for was downloaded; optional and pinned files fetched before the worker existed are kept |
|
|
9
|
+
| 2 | Reload | the server is asked for nothing but `sw.js` |
|
|
10
|
+
| 3 | Offline | with the network off, a reload starts the app and kept files are served; an optional file never fetched online is missing, as it should be |
|
|
11
|
+
| 4 | Update while idle | after one file changes, only that file is downloaded; the new release takes over; the old release cache is gone; kept optional files came across |
|
|
12
|
+
| 5 | Update mid-session | the page is not reloaded during the session; when it ends, the new release takes over |
|
|
13
|
+
| 6 | Two pages open | an update while a second page of the app is open takes over neither page; once only one remains, the next idle moment or load takes it |
|
|
14
|
+
|
|
15
|
+
## Harness
|
|
16
|
+
|
|
17
|
+
- **A logging server.** Serve the built `dist/` from a small server that logs
|
|
18
|
+
every request and answers revalidations with ETags and `304`, as a real host
|
|
19
|
+
does. Count only full `200` responses per path: a path sent twice is a
|
|
20
|
+
duplicate download.
|
|
21
|
+
- **No request interception.** Playwright turns the HTTP cache off whenever a
|
|
22
|
+
route is registered, and the first copy is made from that cache.
|
|
23
|
+
- **A persistent browser profile** (`launchPersistentContext`). It keeps the
|
|
24
|
+
HTTP cache on disk, as on a real device; an in-memory cache may refuse a large
|
|
25
|
+
file.
|
|
26
|
+
- **Polling loops.** Wait by calling `page.evaluate()` in a loop.
|
|
27
|
+
`page.waitForFunction()` does not wait for an async predicate, because a
|
|
28
|
+
promise counts as truthy.
|
|
29
|
+
- **An offline switch.** `context.setOffline(true)` takes the context offline
|
|
30
|
+
for check 3.
|
|
31
|
+
- **An XR session for check 5.** In desktop Chromium the injected IWER emulator
|
|
32
|
+
provides one: call `world.launchXR()` and wait until `world.visibilityState`
|
|
33
|
+
leaves `'non-immersive'`, so `isIdle()` is `false`.
|
|
34
|
+
|
|
35
|
+
Playwright attaches to every service worker, and that can stall activation after
|
|
36
|
+
`skipWaiting()` for over a minute, in some runs and not in others. If checks 4
|
|
37
|
+
or 5 hang on the take-over, drive them over the Chrome DevTools Protocol with
|
|
38
|
+
only the page attached, or by hand.
|
|
39
|
+
|
|
40
|
+
## On the headset
|
|
41
|
+
|
|
42
|
+
Test a production build: `npm run dev` serves no `sw.js`. Build, serve `dist/`
|
|
43
|
+
over plain HTTP on a local port, and forward it so that
|
|
44
|
+
`http://localhost:<port>` counts as a secure context in Meta Quest Browser:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm run build
|
|
48
|
+
python3 -m http.server 4173 --bind 127.0.0.1 --directory dist
|
|
49
|
+
adb reverse tcp:4173 tcp:4173 # then open http://localhost:4173 on the headset
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Not `npx vite preview`: the IWSDK Vite plugin serves it over HTTPS with a
|
|
53
|
+
self-signed certificate, and Quest Browser refuses to register a service worker
|
|
54
|
+
from a page with a certificate error.
|
|
55
|
+
|
|
56
|
+
Clear the origin's storage between runs, for example with the DevTools
|
|
57
|
+
Protocol's `Storage.clearDataForOrigin`, or the site settings in the browser.
|
|
@@ -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.1 sha256=24a1d1e5a61472ec045759f5e385de1843df34b6e43613dcd6b591c439ec69f1 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
## PhysicsBody Component Reference
|
|
2
|
+
|
|
3
|
+
Defines the motion behavior of a physics entity. Import from `@iwsdk/core`.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import { PhysicsBody, PhysicsState } from '@iwsdk/core';
|
|
7
|
+
|
|
8
|
+
entity.addComponent(PhysicsBody, {
|
|
9
|
+
state: PhysicsState.Dynamic,
|
|
10
|
+
linearDamping: 0.0,
|
|
11
|
+
angularDamping: 0.0,
|
|
12
|
+
gravityFactor: 1.0,
|
|
13
|
+
centerOfMass: [Infinity, Infinity, Infinity], // Infinity = auto-compute from shape
|
|
14
|
+
});
|
|
15
|
+
```
|
|
16
|
+
**Properties:**
|
|
17
|
+
|
|
18
|
+
| Property | Type | Default | Description |
|
|
19
|
+
| ---------------- | -------------- | -------------------------------- | ----------------------------------------------------- |
|
|
20
|
+
| `state` | `PhysicsState` | `Dynamic` | Motion type (see below) |
|
|
21
|
+
| `linearDamping` | `Float32` | `0.0` | Air resistance for translation (0 = none, 1 = heavy) |
|
|
22
|
+
| `angularDamping` | `Float32` | `0.0` | Air resistance for rotation |
|
|
23
|
+
| `gravityFactor` | `Float32` | `1.0` | Gravity multiplier (0 = floating, 2 = double gravity) |
|
|
24
|
+
| `centerOfMass` | `Vec3` | `[Infinity, Infinity, Infinity]` | Override center of mass; `Infinity` = auto-compute |
|
|
25
|
+
|
|
26
|
+
**Read-only properties** (updated each frame by `PhysicsSystem`):
|
|
27
|
+
|
|
28
|
+
| Property | Type | Description |
|
|
29
|
+
| ------------------ | ------ | ------------------------ |
|
|
30
|
+
| `_linearVelocity` | `Vec3` | Current linear velocity |
|
|
31
|
+
| `_angularVelocity` | `Vec3` | Current angular velocity |
|
|
32
|
+
|
|
33
|
+
### PhysicsState Enum
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
PhysicsState.Static; // Immovable (walls, floors). Zero simulation cost.
|
|
37
|
+
PhysicsState.Dynamic; // Fully simulated. Responds to forces, gravity, collisions.
|
|
38
|
+
PhysicsState.Kinematic; // Programmatically moved. Pushes dynamic bodies but is not affected by them.
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**When to use each:**
|
|
42
|
+
|
|
43
|
+
- **Static** -- Environment geometry (walls, floors, tables). Objects that never move but block dynamic bodies.
|
|
44
|
+
- **Dynamic** -- Objects that respond to physics (balls, crates, interactive props). Default for most gameplay objects.
|
|
45
|
+
- **Kinematic** -- Moving platforms that won't be pushed by other physics bodies.
|
|
46
|
+
|
|
47
|
+
## PhysicsShape Component Reference
|
|
48
|
+
|
|
49
|
+
Defines the collision geometry and material properties. Both `PhysicsShape` and `PhysicsBody` are required for physics simulation.
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { PhysicsShape, PhysicsShapeType } from '@iwsdk/core';
|
|
53
|
+
|
|
54
|
+
entity.addComponent(PhysicsShape, {
|
|
55
|
+
shape: PhysicsShapeType.Auto,
|
|
56
|
+
dimensions: [0, 0, 0],
|
|
57
|
+
density: 1.0,
|
|
58
|
+
restitution: 0.0,
|
|
59
|
+
friction: 0.5,
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Properties:**
|
|
64
|
+
|
|
65
|
+
| Property | Type | Default | Description |
|
|
66
|
+
| ------------- | ------------------ | ----------- | ------------------------------------------------------------------------------------- |
|
|
67
|
+
| `shape` | `PhysicsShapeType` | `Auto` | Collision shape type |
|
|
68
|
+
| `dimensions` | `Vec3` | `[0, 0, 0]` | Shape-specific dimensions array. Not applicable when `PhysicsShapeType.Auto` is used. |
|
|
69
|
+
| `density` | `Float32` | `1.0` | Mass density (kg/m^3). Higher = heavier. |
|
|
70
|
+
| `restitution` | `Float32` | `0.0` | Bounciness (0 = no bounce, 1 = perfect bounce) |
|
|
71
|
+
| `friction` | `Float32` | `0.5` | Surface friction (0 = ice, 1 = rubber) |
|
|
72
|
+
|
|
73
|
+
### PhysicsShapeType Enum
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
PhysicsShapeType.Sphere; // dimensions[0] = radius
|
|
77
|
+
PhysicsShapeType.Box; // dimensions = [width, height, depth]
|
|
78
|
+
PhysicsShapeType.Cylinder; // dimensions[0] = radius, dimensions[1] = height
|
|
79
|
+
PhysicsShapeType.Capsules; // dimensions[0] = radius, dimensions[1] = total height (>= 2 * radius)
|
|
80
|
+
PhysicsShapeType.ConvexHull; // Convex wrapper around mesh vertices (dimensions ignored)
|
|
81
|
+
PhysicsShapeType.TriMesh; // Exact mesh triangles (dimensions ignored). Expensive; use for static only.
|
|
82
|
+
PhysicsShapeType.Auto; // Auto-detect from Three.js geometry type
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Dimensions by Shape Type
|
|
86
|
+
|
|
87
|
+
The `dimensions` property is a `Vec3` (`[x, y, z]`) whose meaning changes depending on the selected shape:
|
|
88
|
+
|
|
89
|
+
| Shape Type | `dimensions[0]` | `dimensions[1]` | `dimensions[2]` | Example |
|
|
90
|
+
| ------------ | --------------- | --------------- | --------------- | ------------------------------- |
|
|
91
|
+
| `Sphere` | radius | _(unused)_ | _(unused)_ | `[0.5, 0, 0]` -- sphere r=0.5 |
|
|
92
|
+
| `Box` | width | height | depth | `[1, 2, 0.5]` -- 1×2×0.5 box |
|
|
93
|
+
| `Cylinder` | radius | height | _(unused)_ | `[0.3, 1.5, 0]` -- r=0.3, h=1.5 |
|
|
94
|
+
| `Capsules` | radius | total height | _(unused)_ | `[0.3, 1.5, 0]` -- r=0.3, h=1.5 |
|
|
95
|
+
| `ConvexHull` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Computed from mesh vertices |
|
|
96
|
+
|
|
97
|
+
Capsule total height is measured end to end and must be at least twice its
|
|
98
|
+
radius. A total height equal to the diameter produces a sphere-length capsule.
|
|
99
|
+
| `TriMesh` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Computed from mesh triangles |
|
|
100
|
+
| `Auto` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Auto-detected from geometry |
|
|
101
|
+
|
|
102
|
+
For `ConvexHull`, `TriMesh`, and `Auto`, the dimensions array is not used -- the shape is derived directly from the entity's Three.js geometry.
|
|
103
|
+
|
|
104
|
+
**Auto-detection mapping:**
|
|
105
|
+
|
|
106
|
+
| Three.js Geometry | Detected Shape | Dimensions Source |
|
|
107
|
+
| ------------------------------- | -------------- | ----------------------------------------------- |
|
|
108
|
+
| `SphereGeometry` | Sphere | `radius` from geometry parameters |
|
|
109
|
+
| `BoxGeometry` | Box | `width, height, depth` from parameters |
|
|
110
|
+
| `PlaneGeometry` | Box | `width, height, 0.01` (thin box) |
|
|
111
|
+
| `CylinderGeometry` | Cylinder | Average of `radiusTop`/`radiusBottom`, `height` |
|
|
112
|
+
| `BufferGeometry` (generic/GLTF) | ConvexHull | From mesh vertices |
|
|
113
|
+
| Unknown | Box (fallback) | From bounding box |
|
|
114
|
+
|
|
115
|
+
**Performance guidance:**
|
|
116
|
+
|
|
117
|
+
- Sphere/Box/Cylinder: Fastest collision detection. Prefer these when possible.
|
|
118
|
+
- ConvexHull: Good balance for complex meshes. Default for GLTF models via Auto.
|
|
119
|
+
- TriMesh: Exact geometry collision. Use only for static objects (walls, floors, terrain).
|
|
120
|
+
|
|
121
|
+
## PhysicsManipulation Component Reference
|
|
122
|
+
|
|
123
|
+
A **one-shot** component for applying forces and velocities. Automatically removed after one frame.
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
import { PhysicsManipulation } from '@iwsdk/core';
|
|
127
|
+
|
|
128
|
+
// Apply an impulse (removed automatically after 1 frame)
|
|
129
|
+
entity.addComponent(PhysicsManipulation, {
|
|
130
|
+
force: [0, 10, 0], // Impulse force vector
|
|
131
|
+
linearVelocity: [0, 0, 0], // Override linear velocity (0 = no change)
|
|
132
|
+
angularVelocity: [0, 0, 0], // Override angular velocity (0 = no change)
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
**Properties:**
|
|
137
|
+
|
|
138
|
+
| Property | Type | Default | Description |
|
|
139
|
+
| ----------------- | ------ | ----------- | --------------------------------------- |
|
|
140
|
+
| `force` | `Vec3` | `[0, 0, 0]` | Impulse force applied at center of mass |
|
|
141
|
+
| `linearVelocity` | `Vec3` | `[0, 0, 0]` | Sets absolute linear velocity |
|
|
142
|
+
| `angularVelocity` | `Vec3` | `[0, 0, 0]` | Sets absolute angular velocity |
|
|
143
|
+
|
|
144
|
+
**The component is auto-removed** by `PhysicsSystem` after applying values. For sustained forces, re-add each frame:
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
update() {
|
|
148
|
+
if (!entity.hasComponent(PhysicsManipulation)) {
|
|
149
|
+
entity.addComponent(PhysicsManipulation, { force: [0, 5, 0] });
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
## Material Tuning Guide
|
|
2
|
+
|
|
3
|
+
Adjust `density`, `restitution`, and `friction` on `PhysicsShape` to simulate different materials:
|
|
4
|
+
|
|
5
|
+
| Material | Density | Restitution | Friction |
|
|
6
|
+
| ----------- | ------- | ----------- | -------- |
|
|
7
|
+
| Wood | 0.6 | 0.3 | 0.5 |
|
|
8
|
+
| Metal/Steel | 7.8 | 0.2 | 0.4 |
|
|
9
|
+
| Rubber | 1.1 | 0.8 | 0.9 |
|
|
10
|
+
| Ice | 0.9 | 0.1 | 0.05 |
|
|
11
|
+
| Concrete | 2.4 | 0.1 | 0.7 |
|
|
12
|
+
| Foam/Light | 0.05 | 0.1 | 0.6 |
|
|
13
|
+
| Bouncy ball | 1.0 | 0.95 | 0.5 |
|
|
14
|
+
|
|
15
|
+
## System Priority Order
|
|
16
|
+
|
|
17
|
+
Physics runs in a carefully orchestrated sequence:
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
Priority -5: LocomotionSystem (Player movement)
|
|
21
|
+
Priority -4: InputSystem (Controller/hand input)
|
|
22
|
+
Priority -3: GrabSystem (Grab interactions)
|
|
23
|
+
Priority -2: PhysicsSystem (Physics simulation)
|
|
24
|
+
Priority -1: SceneUnderstanding (AR plane/mesh updates)
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Register custom physics-related systems after the built-in PhysicsSystem (priority > -2) to read updated transforms:
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
world.registerSystem(MyPhysicsLogicSystem, { priority: 5 });
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## PhysicsSystem Configuration
|
|
34
|
+
|
|
35
|
+
The project manifest accepts execution, frequency, and interpolation options:
|
|
36
|
+
|
|
37
|
+
```jsonc
|
|
38
|
+
"physics": {
|
|
39
|
+
"useWorker": true,
|
|
40
|
+
"updateFrequency": 60,
|
|
41
|
+
"interpolation": true
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- `useWorker` defaults to `true`. Set it to `false` to run the same runtime and message protocol on the main thread.
|
|
46
|
+
- `updateFrequency` defaults to 60 Hz and is capped at 240 Hz.
|
|
47
|
+
- `interpolation` defaults to `true` and smooths rendered transforms between fixed physics snapshots.
|
|
48
|
+
- `applyScale` defaults to `false`. `Auto` shapes and mesh-derived `ConvexHull`/`TriMesh` shapes always use the object's world scale. Shapes with explicit `dimensions` ignore it unless `applyScale` is `true`; a scaled object with explicit dimensions logs a one-time warning. Prefer `applyScale: true` in new projects and author dimensions in the object's unscaled units.
|
|
49
|
+
|
|
50
|
+
The system also accepts a reactive `gravity` config (defaults to Earth gravity):
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import { PhysicsSystem } from '@iwsdk/core';
|
|
54
|
+
|
|
55
|
+
const physicsSystem = world.getSystem(PhysicsSystem);
|
|
56
|
+
physicsSystem.config.gravity.value = [0, -9.81, 0]; // Earth gravity (default)
|
|
57
|
+
physicsSystem.config.gravity.value = [0, -1.62, 0]; // Moon gravity
|
|
58
|
+
physicsSystem.config.gravity.value = [0, 0, 0]; // Zero gravity
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Native Scene JSON Configuration
|
|
62
|
+
|
|
63
|
+
Physics components can be configured declaratively in native scene JSON files:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"id": "dynamic-box",
|
|
68
|
+
"content": { "type": "asset", "asset": "box" },
|
|
69
|
+
"transform": { "position": [0, 1.5, -1] },
|
|
70
|
+
"components": {
|
|
71
|
+
"PhysicsShape": {
|
|
72
|
+
"shape": "Box",
|
|
73
|
+
"dimensions": [1, 1, 1],
|
|
74
|
+
"density": 1,
|
|
75
|
+
"friction": 0.5,
|
|
76
|
+
"restitution": 0
|
|
77
|
+
},
|
|
78
|
+
"PhysicsBody": {
|
|
79
|
+
"state": "DYNAMIC",
|
|
80
|
+
"gravityFactor": 1,
|
|
81
|
+
"linearDamping": 0,
|
|
82
|
+
"angularDamping": 0
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**State enum values in scene JSON:**
|
|
89
|
+
|
|
90
|
+
- `STATIC`
|
|
91
|
+
- `DYNAMIC`
|
|
92
|
+
- `KINEMATIC`
|
|
93
|
+
|
|
94
|
+
**Shape enum values in scene JSON:**
|
|
95
|
+
|
|
96
|
+
- `Sphere`
|
|
97
|
+
- `Box`
|
|
98
|
+
- `Cylinder`
|
|
99
|
+
- `Capsules`
|
|
100
|
+
- `ConvexHull`
|
|
101
|
+
- `TriMesh`
|
|
102
|
+
- `Auto`
|