@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,1532 @@
1
+ # IWSDK API Reference & Best Practices
2
+
3
+ Ground-truth API patterns for IWSDK app development. This file is the shared
4
+ API reference behind `iwsdk-dev`; load it when grounding implementation details,
5
+ writing IWSDK code, or reviewing it. It contains no process guidance. The router
6
+ lives in `SKILL.md`, and the internal planner and iterate playbooks are siblings
7
+ in this directory.
8
+
9
+ **Version sensitivity:** this reference tracks the SDK at the time the skill
10
+ shipped. For any API your plan depends on, verify the signature against the
11
+ _installed_ package (`node_modules/@iwsdk/core/dist/**/*.d.ts`) — newer
12
+ methods (e.g. `GrabSystem.forceRelease`) may not exist in the version your
13
+ app has installed, and vice versa.
14
+
15
+ ## Core Architecture
16
+
17
+ IWSDK is built on three pillars:
18
+
19
+ 1. **ECS (Entity Component System)** via `elics` library
20
+ 2. **Reactive Signals** via `@preact/signals-core`
21
+ 3. **Three.js Integration** with zero-copy transform binding (super-three v0.185.0)
22
+
23
+ IWSDK is a 3D web framework with first-class XR support. `World.create()` always creates a persistent `world.player` origin and keeps `world.camera` under it, even when `xr: false` is used for browser-only apps. For first-person browser movement, move `world.player`; for orbit, editor, product, cinematic, or third-person cameras, it is fine to keep `world.player` at the origin and drive `world.camera`. Remember that `world.camera.position` is local to `world.player`, so use `camera.getWorldPosition(...)` when world-space viewer position matters.
24
+
25
+ ### Project manifest authority
26
+
27
+ Generated 0.5 projects keep JSON-safe scene, module, XR, render, input, feature,
28
+ and emulator settings in `iwsdk.config.json`. `src/index.ts` imports
29
+ `virtual:iwsdk-project`, passes it to `World.create()`, and retains explicit
30
+ system registration. The direct `World.create(container, WorldOptions)` shapes
31
+ below remain the low-level API reference; when editing a generated project,
32
+ translate their serializable fields into the manifest instead of creating a
33
+ second configuration authority in code.
34
+
35
+ Asset/component modules are selected by extensionless manifest paths and are
36
+ shared by runtime and editor. Build local public URLs from
37
+ `import.meta.env.BASE_URL`; literal `./...` URLs resolve against the managed
38
+ editor route during editor use and are not a safe project-wide convention.
39
+
40
+ Use `input.canvasPointerEvents` for browser mouse/touch canvas events. Browser canvas pointers and XR rays both feed Three/Object3D pointer events and ECS `Hovered`/`Pressed` tags on `RayInteractable` entities. XR-specific input is available at `world.input.xr`; keyboard and standard browser gamepads live at `world.input.keyboard` and `world.input.browserGamepads`. Reusable systems should prefer `world.input.actions` for intent such as `locomotion.move` or `locomotion.jump`; opt into browser locomotion bindings with `features.locomotion.browserControls`.
41
+
42
+ ## Critical Best Practices
43
+
44
+ `createSystem()` accepts query descriptors as its first argument and optional
45
+ configuration schema as its second. Lifecycle methods never go inside either
46
+ object: define `init()`, `update()`, and `destroy()` in the subclass body. A
47
+ function inside the query map is a lifecycle-placement mistake, not a query.
48
+
49
+ ### 1. Keep Systems Stateless
50
+
51
+ Systems should NOT store arrays of entities or maintain entity references. Use queries instead.
52
+
53
+ ```typescript
54
+ // ❌ BAD - Storing entity references
55
+ export class BadSystem extends createSystem({
56
+ items: { required: [MyComponent] },
57
+ }) {
58
+ private myEntities: Entity[] = []; // DON'T DO THIS
59
+
60
+ init() {
61
+ this.queries.items.subscribe('qualify', (entity) => {
62
+ this.myEntities.push(entity); // BAD: manually tracking entities
63
+ });
64
+ }
65
+ }
66
+
67
+ // ✅ GOOD - Use queries for entity access
68
+ export class GoodSystem extends createSystem({
69
+ items: { required: [MyComponent] },
70
+ }) {
71
+ update() {
72
+ // Query always gives current matching entities
73
+ for (const entity of this.queries.items.entities) {
74
+ // Process entity
75
+ }
76
+ }
77
+ }
78
+ ```
79
+
80
+ **Exception:** Scratch variables for temporary per-frame calculations are OK.
81
+
82
+ ### 2. Use Query Subscribe/Unsubscribe for Reactive Programming
83
+
84
+ Instead of polling or storing state, react to entity lifecycle events:
85
+
86
+ ```typescript
87
+ export class ReactiveSystem extends createSystem({
88
+ interactables: { required: [RayInteractable, Transform] },
89
+ }) {
90
+ init() {
91
+ // React when entities enter the query
92
+ this.queries.interactables.subscribe('qualify', (entity) => {
93
+ this.setupEventListeners(entity);
94
+ });
95
+
96
+ // React when entities leave the query
97
+ this.queries.interactables.subscribe('disqualify', (entity) => {
98
+ this.cleanupEventListeners(entity);
99
+ });
100
+ }
101
+ }
102
+ ```
103
+
104
+ ### 3. Use Signals for Reactive State
105
+
106
+ IWSDK uses `@preact/signals-core`. Prefer signals over manual state tracking:
107
+
108
+ ```typescript
109
+ // System config properties are automatically signals
110
+ export class MySystem extends createSystem(
111
+ {},
112
+ {
113
+ speed: { type: Types.Float32, default: 5.0 },
114
+ jumpHeight: { type: Types.Float32, default: 2.0 },
115
+ },
116
+ ) {
117
+ init() {
118
+ // Subscribe to config changes reactively
119
+ this.cleanupFuncs.push(
120
+ this.config.speed.subscribe((newSpeed) => {
121
+ console.log('Speed changed:', newSpeed);
122
+ }),
123
+ );
124
+ }
125
+
126
+ update(delta) {
127
+ // Read signal value with .peek() in update loops (no subscription overhead)
128
+ const currentSpeed = this.config.speed.peek();
129
+ }
130
+ }
131
+ ```
132
+
133
+ ### World Globals Signals for Cross-System Communication
134
+
135
+ Store signals in `world.globals` for state that multiple systems need to read/write:
136
+
137
+ ```typescript
138
+ // In index.ts (initialization)
139
+ import { signal } from '@preact/signals-core';
140
+
141
+ (world.globals as Record<string, unknown>).gamePaused = signal(true);
142
+ (world.globals as Record<string, unknown>).audioMasterVolume = signal(1.0);
143
+
144
+ // In any system (reading with peek() in hot paths)
145
+ const gamePaused = (this.globals.gamePaused as Signal<boolean>).peek();
146
+
147
+ // In any system (writing)
148
+ const gamePausedSignal = this.globals.gamePaused as Signal<boolean>;
149
+ gamePausedSignal.value = !gamePausedSignal.value;
150
+ ```
151
+
152
+ ### 4. Component Types (Complete List)
153
+
154
+ ```typescript
155
+ import { Types } from '@iwsdk/core';
156
+
157
+ Types.Float32; // 32-bit float
158
+ Types.Float64; // 64-bit float (for physics engine refs)
159
+ Types.Int8; // 8-bit signed integer
160
+ Types.Int16; // 16-bit signed integer
161
+ Types.Int32; // 32-bit signed integer
162
+ Types.Boolean; // true/false
163
+ Types.String; // text
164
+ Types.FilePath; // file path string (asset-referencing fields like AudioSource.src)
165
+ Types.Vec2; // [x, y] - 2 floats
166
+ Types.Vec3; // [x, y, z] - 3 floats
167
+ Types.Vec4; // [x, y, z, w] - 4 floats (quaternions)
168
+ Types.Color; // [r, g, b, a] - 4 floats (RGBA)
169
+ Types.Entity; // Reference to another entity
170
+ Types.Enum; // Enumerated value
171
+ Types.Object; // Any JS object (avoid if possible - not optimized)
172
+ ```
173
+
174
+ ### 5. Component Design Patterns
175
+
176
+ ```typescript
177
+ import { createComponent, Types } from '@iwsdk/core';
178
+
179
+ // Tag component (no data, just marks entities)
180
+ export const Targetable = createComponent('Targetable', {}, '');
181
+
182
+ // Data component with proper types
183
+ export const Health = createComponent('Health', {
184
+ current: { type: Types.Float32, default: 100 },
185
+ max: { type: Types.Float32, default: 100 },
186
+ });
187
+
188
+ // With enums
189
+ export const State = createComponent('State', {
190
+ mode: {
191
+ type: Types.Enum,
192
+ enum: { Idle: 'idle', Moving: 'moving', Attacking: 'attacking' },
193
+ default: 'idle',
194
+ },
195
+ });
196
+
197
+ // With vectors (stored as TypedArrays for performance)
198
+ export const Velocity = createComponent('Velocity', {
199
+ linear: { type: Types.Vec3, default: [0, 0, 0] },
200
+ angular: { type: Types.Vec3, default: [0, 0, 0] },
201
+ });
202
+
203
+ // With colors (RGBA, 4 components)
204
+ export const Tint = createComponent('Tint', {
205
+ color: { type: Types.Color, default: [1, 1, 1, 1] },
206
+ });
207
+ ```
208
+
209
+ ### 6. Query Patterns with Filters
210
+
211
+ ```typescript
212
+ export class DamageSystem extends createSystem({
213
+ // Basic query
214
+ enemies: { required: [Enemy] },
215
+
216
+ // With exclusions
217
+ vulnerableEnemies: {
218
+ required: [Enemy, Health],
219
+ excluded: [Invulnerable, Shield],
220
+ },
221
+
222
+ // With value filters
223
+ lowHealth: {
224
+ required: [Health],
225
+ where: [lt(Health, 'current', 20)],
226
+ },
227
+
228
+ // Complex filters
229
+ activeBosses: {
230
+ required: [Boss, Health],
231
+ where: [gt(Health, 'current', 0), eq(State, 'mode', 'attacking')],
232
+ },
233
+ }) {}
234
+
235
+ // Available filter operators: eq, ne, lt, le, gt, ge, isin, nin
236
+ ```
237
+
238
+ ### 7. System Interface (Full)
239
+
240
+ ```typescript
241
+ interface System {
242
+ // World access
243
+ world: World;
244
+
245
+ // Query results
246
+ queries: Record<string, Query>;
247
+
248
+ // Reactive config (auto-created from schema)
249
+ config: { [key]: Signal };
250
+
251
+ // Cleanup registration
252
+ cleanupFuncs: Array<() => void>;
253
+
254
+ // XR/Player access
255
+ player: XROrigin;
256
+ input: InputManager; // XR devices at input.xr, keyboard at input.keyboard, browser gamepads at input.browserGamepads, actions at input.actions
257
+
258
+ // Three.js access
259
+ scene: Scene;
260
+ camera: PerspectiveCamera;
261
+ renderer: WebGLRenderer;
262
+
263
+ // XR state
264
+ visibilityState: Signal<VisibilityState>;
265
+ xrManager: WebXRManager;
266
+ xrFrame: XRFrame;
267
+
268
+ // Shared state
269
+ globals: Record<string, any>;
270
+
271
+ // Entity creation helpers
272
+ createEntity(): Entity;
273
+ createTransformEntity(object?: Object3D, parent?: Entity): Entity;
274
+
275
+ // Lifecycle
276
+ init(): void;
277
+ update(delta: number, time: number): void;
278
+ play(): void;
279
+ stop(): void;
280
+ }
281
+ ```
282
+
283
+ ### 8. XR Input System (Critical)
284
+
285
+ ```typescript
286
+ update() {
287
+ const leftGamepad = this.input.xr.gamepads.left;
288
+ const rightGamepad = this.input.xr.gamepads.right;
289
+
290
+ // Button states
291
+ leftGamepad?.getButtonPressed(InputComponent.Trigger); // Currently pressed
292
+ leftGamepad?.getButtonDown(InputComponent.Trigger); // Just pressed this frame
293
+ leftGamepad?.getButtonUp(InputComponent.Trigger); // Just released this frame
294
+ leftGamepad?.getButtonValue(InputComponent.Trigger); // Analog value 0-1
295
+ leftGamepad?.getButtonTouched(InputComponent.Trigger); // Finger touching
296
+
297
+ // Special select button (primary action)
298
+ leftGamepad?.getSelectStart(); // Primary button just pressed
299
+ leftGamepad?.getSelectEnd(); // Primary button just released
300
+ leftGamepad?.getSelecting(); // Primary button held
301
+
302
+ // Thumbstick/touchpad axes
303
+ const axes = leftGamepad?.getAxesValues(InputComponent.Thumbstick);
304
+ console.log(axes?.x, axes?.y); // -1 to 1 range
305
+
306
+ // Directional axes state
307
+ leftGamepad?.getAxesEnteringUp(InputComponent.Thumbstick);
308
+ leftGamepad?.getAxesEnteringDown(InputComponent.Thumbstick);
309
+ leftGamepad?.getAxesEnteringLeft(InputComponent.Thumbstick);
310
+ leftGamepad?.getAxesEnteringRight(InputComponent.Thumbstick);
311
+ }
312
+ ```
313
+
314
+ **InputComponent Enum:**
315
+
316
+ ```typescript
317
+ import { InputComponent } from '@iwsdk/core';
318
+
319
+ InputComponent.Trigger; // 'xr-standard-trigger'
320
+ InputComponent.Squeeze; // 'xr-standard-squeeze'
321
+ InputComponent.Touchpad; // 'xr-standard-touchpad'
322
+ InputComponent.Thumbstick; // 'xr-standard-thumbstick'
323
+ InputComponent.A_Button; // 'a-button'
324
+ InputComponent.B_Button; // 'b-button'
325
+ InputComponent.X_Button; // 'x-button'
326
+ InputComponent.Y_Button; // 'y-button'
327
+ InputComponent.Thumbrest; // 'thumbrest'
328
+ InputComponent.Menu; // 'menu'
329
+ ```
330
+
331
+ ### 9. Player/XROrigin Access (Critical)
332
+
333
+ ```typescript
334
+ // Accessing player spatial hierarchy in a system
335
+ this.player; // XROrigin (Group) - VR rig root
336
+ this.player.head; // Head tracking (viewer pose)
337
+ this.player.raySpaces.left; // Left controller ray origin
338
+ this.player.raySpaces.right; // Right controller ray origin
339
+ this.player.gripSpaces.left; // Left controller grip pose
340
+ this.player.gripSpaces.right; // Right controller grip pose
341
+ this.player.secondaryRaySpaces.left; // Secondary left ray
342
+ this.player.secondaryRaySpaces.right; // Secondary right ray
343
+ this.player.secondaryGripSpaces.left; // Secondary left grip
344
+ this.player.secondaryGripSpaces.right; // Secondary right grip
345
+
346
+ // Getting world positions
347
+ const headPos = new Vector3();
348
+ this.player.head.getWorldPosition(headPos);
349
+
350
+ const rightHandPos = new Vector3();
351
+ this.player.gripSpaces.right.getWorldPosition(rightHandPos);
352
+
353
+ // Attach a held model so it inherits both grip position and orientation.
354
+ heldModel.position.set(0, -0.02, 0.05); // Model-local alignment offset.
355
+ this.player.gripSpaces.right.add(heldModel);
356
+ ```
357
+
358
+ ### 10. Audio System
359
+
360
+ ```typescript
361
+ import {
362
+ AudioSource,
363
+ PlaybackMode,
364
+ AudioUtils,
365
+ InstanceStealPolicy,
366
+ DistanceModel,
367
+ } from '@iwsdk/core';
368
+
369
+ // Adding audio to an entity
370
+ entity.addComponent(AudioSource, {
371
+ src: 'audio/click.mp3',
372
+ positional: true, // 3D spatial audio
373
+ loop: false,
374
+ autoplay: false,
375
+ volume: 0.5,
376
+ refDistance: 1,
377
+ rolloffFactor: 1,
378
+ maxDistance: 10000,
379
+ maxInstances: 1,
380
+ playbackMode: PlaybackMode.Restart,
381
+ });
382
+
383
+ // Playing audio
384
+ AudioUtils.play(entity);
385
+ ```
386
+
387
+ **PlaybackMode:**
388
+
389
+ ```typescript
390
+ PlaybackMode.Restart; // Stop current and restart
391
+ PlaybackMode.Overlap; // Always start new instance
392
+ PlaybackMode.Ignore; // Ignore if already playing
393
+ PlaybackMode.FadeRestart; // Fade out current, start new
394
+ ```
395
+
396
+ **InstanceStealPolicy:**
397
+
398
+ ```typescript
399
+ InstanceStealPolicy.Oldest; // Steal oldest instance
400
+ InstanceStealPolicy.Quietest; // Steal quietest instance
401
+ InstanceStealPolicy.Furthest; // Steal furthest instance
402
+ ```
403
+
404
+ **DistanceModel:**
405
+
406
+ ```typescript
407
+ DistanceModel.Linear; // Linear falloff
408
+ DistanceModel.Inverse; // Inverse falloff
409
+ DistanceModel.Exponential; // Exponential falloff
410
+ ```
411
+
412
+ ### 11. Physics System
413
+
414
+ **PhysicsBody - motion properties:**
415
+
416
+ ```typescript
417
+ import { PhysicsBody, PhysicsState, PhysicsSystem } from '@iwsdk/core';
418
+
419
+ entity.addComponent(PhysicsBody, {
420
+ state: PhysicsState.Dynamic, // Static, Dynamic, Kinematic
421
+ linearDamping: 0.0,
422
+ angularDamping: 0.0,
423
+ gravityFactor: 1.0,
424
+ centerOfMass: [Infinity, Infinity, Infinity], // Infinity = auto-compute
425
+ });
426
+ ```
427
+
428
+ **PhysicsState:**
429
+
430
+ ```typescript
431
+ PhysicsState.Static; // Immovable (walls, floors)
432
+ PhysicsState.Dynamic; // Affected by physics
433
+ PhysicsState.Kinematic; // Moved by code, affects others
434
+ ```
435
+
436
+ **PhysicsShape - collision shape AND material properties:**
437
+
438
+ ```typescript
439
+ import { PhysicsShape, PhysicsShapeType } from '@iwsdk/core';
440
+
441
+ entity.addComponent(PhysicsShape, {
442
+ shape: PhysicsShapeType.Auto, // Auto-detect from geometry
443
+ dimensions: [0, 0, 0], // Shape-specific dimensions
444
+ density: 1.0, // Affects mass
445
+ restitution: 0.0, // Bounciness (0-1)
446
+ friction: 0.5, // Sliding behavior
447
+ });
448
+ ```
449
+
450
+ **PhysicsShapeType:**
451
+
452
+ ```typescript
453
+ PhysicsShapeType.Sphere; // dimensions[0] = radius
454
+ PhysicsShapeType.Box; // dimensions = [width, height, depth]
455
+ PhysicsShapeType.Cylinder; // dimensions[0] = radius, dimensions[1] = height
456
+ PhysicsShapeType.Capsules; // dimensions[0] = radius, dimensions[1] = total height (>= 2 * radius)
457
+ PhysicsShapeType.ConvexHull; // Convex wrapper around mesh
458
+ PhysicsShapeType.TriMesh; // Exact mesh geometry (expensive)
459
+ PhysicsShapeType.Auto; // Auto-detect from Three.js geometry
460
+ ```
461
+
462
+ **Teleporting / re-posing an existing body:** use the live physics system rather than
463
+ removing and re-adding components. It updates Havok and the Object3D immediately and
464
+ clears velocity by default. The pose is parent-relative unless you pass
465
+ `{ space: 'world' }`:
466
+
467
+ ```typescript
468
+ const physics = world.getSystem(PhysicsSystem);
469
+ physics.setBodyTransform(entity, {
470
+ position: homePosition,
471
+ quaternion: homeQuaternion,
472
+ });
473
+ ```
474
+
475
+ Writing only the Transform of a dynamic body is clobbered by the next physics frame.
476
+ `gravityFactor`, `linearDamping`, and `angularDamping` are reactive; motion `state` and
477
+ shape construction still require deliberate body lifecycle handling.
478
+
479
+ ### 12. Grabbable Components
480
+
481
+ ```typescript
482
+ import {
483
+ OneHandGrabbable,
484
+ TwoHandsGrabbable,
485
+ DistanceGrabbable,
486
+ MovementMode,
487
+ } from '@iwsdk/core';
488
+
489
+ // Basic single-hand grab
490
+ entity.addComponent(OneHandGrabbable, {});
491
+
492
+ // Constrained manipulation
493
+ entity.addComponent(OneHandGrabbable, {
494
+ rotate: true,
495
+ rotateMin: [0, -Math.PI, 0],
496
+ rotateMax: [0, Math.PI, 0],
497
+ translate: true,
498
+ translateMin: [-2, 0, -2],
499
+ translateMax: [2, 3, 2],
500
+ });
501
+
502
+ // Two-hand manipulation (with scaling)
503
+ entity.addComponent(TwoHandsGrabbable, {
504
+ rotate: true,
505
+ translate: true,
506
+ scale: true,
507
+ scaleMin: [0.5, 0.5, 0.5],
508
+ scaleMax: [2, 2, 2],
509
+ });
510
+
511
+ // ⚠️ One handle per entity: OneHandGrabbable, TwoHandsGrabbable, and
512
+ // DistanceGrabbable are MUTUALLY EXCLUSIVE on the same entity (GrabSystem
513
+ // creates a single Handle; near-grab denies ray pointers, distance-grab
514
+ // denies grab pointers). Pick one per entity — DistanceGrabbable with
515
+ // MoveTowardsTarget covers both near and far pickup via trigger.
516
+
517
+ // Distance grab
518
+ entity.addComponent(DistanceGrabbable, {
519
+ rotate: true,
520
+ translate: true,
521
+ scale: true,
522
+ movementMode: MovementMode.MoveTowardsTarget, // MoveTowardsTarget | MoveAtSource | RotateAtSource | MoveFromTarget
523
+ returnToOrigin: false, // Snap back when released
524
+ moveSpeedFactor: 0.1, // MoveTowardsTarget pull lerp: alpha = factor * delta * 100, NOT clamped — keep <= 0.03 if frames can hitch (background tabs/CI) or the pull overshoots and diverges
525
+ });
526
+
527
+ // Force-release / hand lookup (game reset, weapon swap, recoil, etc.)
528
+ import { GrabSystem } from '@iwsdk/core';
529
+ const grab = world.getSystem(GrabSystem);
530
+ grab.forceRelease(entity); // drop a held entity safely (no-op if not held)
531
+ const hand = grab.getHolderHand(entity); // 'left' | 'right' | null ('left' for two-hand grabs)
532
+ ```
533
+
534
+ ### 13. Environment/Lighting
535
+
536
+ ```typescript
537
+ import {
538
+ DomeGradient,
539
+ DomeTexture,
540
+ IBLGradient,
541
+ IBLTexture,
542
+ } from '@iwsdk/core';
543
+
544
+ // Gradient sky dome (RGBA display colors - 4 components)
545
+ entity.addComponent(DomeGradient, {
546
+ sky: [0.2423, 0.6172, 0.8308, 1.0], // RGBA
547
+ equator: [0.6584, 0.7084, 0.7913, 1.0], // RGBA
548
+ ground: [0.807, 0.7758, 0.7454, 1.0], // RGBA
549
+ intensity: 1.0, // 0 = black
550
+ elevationDeg: 90, // sky pole height: 90 = straight up, lower tilts it
551
+ azimuthDeg: 0, // sky pole heading, node Y-rotation convention (90 = -X)
552
+ dither: false, // true adds ±0.5/255 noise against banding
553
+ });
554
+
555
+ // HDR texture sky
556
+ entity.addComponent(DomeTexture, {
557
+ src: './textures/sky.hdr',
558
+ });
559
+
560
+ // Image-based lighting from gradient
561
+ entity.addComponent(IBLGradient, {
562
+ sky: [0.6902, 0.749, 0.7843, 1.0], // RGBA
563
+ equator: [0.6584, 0.7084, 0.7913, 1.0], // RGBA
564
+ ground: [0.807, 0.7758, 0.7454, 1.0], // RGBA
565
+ intensity: 1.0, // applied once since 1.1.0 (square a 1.0.x value)
566
+ });
567
+
568
+ // IBL from texture
569
+ entity.addComponent(IBLTexture, {
570
+ src: 'room', // or URL to HDR
571
+ intensity: 1.0,
572
+ rotation: [0, 0, 0],
573
+ });
574
+ ```
575
+
576
+ **Critical Environment Usage Notes:**
577
+
578
+ 1. **Environment components MUST be added to the level root entity**, not arbitrary entities. The `EnvironmentSystem` queries require `LevelRoot`:
579
+
580
+ ```typescript
581
+ // ❌ BAD - Added to a random entity (silently ignored)
582
+ someEntity.addComponent(DomeGradient, { ... });
583
+
584
+ // ✅ GOOD - Added to the level root
585
+ const root = world.activeLevel.value;
586
+ root.addComponent(DomeGradient, { sky: [0.24, 0.62, 0.83, 1.0], ... });
587
+ ```
588
+
589
+ 2. **After changing `DomeTexture` or `IBLTexture`, MUST set `_needsUpdate: true`** — their changes are silently ignored without it. `DomeGradient` and `IBLGradient` apply edits on the next frame; `_needsUpdate` is optional for them:
590
+
591
+ ```typescript
592
+ root.setValue(DomeTexture, 'intensity', 0.6);
593
+ root.setValue(DomeTexture, '_needsUpdate', true); // Required for textures!
594
+
595
+ root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]); // applies next frame
596
+ root.setValue(DomeGradient, 'elevationDeg', 30); // applies next frame
597
+ ```
598
+
599
+ 3. **Background vs IBL are separate**: `DomeTexture`/`DomeGradient` controls the visible sky. `IBLTexture`/`IBLGradient` controls scene lighting (reflections, ambient). You can mix them:
600
+
601
+ ```typescript
602
+ root.addComponent(DomeTexture, { src: './envs/sky.hdr', intensity: 0.9 });
603
+ root.addComponent(IBLTexture, { src: 'room', intensity: 1.2 }); // Lighting only
604
+ ```
605
+
606
+ 4. **In AR sessions**, backgrounds (dome) are automatically hidden but IBL remains active for realistic lighting on virtual objects.
607
+
608
+ 5. **`DomeFade` is a node component** that fades that node's own meshes into the root `DomeGradient` with horizontal distance from the node origin, so a floor has no visible edge. It does nothing without a `DomeGradient`, and its meshes hide with the dome in AR:
609
+
610
+ ```json
611
+ {
612
+ "id": "floor",
613
+ "content": { "type": "asset", "asset": "floor" },
614
+ "components": {
615
+ "com.iwsdk.components.DomeFade": { "start": 4, "end": 10 }
616
+ }
617
+ }
618
+ ```
619
+
620
+ ### 14. Asset Loading
621
+
622
+ ```typescript
623
+ import { AssetManager, AssetType } from '@iwsdk/core';
624
+
625
+ const publicAssetUrl = (path: string) =>
626
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
627
+
628
+ const world = await World.create(container, {
629
+ assets: {
630
+ myModel: {
631
+ url: publicAssetUrl('models/scene.glb'),
632
+ type: AssetType.GLTF,
633
+ priority: 'critical',
634
+ },
635
+ mySound: {
636
+ url: publicAssetUrl('audio/click.mp3'),
637
+ type: AssetType.Audio,
638
+ priority: 'background',
639
+ },
640
+ myTexture: {
641
+ url: publicAssetUrl('textures/wood.jpg'),
642
+ type: AssetType.Texture,
643
+ },
644
+ myHDR: {
645
+ url: publicAssetUrl('textures/env.hdr'),
646
+ type: AssetType.HDRTexture,
647
+ },
648
+ },
649
+ });
650
+
651
+ // Access preloaded assets
652
+ const model = AssetManager.getGLTF('myModel');
653
+ // `getGLTF` returns a fresh clone of `scene`/`scenes` per call, so the
654
+ // same key safely backs multiple entities. Use `{ shared: true }` for
655
+ // the cached instance.
656
+ const texture = AssetManager.getTexture('myTexture');
657
+ const audio = AssetManager.getAudio('mySound');
658
+ ```
659
+
660
+ **AssetType Enum:**
661
+
662
+ ```typescript
663
+ AssetType.GLTF; // 3D models
664
+ AssetType.Audio; // Sound files
665
+ AssetType.Texture; // Images
666
+ AssetType.HDRTexture; // HDR environment maps
667
+ ```
668
+
669
+ ### 15. VisibilityState
670
+
671
+ ```typescript
672
+ import { VisibilityState } from '@iwsdk/core';
673
+
674
+ VisibilityState.NonImmersive; // Browser mode (no XR)
675
+ VisibilityState.Hidden; // XR but not rendering
676
+ VisibilityState.Visible; // Full XR experience
677
+ VisibilityState.VisibleBlurred; // XR but focus lost
678
+
679
+ this.world.visibilityState.subscribe((state) => {
680
+ switch (state) {
681
+ case VisibilityState.NonImmersive:
682
+ // Show 2D fallback UI
683
+ break;
684
+ case VisibilityState.Visible:
685
+ // Full XR experience
686
+ break;
687
+ case VisibilityState.VisibleBlurred:
688
+ // Pause game, show overlay
689
+ break;
690
+ }
691
+ });
692
+ ```
693
+
694
+ ### XR Session Optimization
695
+
696
+ Configure frame rate and foveation when the XR session becomes visible:
697
+
698
+ ```typescript
699
+ this.world.visibilityState.subscribe((state) => {
700
+ if (state === VisibilityState.Visible) {
701
+ this.world.session?.updateTargetFrameRate(72); // Request 72 FPS
702
+ this.world.renderer.xr.setFoveation(1); // Max foveation for performance
703
+ }
704
+ });
705
+ ```
706
+
707
+ ### 16. Locomotion Configuration
708
+
709
+ ```typescript
710
+ import { LocomotionSystem, TurningMethod } from '@iwsdk/core';
711
+
712
+ const locomotion = world.getSystem(LocomotionSystem);
713
+
714
+ // All config properties are signals
715
+ locomotion.config.slidingSpeed.value = 3.0;
716
+ locomotion.config.turningMethod.value = TurningMethod.SmoothTurn; // SnapTurn = 1, SmoothTurn = 2 — always use the enum, not raw numbers
717
+ locomotion.config.turningAngle.value = 45;
718
+ locomotion.config.turningSpeed.value = 180;
719
+ locomotion.config.comfortAssist.value = 0.5;
720
+ locomotion.config.rayGravity.value = -0.4;
721
+ locomotion.config.jumpHeight.value = 1.5;
722
+ locomotion.config.jumpCooldown.value = 0.1;
723
+ locomotion.config.maxDropDistance.value = 5.0;
724
+ locomotion.config.useWorker.value = true;
725
+ locomotion.config.enableJumping.value = true; // Enable/disable jumping entirely
726
+ locomotion.config.initialPlayerPosition.value = [0, 0, 0]; // Starting position
727
+ ```
728
+
729
+ **EnvironmentType** (used with `LocomotionEnvironment` component):
730
+
731
+ ```typescript
732
+ import { EnvironmentType } from '@iwsdk/core';
733
+
734
+ EnvironmentType.STATIC; // Fixed geometry (walls, floors) — default
735
+ EnvironmentType.KINEMATIC; // Moving platforms (elevators, conveyors)
736
+ ```
737
+
738
+ ### 17. Scene Understanding (AR)
739
+
740
+ ```typescript
741
+ import { XRPlane, XRMesh, XRAnchor } from '@iwsdk/core';
742
+
743
+ // Enable in World.create
744
+ World.create(container, {
745
+ xr: {
746
+ sessionMode: SessionMode.ImmersiveAR,
747
+ features: { planeDetection: true, meshDetection: true },
748
+ },
749
+ features: {
750
+ sceneUnderstanding: true,
751
+ },
752
+ });
753
+
754
+ // Query detected planes/meshes
755
+ export class MyARSystem extends createSystem({
756
+ planes: { required: [XRPlane] },
757
+ meshes: { required: [XRMesh] },
758
+ anchors: { required: [XRAnchor] },
759
+ }) {
760
+ init() {
761
+ this.queries.planes.subscribe('qualify', (entity) => {
762
+ // New plane detected
763
+ const plane = entity.object3D;
764
+ });
765
+ }
766
+ }
767
+ ```
768
+
769
+ ### 18. Feature Configuration (Critical!)
770
+
771
+ **Only enable features that your experience actually uses.** Features have prerequisites - enabling them without proper setup causes problems.
772
+
773
+ #### Feature Decision Matrix
774
+
775
+ | Feature | Enable When | Prerequisites | If Missing |
776
+ | -------------------- | ------------------------------------- | ------------------------------------------ | ------------------------------ |
777
+ | `locomotion` | Player needs to move (teleport/slide) | Collision geometry in scene (floor, walls) | **Player falls through world** |
778
+ | `physics` | Objects need dynamic simulation | PhysicsShape + PhysicsBody components | Wasted overhead |
779
+ | `grabbing` | Objects are grabbable | Grabbable components on entities | Wasted overhead |
780
+ | `sceneUnderstanding` | AR with real-world surfaces | AR session mode | Feature won't work |
781
+ | `environmentRaycast` | AR object placement | AR session + hit-test support | Feature won't work |
782
+ | `spatialUI` | Rendering UIKitML assets | Manifest `AssetType.UIKitML` entries | No UI renders |
783
+
784
+ #### Locomotion Requires Environment Setup
785
+
786
+ ```typescript
787
+ // ❌ BAD - Locomotion enabled but no collision geometry
788
+ const world = await World.create(container, {
789
+ features: {
790
+ locomotion: true, // Player will fall through the floor!
791
+ },
792
+ });
793
+
794
+ // ✅ GOOD - Locomotion with proper environment
795
+ const world = await World.create(container, {
796
+ level: './scenes/vr.iwsdk.scene.json', // Scene has collision meshes
797
+ features: {
798
+ locomotion: true,
799
+ physics: true, // Physics provides collision detection
800
+ },
801
+ });
802
+
803
+ // ✅ GOOD - Static experience, no locomotion needed
804
+ const world = await World.create(container, {
805
+ features: {
806
+ locomotion: false, // Player stays at origin
807
+ grabbing: true, // Can still interact with objects
808
+ },
809
+ });
810
+ ```
811
+
812
+ #### VR vs AR Feature Sets
813
+
814
+ ```typescript
815
+ // VR Experience - typically needs locomotion
816
+ const vrWorld = await World.create(container, {
817
+ xr: { sessionMode: SessionMode.ImmersiveVR },
818
+ features: {
819
+ locomotion: true, // Move around virtual space
820
+ grabbing: true,
821
+ physics: true,
822
+ },
823
+ });
824
+
825
+ // AR Experience - player moves physically, no virtual locomotion
826
+ const arWorld = await World.create(container, {
827
+ xr: {
828
+ sessionMode: SessionMode.ImmersiveAR,
829
+ features: { planeDetection: true, hitTest: true },
830
+ },
831
+ features: {
832
+ locomotion: false, // Player walks in real world
833
+ sceneUnderstanding: true, // Detect real surfaces
834
+ environmentRaycast: true, // Place objects on surfaces
835
+ grabbing: true,
836
+ },
837
+ });
838
+ ```
839
+
840
+ ### 19. World Initialization Pattern
841
+
842
+ ```typescript
843
+ import { World, SessionMode } from '@iwsdk/core';
844
+
845
+ const publicAssetUrl = (path: string) =>
846
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
847
+
848
+ const world = await World.create(container, {
849
+ render: {
850
+ fov: 50,
851
+ near: 0.1,
852
+ far: 200,
853
+ stencil: false, // Enable stencil buffer if needed
854
+ },
855
+
856
+ assets: {
857
+ myModel: {
858
+ url: publicAssetUrl('models/scene.glb'),
859
+ type: AssetType.GLTF,
860
+ },
861
+ },
862
+
863
+ level: './scenes/main.iwsdk.scene.json',
864
+
865
+ xr: {
866
+ sessionMode: SessionMode.ImmersiveVR,
867
+ referenceSpace: { type: 'local-floor' },
868
+ // Structured feature flags — NOT raw string arrays. Each accepts a
869
+ // boolean or { required: true }.
870
+ features: { handTracking: true, planeDetection: true },
871
+ offer: 'once', // 'none' | 'once' | 'always' (default: 'always')
872
+ },
873
+
874
+ // Enable feature systems - ONLY what you need!
875
+ features: {
876
+ locomotion: true, // Only if scene has collision geometry
877
+ // OR object form:
878
+ // locomotion: {
879
+ // useWorker: true,
880
+ // initialPlayerPosition: [0, 0, 0],
881
+ // comfortAssistLevel: 0.5, // option key; maps to the LocomotionSystem 'comfortAssist' config signal
882
+ // turningMethod: TurningMethod.SnapTurn,
883
+ // enableJumping: true,
884
+ // },
885
+ grabbing: true, // Only if objects are grabbable
886
+ // OR object form: grabbing: { useHandPinchForGrab: false }, // pinch grabs by default
887
+ physics: true, // Only if using dynamic physics
888
+ sceneUnderstanding: true, // OR: { showWireFrame: true }
889
+ environmentRaycast: true, // AR hit-test against real-world surfaces
890
+ camera: true, // Camera video access (requires XR session)
891
+ spatialUI: {
892
+ forwardHtmlEvents: true,
893
+ preferredColorScheme: 'dark',
894
+ },
895
+ },
896
+ });
897
+
898
+ // Register custom systems
899
+ world.registerSystem(MySystem);
900
+
901
+ // Launch/exit XR
902
+ world.launchXR();
903
+ world.exitXR();
904
+ ```
905
+
906
+ Background and image-based lighting are authored explicitly with dome and IBL
907
+ components on the level root. IWSDK does not synthesize missing environment
908
+ components; the VR and Desktop 3D starter scene authors `DomeGradient` and
909
+ `IBLGradient`, and the AR starter authors only `IBLGradient` so no sky covers
910
+ passthrough.
911
+
912
+ ### Post-Creation Initialization Sequence
913
+
914
+ After `World.create()`, follow this order for proper initialization:
915
+
916
+ ```typescript
917
+ // 1. Create subsystems (physics engine, networking, etc.)
918
+ const simulator = await RaceSimulator.create({ useWorker: true });
919
+
920
+ // 2. Store shared state in world.globals
921
+ world.globals.raceSimulator = simulator;
922
+ (world.globals as Record<string, unknown>).carProxies = new Map();
923
+ (world.globals as Record<string, unknown>).gamePaused = signal(true);
924
+
925
+ // 3. Register components
926
+ world
927
+ .registerComponent(VehiclePhysicsLink)
928
+ .registerComponent(VehiclePhysicsState);
929
+
930
+ // 4. Setup scene (creates entities)
931
+ await setupScene(world, simulator, { aiCount: 5 });
932
+
933
+ // 5. Register systems with priorities
934
+ world
935
+ .registerSystem(PlayerInputSystem, { priority: 0 })
936
+ .registerSystem(PhysicsStepSystem, { priority: 10 });
937
+ ```
938
+
939
+ ### 20. Transform Entity Creation
940
+
941
+ ```typescript
942
+ // Create entity with Object3D binding
943
+ const entity = world.createTransformEntity(mesh, {
944
+ parent: parentEntity, // Optional parent
945
+ persistent: false, // false = destroyed with level
946
+ });
947
+
948
+ // Transform component automatically syncs with Object3D (zero-copy)
949
+ entity.object3D.position.set(0, 1, 0);
950
+
951
+ // Component API for vector fields: getVectorView ONLY — in elics 3.4.x
952
+ // setValue/getValue THROW for Vec2/Vec3/Vec4/Color fields. setValue is
953
+ // fine for scalars, booleans, strings, and enums.
954
+ const posView = entity.getVectorView(Transform, 'position');
955
+ posView.set([0, 1, 0]); // write
956
+ posView[0] += delta; // direct array element write
957
+ ```
958
+
959
+ ### 21. Panel UI Pattern
960
+
961
+ ```typescript
962
+ import { UIKit, UIKitMLAsset, VisibilityState } from '@iwsdk/core';
963
+
964
+ // "settings-panel" is the stable scene node id. Its content.asset points to
965
+ // an AssetType.UIKitML manifest entry.
966
+ const panel = world.requireSceneObject<UIKitMLAsset>('settings-panel');
967
+ const saveButton = panel.requireElementById<UIKit.Text>('save-button');
968
+ const xrButton = panel.requireElementById<UIKit.Text>('xr-button');
969
+
970
+ saveButton.addEventListener('click', () => {
971
+ // Apply settings and play feedback here.
972
+ });
973
+
974
+ const unsubscribe = world.visibilityState.subscribe((state) => {
975
+ const is2D = state === VisibilityState.NonImmersive;
976
+ xrButton.setProperties({ display: is2D ? 'flex' : 'none' });
977
+ });
978
+
979
+ // Retain unsubscribe and call it when the owning feature/system is destroyed.
980
+ ```
981
+
982
+ The manifest ID identifies the reusable UIKitML definition; the scene node ID
983
+ identifies a placed instance; element IDs identify controls inside it. For code-owned
984
+ instances, retain the object returned by the asset manager:
985
+
986
+ ```typescript
987
+ const panel = await world.assets.instantiate<UIKitMLAsset>('settings-panel');
988
+ const entity = world.createTransformEntity(panel);
989
+ panel.requireElementById('save-button').addEventListener('click', save);
990
+ ```
991
+
992
+ Do not discover application panels through internal `PanelDocument` storage or
993
+ transient ECS indices.
994
+
995
+ ### 22. Environment Raycasting (AR Hit-Test)
996
+
997
+ `EnvironmentRaycastTarget` makes an entity automatically follow XR hit-test results (raycast against real-world surfaces). The entity is positioned at the hit point and oriented to match the surface normal.
998
+
999
+ ```typescript
1000
+ import { EnvironmentRaycastTarget, RaycastSpace } from '@iwsdk/core';
1001
+
1002
+ // Reticle that follows right controller ray
1003
+ const reticle = world.createTransformEntity(reticleMesh);
1004
+ reticle.addComponent(EnvironmentRaycastTarget, {
1005
+ space: RaycastSpace.Right, // Ray source
1006
+ maxDistance: 100, // Max raycast distance in meters
1007
+ });
1008
+
1009
+ // For phone AR: tap-to-place (uses screen touch)
1010
+ const marker = world.createTransformEntity(markerMesh);
1011
+ marker.addComponent(EnvironmentRaycastTarget, {
1012
+ space: RaycastSpace.Screen, // Tracks screen touch
1013
+ });
1014
+
1015
+ // Read hit-test result (e.g., to spawn an object on trigger press)
1016
+ const xrResult = entity.getValue(EnvironmentRaycastTarget, 'xrHitTestResult');
1017
+ if (xrResult && gamepad?.getSelectStart()) {
1018
+ spawnObject(entity.object3D.position.clone());
1019
+ }
1020
+ ```
1021
+
1022
+ **RaycastSpace:**
1023
+
1024
+ ```typescript
1025
+ RaycastSpace.Left; // Left controller's target ray
1026
+ RaycastSpace.Right; // Right controller's target ray (default)
1027
+ RaycastSpace.Viewer; // Head/gaze direction
1028
+ RaycastSpace.Screen; // Phone AR screen touch (tap-to-place)
1029
+ ```
1030
+
1031
+ **Prerequisites:** `features: { environmentRaycast: true }` and `xr.features: { hitTest: true }` in AR session mode.
1032
+
1033
+ ### 23. Follower Component
1034
+
1035
+ Makes an entity follow another Object3D with thresholded, smoothed motion. It
1036
+ can keep compact global UI discoverable without rigidly head-locking it.
1037
+
1038
+ ```typescript
1039
+ import { Follower, FollowBehavior } from '@iwsdk/core';
1040
+
1041
+ entity.addComponent(Follower, {
1042
+ target: world.player.head, // Must be an Object3D
1043
+ offsetPosition: [0, -0.2, -0.8], // Offset in target's local space
1044
+ behavior: FollowBehavior.PivotY, // Rotation behavior
1045
+ maxAngle: 30, // Degrees before snapping forward
1046
+ tolerance: 0.4, // Meters of positional slack
1047
+ speed: 1, // Lerp speed
1048
+ });
1049
+ ```
1050
+
1051
+ **FollowBehavior:**
1052
+
1053
+ ```typescript
1054
+ FollowBehavior.FaceTarget; // Fully face the target
1055
+ FollowBehavior.PivotY; // Only rotate around Y axis (default)
1056
+ FollowBehavior.NoRotation; // Follow position only, no rotation
1057
+ ```
1058
+
1059
+ **Note:** `target` must be an `Object3D` instance (e.g., `world.player.head`), not an entity.
1060
+
1061
+ ### 24. CameraSource Component
1062
+
1063
+ Access device camera video as a texture. Useful for mixed reality effects or photo capture.
1064
+
1065
+ ```typescript
1066
+ import {
1067
+ CameraSource,
1068
+ CameraFacing,
1069
+ CameraState,
1070
+ CameraUtils,
1071
+ } from '@iwsdk/core';
1072
+
1073
+ // Add camera to an entity
1074
+ entity.addComponent(CameraSource, {
1075
+ // Input fields (user-configurable)
1076
+ deviceId: '', // Empty = auto-select based on facing
1077
+ facing: CameraFacing.Back, // Preferred camera direction
1078
+ width: 1920, // Requested resolution
1079
+ height: 1080,
1080
+ frameRate: 30,
1081
+ });
1082
+
1083
+ // Read-only output fields (managed by CameraSystem):
1084
+ // state: CameraState.Inactive | .Starting | .Active | .Error
1085
+ // texture: VideoTexture (apply to materials)
1086
+ // videoElement: HTMLVideoElement (advanced use)
1087
+ ```
1088
+
1089
+ **CameraFacing:**
1090
+
1091
+ ```typescript
1092
+ CameraFacing.Back; // Rear-facing camera
1093
+ CameraFacing.Front; // Front-facing (selfie) camera
1094
+ CameraFacing.Unknown; // Any available camera (default)
1095
+ ```
1096
+
1097
+ **CameraState:**
1098
+
1099
+ ```typescript
1100
+ CameraState.Inactive; // Not started
1101
+ CameraState.Starting; // Async initialization in progress
1102
+ CameraState.Active; // Stream running
1103
+ CameraState.Error; // Failed to start; terminal until explicitly restarted
1104
+ ```
1105
+
1106
+ **CameraUtils** static class:
1107
+
1108
+ ```typescript
1109
+ // List available cameras (requests permission on first call)
1110
+ const devices = await CameraUtils.getDevices();
1111
+ const backCam = CameraUtils.findByFacing(devices, CameraFacing.Back);
1112
+
1113
+ // Retry after correcting a startup error or changing camera configuration
1114
+ CameraUtils.restart(cameraEntity);
1115
+
1116
+ // Capture current frame as canvas (for snapshot/processing)
1117
+ const canvas = CameraUtils.captureFrame(cameraEntity);
1118
+ if (canvas) {
1119
+ const texture = new CanvasTexture(canvas);
1120
+ }
1121
+ ```
1122
+
1123
+ **Requires:** `features: { camera: true }`, a secure context, camera permission, and a camera exposed through browser `MediaDevices`. Streams can run while the world is visible in browser-only or immersive XR mode. `CameraSource` does not expose Quest passthrough or raw headset-camera frames.
1124
+
1125
+ ### 25. PhysicsManipulation Component
1126
+
1127
+ Applies forces or velocity changes to physics bodies. **One-shot component** — `PhysicsSystem` applies the values and auto-removes it each frame.
1128
+
1129
+ ```typescript
1130
+ import { PhysicsManipulation } from '@iwsdk/core';
1131
+
1132
+ // Apply an impulse force
1133
+ entity.addComponent(PhysicsManipulation, {
1134
+ force: [0, 10, 0], // Force vector (one-shot impulse)
1135
+ linearVelocity: [0, 0, 0], // Set linear velocity directly
1136
+ angularVelocity: [0, 0, 0], // Set angular velocity directly
1137
+ });
1138
+ // PhysicsSystem applies these values and auto-removes PhysicsManipulation
1139
+
1140
+ // For sustained forces, re-add the component each frame:
1141
+ update() {
1142
+ if (!entity.hasComponent(PhysicsManipulation)) {
1143
+ entity.addComponent(PhysicsManipulation, { force: [0, 5, 0] });
1144
+ }
1145
+ }
1146
+ ```
1147
+
1148
+ ### 26. ScreenSpace Usage Notes
1149
+
1150
+ `ScreenSpace` positions the UIKit document under a manifest-backed UIKitML entity
1151
+ relative to the screen in non-XR (browser) mode. It is intentional application
1152
+ behavior, not a temporary preview technique; use the editor's isolated preview for
1153
+ development.
1154
+
1155
+ **All position/size values are CSS strings**, not numbers:
1156
+
1157
+ ```typescript
1158
+ import { ScreenSpace } from '@iwsdk/core';
1159
+
1160
+ entity.addComponent(ScreenSpace, {
1161
+ width: '400px', // Explicit CSS size: '400px', '50vw', calc(...)
1162
+ height: '300px', // Explicit CSS size: '300px', '40vh', calc(...)
1163
+ top: '20px', // CSS position or 'auto'
1164
+ left: '20px', // CSS position or 'auto'
1165
+ bottom: 'auto',
1166
+ right: 'auto',
1167
+ zOffset: 0.2, // Distance in meters from camera near plane (NOT CSS)
1168
+ });
1169
+ ```
1170
+
1171
+ **How it works:** The system creates hidden DOM elements and uses `getComputedStyle()` to convert CSS values → pixels → meters. Use explicit dimensions (`calc()`, `vw`, `vh`, `%`, etc.); unconstrained `auto` dimensions fall back to a small viewport-relative size and warn.
1172
+
1173
+ **XR behavior:** When entering XR, `ScreenSpaceUISystem` automatically moves the panel back to world space. When exiting XR, it re-positions to screen space.
1174
+
1175
+ ### 27. Entity API
1176
+
1177
+ ```typescript
1178
+ // Destroy entity only (components removed, Object3D detached)
1179
+ entity.destroy();
1180
+
1181
+ // Destroy entity AND dispose GPU resources (geometry, materials, textures)
1182
+ // Use for entities with meshes/materials that need proper GPU cleanup
1183
+ entity.dispose();
1184
+
1185
+ // Get all component classes attached to this entity
1186
+ entity.getComponents();
1187
+ ```
1188
+
1189
+ **`dispose()` vs `destroy()`:** Use `dispose()` when the entity has meshes, materials, or textures that should be freed from GPU memory. Use `destroy()` when GPU resources are shared or managed elsewhere. Use `dispose()` with caution when resources may be shared across multiple entities.
1190
+
1191
+ ### 28. Utility Functions
1192
+
1193
+ ```typescript
1194
+ import { setWorldPosition, setWorldQuaternion } from '@iwsdk/core';
1195
+
1196
+ // Set world-space position (correctly handles parent transform chain)
1197
+ setWorldPosition(object3D, worldPosition);
1198
+
1199
+ // Set world-space quaternion (correctly handles parent transforms including non-uniform scale)
1200
+ setWorldQuaternion(object3D, worldQuaternion);
1201
+ ```
1202
+
1203
+ These are useful when you need to position an object in world space but it's nested under transformed parents. They compute the correct local transform to achieve the desired world transform.
1204
+
1205
+ ```typescript
1206
+ // Level root helpers on World:
1207
+ world.getActiveRoot(); // Returns active level's Object3D (or scene)
1208
+ world.getPersistentRoot(); // Returns the scene Object3D
1209
+ ```
1210
+
1211
+ ## Core Components Reference (30 Total)
1212
+
1213
+ | Component | Purpose |
1214
+ | ------------------------ | ----------------------------------------------- |
1215
+ | Transform | Position, rotation, scale |
1216
+ | Visibility | Show/hide objects |
1217
+ | LevelTag | Marks level membership |
1218
+ | LevelRoot | Level root marker |
1219
+ | RayInteractable | Marks objects for ray and pointer interaction |
1220
+ | Hovered | Currently hovered |
1221
+ | Pressed | Currently pressed/grabbed |
1222
+ | OneHandGrabbable | Single-hand manipulation |
1223
+ | TwoHandsGrabbable | Two-hand manipulation |
1224
+ | DistanceGrabbable | Grab from distance |
1225
+ | Handle | Manipulation handle |
1226
+ | PhysicsBody | Physics motion properties |
1227
+ | PhysicsShape | Collision shape + material |
1228
+ | PhysicsManipulation | Force/velocity application |
1229
+ | DomeGradient | Gradient sky |
1230
+ | DomeTexture | Textured sky |
1231
+ | IBLGradient | Gradient IBL lighting |
1232
+ | IBLTexture | Texture IBL lighting |
1233
+ | PanelUI | Legacy component-backed UI loader compatibility |
1234
+ | PanelDocument | Internal loaded UI document state |
1235
+ | ScreenSpace | Screen-attached UI |
1236
+ | Follower | Object following |
1237
+ | XRPlane | Detected AR planes |
1238
+ | XRMesh | Detected AR meshes |
1239
+ | XRAnchor | Spatial anchors |
1240
+ | AudioSource | Audio configuration |
1241
+ | CameraSource | Camera device |
1242
+ | DepthOccludable | Depth-based occlusion for AR |
1243
+ | LocomotionEnvironment | Locomotion settings |
1244
+ | EnvironmentRaycastTarget | AR environment hit-test target |
1245
+
1246
+ ## Core Systems Reference (20 Total)
1247
+
1248
+ | System | Priority | Purpose |
1249
+ | ------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
1250
+ | LocomotionSystem | -5 | Movement (teleport/slide/turn) |
1251
+ | InputSystem | -4 | Pointer interaction state management |
1252
+ | GrabSystem | -3 | Grab handling |
1253
+ | PhysicsSystem | -2 | Physics simulation |
1254
+ | SceneUnderstandingSystem | -1 | AR plane/mesh detection |
1255
+ | EnvironmentRaycastSystem | -1 | AR environment raycasting |
1256
+ | PanelUISystem | -3.8 | UI panels |
1257
+ | ScreenSpaceUISystem | -3.75 | Screen UI |
1258
+ | CanvasPointerSystem | -3.5 | DOM pointer → scene forwarding (registered when input.canvasPointerEvents is enabled — the default) |
1259
+ | CameraSystem | default | Camera access |
1260
+ | LevelSystem | default | Level loading |
1261
+ | EnvironmentSystem | default | Lighting/sky |
1262
+ | AudioSystem | default | Spatial audio |
1263
+ | TransformSystem | default | Transform sync |
1264
+ | VisibilitySystem | default | Visibility sync |
1265
+ | FollowSystem | default | Object following |
1266
+ | TurnSystem | default | Rotation |
1267
+ | TeleportSystem | default | Teleportation |
1268
+ | SlideSystem | default | Smooth movement |
1269
+ | DepthSensingSystem | default | Depth occlusion for AR |
1270
+
1271
+ ### Custom System Priority Guidelines
1272
+
1273
+ Register custom systems with priorities following input→simulation→rendering pipeline:
1274
+
1275
+ ```
1276
+ Priority 0-9: Input capture (player input, AI decisions)
1277
+ Priority 10-19: Simulation (physics step, game logic)
1278
+ Priority 20-29: Visual sync (sync Three.js objects to physics)
1279
+ Priority 30+: Low-priority updates (UI, HUD, ambient effects)
1280
+ ```
1281
+
1282
+ Example:
1283
+
1284
+ ```typescript
1285
+ world
1286
+ .registerSystem(PlayerInputSystem, { priority: 0 })
1287
+ .registerSystem(AIDriverSystem, { priority: 1 })
1288
+ .registerSystem(PhysicsStepSystem, { priority: 10 })
1289
+ .registerSystem(VehicleSyncSystem, { priority: 20 })
1290
+ .registerSystem(DashboardSystem, { priority: 35 });
1291
+ ```
1292
+
1293
+ ## Project Structure
1294
+
1295
+ ```
1296
+ my-iwsdk-project/
1297
+ ├── iwsdk.config.json # Declarative project/world authority
1298
+ ├── src/
1299
+ │ ├── index.ts # World.create() plus system registration
1300
+ │ ├── assets.ts # defineAssets() project catalog
1301
+ │ ├── components.ts # defineComponents() declarations
1302
+ │ ├── systems/
1303
+ │ │ ├── ui-system.ts # Panel/UI management
1304
+ │ │ └── game-system.ts # Game logic
1305
+ │ └── components/
1306
+ │ └── custom.ts # Custom component definitions
1307
+ ├── public/
1308
+ │ ├── scenes/ # Native IWSDK scene JSON files
1309
+ │ ├── audio/ # Audio files
1310
+ │ └── ui/ # Runtime-loaded .uikitml files and fonts
1311
+ ├── vite.config.ts
1312
+ └── package.json
1313
+ ```
1314
+
1315
+ ## What IWSDK Provides (Don't Rebuild These)
1316
+
1317
+ Before writing custom code, check if IWSDK already provides the functionality. Rebuilding built-in features wastes time and produces inferior results (missing BVH acceleration, XR compatibility, comfort features, etc.).
1318
+
1319
+ ### Reinvention Risk Table
1320
+
1321
+ | What you might build from scratch | What IWSDK already provides |
1322
+ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
1323
+ | GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
1324
+ | Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
1325
+ | Hover/click interaction with Raycaster | `RayInteractable` + `Hovered` + `Pressed` components |
1326
+ | Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
1327
+ | Floor fading into the sky (`onBeforeCompile` with copied sky GLSL) | `DomeFade` on the floor node |
1328
+ | PBR environment lighting | `IBLGradient` or `IBLTexture` component |
1329
+ | Canvas or radial blob shadow card | `ContactShadow` node component |
1330
+ | ShadowMaterial plane for AR | `ShadowCatcher` node component |
1331
+ | Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
1332
+ | Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
1333
+ | Controller 3D models | Auto-loaded from WebXR Input Profiles |
1334
+ | Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
1335
+ | Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
1336
+ | Hit-test against real world | `EnvironmentRaycastTarget` component |
1337
+ | Spatial audio | `AudioSource` component with pooling |
1338
+ | Camera feed texture | `CameraSource` component |
1339
+ | Depth occlusion shader | `DepthOccludable` component |
1340
+ | HUD / screen-space UI | `ScreenSpace` component with CSS units |
1341
+ | Follow-head billboard | `Follower` component |
1342
+ | Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
1343
+ | Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
1344
+ | Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
1345
+ | Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
1346
+ | Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
1347
+ | Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
1348
+
1349
+ ### Asset Loading (AssetManager)
1350
+
1351
+ **Always use AssetManager** — never use raw `GLTFLoader`, `TextureLoader`, etc. AssetManager handles DRACO/KTX2 decoder setup, caching, and de-duplication automatically.
1352
+
1353
+ **Manifest pattern (preload at startup):**
1354
+
1355
+ ```typescript
1356
+ const publicAssetUrl = (path: string) =>
1357
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
1358
+
1359
+ const world = await World.create(container, {
1360
+ assets: {
1361
+ myModel: {
1362
+ url: publicAssetUrl('models/scene.glb'),
1363
+ type: AssetType.GLTF,
1364
+ priority: 'critical',
1365
+ },
1366
+ mySound: {
1367
+ url: publicAssetUrl('audio/click.mp3'),
1368
+ type: AssetType.Audio,
1369
+ priority: 'background',
1370
+ },
1371
+ myTexture: {
1372
+ url: publicAssetUrl('textures/wood.jpg'),
1373
+ type: AssetType.Texture,
1374
+ },
1375
+ myHDR: {
1376
+ url: publicAssetUrl('textures/env.hdr'),
1377
+ type: AssetType.HDRTexture,
1378
+ },
1379
+ },
1380
+ });
1381
+
1382
+ // Retrieve preloaded assets (synchronous — already loaded)
1383
+ const gltf = AssetManager.getGLTF('myModel');
1384
+ // `getGLTF` returns a fresh clone of `scene`/`scenes` per call, so the
1385
+ // same key safely backs multiple entities. Pass `{ shared: true }` to
1386
+ // get the cached instance.
1387
+ const texture = AssetManager.getTexture('myTexture');
1388
+ const audio = AssetManager.getAudio('mySound');
1389
+ ```
1390
+
1391
+ **Render loop (headless automation):** `world.renderMode` is `'continuous'`
1392
+ (default) or `'on-demand'`. On demand, systems still run every frame but only
1393
+ frames asked for are drawn: `await world.requestRender(frames)` or
1394
+ `const release = world.holdRender()` (draw every frame until `release()`).
1395
+ Headless dev sessions switch it on for you; shipped apps keep `'continuous'`.
1396
+
1397
+ **Runtime loading (on-demand):**
1398
+
1399
+ ```typescript
1400
+ // Load at runtime when not known at startup
1401
+ const gltf = await AssetManager.loadGLTF(
1402
+ './models/dynamic.glb',
1403
+ 'dynamicModel',
1404
+ );
1405
+ const texture = await AssetManager.loadTexture(
1406
+ './textures/new.jpg',
1407
+ 'newTexture',
1408
+ );
1409
+ ```
1410
+
1411
+ **Supported AssetTypes:** `GLTF`, `Audio`, `Texture`, `HDRTexture`
1412
+
1413
+ ### Entity Parenting & Level Lifecycle
1414
+
1415
+ **Always use `createTransformEntity`** — never `scene.add()`. Entities created with `createTransformEntity` get a `Transform` component, participate in ECS queries, and are automatically managed by the level system.
1416
+
1417
+ ```typescript
1418
+ // Basic entity with parent
1419
+ const entity = world.createTransformEntity(mesh, parentEntity);
1420
+
1421
+ // With options object
1422
+ const entity = world.createTransformEntity(mesh, {
1423
+ parent: parentEntity,
1424
+ persistent: false, // false (default) = destroyed when level changes
1425
+ });
1426
+
1427
+ // Persistent entity — survives level changes
1428
+ const hud = world.createTransformEntity(hudMesh, {
1429
+ parent: world.sceneEntity,
1430
+ persistent: true,
1431
+ });
1432
+ ```
1433
+
1434
+ **Level lifecycle:**
1435
+
1436
+ - Entities with `LevelTag` are automatically destroyed when `world.loadLevel()` is called
1437
+ - Non-persistent entities created via `createTransformEntity` automatically get `LevelTag`
1438
+ - Use `persistent: true` for entities that should survive level transitions (HUDs, audio managers, etc.)
1439
+ - `world.loadLevel(url)` destroys all level-tagged entities, then loads the new native scene document
1440
+
1441
+ **Warning:** Parenting an Object3D under another Object3D that is NOT an entity's `object3D` will silently reparent it to the scene root and log a warning.
1442
+
1443
+ ### Input & Interaction
1444
+
1445
+ **RayInteractable → Hovered/Pressed flow:**
1446
+
1447
+ 1. Add `RayInteractable` component to any entity that should respond to pointer input
1448
+ 2. `InputSystem` automatically performs BVH-accelerated raycasting each frame
1449
+ 3. When a ray hits a RayInteractable entity, `Hovered` tag is added
1450
+ 4. When the user presses the select button while hovering, `Pressed` tag is added
1451
+ 5. Query for `Hovered`/`Pressed` in your system to react to interactions
1452
+
1453
+ ```typescript
1454
+ // Setup
1455
+ entity.addComponent(RayInteractable);
1456
+
1457
+ // In your system — react to interactions
1458
+ export class MyInteractionSystem extends createSystem({
1459
+ hovered: { required: [MyComponent, Hovered] },
1460
+ pressed: { required: [MyComponent, Pressed] },
1461
+ }) {
1462
+ init() {
1463
+ this.queries.pressed.subscribe('qualify', (entity) => {
1464
+ // Entity was just clicked/selected
1465
+ });
1466
+ }
1467
+ }
1468
+ ```
1469
+
1470
+ **StatefulGamepad API** (accessed via `this.input.xr.gamepads.left` / `.right`):
1471
+
1472
+ - `getButtonDown(InputComponent.Trigger)` — true on the frame the button was pressed
1473
+ - `getButtonUp(InputComponent.Trigger)` — true on the frame the button was released
1474
+ - `getButtonPressed(InputComponent.Trigger)` — true while held
1475
+ - `getButtonValue(InputComponent.Trigger)` — analog 0-1
1476
+ - `getAxesValues(InputComponent.Thumbstick)` — `{ x, y }` in -1 to 1 range
1477
+ - `getAxesEnteringUp/Down/Left/Right(InputComponent.Thumbstick)` — directional flick detection
1478
+
1479
+ ### Built-in Visuals (Don't Recreate)
1480
+
1481
+ These visuals are automatically created and managed by IWSDK systems:
1482
+
1483
+ - **RayPointer** — Cylinder mesh with gradient shader + circular cursor at hit point. Created automatically by `InputSystem` for each connected controller.
1484
+ - **AnimatedController** — GLTF controller models auto-loaded from the WebXR Input Profiles registry. Matches the user's actual hardware.
1485
+ - **AnimatedHand** — Skeletal hand mesh with outline shader for hand tracking mode. Auto-managed by the input system.
1486
+ - **Teleport visuals** — Parabolic arc + landing circle indicator. Rendered by `LocomotionSystem` when teleport mode is active.
1487
+ - **Comfort vignette** — Screen-edge darkening during smooth locomotion. Controlled by `locomotion.config.comfortAssist` (0 = off, 1 = maximum).
1488
+ - **DomeGradient / DomeTexture** — Sky dome rendering. Add the component to an entity; `EnvironmentSystem` handles the rest.
1489
+
1490
+ ## Anti-Patterns to Avoid
1491
+
1492
+ 1. **DON'T** store entity arrays in systems - use queries
1493
+ 2. **DON'T** poll for state changes - use signal subscriptions
1494
+ 3. **DON'T** manually track component additions/removals - use query subscribe
1495
+ 4. **DON'T** create entities in update() without proper lifecycle management
1496
+ 5. **DON'T** use `Types.Object` for data that could be typed (use Vec3, Float32, etc.)
1497
+ 6. **DON'T** forget cleanup functions for subscriptions and resources
1498
+ 7. **DON'T** mutate live query Sets while iterating: if your loop body removes AND re-adds required components, the re-qualified entity is revisited by the same iteration — an infinite loop. Iterate `Array.from(query.entities)` instead
1499
+ 8. **DON'T** enable locomotion without collision geometry - player falls through world
1500
+ 9. **DON'T** enable features you don't use - adds overhead and can cause bugs
1501
+ 10. **DON'T** confuse PhysicsBody (motion) with PhysicsShape (collision + material)
1502
+ 11. **DON'T** use raw `GLTFLoader`/`TextureLoader` — use `AssetManager` for caching, DRACO/KTX2 setup
1503
+ 12. **DON'T** use `scene.add()` — use `createTransformEntity()` for proper ECS integration
1504
+ 13. **DON'T** replace IWSDK pointer interaction with `new Raycaster()` — use `RayInteractable`; raw raycasters are valid for custom geometric queries, but the caller owns ECS entity mapping, target filtering, and pointer lifecycle
1505
+ 14. **DON'T** add environment components (`DomeGradient`/`IBLTexture`/etc.) to arbitrary entities — must go on the level root (`world.activeLevel.value`)
1506
+ 15. **DON'T** forget `_needsUpdate` after changing `DomeTexture` or `IBLTexture` properties — their changes are silently ignored without `entity.setValue(DomeTexture, '_needsUpdate', true)`. `DomeGradient` and `IBLGradient` apply edits without it
1507
+ 16. **DON'T** use `entity.destroy()` for objects with GPU resources — use `entity.dispose()` which also cleans up geometry/materials/textures
1508
+ 17. **DON'T** pass numbers to `ScreenSpace` — all position/size values are CSS strings like `'400px'` or `'50vw'`
1509
+
1510
+ ## Performance Tips
1511
+
1512
+ 1. Use `getVectorView()` for direct TypedArray access (zero-copy)
1513
+ 2. Batch query enumeration (don't create intermediate arrays)
1514
+ 3. Use tag components for cheap boolean queries
1515
+ 4. Leverage query filters (`where`) to reduce iteration scope
1516
+ 5. System config signals auto-deduplicate (no callback if value unchanged)
1517
+ 6. Physics and locomotion can run in Web Workers for heavy scenes
1518
+ 7. Use `PhysicsShapeType.Auto` to let IWSDK pick optimal collision shape
1519
+
1520
+ ## When Planning a New Feature
1521
+
1522
+ 1. **Determine feature flags** - What built-in features does this need? (locomotion, physics, grabbing, etc.)
1523
+ 2. **Check prerequisites** - If using locomotion, is collision geometry set up?
1524
+ 3. **Identify components needed** - What data does this feature require?
1525
+ 4. **Design queries** - How will systems find relevant entities?
1526
+ 5. **Plan reactivity** - What changes should trigger updates?
1527
+ 6. **Consider lifecycle** - When are entities created/destroyed?
1528
+ 7. **Map to existing systems** - Can built-in systems (grab, physics, etc.) help?
1529
+ 8. **VR vs AR** - Does this work differently in each mode?
1530
+ 9. **Input handling** - What controller/hand inputs are needed?
1531
+ 10. **Audio feedback** - What sounds should play on interactions?
1532
+ 11. **Select 3D assets** - What models are needed, and what are their licensing, provenance, and performance constraints?