@iwsdk/cli 1.1.0 → 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,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "UIKitML panels"
|
|
3
|
+
globs:
|
|
4
|
+
- "public/ui/**"
|
|
5
|
+
alwaysApply: false
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# UIKitML panels
|
|
9
|
+
|
|
10
|
+
HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
|
|
11
|
+
|
|
12
|
+
**Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
|
|
13
|
+
0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
|
|
14
|
+
|
|
15
|
+
**Panels are single-sided and face +Z.** To aim one at a camera, yaw by
|
|
16
|
+
`atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
|
|
17
|
+
nothing, reports no error, and still returns `valid: true` from
|
|
18
|
+
`scene_render_file`; the only signal is its absence from
|
|
19
|
+
`renderStats.visibleNodeIds`.
|
|
20
|
+
|
|
21
|
+
Verified working: `display: flex`, `flex-direction`, `align-items`,
|
|
22
|
+
`justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
|
|
23
|
+
`height`, `background-color`, `border-color`, `border-width`, `border-radius`,
|
|
24
|
+
`font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
|
|
25
|
+
`button` all work.
|
|
26
|
+
|
|
27
|
+
Expand shorthands (`padding: 12 18` → four properties), use unitless
|
|
28
|
+
line-height multipliers, and prefer uniform `border-color`/`border-width` over
|
|
29
|
+
directional variants. Parser errors include source locations.
|
|
30
|
+
|
|
31
|
+
**Production builds drop unused Lucide icons.** They keep only icons named in
|
|
32
|
+
`public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
|
|
33
|
+
from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
|
|
34
|
+
they fail after `npm run build`.
|
|
35
|
+
|
|
36
|
+
## Runtime API
|
|
37
|
+
|
|
38
|
+
Resolve the placed panel by **scene node id**, then elements by their `id`
|
|
39
|
+
attribute:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
|
|
43
|
+
const chip = panel?.getElementById<UIKit.Text>('finish-gold');
|
|
44
|
+
chip?.addEventListener('click', onClick);
|
|
45
|
+
chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`setProperties` updates both text (`{ text }`) and style
|
|
49
|
+
(`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
|
|
50
|
+
including over class-based styles from the `<style>` block. `UIKit.Text` is the
|
|
51
|
+
public element type; no deep import from `@pmndrs/uikit` is needed.
|
|
52
|
+
|
|
53
|
+
Three distinct identities, don't conflate them: the **manifest ID** names the
|
|
54
|
+
reusable asset, the **scene node ID** names the placed instance, and the element
|
|
55
|
+
`id` names a field inside it. Never depend on a transient entity index.
|
|
56
|
+
|
|
57
|
+
Give the panel node `RayInteractable` so clicks land.
|
|
58
|
+
|
|
59
|
+
The editor render does not run application systems, so `scene_screenshot` can
|
|
60
|
+
never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
|
|
61
|
+
can.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
66
|
+
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
67
|
+
than improvising. This file is the format reference it relies on.
|
|
68
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=ce002bd4759a1d087c3e18fd3e2a9a009eb3bef5561d0a698f86726a1bd7f9c3 name=uikitml.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "src/assets.ts,src/assets.js,src/iwsdk/assets.ts,src/iwsdk/assets.js,src/scene-assets/**"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Asset manifest contract
|
|
6
|
+
|
|
7
|
+
`src/assets.ts` is imported **independently by the app runtime and the editor**,
|
|
8
|
+
in separate JS realms. It must therefore be deterministic and self-contained:
|
|
9
|
+
|
|
10
|
+
- no `World`, scene, iframe, editor object or DOM access
|
|
11
|
+
- no timers, no fetching ambient state
|
|
12
|
+
- no reliance on singleton object identity across realms
|
|
13
|
+
- prototypes immutable after registration, and never parented
|
|
14
|
+
|
|
15
|
+
A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
|
|
16
|
+
or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
|
|
17
|
+
`HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
|
|
18
|
+
as scene content; audio/texture/HDR are for application systems.
|
|
19
|
+
|
|
20
|
+
Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
|
|
21
|
+
builds resolve identically. A file in `public/` is **not** available to a scene
|
|
22
|
+
until it is registered here.
|
|
23
|
+
|
|
24
|
+
## Procedural assets
|
|
25
|
+
|
|
26
|
+
Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
|
|
27
|
+
register it under a stable ID. The registry rejects an already-parented
|
|
28
|
+
prototype.
|
|
29
|
+
|
|
30
|
+
Every placement is a distinct hierarchy clone, but **geometry and materials stay
|
|
31
|
+
shared**. Never dispose them from a placed clone; world teardown owns their
|
|
32
|
+
lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
|
|
33
|
+
one instance — mutating the shared material in place changes every instance.
|
|
34
|
+
|
|
35
|
+
Bounds come from `Box3` over the instantiated asset and drive placement,
|
|
36
|
+
selection, framing and scatter collision. Put the origin where composition wants
|
|
37
|
+
it (usually floor contact, or the object's own pivot), keep transforms finite,
|
|
38
|
+
and don't let invisible helpers inflate bounds.
|
|
39
|
+
|
|
40
|
+
## Cost
|
|
41
|
+
|
|
42
|
+
Split tessellation by viewing distance rather than using one budget everywhere: a
|
|
43
|
+
close-range hero model and coarser display copies of the same form are two
|
|
44
|
+
prototypes from one factory function. Sphere/lathe segment counts dominate small
|
|
45
|
+
repeated detail more than people expect — check `renderStats.triangles` rather
|
|
46
|
+
than guessing.
|
|
47
|
+
|
|
48
|
+
Reuse material instances within a module. Prefer prefabs plus a deterministic
|
|
49
|
+
pattern for repetition; a pattern whose prefab resolves to a single component-free
|
|
50
|
+
mesh lowers to one `InstancedMesh`.
|
|
51
|
+
|
|
52
|
+
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
53
|
+
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
54
|
+
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
55
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=6949b512ef5bb71b488b7e8544b4e572f46f73f72a941b248a0856228299bfad name=assets-and-manifest.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "src/**/*.ts,src/**/*.js"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# ECS API reference
|
|
6
|
+
|
|
7
|
+
## Field types
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
|
|
11
|
+
Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
|
|
12
|
+
Types.Object // avoid — not optimised
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Component
|
|
16
|
+
|
|
17
|
+
Declare in a system-free module, then list it in `src/components.ts` via
|
|
18
|
+
`defineComponents()` or the editor cannot author it.
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
export const MyComponent = createComponent('MyComponent', {
|
|
22
|
+
speed: { type: Types.Float32, default: 1 },
|
|
23
|
+
tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
|
|
28
|
+
`widget` — drives the editor inspector.
|
|
29
|
+
|
|
30
|
+
## System
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
export class MySystem extends createSystem(
|
|
34
|
+
{
|
|
35
|
+
items: { required: [MyComponent] },
|
|
36
|
+
active: { required: [MyComponent], excluded: [Grabbed] },
|
|
37
|
+
},
|
|
38
|
+
{ speed: { type: Types.Float32, default: 1 } }, // optional config
|
|
39
|
+
) {
|
|
40
|
+
private temp!: Vector3;
|
|
41
|
+
|
|
42
|
+
init() {
|
|
43
|
+
this.temp = new Vector3();
|
|
44
|
+
this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
|
|
45
|
+
this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
update(delta: number, time: number) {
|
|
49
|
+
for (const entity of this.queries.active.entities) { /* no allocations */ }
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
|
|
55
|
+
`lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
|
|
56
|
+
entities in a transient state — e.g. excluding `Grabbed` so a held object is left
|
|
57
|
+
alone.
|
|
58
|
+
|
|
59
|
+
Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
|
|
60
|
+
|
|
61
|
+
Read fields with `entity.getValue(Component, 'field')`. For vector fields use
|
|
62
|
+
`entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
|
|
63
|
+
no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
|
|
64
|
+
|
|
65
|
+
## Interaction components
|
|
66
|
+
|
|
67
|
+
`RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
|
|
68
|
+
and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
|
|
69
|
+
proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
|
|
70
|
+
ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
|
|
71
|
+
`GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
|
|
72
|
+
defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
|
|
73
|
+
|
|
74
|
+
`DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
|
|
75
|
+
`MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
|
|
76
|
+
`detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
|
|
77
|
+
`targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
|
|
78
|
+
no custom code.
|
|
79
|
+
|
|
80
|
+
For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
|
|
81
|
+
`getHolderHand(entity)` — never deep-import `Handle`.
|
|
82
|
+
|
|
83
|
+
## XR input
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const pad = this.input.xr.gamepads.right;
|
|
87
|
+
pad?.getButtonDown(InputComponent.Trigger); // just pressed
|
|
88
|
+
pad?.getAxesValues(InputComponent.Thumbstick);
|
|
89
|
+
this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
|
|
93
|
+
buttons. Browser controls live at `world.input.keyboard` and
|
|
94
|
+
`world.input.browserGamepads`.
|
|
95
|
+
|
|
96
|
+
## Lifecycle
|
|
97
|
+
|
|
98
|
+
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
99
|
+
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
100
|
+
`getWorldPosition()` when logic needs the true viewer position.
|
|
101
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=724a02986ce0999bc31c02b4f1e4a7b6b83c9966f994979a340e36b6243d26fd name=ecs-api.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "public/scenes/**"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Scene JSON — things that fail silently
|
|
6
|
+
|
|
7
|
+
Format reference lives in
|
|
8
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
9
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
10
|
+
it for imports, prefabs, patterns, or a schema detail not covered by active
|
|
11
|
+
guidance. For ordinary flat node, component, and authored-view edits, this rule,
|
|
12
|
+
the existing scene, and the active specialist are sufficient. This file is only
|
|
13
|
+
the short list of behaviours that produce no error when you get them wrong.
|
|
14
|
+
|
|
15
|
+
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
16
|
+
closed — an unknown field fails validation.
|
|
17
|
+
|
|
18
|
+
## Imports stop at the authoring boundary
|
|
19
|
+
|
|
20
|
+
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
21
|
+
scenes remain useful for composition. The editable scene session and application
|
|
22
|
+
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
23
|
+
`npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
|
|
24
|
+
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
25
|
+
later human editor changes.
|
|
26
|
+
|
|
27
|
+
## The player materialises at the scene origin
|
|
28
|
+
|
|
29
|
+
`0,0,0` unless the document authors `player.transform`. Nothing warns you. A
|
|
30
|
+
scene can pass every authored camera view and still spawn the player inside the
|
|
31
|
+
geometry, because review cameras are not the viewpoint that ships. Keep that
|
|
32
|
+
volume clear or place the player deliberately, and author a diagnostic view at
|
|
33
|
+
player eye height to prove it.
|
|
34
|
+
|
|
35
|
+
## `visibleNodeIds` is the silent-failure detector
|
|
36
|
+
|
|
37
|
+
`renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
|
|
38
|
+
did not appear — even when the image looks plausible and `valid` is `true`. Check
|
|
39
|
+
it against what you expect rather than trusting the picture. Single-sided
|
|
40
|
+
surfaces facing away from the camera are the usual cause, and they report nothing.
|
|
41
|
+
`ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
|
|
42
|
+
content is one of them is never listed; check the object it grounds instead.
|
|
43
|
+
|
|
44
|
+
## Component keys come in two forms
|
|
45
|
+
|
|
46
|
+
Root-level components use the namespaced form
|
|
47
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
48
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
49
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
50
|
+
node already uses instead of normalising.
|
|
51
|
+
|
|
52
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
53
|
+
|
|
54
|
+
## Browser hero views and XR spawn framing are distinct
|
|
55
|
+
|
|
56
|
+
Outside immersive XR, the hero authoring view supersedes `world.render.camera`
|
|
57
|
+
from `iwsdk.config.json` once the level initialises. While XR is presenting,
|
|
58
|
+
the tracked player rig owns the camera and the hero view is intentionally not
|
|
59
|
+
applied. Use the hero view for editor/browser framing, and validate important
|
|
60
|
+
content from the authored `player.transform` spawn (or the default standing
|
|
61
|
+
view near `[0, 1.6, 0]`) before accepting XR framing.
|
|
62
|
+
|
|
63
|
+
## Validation
|
|
64
|
+
|
|
65
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
66
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
67
|
+
back. Render each changed module before the root.
|
|
68
|
+
|
|
69
|
+
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
70
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
71
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=c73f635cec34f9e99b2bc59ffe63583842d40e419a499225a56cbb7838d9bccd name=scene-json.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
applyTo: "public/ui/**"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# UIKitML panels
|
|
6
|
+
|
|
7
|
+
HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
|
|
8
|
+
|
|
9
|
+
**Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
|
|
10
|
+
0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
|
|
11
|
+
|
|
12
|
+
**Panels are single-sided and face +Z.** To aim one at a camera, yaw by
|
|
13
|
+
`atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
|
|
14
|
+
nothing, reports no error, and still returns `valid: true` from
|
|
15
|
+
`scene_render_file`; the only signal is its absence from
|
|
16
|
+
`renderStats.visibleNodeIds`.
|
|
17
|
+
|
|
18
|
+
Verified working: `display: flex`, `flex-direction`, `align-items`,
|
|
19
|
+
`justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
|
|
20
|
+
`height`, `background-color`, `border-color`, `border-width`, `border-radius`,
|
|
21
|
+
`font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
|
|
22
|
+
`button` all work.
|
|
23
|
+
|
|
24
|
+
Expand shorthands (`padding: 12 18` → four properties), use unitless
|
|
25
|
+
line-height multipliers, and prefer uniform `border-color`/`border-width` over
|
|
26
|
+
directional variants. Parser errors include source locations.
|
|
27
|
+
|
|
28
|
+
**Production builds drop unused Lucide icons.** They keep only icons named in
|
|
29
|
+
`public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
|
|
30
|
+
from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
|
|
31
|
+
they fail after `npm run build`.
|
|
32
|
+
|
|
33
|
+
## Runtime API
|
|
34
|
+
|
|
35
|
+
Resolve the placed panel by **scene node id**, then elements by their `id`
|
|
36
|
+
attribute:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
|
|
40
|
+
const chip = panel?.getElementById<UIKit.Text>('finish-gold');
|
|
41
|
+
chip?.addEventListener('click', onClick);
|
|
42
|
+
chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`setProperties` updates both text (`{ text }`) and style
|
|
46
|
+
(`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
|
|
47
|
+
including over class-based styles from the `<style>` block. `UIKit.Text` is the
|
|
48
|
+
public element type; no deep import from `@pmndrs/uikit` is needed.
|
|
49
|
+
|
|
50
|
+
Three distinct identities, don't conflate them: the **manifest ID** names the
|
|
51
|
+
reusable asset, the **scene node ID** names the placed instance, and the element
|
|
52
|
+
`id` names a field inside it. Never depend on a transient entity index.
|
|
53
|
+
|
|
54
|
+
Give the panel node `RayInteractable` so clicks land.
|
|
55
|
+
|
|
56
|
+
The editor render does not run application systems, so `scene_screenshot` can
|
|
57
|
+
never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
|
|
58
|
+
can.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
63
|
+
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
64
|
+
than improvising. This file is the format reference it relies on.
|
|
65
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f06c88f681a856a0b8b93b5552257dd316f189082dfc0a6bca87e2e642ecbb3e name=uikitml.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -1,5 +1,14 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=bb25ffd600c99d3f30cdc95518bb89161659907c667de45adcb29315b669bc7f -->
|
|
1
2
|
# IWSDK project
|
|
2
3
|
|
|
4
|
+
IWSDK changes faster than model training data. GLXF scenes, the external 0.4
|
|
5
|
+
scene editor and its Vite plugin, and the UIKitML-compile and glTF-optimizer Vite
|
|
6
|
+
plugins were removed in 0.5: scenes are native `*.iwsdk.scene.json` files edited
|
|
7
|
+
in IWSDK's built-in editor, and `@iwsdk/vite-plugin-dev` is the only IWSDK Vite
|
|
8
|
+
plugin. Trust this file and the project skills over what you remember about
|
|
9
|
+
IWSDK. To upgrade IWSDK, run `npx @iwsdk/cli@latest upgrade` and follow the
|
|
10
|
+
migration guides it writes to `.iwsdk/migrations/`.
|
|
11
|
+
|
|
3
12
|
A Vite + TypeScript or JavaScript app, but several things do **not** work the way
|
|
4
13
|
a normal Vite project works. Read this section before assuming anything.
|
|
5
14
|
|
|
@@ -16,6 +25,12 @@ applicable IWSDK guide or concept page.
|
|
|
16
25
|
|
|
17
26
|
## What is not standard Vite
|
|
18
27
|
|
|
28
|
+
**No `iwsdk.config.json` in this project?** IWSDK was added by hand. Run
|
|
29
|
+
`npx @iwsdk/create@latest . --yes --target vr` (`ar` for mixed reality,
|
|
30
|
+
`browser` for desktop 3D) to add the project manifest, an empty scene, and a
|
|
31
|
+
`virtual:iwsdk-project` entry in `src/iwsdk/` without overwriting any file; the
|
|
32
|
+
rest of this file assumes them.
|
|
33
|
+
|
|
19
34
|
**`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
|
|
20
35
|
the active scene, the asset module, the component module, and all XR/world
|
|
21
36
|
features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
|
|
@@ -44,12 +59,29 @@ tabGeneration on every physical command. Reload is supported through the page
|
|
|
44
59
|
bridge; screenshot, snapshot, interaction, profiling, console capture, and the
|
|
45
60
|
managed editor are host-only. Rediscover after reload to get the new generation.
|
|
46
61
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
62
|
+
**Choose the session mode before the first `dev up`, and pass it explicitly**
|
|
63
|
+
(the CLI default is headed):
|
|
64
|
+
|
|
65
|
+
- `--ai-mode collaborate` (headed, draws every frame, Runtime/Editor toggle)
|
|
66
|
+
when the user wants to watch or steer the work as it happens: they ask to see
|
|
67
|
+
it, are pairing live, or will judge visuals or motion by eye.
|
|
68
|
+
- `--ai-mode agent` (headless, draws only when a tool needs pixels, fast without
|
|
69
|
+
a GPU) for everything else: autonomous or background work, CI, a remote host
|
|
70
|
+
or no display.
|
|
71
|
+
|
|
72
|
+
If the request does not say and the user is there, ask once whether they want to
|
|
73
|
+
watch in a browser window or let you work headless; if nobody can answer, use
|
|
74
|
+
agent. That one question is allowed even where a playbook avoids pausing; put it
|
|
75
|
+
in your first reply, and start agent mode if no answer has come by the time you
|
|
76
|
+
need the session. Reuse a healthy session in whatever mode it runs, and announce
|
|
77
|
+
any mode change before restarting. Headless screenshots always show a fresh
|
|
78
|
+
frame, but frame rate there means nothing; the iwsdk-dev skill's
|
|
79
|
+
`references/headless-rendering.md` covers exact frames, filmstrips and
|
|
80
|
+
`RuntimeSettings`. In a visible collaboration session, use the Runtime/Editor
|
|
81
|
+
toggle in the single managed Chromium window. Its expected unsupported-flag
|
|
82
|
+
banner comes from `--ignore-certificate-errors` for the local development
|
|
83
|
+
certificate. Playwright may add separate sandbox-related flags in constrained
|
|
84
|
+
environments.
|
|
53
85
|
|
|
54
86
|
**`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
|
|
55
87
|
realms** — once by the app runtime, once by the editor. It must be deterministic
|
|
@@ -70,18 +102,17 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
|
|
|
70
102
|
|
|
71
103
|
## Traps that produce silent failures
|
|
72
104
|
|
|
73
|
-
| Trap | Symptom | Fix
|
|
74
|
-
| -------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
75
|
-
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface
|
|
76
|
-
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform`
|
|
77
|
-
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output
|
|
78
|
-
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()`
|
|
79
|
-
| `setValue` on a Vec2/Vec3/Vec4
|
|
80
|
-
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only
|
|
81
|
-
| `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`)
|
|
82
|
-
| `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it
|
|
83
|
-
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'`
|
|
84
|
-
| `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
|
|
105
|
+
| Trap | Symptom | Fix |
|
|
106
|
+
| -------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
107
|
+
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
|
|
108
|
+
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
|
|
109
|
+
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
|
|
110
|
+
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
|
|
111
|
+
| `setValue` on a Vec2/Vec3/Vec4 field | throws in elics 3.4.x | use `entity.getVectorView(...)` (Color fields take `setValue` with hex or `Color`) |
|
|
112
|
+
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
|
|
113
|
+
| `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`) |
|
|
114
|
+
| `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it |
|
|
115
|
+
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
|
|
85
116
|
|
|
86
117
|
## Verify before you claim it works
|
|
87
118
|
|
|
@@ -112,11 +143,21 @@ active XR session (`npx @iwsdk/cli xr status`). A flat runtime screenshot taken
|
|
|
112
143
|
outside XR can prove that the app renders, but it cannot prove immersive pose or
|
|
113
144
|
interaction correctness.
|
|
114
145
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
146
|
+
**When the user wants to try the app in a headset themselves**, give them a
|
|
147
|
+
plain session, never a native-control one. A session started with
|
|
148
|
+
`--native-xr-control` hands the head pose and controllers of every Quest Browser
|
|
149
|
+
page it serves to the CLI, with or without a pairing token in the URL, so the
|
|
150
|
+
user's own movement does nothing. If this session was started with
|
|
151
|
+
`--native-xr-control`, or you cannot tell, first run
|
|
152
|
+
`npx @iwsdk/cli dev restart` with the session's own `--ai-mode` and without that
|
|
153
|
+
flag; say so before restarting. Then run `npx @iwsdk/cli dev status` and give the
|
|
154
|
+
user a plain URL, never a `runtime pair-headset` URL: on the same Wi-Fi network,
|
|
155
|
+
one from `data.runtimeUrls.network` (they accept the expected local certificate
|
|
156
|
+
warning); on a Quest connected over USB, run
|
|
157
|
+
`adb -s <serial> reverse tcp:<port> tcp:<port>` and give
|
|
158
|
+
`data.runtimeUrls.local`. Invoke `iwsdk-native-xr-test` only when you drive the
|
|
159
|
+
headset yourself: automating, scripting, or debugging the app on a USB Quest.
|
|
160
|
+
See [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
|
|
120
161
|
for the complete workflow.
|
|
121
162
|
|
|
122
163
|
**Meta VR Glasses are not a Quest.** Their view is much narrower (37° left and
|
|
@@ -175,11 +216,14 @@ The selected playbook routes work to the narrowest owning specialist:
|
|
|
175
216
|
- a model-local defect found during composition routes back to `iwsdk-build-model`;
|
|
176
217
|
a placement or lighting defect stays in `iwsdk-compose-scene`.
|
|
177
218
|
|
|
178
|
-
UI authoring, physics, depth occlusion, grab and ray interaction testing,
|
|
179
|
-
frame-stepping,
|
|
180
|
-
the selected `iwsdk-dev` playbook calls for
|
|
219
|
+
UI authoring, physics, depth occlusion, grab and ray interaction testing, and
|
|
220
|
+
debugging (including ECS frame-stepping, in `iwsdk-debug`) have their own
|
|
221
|
+
project skills. Use them only when the selected `iwsdk-dev` playbook calls for
|
|
222
|
+
the matching specialty.
|
|
223
|
+
Invoke `iwsdk-upgrade` whenever the user asks to upgrade or bump IWSDK.
|
|
181
224
|
Two device-testing skills are invoked directly: `iwsdk-native-xr-test` whenever
|
|
182
|
-
|
|
225
|
+
you will drive the app on a connected Quest yourself (automate, script-test, or
|
|
226
|
+
debug it), never when the user wants to put the headset on and try it, and
|
|
183
227
|
`iwsdk-glasses-test` whenever the user targets Meta VR Glasses or asks for gaze
|
|
184
228
|
input.
|
|
185
229
|
|
|
@@ -199,6 +243,10 @@ public/scenes/ *.iwsdk.scene.json — composition only
|
|
|
199
243
|
public/ui/ *.uikitml — runtime-loaded panels
|
|
200
244
|
```
|
|
201
245
|
|
|
246
|
+
An app that added IWSDK to an existing project keeps these modules in
|
|
247
|
+
`src/iwsdk/` instead. `iwsdk.config.json` names the modules either way; the
|
|
248
|
+
`src/...` paths in this guidance mean the modules it names.
|
|
249
|
+
|
|
202
250
|
No barrel `index.ts` files. Keep component declarations free of system, DOM and
|
|
203
251
|
renderer imports; systems import the declarations, never the reverse.
|
|
204
252
|
|
|
@@ -212,12 +260,44 @@ renderer imports; systems import the declarations, never the reverse.
|
|
|
212
260
|
- Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
|
|
213
261
|
- Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
|
|
214
262
|
- Use the `RayInteractable` component, never a manual `Raycaster`.
|
|
263
|
+
- Give a UI panel or button both `RayInteractable` and `PokeInteractable`.
|
|
264
|
+
Fingertip touches only reach entities with `PokeInteractable`, so a
|
|
265
|
+
ray-only panel ignores hand presses.
|
|
215
266
|
- VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
|
|
267
|
+
- Keep an Enter XR control on the flat page of every XR app: the starter's
|
|
268
|
+
welcome-panel button, or your own UIKit or DOM button that calls
|
|
269
|
+
`world.launchXR()`. If you remove the welcome panel, replace its button.
|
|
270
|
+
`xr.offer` alone only adds a small "Enter VR" pill to the Quest Browser
|
|
271
|
+
toolbar (labelled VR even for AR), which people miss, so the page looks like
|
|
272
|
+
it has no way into XR.
|
|
273
|
+
- Keep app and game state that a person or agent will want to read or change
|
|
274
|
+
(score, lives, gold, wave, phase, timers, debug switches) in ECS components,
|
|
275
|
+
not module-level objects. `ecs query` and `ecs set-component` then read it and
|
|
276
|
+
jump it to any state from the CLI or MCP, in the emulator and on a paired
|
|
277
|
+
headset, without editing code or scripting the page.
|
|
278
|
+
|
|
279
|
+
**Browser automation is a last resort.** `dev up --allow-browser-automation`
|
|
280
|
+
enables `browser run`, which runs your own Playwright script inside the managed
|
|
281
|
+
browser. Before you reach for it, or for a temporary source edit such as
|
|
282
|
+
lowering a start value, to reach a hard-to-reach state, check whether that state
|
|
283
|
+
belongs in ECS. If it does, move it into a component as part of the work and
|
|
284
|
+
drive it with `ecs set-component`. Use browser automation only for what ECS and
|
|
285
|
+
the built-in tools cannot express, and say why.
|
|
216
286
|
|
|
217
287
|
## Deep reference
|
|
218
288
|
|
|
289
|
+
Look up IWSDK APIs with `npx @iwsdk/cli reference <op> --input-json '{...}'`
|
|
290
|
+
(the same tools are on MCP) instead of reading `node_modules`: `api`
|
|
291
|
+
`{"name":"World"}` for a known name, `search` `{"query":"PokeInteractable hand"}`,
|
|
292
|
+
`components` and `systems` to list every ECS type, `examples`
|
|
293
|
+
`{"api_name":"createSystem"}` for usage. `search` is a keyword search: give
|
|
294
|
+
identifiers plus a few words, not questions. The corpus ships inside
|
|
295
|
+
`@iwsdk/reference`, matches the installed version and needs no network or
|
|
296
|
+
warmup.
|
|
297
|
+
|
|
219
298
|
Harness-native scoped rules cover `public/scenes/**`, `public/ui/**`,
|
|
220
299
|
`src/assets.ts`, `src/scene-assets/**`, and `src/**/*.ts`. `AGENTS.md`-based
|
|
221
300
|
harnesses receive nested instruction files; Cursor and Copilot receive their
|
|
222
301
|
native rule formats. Skill procedures live in the selected harness's project
|
|
223
302
|
skill directory and state when they apply.
|
|
303
|
+
<!-- END iwsdk-agent-guidance -->
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
<!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=4451a5b98ba38a835cca3fc49666cbe62ba77353f6b8d0ed7d46b691d35067c1 -->
|
|
2
|
+
# IWSDK scoped project guidance
|
|
3
|
+
|
|
4
|
+
This file augments the repository-root `AGENTS.md` for files in this directory.
|
|
5
|
+
|
|
6
|
+
# Scene JSON — things that fail silently
|
|
7
|
+
|
|
8
|
+
Format reference lives in
|
|
9
|
+
`.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
|
|
10
|
+
boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
|
|
11
|
+
it for imports, prefabs, patterns, or a schema detail not covered by active
|
|
12
|
+
guidance. For ordinary flat node, component, and authored-view edits, this rule,
|
|
13
|
+
the existing scene, and the active specialist are sufficient. This file is only
|
|
14
|
+
the short list of behaviours that produce no error when you get them wrong.
|
|
15
|
+
|
|
16
|
+
Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
|
|
17
|
+
closed — an unknown field fails validation.
|
|
18
|
+
|
|
19
|
+
## Imports stop at the authoring boundary
|
|
20
|
+
|
|
21
|
+
Authoring tools can validate and render a root with `imports`, so modular scratch
|
|
22
|
+
scenes remain useful for composition. The editable scene session and application
|
|
23
|
+
runtime deliberately reject imports. Run `scene_flatten_file` or
|
|
24
|
+
`npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
|
|
25
|
+
then make the flat output the sole editable source of truth. Never re-flatten over
|
|
26
|
+
later human editor changes.
|
|
27
|
+
|
|
28
|
+
## The player materialises at the scene origin
|
|
29
|
+
|
|
30
|
+
`0,0,0` unless the document authors `player.transform`. Nothing warns you. A
|
|
31
|
+
scene can pass every authored camera view and still spawn the player inside the
|
|
32
|
+
geometry, because review cameras are not the viewpoint that ships. Keep that
|
|
33
|
+
volume clear or place the player deliberately, and author a diagnostic view at
|
|
34
|
+
player eye height to prove it.
|
|
35
|
+
|
|
36
|
+
## `visibleNodeIds` is the silent-failure detector
|
|
37
|
+
|
|
38
|
+
`renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
|
|
39
|
+
did not appear — even when the image looks plausible and `valid` is `true`. Check
|
|
40
|
+
it against what you expect rather than trusting the picture. Single-sided
|
|
41
|
+
surfaces facing away from the camera are the usual cause, and they report nothing.
|
|
42
|
+
`ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
|
|
43
|
+
content is one of them is never listed; check the object it grounds instead.
|
|
44
|
+
|
|
45
|
+
## Component keys come in two forms
|
|
46
|
+
|
|
47
|
+
Root-level components use the namespaced form
|
|
48
|
+
(`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
|
|
49
|
+
(`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
|
|
50
|
+
form on nodes**, so a file touched by both hands contains both. Match whatever the
|
|
51
|
+
node already uses instead of normalising.
|
|
52
|
+
|
|
53
|
+
`LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
|
|
54
|
+
|
|
55
|
+
## Browser hero views and XR spawn framing are distinct
|
|
56
|
+
|
|
57
|
+
Outside immersive XR, the hero authoring view supersedes `world.render.camera`
|
|
58
|
+
from `iwsdk.config.json` once the level initialises. While XR is presenting,
|
|
59
|
+
the tracked player rig owns the camera and the hero view is intentionally not
|
|
60
|
+
applied. Use the hero view for editor/browser framing, and validate important
|
|
61
|
+
content from the authored `player.transform` spawn (or the default standing
|
|
62
|
+
view near `[0, 1.6, 0]`) before accepting XR framing.
|
|
63
|
+
|
|
64
|
+
## Validation
|
|
65
|
+
|
|
66
|
+
`scene_render_file` validates, composes, lowers and renders without touching the
|
|
67
|
+
open document. A result is usable only when `valid: true` **and** a PNG comes
|
|
68
|
+
back. Render each changed module before the root.
|
|
69
|
+
|
|
70
|
+
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
71
|
+
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
72
|
+
<!-- END iwsdk-agent-guidance -->
|