@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.
Files changed (160) hide show
  1. package/README.md +106 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1532 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +267 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +179 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +309 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  42. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  43. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  44. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  45. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  46. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  47. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  48. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +335 -0
  49. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  50. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  51. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  52. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  53. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  54. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  55. package/dist/agent-guidance/files/.claude/settings.json +30 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1532 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +267 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +179 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  86. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  87. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  88. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  89. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  90. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  91. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  92. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +309 -0
  93. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  94. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  95. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  96. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  97. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  98. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  99. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  100. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +335 -0
  101. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  102. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  103. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  104. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  105. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  106. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  107. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  108. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  109. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  110. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  111. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  112. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  113. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  114. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  115. package/dist/agent-guidance/manifest.json +954 -0
  116. package/dist/agent-guidance.d.ts +140 -0
  117. package/dist/agent-guidance.d.ts.map +1 -0
  118. package/dist/agent-guidance.js +3612 -0
  119. package/dist/agent-guidance.js.map +1 -0
  120. package/dist/cli.js +4010 -750
  121. package/dist/cli.js.map +1 -1
  122. package/dist/commands/adapter.d.ts +1 -0
  123. package/dist/commands/adapter.d.ts.map +1 -1
  124. package/dist/commands/agents.d.ts +11 -0
  125. package/dist/commands/agents.d.ts.map +1 -0
  126. package/dist/commands/browser.d.ts +11 -0
  127. package/dist/commands/browser.d.ts.map +1 -1
  128. package/dist/commands/dev.d.ts +1 -0
  129. package/dist/commands/dev.d.ts.map +1 -1
  130. package/dist/commands/reference.d.ts +15 -1
  131. package/dist/commands/reference.d.ts.map +1 -1
  132. package/dist/commands/runtime.d.ts.map +1 -1
  133. package/dist/commands/upgrade.d.ts +138 -0
  134. package/dist/commands/upgrade.d.ts.map +1 -0
  135. package/dist/contract.js +32 -0
  136. package/dist/contract.js.map +1 -1
  137. package/dist/guidance-refresh.d.ts +53 -0
  138. package/dist/guidance-refresh.d.ts.map +1 -0
  139. package/dist/help.d.ts +2 -0
  140. package/dist/help.d.ts.map +1 -1
  141. package/dist/index.d.ts.map +1 -1
  142. package/dist/index.js +6114 -508
  143. package/dist/index.js.map +1 -1
  144. package/dist/mcp-stdio.d.ts.map +1 -1
  145. package/dist/metavr-telemetry.d.ts +6 -0
  146. package/dist/metavr-telemetry.d.ts.map +1 -1
  147. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  148. package/dist/migrations.d.ts +36 -0
  149. package/dist/migrations.d.ts.map +1 -0
  150. package/dist/package-manager.d.ts +34 -0
  151. package/dist/package-manager.d.ts.map +1 -0
  152. package/dist/release-notes.d.ts +28 -0
  153. package/dist/release-notes.d.ts.map +1 -0
  154. package/dist/release-notes.json +1506 -0
  155. package/dist/runtime-contract.d.ts +8 -0
  156. package/dist/runtime-contract.d.ts.map +1 -1
  157. package/dist/runtime-telemetry.d.ts +8 -1
  158. package/dist/runtime-telemetry.d.ts.map +1 -1
  159. package/dist/version.d.ts +1 -1
  160. package/package.json +9 -3
@@ -0,0 +1,72 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 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 -->
@@ -0,0 +1,66 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=abe74e27fdcd33f9fbdfa6fef5b11cd1427fe15c66fec1a0b884f3a09b750266 -->
2
+ # IWSDK scoped project guidance
3
+
4
+ This file augments the repository-root `AGENTS.md` for files in this directory.
5
+
6
+ # UIKitML panels
7
+
8
+ HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
9
+
10
+ **Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
11
+ 0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
12
+
13
+ **Panels are single-sided and face +Z.** To aim one at a camera, yaw by
14
+ `atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
15
+ nothing, reports no error, and still returns `valid: true` from
16
+ `scene_render_file`; the only signal is its absence from
17
+ `renderStats.visibleNodeIds`.
18
+
19
+ Verified working: `display: flex`, `flex-direction`, `align-items`,
20
+ `justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
21
+ `height`, `background-color`, `border-color`, `border-width`, `border-radius`,
22
+ `font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
23
+ `button` all work.
24
+
25
+ Expand shorthands (`padding: 12 18` → four properties), use unitless
26
+ line-height multipliers, and prefer uniform `border-color`/`border-width` over
27
+ directional variants. Parser errors include source locations.
28
+
29
+ **Production builds drop unused Lucide icons.** They keep only icons named in
30
+ `public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
31
+ from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
32
+ they fail after `npm run build`.
33
+
34
+ ## Runtime API
35
+
36
+ Resolve the placed panel by **scene node id**, then elements by their `id`
37
+ attribute:
38
+
39
+ ```ts
40
+ const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
41
+ const chip = panel?.getElementById<UIKit.Text>('finish-gold');
42
+ chip?.addEventListener('click', onClick);
43
+ chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
44
+ ```
45
+
46
+ `setProperties` updates both text (`{ text }`) and style
47
+ (`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
48
+ including over class-based styles from the `<style>` block. `UIKit.Text` is the
49
+ public element type; no deep import from `@pmndrs/uikit` is needed.
50
+
51
+ Three distinct identities, don't conflate them: the **manifest ID** names the
52
+ reusable asset, the **scene node ID** names the placed instance, and the element
53
+ `id` names a field inside it. Never depend on a transient entity index.
54
+
55
+ Give the panel node `RayInteractable` so clicks land.
56
+
57
+ The editor render does not run application systems, so `scene_screenshot` can
58
+ never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
59
+ can.
60
+
61
+ ---
62
+
63
+ For the authoring procedure — isolated preview, placement, editing, wiring
64
+ runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
65
+ than improvising. This file is the format reference it relies on.
66
+ <!-- END iwsdk-agent-guidance -->
@@ -0,0 +1,153 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=b60c812e637c6f5bd8f4480f83d7c28a93e042abac20fee504238e8981fa2b6f -->
2
+ # IWSDK scoped project guidance
3
+
4
+ This file augments the repository-root `AGENTS.md` for files in this directory.
5
+
6
+ # ECS API reference
7
+
8
+ ## Field types
9
+
10
+ ```
11
+ Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
12
+ Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
13
+ Types.Object // avoid — not optimised
14
+ ```
15
+
16
+ ## Component
17
+
18
+ Declare in a system-free module, then list it in `src/components.ts` via
19
+ `defineComponents()` or the editor cannot author it.
20
+
21
+ ```ts
22
+ export const MyComponent = createComponent('MyComponent', {
23
+ speed: { type: Types.Float32, default: 1 },
24
+ tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
25
+ });
26
+ ```
27
+
28
+ Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
29
+ `widget` — drives the editor inspector.
30
+
31
+ ## System
32
+
33
+ ```ts
34
+ export class MySystem extends createSystem(
35
+ {
36
+ items: { required: [MyComponent] },
37
+ active: { required: [MyComponent], excluded: [Grabbed] },
38
+ },
39
+ { speed: { type: Types.Float32, default: 1 } }, // optional config
40
+ ) {
41
+ private temp!: Vector3;
42
+
43
+ init() {
44
+ this.temp = new Vector3();
45
+ this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
46
+ this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
47
+ }
48
+
49
+ update(delta: number, time: number) {
50
+ for (const entity of this.queries.active.entities) { /* no allocations */ }
51
+ }
52
+ }
53
+ ```
54
+
55
+ Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
56
+ `lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
57
+ entities in a transient state — e.g. excluding `Grabbed` so a held object is left
58
+ alone.
59
+
60
+ Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
61
+
62
+ Read fields with `entity.getValue(Component, 'field')`. For vector fields use
63
+ `entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
64
+ no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
65
+
66
+ ## Interaction components
67
+
68
+ `RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
69
+ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
70
+ proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
71
+ ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
72
+ `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
73
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
74
+
75
+ `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
76
+ `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
77
+ `detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
78
+ `targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
79
+ no custom code.
80
+
81
+ For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
82
+ `getHolderHand(entity)` — never deep-import `Handle`.
83
+
84
+ ## XR input
85
+
86
+ ```ts
87
+ const pad = this.input.xr.gamepads.right;
88
+ pad?.getButtonDown(InputComponent.Trigger); // just pressed
89
+ pad?.getAxesValues(InputComponent.Thumbstick);
90
+ this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
91
+ ```
92
+
93
+ Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
94
+ buttons. Browser controls live at `world.input.keyboard` and
95
+ `world.input.browserGamepads`.
96
+
97
+ ## Lifecycle
98
+
99
+ `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
100
+ pause simulation on blur. `world.camera.position` is local to `world.player`; use
101
+ `getWorldPosition()` when logic needs the true viewer position.
102
+
103
+ # Asset manifest contract
104
+
105
+ `src/assets.ts` is imported **independently by the app runtime and the editor**,
106
+ in separate JS realms. It must therefore be deterministic and self-contained:
107
+
108
+ - no `World`, scene, iframe, editor object or DOM access
109
+ - no timers, no fetching ambient state
110
+ - no reliance on singleton object identity across realms
111
+ - prototypes immutable after registration, and never parented
112
+
113
+ A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
114
+ or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
115
+ `HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
116
+ as scene content; audio/texture/HDR are for application systems.
117
+
118
+ Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
119
+ builds resolve identically. A file in `public/` is **not** available to a scene
120
+ until it is registered here.
121
+
122
+ ## Procedural assets
123
+
124
+ Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
125
+ register it under a stable ID. The registry rejects an already-parented
126
+ prototype.
127
+
128
+ Every placement is a distinct hierarchy clone, but **geometry and materials stay
129
+ shared**. Never dispose them from a placed clone; world teardown owns their
130
+ lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
131
+ one instance — mutating the shared material in place changes every instance.
132
+
133
+ Bounds come from `Box3` over the instantiated asset and drive placement,
134
+ selection, framing and scatter collision. Put the origin where composition wants
135
+ it (usually floor contact, or the object's own pivot), keep transforms finite,
136
+ and don't let invisible helpers inflate bounds.
137
+
138
+ ## Cost
139
+
140
+ Split tessellation by viewing distance rather than using one budget everywhere: a
141
+ close-range hero model and coarser display copies of the same form are two
142
+ prototypes from one factory function. Sphere/lathe segment counts dominate small
143
+ repeated detail more than people expect — check `renderStats.triangles` rather
144
+ than guessing.
145
+
146
+ Reuse material instances within a module. Prefer prefabs plus a deterministic
147
+ pattern for repetition; a pattern whose prefab resolves to a single component-free
148
+ mesh lowers to one `InstancedMesh`.
149
+
150
+ Start assets at `castShadow: false` and opt in only for grounded focal masses.
151
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
152
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
153
+ <!-- END iwsdk-agent-guidance -->