@iwsdk/cli 1.1.0 → 1.2.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +79 -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 +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -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 +178 -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-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
@@ -0,0 +1,1531 @@
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:
465
+
466
+ ```typescript
467
+ const physics = world.getSystem(PhysicsSystem);
468
+ physics.setBodyTransform(entity, {
469
+ position: homePosition,
470
+ quaternion: homeQuaternion,
471
+ });
472
+ ```
473
+
474
+ Writing only the Transform of a dynamic body is clobbered by the next physics frame.
475
+ `gravityFactor`, `linearDamping`, and `angularDamping` are reactive; motion `state` and
476
+ shape construction still require deliberate body lifecycle handling.
477
+
478
+ ### 12. Grabbable Components
479
+
480
+ ```typescript
481
+ import {
482
+ OneHandGrabbable,
483
+ TwoHandsGrabbable,
484
+ DistanceGrabbable,
485
+ MovementMode,
486
+ } from '@iwsdk/core';
487
+
488
+ // Basic single-hand grab
489
+ entity.addComponent(OneHandGrabbable, {});
490
+
491
+ // Constrained manipulation
492
+ entity.addComponent(OneHandGrabbable, {
493
+ rotate: true,
494
+ rotateMin: [0, -Math.PI, 0],
495
+ rotateMax: [0, Math.PI, 0],
496
+ translate: true,
497
+ translateMin: [-2, 0, -2],
498
+ translateMax: [2, 3, 2],
499
+ });
500
+
501
+ // Two-hand manipulation (with scaling)
502
+ entity.addComponent(TwoHandsGrabbable, {
503
+ rotate: true,
504
+ translate: true,
505
+ scale: true,
506
+ scaleMin: [0.5, 0.5, 0.5],
507
+ scaleMax: [2, 2, 2],
508
+ });
509
+
510
+ // ⚠️ One handle per entity: OneHandGrabbable, TwoHandsGrabbable, and
511
+ // DistanceGrabbable are MUTUALLY EXCLUSIVE on the same entity (GrabSystem
512
+ // creates a single Handle; near-grab denies ray pointers, distance-grab
513
+ // denies grab pointers). Pick one per entity — DistanceGrabbable with
514
+ // MoveTowardsTarget covers both near and far pickup via trigger.
515
+
516
+ // Distance grab
517
+ entity.addComponent(DistanceGrabbable, {
518
+ rotate: true,
519
+ translate: true,
520
+ scale: true,
521
+ movementMode: MovementMode.MoveTowardsTarget, // MoveTowardsTarget | MoveAtSource | RotateAtSource | MoveFromTarget
522
+ returnToOrigin: false, // Snap back when released
523
+ 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
524
+ });
525
+
526
+ // Force-release / hand lookup (game reset, weapon swap, recoil, etc.)
527
+ import { GrabSystem } from '@iwsdk/core';
528
+ const grab = world.getSystem(GrabSystem);
529
+ grab.forceRelease(entity); // drop a held entity safely (no-op if not held)
530
+ const hand = grab.getHolderHand(entity); // 'left' | 'right' | null ('left' for two-hand grabs)
531
+ ```
532
+
533
+ ### 13. Environment/Lighting
534
+
535
+ ```typescript
536
+ import {
537
+ DomeGradient,
538
+ DomeTexture,
539
+ IBLGradient,
540
+ IBLTexture,
541
+ } from '@iwsdk/core';
542
+
543
+ // Gradient sky dome (RGBA display colors - 4 components)
544
+ entity.addComponent(DomeGradient, {
545
+ sky: [0.2423, 0.6172, 0.8308, 1.0], // RGBA
546
+ equator: [0.6584, 0.7084, 0.7913, 1.0], // RGBA
547
+ ground: [0.807, 0.7758, 0.7454, 1.0], // RGBA
548
+ intensity: 1.0, // 0 = black
549
+ elevationDeg: 90, // sky pole height: 90 = straight up, lower tilts it
550
+ azimuthDeg: 0, // sky pole heading, node Y-rotation convention (90 = -X)
551
+ dither: false, // true adds ±0.5/255 noise against banding
552
+ });
553
+
554
+ // HDR texture sky
555
+ entity.addComponent(DomeTexture, {
556
+ src: './textures/sky.hdr',
557
+ });
558
+
559
+ // Image-based lighting from gradient
560
+ entity.addComponent(IBLGradient, {
561
+ sky: [0.6902, 0.749, 0.7843, 1.0], // RGBA
562
+ equator: [0.6584, 0.7084, 0.7913, 1.0], // RGBA
563
+ ground: [0.807, 0.7758, 0.7454, 1.0], // RGBA
564
+ intensity: 1.0, // applied once since 1.1.0 (square a 1.0.x value)
565
+ });
566
+
567
+ // IBL from texture
568
+ entity.addComponent(IBLTexture, {
569
+ src: 'room', // or URL to HDR
570
+ intensity: 1.0,
571
+ rotation: [0, 0, 0],
572
+ });
573
+ ```
574
+
575
+ **Critical Environment Usage Notes:**
576
+
577
+ 1. **Environment components MUST be added to the level root entity**, not arbitrary entities. The `EnvironmentSystem` queries require `LevelRoot`:
578
+
579
+ ```typescript
580
+ // ❌ BAD - Added to a random entity (silently ignored)
581
+ someEntity.addComponent(DomeGradient, { ... });
582
+
583
+ // ✅ GOOD - Added to the level root
584
+ const root = world.activeLevel.value;
585
+ root.addComponent(DomeGradient, { sky: [0.24, 0.62, 0.83, 1.0], ... });
586
+ ```
587
+
588
+ 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:
589
+
590
+ ```typescript
591
+ root.setValue(DomeTexture, 'intensity', 0.6);
592
+ root.setValue(DomeTexture, '_needsUpdate', true); // Required for textures!
593
+
594
+ root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]); // applies next frame
595
+ root.setValue(DomeGradient, 'elevationDeg', 30); // applies next frame
596
+ ```
597
+
598
+ 3. **Background vs IBL are separate**: `DomeTexture`/`DomeGradient` controls the visible sky. `IBLTexture`/`IBLGradient` controls scene lighting (reflections, ambient). You can mix them:
599
+
600
+ ```typescript
601
+ root.addComponent(DomeTexture, { src: './envs/sky.hdr', intensity: 0.9 });
602
+ root.addComponent(IBLTexture, { src: 'room', intensity: 1.2 }); // Lighting only
603
+ ```
604
+
605
+ 4. **In AR sessions**, backgrounds (dome) are automatically hidden but IBL remains active for realistic lighting on virtual objects.
606
+
607
+ 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:
608
+
609
+ ```json
610
+ {
611
+ "id": "floor",
612
+ "content": { "type": "asset", "asset": "floor" },
613
+ "components": {
614
+ "com.iwsdk.components.DomeFade": { "start": 4, "end": 10 }
615
+ }
616
+ }
617
+ ```
618
+
619
+ ### 14. Asset Loading
620
+
621
+ ```typescript
622
+ import { AssetManager, AssetType } from '@iwsdk/core';
623
+
624
+ const publicAssetUrl = (path: string) =>
625
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
626
+
627
+ const world = await World.create(container, {
628
+ assets: {
629
+ myModel: {
630
+ url: publicAssetUrl('models/scene.glb'),
631
+ type: AssetType.GLTF,
632
+ priority: 'critical',
633
+ },
634
+ mySound: {
635
+ url: publicAssetUrl('audio/click.mp3'),
636
+ type: AssetType.Audio,
637
+ priority: 'background',
638
+ },
639
+ myTexture: {
640
+ url: publicAssetUrl('textures/wood.jpg'),
641
+ type: AssetType.Texture,
642
+ },
643
+ myHDR: {
644
+ url: publicAssetUrl('textures/env.hdr'),
645
+ type: AssetType.HDRTexture,
646
+ },
647
+ },
648
+ });
649
+
650
+ // Access preloaded assets
651
+ const model = AssetManager.getGLTF('myModel');
652
+ // `getGLTF` returns a fresh clone of `scene`/`scenes` per call, so the
653
+ // same key safely backs multiple entities. Use `{ shared: true }` for
654
+ // the cached instance.
655
+ const texture = AssetManager.getTexture('myTexture');
656
+ const audio = AssetManager.getAudio('mySound');
657
+ ```
658
+
659
+ **AssetType Enum:**
660
+
661
+ ```typescript
662
+ AssetType.GLTF; // 3D models
663
+ AssetType.Audio; // Sound files
664
+ AssetType.Texture; // Images
665
+ AssetType.HDRTexture; // HDR environment maps
666
+ ```
667
+
668
+ ### 15. VisibilityState
669
+
670
+ ```typescript
671
+ import { VisibilityState } from '@iwsdk/core';
672
+
673
+ VisibilityState.NonImmersive; // Browser mode (no XR)
674
+ VisibilityState.Hidden; // XR but not rendering
675
+ VisibilityState.Visible; // Full XR experience
676
+ VisibilityState.VisibleBlurred; // XR but focus lost
677
+
678
+ this.world.visibilityState.subscribe((state) => {
679
+ switch (state) {
680
+ case VisibilityState.NonImmersive:
681
+ // Show 2D fallback UI
682
+ break;
683
+ case VisibilityState.Visible:
684
+ // Full XR experience
685
+ break;
686
+ case VisibilityState.VisibleBlurred:
687
+ // Pause game, show overlay
688
+ break;
689
+ }
690
+ });
691
+ ```
692
+
693
+ ### XR Session Optimization
694
+
695
+ Configure frame rate and foveation when the XR session becomes visible:
696
+
697
+ ```typescript
698
+ this.world.visibilityState.subscribe((state) => {
699
+ if (state === VisibilityState.Visible) {
700
+ this.world.session?.updateTargetFrameRate(72); // Request 72 FPS
701
+ this.world.renderer.xr.setFoveation(1); // Max foveation for performance
702
+ }
703
+ });
704
+ ```
705
+
706
+ ### 16. Locomotion Configuration
707
+
708
+ ```typescript
709
+ import { LocomotionSystem, TurningMethod } from '@iwsdk/core';
710
+
711
+ const locomotion = world.getSystem(LocomotionSystem);
712
+
713
+ // All config properties are signals
714
+ locomotion.config.slidingSpeed.value = 3.0;
715
+ locomotion.config.turningMethod.value = TurningMethod.SmoothTurn; // SnapTurn = 1, SmoothTurn = 2 — always use the enum, not raw numbers
716
+ locomotion.config.turningAngle.value = 45;
717
+ locomotion.config.turningSpeed.value = 180;
718
+ locomotion.config.comfortAssist.value = 0.5;
719
+ locomotion.config.rayGravity.value = -0.4;
720
+ locomotion.config.jumpHeight.value = 1.5;
721
+ locomotion.config.jumpCooldown.value = 0.1;
722
+ locomotion.config.maxDropDistance.value = 5.0;
723
+ locomotion.config.useWorker.value = true;
724
+ locomotion.config.enableJumping.value = true; // Enable/disable jumping entirely
725
+ locomotion.config.initialPlayerPosition.value = [0, 0, 0]; // Starting position
726
+ ```
727
+
728
+ **EnvironmentType** (used with `LocomotionEnvironment` component):
729
+
730
+ ```typescript
731
+ import { EnvironmentType } from '@iwsdk/core';
732
+
733
+ EnvironmentType.STATIC; // Fixed geometry (walls, floors) — default
734
+ EnvironmentType.KINEMATIC; // Moving platforms (elevators, conveyors)
735
+ ```
736
+
737
+ ### 17. Scene Understanding (AR)
738
+
739
+ ```typescript
740
+ import { XRPlane, XRMesh, XRAnchor } from '@iwsdk/core';
741
+
742
+ // Enable in World.create
743
+ World.create(container, {
744
+ xr: {
745
+ sessionMode: SessionMode.ImmersiveAR,
746
+ features: { planeDetection: true, meshDetection: true },
747
+ },
748
+ features: {
749
+ sceneUnderstanding: true,
750
+ },
751
+ });
752
+
753
+ // Query detected planes/meshes
754
+ export class MyARSystem extends createSystem({
755
+ planes: { required: [XRPlane] },
756
+ meshes: { required: [XRMesh] },
757
+ anchors: { required: [XRAnchor] },
758
+ }) {
759
+ init() {
760
+ this.queries.planes.subscribe('qualify', (entity) => {
761
+ // New plane detected
762
+ const plane = entity.object3D;
763
+ });
764
+ }
765
+ }
766
+ ```
767
+
768
+ ### 18. Feature Configuration (Critical!)
769
+
770
+ **Only enable features that your experience actually uses.** Features have prerequisites - enabling them without proper setup causes problems.
771
+
772
+ #### Feature Decision Matrix
773
+
774
+ | Feature | Enable When | Prerequisites | If Missing |
775
+ | -------------------- | ------------------------------------- | ------------------------------------------ | ------------------------------ |
776
+ | `locomotion` | Player needs to move (teleport/slide) | Collision geometry in scene (floor, walls) | **Player falls through world** |
777
+ | `physics` | Objects need dynamic simulation | PhysicsShape + PhysicsBody components | Wasted overhead |
778
+ | `grabbing` | Objects are grabbable | Grabbable components on entities | Wasted overhead |
779
+ | `sceneUnderstanding` | AR with real-world surfaces | AR session mode | Feature won't work |
780
+ | `environmentRaycast` | AR object placement | AR session + hit-test support | Feature won't work |
781
+ | `spatialUI` | Rendering UIKitML assets | Manifest `AssetType.UIKitML` entries | No UI renders |
782
+
783
+ #### Locomotion Requires Environment Setup
784
+
785
+ ```typescript
786
+ // ❌ BAD - Locomotion enabled but no collision geometry
787
+ const world = await World.create(container, {
788
+ features: {
789
+ locomotion: true, // Player will fall through the floor!
790
+ },
791
+ });
792
+
793
+ // ✅ GOOD - Locomotion with proper environment
794
+ const world = await World.create(container, {
795
+ level: './scenes/vr.iwsdk.scene.json', // Scene has collision meshes
796
+ features: {
797
+ locomotion: true,
798
+ physics: true, // Physics provides collision detection
799
+ },
800
+ });
801
+
802
+ // ✅ GOOD - Static experience, no locomotion needed
803
+ const world = await World.create(container, {
804
+ features: {
805
+ locomotion: false, // Player stays at origin
806
+ grabbing: true, // Can still interact with objects
807
+ },
808
+ });
809
+ ```
810
+
811
+ #### VR vs AR Feature Sets
812
+
813
+ ```typescript
814
+ // VR Experience - typically needs locomotion
815
+ const vrWorld = await World.create(container, {
816
+ xr: { sessionMode: SessionMode.ImmersiveVR },
817
+ features: {
818
+ locomotion: true, // Move around virtual space
819
+ grabbing: true,
820
+ physics: true,
821
+ },
822
+ });
823
+
824
+ // AR Experience - player moves physically, no virtual locomotion
825
+ const arWorld = await World.create(container, {
826
+ xr: {
827
+ sessionMode: SessionMode.ImmersiveAR,
828
+ features: { planeDetection: true, hitTest: true },
829
+ },
830
+ features: {
831
+ locomotion: false, // Player walks in real world
832
+ sceneUnderstanding: true, // Detect real surfaces
833
+ environmentRaycast: true, // Place objects on surfaces
834
+ grabbing: true,
835
+ },
836
+ });
837
+ ```
838
+
839
+ ### 19. World Initialization Pattern
840
+
841
+ ```typescript
842
+ import { World, SessionMode } from '@iwsdk/core';
843
+
844
+ const publicAssetUrl = (path: string) =>
845
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
846
+
847
+ const world = await World.create(container, {
848
+ render: {
849
+ fov: 50,
850
+ near: 0.1,
851
+ far: 200,
852
+ stencil: false, // Enable stencil buffer if needed
853
+ },
854
+
855
+ assets: {
856
+ myModel: {
857
+ url: publicAssetUrl('models/scene.glb'),
858
+ type: AssetType.GLTF,
859
+ },
860
+ },
861
+
862
+ level: './scenes/main.iwsdk.scene.json',
863
+
864
+ xr: {
865
+ sessionMode: SessionMode.ImmersiveVR,
866
+ referenceSpace: { type: 'local-floor' },
867
+ // Structured feature flags — NOT raw string arrays. Each accepts a
868
+ // boolean or { required: true }.
869
+ features: { handTracking: true, planeDetection: true },
870
+ offer: 'once', // 'none' | 'once' | 'always' (default: 'always')
871
+ },
872
+
873
+ // Enable feature systems - ONLY what you need!
874
+ features: {
875
+ locomotion: true, // Only if scene has collision geometry
876
+ // OR object form:
877
+ // locomotion: {
878
+ // useWorker: true,
879
+ // initialPlayerPosition: [0, 0, 0],
880
+ // comfortAssistLevel: 0.5, // option key; maps to the LocomotionSystem 'comfortAssist' config signal
881
+ // turningMethod: TurningMethod.SnapTurn,
882
+ // enableJumping: true,
883
+ // },
884
+ grabbing: true, // Only if objects are grabbable
885
+ // OR object form: grabbing: { useHandPinchForGrab: false }, // pinch grabs by default
886
+ physics: true, // Only if using dynamic physics
887
+ sceneUnderstanding: true, // OR: { showWireFrame: true }
888
+ environmentRaycast: true, // AR hit-test against real-world surfaces
889
+ camera: true, // Camera video access (requires XR session)
890
+ spatialUI: {
891
+ forwardHtmlEvents: true,
892
+ preferredColorScheme: 'dark',
893
+ },
894
+ },
895
+ });
896
+
897
+ // Register custom systems
898
+ world.registerSystem(MySystem);
899
+
900
+ // Launch/exit XR
901
+ world.launchXR();
902
+ world.exitXR();
903
+ ```
904
+
905
+ Background and image-based lighting are authored explicitly with dome and IBL
906
+ components on the level root. IWSDK does not synthesize missing environment
907
+ components; the VR and Desktop 3D starter scene authors `DomeGradient` and
908
+ `IBLGradient`, and the AR starter authors only `IBLGradient` so no sky covers
909
+ passthrough.
910
+
911
+ ### Post-Creation Initialization Sequence
912
+
913
+ After `World.create()`, follow this order for proper initialization:
914
+
915
+ ```typescript
916
+ // 1. Create subsystems (physics engine, networking, etc.)
917
+ const simulator = await RaceSimulator.create({ useWorker: true });
918
+
919
+ // 2. Store shared state in world.globals
920
+ world.globals.raceSimulator = simulator;
921
+ (world.globals as Record<string, unknown>).carProxies = new Map();
922
+ (world.globals as Record<string, unknown>).gamePaused = signal(true);
923
+
924
+ // 3. Register components
925
+ world
926
+ .registerComponent(VehiclePhysicsLink)
927
+ .registerComponent(VehiclePhysicsState);
928
+
929
+ // 4. Setup scene (creates entities)
930
+ await setupScene(world, simulator, { aiCount: 5 });
931
+
932
+ // 5. Register systems with priorities
933
+ world
934
+ .registerSystem(PlayerInputSystem, { priority: 0 })
935
+ .registerSystem(PhysicsStepSystem, { priority: 10 });
936
+ ```
937
+
938
+ ### 20. Transform Entity Creation
939
+
940
+ ```typescript
941
+ // Create entity with Object3D binding
942
+ const entity = world.createTransformEntity(mesh, {
943
+ parent: parentEntity, // Optional parent
944
+ persistent: false, // false = destroyed with level
945
+ });
946
+
947
+ // Transform component automatically syncs with Object3D (zero-copy)
948
+ entity.object3D.position.set(0, 1, 0);
949
+
950
+ // Component API for vector fields: getVectorView ONLY — in elics 3.4.x
951
+ // setValue/getValue THROW for Vec2/Vec3/Vec4/Color fields. setValue is
952
+ // fine for scalars, booleans, strings, and enums.
953
+ const posView = entity.getVectorView(Transform, 'position');
954
+ posView.set([0, 1, 0]); // write
955
+ posView[0] += delta; // direct array element write
956
+ ```
957
+
958
+ ### 21. Panel UI Pattern
959
+
960
+ ```typescript
961
+ import { UIKit, UIKitMLAsset, VisibilityState } from '@iwsdk/core';
962
+
963
+ // "settings-panel" is the stable scene node id. Its content.asset points to
964
+ // an AssetType.UIKitML manifest entry.
965
+ const panel = world.requireSceneObject<UIKitMLAsset>('settings-panel');
966
+ const saveButton = panel.requireElementById<UIKit.Text>('save-button');
967
+ const xrButton = panel.requireElementById<UIKit.Text>('xr-button');
968
+
969
+ saveButton.addEventListener('click', () => {
970
+ // Apply settings and play feedback here.
971
+ });
972
+
973
+ const unsubscribe = world.visibilityState.subscribe((state) => {
974
+ const is2D = state === VisibilityState.NonImmersive;
975
+ xrButton.setProperties({ display: is2D ? 'flex' : 'none' });
976
+ });
977
+
978
+ // Retain unsubscribe and call it when the owning feature/system is destroyed.
979
+ ```
980
+
981
+ The manifest ID identifies the reusable UIKitML definition; the scene node ID
982
+ identifies a placed instance; element IDs identify controls inside it. For code-owned
983
+ instances, retain the object returned by the asset manager:
984
+
985
+ ```typescript
986
+ const panel = await world.assets.instantiate<UIKitMLAsset>('settings-panel');
987
+ const entity = world.createTransformEntity(panel);
988
+ panel.requireElementById('save-button').addEventListener('click', save);
989
+ ```
990
+
991
+ Do not discover application panels through internal `PanelDocument` storage or
992
+ transient ECS indices.
993
+
994
+ ### 22. Environment Raycasting (AR Hit-Test)
995
+
996
+ `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.
997
+
998
+ ```typescript
999
+ import { EnvironmentRaycastTarget, RaycastSpace } from '@iwsdk/core';
1000
+
1001
+ // Reticle that follows right controller ray
1002
+ const reticle = world.createTransformEntity(reticleMesh);
1003
+ reticle.addComponent(EnvironmentRaycastTarget, {
1004
+ space: RaycastSpace.Right, // Ray source
1005
+ maxDistance: 100, // Max raycast distance in meters
1006
+ });
1007
+
1008
+ // For phone AR: tap-to-place (uses screen touch)
1009
+ const marker = world.createTransformEntity(markerMesh);
1010
+ marker.addComponent(EnvironmentRaycastTarget, {
1011
+ space: RaycastSpace.Screen, // Tracks screen touch
1012
+ });
1013
+
1014
+ // Read hit-test result (e.g., to spawn an object on trigger press)
1015
+ const xrResult = entity.getValue(EnvironmentRaycastTarget, 'xrHitTestResult');
1016
+ if (xrResult && gamepad?.getSelectStart()) {
1017
+ spawnObject(entity.object3D.position.clone());
1018
+ }
1019
+ ```
1020
+
1021
+ **RaycastSpace:**
1022
+
1023
+ ```typescript
1024
+ RaycastSpace.Left; // Left controller's target ray
1025
+ RaycastSpace.Right; // Right controller's target ray (default)
1026
+ RaycastSpace.Viewer; // Head/gaze direction
1027
+ RaycastSpace.Screen; // Phone AR screen touch (tap-to-place)
1028
+ ```
1029
+
1030
+ **Prerequisites:** `features: { environmentRaycast: true }` and `xr.features: { hitTest: true }` in AR session mode.
1031
+
1032
+ ### 23. Follower Component
1033
+
1034
+ Makes an entity follow another Object3D with thresholded, smoothed motion. It
1035
+ can keep compact global UI discoverable without rigidly head-locking it.
1036
+
1037
+ ```typescript
1038
+ import { Follower, FollowBehavior } from '@iwsdk/core';
1039
+
1040
+ entity.addComponent(Follower, {
1041
+ target: world.player.head, // Must be an Object3D
1042
+ offsetPosition: [0, -0.2, -0.8], // Offset in target's local space
1043
+ behavior: FollowBehavior.PivotY, // Rotation behavior
1044
+ maxAngle: 30, // Degrees before snapping forward
1045
+ tolerance: 0.4, // Meters of positional slack
1046
+ speed: 1, // Lerp speed
1047
+ });
1048
+ ```
1049
+
1050
+ **FollowBehavior:**
1051
+
1052
+ ```typescript
1053
+ FollowBehavior.FaceTarget; // Fully face the target
1054
+ FollowBehavior.PivotY; // Only rotate around Y axis (default)
1055
+ FollowBehavior.NoRotation; // Follow position only, no rotation
1056
+ ```
1057
+
1058
+ **Note:** `target` must be an `Object3D` instance (e.g., `world.player.head`), not an entity.
1059
+
1060
+ ### 24. CameraSource Component
1061
+
1062
+ Access device camera video as a texture. Useful for mixed reality effects or photo capture.
1063
+
1064
+ ```typescript
1065
+ import {
1066
+ CameraSource,
1067
+ CameraFacing,
1068
+ CameraState,
1069
+ CameraUtils,
1070
+ } from '@iwsdk/core';
1071
+
1072
+ // Add camera to an entity
1073
+ entity.addComponent(CameraSource, {
1074
+ // Input fields (user-configurable)
1075
+ deviceId: '', // Empty = auto-select based on facing
1076
+ facing: CameraFacing.Back, // Preferred camera direction
1077
+ width: 1920, // Requested resolution
1078
+ height: 1080,
1079
+ frameRate: 30,
1080
+ });
1081
+
1082
+ // Read-only output fields (managed by CameraSystem):
1083
+ // state: CameraState.Inactive | .Starting | .Active | .Error
1084
+ // texture: VideoTexture (apply to materials)
1085
+ // videoElement: HTMLVideoElement (advanced use)
1086
+ ```
1087
+
1088
+ **CameraFacing:**
1089
+
1090
+ ```typescript
1091
+ CameraFacing.Back; // Rear-facing camera
1092
+ CameraFacing.Front; // Front-facing (selfie) camera
1093
+ CameraFacing.Unknown; // Any available camera (default)
1094
+ ```
1095
+
1096
+ **CameraState:**
1097
+
1098
+ ```typescript
1099
+ CameraState.Inactive; // Not started
1100
+ CameraState.Starting; // Async initialization in progress
1101
+ CameraState.Active; // Stream running
1102
+ CameraState.Error; // Failed to start; terminal until explicitly restarted
1103
+ ```
1104
+
1105
+ **CameraUtils** static class:
1106
+
1107
+ ```typescript
1108
+ // List available cameras (requests permission on first call)
1109
+ const devices = await CameraUtils.getDevices();
1110
+ const backCam = CameraUtils.findByFacing(devices, CameraFacing.Back);
1111
+
1112
+ // Retry after correcting a startup error or changing camera configuration
1113
+ CameraUtils.restart(cameraEntity);
1114
+
1115
+ // Capture current frame as canvas (for snapshot/processing)
1116
+ const canvas = CameraUtils.captureFrame(cameraEntity);
1117
+ if (canvas) {
1118
+ const texture = new CanvasTexture(canvas);
1119
+ }
1120
+ ```
1121
+
1122
+ **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.
1123
+
1124
+ ### 25. PhysicsManipulation Component
1125
+
1126
+ Applies forces or velocity changes to physics bodies. **One-shot component** — `PhysicsSystem` applies the values and auto-removes it each frame.
1127
+
1128
+ ```typescript
1129
+ import { PhysicsManipulation } from '@iwsdk/core';
1130
+
1131
+ // Apply an impulse force
1132
+ entity.addComponent(PhysicsManipulation, {
1133
+ force: [0, 10, 0], // Force vector (one-shot impulse)
1134
+ linearVelocity: [0, 0, 0], // Set linear velocity directly
1135
+ angularVelocity: [0, 0, 0], // Set angular velocity directly
1136
+ });
1137
+ // PhysicsSystem applies these values and auto-removes PhysicsManipulation
1138
+
1139
+ // For sustained forces, re-add the component each frame:
1140
+ update() {
1141
+ if (!entity.hasComponent(PhysicsManipulation)) {
1142
+ entity.addComponent(PhysicsManipulation, { force: [0, 5, 0] });
1143
+ }
1144
+ }
1145
+ ```
1146
+
1147
+ ### 26. ScreenSpace Usage Notes
1148
+
1149
+ `ScreenSpace` positions the UIKit document under a manifest-backed UIKitML entity
1150
+ relative to the screen in non-XR (browser) mode. It is intentional application
1151
+ behavior, not a temporary preview technique; use the editor's isolated preview for
1152
+ development.
1153
+
1154
+ **All position/size values are CSS strings**, not numbers:
1155
+
1156
+ ```typescript
1157
+ import { ScreenSpace } from '@iwsdk/core';
1158
+
1159
+ entity.addComponent(ScreenSpace, {
1160
+ width: '400px', // Explicit CSS size: '400px', '50vw', calc(...)
1161
+ height: '300px', // Explicit CSS size: '300px', '40vh', calc(...)
1162
+ top: '20px', // CSS position or 'auto'
1163
+ left: '20px', // CSS position or 'auto'
1164
+ bottom: 'auto',
1165
+ right: 'auto',
1166
+ zOffset: 0.2, // Distance in meters from camera near plane (NOT CSS)
1167
+ });
1168
+ ```
1169
+
1170
+ **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.
1171
+
1172
+ **XR behavior:** When entering XR, `ScreenSpaceUISystem` automatically moves the panel back to world space. When exiting XR, it re-positions to screen space.
1173
+
1174
+ ### 27. Entity API
1175
+
1176
+ ```typescript
1177
+ // Destroy entity only (components removed, Object3D detached)
1178
+ entity.destroy();
1179
+
1180
+ // Destroy entity AND dispose GPU resources (geometry, materials, textures)
1181
+ // Use for entities with meshes/materials that need proper GPU cleanup
1182
+ entity.dispose();
1183
+
1184
+ // Get all component classes attached to this entity
1185
+ entity.getComponents();
1186
+ ```
1187
+
1188
+ **`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.
1189
+
1190
+ ### 28. Utility Functions
1191
+
1192
+ ```typescript
1193
+ import { setWorldPosition, setWorldQuaternion } from '@iwsdk/core';
1194
+
1195
+ // Set world-space position (correctly handles parent transform chain)
1196
+ setWorldPosition(object3D, worldPosition);
1197
+
1198
+ // Set world-space quaternion (correctly handles parent transforms including non-uniform scale)
1199
+ setWorldQuaternion(object3D, worldQuaternion);
1200
+ ```
1201
+
1202
+ 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.
1203
+
1204
+ ```typescript
1205
+ // Level root helpers on World:
1206
+ world.getActiveRoot(); // Returns active level's Object3D (or scene)
1207
+ world.getPersistentRoot(); // Returns the scene Object3D
1208
+ ```
1209
+
1210
+ ## Core Components Reference (30 Total)
1211
+
1212
+ | Component | Purpose |
1213
+ | ------------------------ | ----------------------------------------------- |
1214
+ | Transform | Position, rotation, scale |
1215
+ | Visibility | Show/hide objects |
1216
+ | LevelTag | Marks level membership |
1217
+ | LevelRoot | Level root marker |
1218
+ | RayInteractable | Marks objects for ray and pointer interaction |
1219
+ | Hovered | Currently hovered |
1220
+ | Pressed | Currently pressed/grabbed |
1221
+ | OneHandGrabbable | Single-hand manipulation |
1222
+ | TwoHandsGrabbable | Two-hand manipulation |
1223
+ | DistanceGrabbable | Grab from distance |
1224
+ | Handle | Manipulation handle |
1225
+ | PhysicsBody | Physics motion properties |
1226
+ | PhysicsShape | Collision shape + material |
1227
+ | PhysicsManipulation | Force/velocity application |
1228
+ | DomeGradient | Gradient sky |
1229
+ | DomeTexture | Textured sky |
1230
+ | IBLGradient | Gradient IBL lighting |
1231
+ | IBLTexture | Texture IBL lighting |
1232
+ | PanelUI | Legacy component-backed UI loader compatibility |
1233
+ | PanelDocument | Internal loaded UI document state |
1234
+ | ScreenSpace | Screen-attached UI |
1235
+ | Follower | Object following |
1236
+ | XRPlane | Detected AR planes |
1237
+ | XRMesh | Detected AR meshes |
1238
+ | XRAnchor | Spatial anchors |
1239
+ | AudioSource | Audio configuration |
1240
+ | CameraSource | Camera device |
1241
+ | DepthOccludable | Depth-based occlusion for AR |
1242
+ | LocomotionEnvironment | Locomotion settings |
1243
+ | EnvironmentRaycastTarget | AR environment hit-test target |
1244
+
1245
+ ## Core Systems Reference (20 Total)
1246
+
1247
+ | System | Priority | Purpose |
1248
+ | ------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
1249
+ | LocomotionSystem | -5 | Movement (teleport/slide/turn) |
1250
+ | InputSystem | -4 | Pointer interaction state management |
1251
+ | GrabSystem | -3 | Grab handling |
1252
+ | PhysicsSystem | -2 | Physics simulation |
1253
+ | SceneUnderstandingSystem | -1 | AR plane/mesh detection |
1254
+ | EnvironmentRaycastSystem | -1 | AR environment raycasting |
1255
+ | PanelUISystem | -3.8 | UI panels |
1256
+ | ScreenSpaceUISystem | -3.75 | Screen UI |
1257
+ | CanvasPointerSystem | -3.5 | DOM pointer → scene forwarding (registered when input.canvasPointerEvents is enabled — the default) |
1258
+ | CameraSystem | default | Camera access |
1259
+ | LevelSystem | default | Level loading |
1260
+ | EnvironmentSystem | default | Lighting/sky |
1261
+ | AudioSystem | default | Spatial audio |
1262
+ | TransformSystem | default | Transform sync |
1263
+ | VisibilitySystem | default | Visibility sync |
1264
+ | FollowSystem | default | Object following |
1265
+ | TurnSystem | default | Rotation |
1266
+ | TeleportSystem | default | Teleportation |
1267
+ | SlideSystem | default | Smooth movement |
1268
+ | DepthSensingSystem | default | Depth occlusion for AR |
1269
+
1270
+ ### Custom System Priority Guidelines
1271
+
1272
+ Register custom systems with priorities following input→simulation→rendering pipeline:
1273
+
1274
+ ```
1275
+ Priority 0-9: Input capture (player input, AI decisions)
1276
+ Priority 10-19: Simulation (physics step, game logic)
1277
+ Priority 20-29: Visual sync (sync Three.js objects to physics)
1278
+ Priority 30+: Low-priority updates (UI, HUD, ambient effects)
1279
+ ```
1280
+
1281
+ Example:
1282
+
1283
+ ```typescript
1284
+ world
1285
+ .registerSystem(PlayerInputSystem, { priority: 0 })
1286
+ .registerSystem(AIDriverSystem, { priority: 1 })
1287
+ .registerSystem(PhysicsStepSystem, { priority: 10 })
1288
+ .registerSystem(VehicleSyncSystem, { priority: 20 })
1289
+ .registerSystem(DashboardSystem, { priority: 35 });
1290
+ ```
1291
+
1292
+ ## Project Structure
1293
+
1294
+ ```
1295
+ my-iwsdk-project/
1296
+ ├── iwsdk.config.json # Declarative project/world authority
1297
+ ├── src/
1298
+ │ ├── index.ts # World.create() plus system registration
1299
+ │ ├── assets.ts # defineAssets() project catalog
1300
+ │ ├── components.ts # defineComponents() declarations
1301
+ │ ├── systems/
1302
+ │ │ ├── ui-system.ts # Panel/UI management
1303
+ │ │ └── game-system.ts # Game logic
1304
+ │ └── components/
1305
+ │ └── custom.ts # Custom component definitions
1306
+ ├── public/
1307
+ │ ├── scenes/ # Native IWSDK scene JSON files
1308
+ │ ├── audio/ # Audio files
1309
+ │ └── ui/ # Runtime-loaded .uikitml files and fonts
1310
+ ├── vite.config.ts
1311
+ └── package.json
1312
+ ```
1313
+
1314
+ ## What IWSDK Provides (Don't Rebuild These)
1315
+
1316
+ 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.).
1317
+
1318
+ ### Reinvention Risk Table
1319
+
1320
+ | What you might build from scratch | What IWSDK already provides |
1321
+ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
1322
+ | GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
1323
+ | Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
1324
+ | Hover/click interaction with Raycaster | `RayInteractable` + `Hovered` + `Pressed` components |
1325
+ | Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
1326
+ | Floor fading into the sky (`onBeforeCompile` with copied sky GLSL) | `DomeFade` on the floor node |
1327
+ | PBR environment lighting | `IBLGradient` or `IBLTexture` component |
1328
+ | Canvas or radial blob shadow card | `ContactShadow` node component |
1329
+ | ShadowMaterial plane for AR | `ShadowCatcher` node component |
1330
+ | Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
1331
+ | Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
1332
+ | Controller 3D models | Auto-loaded from WebXR Input Profiles |
1333
+ | Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
1334
+ | Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
1335
+ | Hit-test against real world | `EnvironmentRaycastTarget` component |
1336
+ | Spatial audio | `AudioSource` component with pooling |
1337
+ | Camera feed texture | `CameraSource` component |
1338
+ | Depth occlusion shader | `DepthOccludable` component |
1339
+ | HUD / screen-space UI | `ScreenSpace` component with CSS units |
1340
+ | Follow-head billboard | `Follower` component |
1341
+ | Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
1342
+ | Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
1343
+ | Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
1344
+ | Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
1345
+ | Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
1346
+ | Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
1347
+
1348
+ ### Asset Loading (AssetManager)
1349
+
1350
+ **Always use AssetManager** — never use raw `GLTFLoader`, `TextureLoader`, etc. AssetManager handles DRACO/KTX2 decoder setup, caching, and de-duplication automatically.
1351
+
1352
+ **Manifest pattern (preload at startup):**
1353
+
1354
+ ```typescript
1355
+ const publicAssetUrl = (path: string) =>
1356
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
1357
+
1358
+ const world = await World.create(container, {
1359
+ assets: {
1360
+ myModel: {
1361
+ url: publicAssetUrl('models/scene.glb'),
1362
+ type: AssetType.GLTF,
1363
+ priority: 'critical',
1364
+ },
1365
+ mySound: {
1366
+ url: publicAssetUrl('audio/click.mp3'),
1367
+ type: AssetType.Audio,
1368
+ priority: 'background',
1369
+ },
1370
+ myTexture: {
1371
+ url: publicAssetUrl('textures/wood.jpg'),
1372
+ type: AssetType.Texture,
1373
+ },
1374
+ myHDR: {
1375
+ url: publicAssetUrl('textures/env.hdr'),
1376
+ type: AssetType.HDRTexture,
1377
+ },
1378
+ },
1379
+ });
1380
+
1381
+ // Retrieve preloaded assets (synchronous — already loaded)
1382
+ const gltf = AssetManager.getGLTF('myModel');
1383
+ // `getGLTF` returns a fresh clone of `scene`/`scenes` per call, so the
1384
+ // same key safely backs multiple entities. Pass `{ shared: true }` to
1385
+ // get the cached instance.
1386
+ const texture = AssetManager.getTexture('myTexture');
1387
+ const audio = AssetManager.getAudio('mySound');
1388
+ ```
1389
+
1390
+ **Render loop (headless automation):** `world.renderMode` is `'continuous'`
1391
+ (default) or `'on-demand'`. On demand, systems still run every frame but only
1392
+ frames asked for are drawn: `await world.requestRender(frames)` or
1393
+ `const release = world.holdRender()` (draw every frame until `release()`).
1394
+ Headless dev sessions switch it on for you; shipped apps keep `'continuous'`.
1395
+
1396
+ **Runtime loading (on-demand):**
1397
+
1398
+ ```typescript
1399
+ // Load at runtime when not known at startup
1400
+ const gltf = await AssetManager.loadGLTF(
1401
+ './models/dynamic.glb',
1402
+ 'dynamicModel',
1403
+ );
1404
+ const texture = await AssetManager.loadTexture(
1405
+ './textures/new.jpg',
1406
+ 'newTexture',
1407
+ );
1408
+ ```
1409
+
1410
+ **Supported AssetTypes:** `GLTF`, `Audio`, `Texture`, `HDRTexture`
1411
+
1412
+ ### Entity Parenting & Level Lifecycle
1413
+
1414
+ **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.
1415
+
1416
+ ```typescript
1417
+ // Basic entity with parent
1418
+ const entity = world.createTransformEntity(mesh, parentEntity);
1419
+
1420
+ // With options object
1421
+ const entity = world.createTransformEntity(mesh, {
1422
+ parent: parentEntity,
1423
+ persistent: false, // false (default) = destroyed when level changes
1424
+ });
1425
+
1426
+ // Persistent entity — survives level changes
1427
+ const hud = world.createTransformEntity(hudMesh, {
1428
+ parent: world.sceneEntity,
1429
+ persistent: true,
1430
+ });
1431
+ ```
1432
+
1433
+ **Level lifecycle:**
1434
+
1435
+ - Entities with `LevelTag` are automatically destroyed when `world.loadLevel()` is called
1436
+ - Non-persistent entities created via `createTransformEntity` automatically get `LevelTag`
1437
+ - Use `persistent: true` for entities that should survive level transitions (HUDs, audio managers, etc.)
1438
+ - `world.loadLevel(url)` destroys all level-tagged entities, then loads the new native scene document
1439
+
1440
+ **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.
1441
+
1442
+ ### Input & Interaction
1443
+
1444
+ **RayInteractable → Hovered/Pressed flow:**
1445
+
1446
+ 1. Add `RayInteractable` component to any entity that should respond to pointer input
1447
+ 2. `InputSystem` automatically performs BVH-accelerated raycasting each frame
1448
+ 3. When a ray hits a RayInteractable entity, `Hovered` tag is added
1449
+ 4. When the user presses the select button while hovering, `Pressed` tag is added
1450
+ 5. Query for `Hovered`/`Pressed` in your system to react to interactions
1451
+
1452
+ ```typescript
1453
+ // Setup
1454
+ entity.addComponent(RayInteractable);
1455
+
1456
+ // In your system — react to interactions
1457
+ export class MyInteractionSystem extends createSystem({
1458
+ hovered: { required: [MyComponent, Hovered] },
1459
+ pressed: { required: [MyComponent, Pressed] },
1460
+ }) {
1461
+ init() {
1462
+ this.queries.pressed.subscribe('qualify', (entity) => {
1463
+ // Entity was just clicked/selected
1464
+ });
1465
+ }
1466
+ }
1467
+ ```
1468
+
1469
+ **StatefulGamepad API** (accessed via `this.input.xr.gamepads.left` / `.right`):
1470
+
1471
+ - `getButtonDown(InputComponent.Trigger)` — true on the frame the button was pressed
1472
+ - `getButtonUp(InputComponent.Trigger)` — true on the frame the button was released
1473
+ - `getButtonPressed(InputComponent.Trigger)` — true while held
1474
+ - `getButtonValue(InputComponent.Trigger)` — analog 0-1
1475
+ - `getAxesValues(InputComponent.Thumbstick)` — `{ x, y }` in -1 to 1 range
1476
+ - `getAxesEnteringUp/Down/Left/Right(InputComponent.Thumbstick)` — directional flick detection
1477
+
1478
+ ### Built-in Visuals (Don't Recreate)
1479
+
1480
+ These visuals are automatically created and managed by IWSDK systems:
1481
+
1482
+ - **RayPointer** — Cylinder mesh with gradient shader + circular cursor at hit point. Created automatically by `InputSystem` for each connected controller.
1483
+ - **AnimatedController** — GLTF controller models auto-loaded from the WebXR Input Profiles registry. Matches the user's actual hardware.
1484
+ - **AnimatedHand** — Skeletal hand mesh with outline shader for hand tracking mode. Auto-managed by the input system.
1485
+ - **Teleport visuals** — Parabolic arc + landing circle indicator. Rendered by `LocomotionSystem` when teleport mode is active.
1486
+ - **Comfort vignette** — Screen-edge darkening during smooth locomotion. Controlled by `locomotion.config.comfortAssist` (0 = off, 1 = maximum).
1487
+ - **DomeGradient / DomeTexture** — Sky dome rendering. Add the component to an entity; `EnvironmentSystem` handles the rest.
1488
+
1489
+ ## Anti-Patterns to Avoid
1490
+
1491
+ 1. **DON'T** store entity arrays in systems - use queries
1492
+ 2. **DON'T** poll for state changes - use signal subscriptions
1493
+ 3. **DON'T** manually track component additions/removals - use query subscribe
1494
+ 4. **DON'T** create entities in update() without proper lifecycle management
1495
+ 5. **DON'T** use `Types.Object` for data that could be typed (use Vec3, Float32, etc.)
1496
+ 6. **DON'T** forget cleanup functions for subscriptions and resources
1497
+ 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
1498
+ 8. **DON'T** enable locomotion without collision geometry - player falls through world
1499
+ 9. **DON'T** enable features you don't use - adds overhead and can cause bugs
1500
+ 10. **DON'T** confuse PhysicsBody (motion) with PhysicsShape (collision + material)
1501
+ 11. **DON'T** use raw `GLTFLoader`/`TextureLoader` — use `AssetManager` for caching, DRACO/KTX2 setup
1502
+ 12. **DON'T** use `scene.add()` — use `createTransformEntity()` for proper ECS integration
1503
+ 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
1504
+ 14. **DON'T** add environment components (`DomeGradient`/`IBLTexture`/etc.) to arbitrary entities — must go on the level root (`world.activeLevel.value`)
1505
+ 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
1506
+ 16. **DON'T** use `entity.destroy()` for objects with GPU resources — use `entity.dispose()` which also cleans up geometry/materials/textures
1507
+ 17. **DON'T** pass numbers to `ScreenSpace` — all position/size values are CSS strings like `'400px'` or `'50vw'`
1508
+
1509
+ ## Performance Tips
1510
+
1511
+ 1. Use `getVectorView()` for direct TypedArray access (zero-copy)
1512
+ 2. Batch query enumeration (don't create intermediate arrays)
1513
+ 3. Use tag components for cheap boolean queries
1514
+ 4. Leverage query filters (`where`) to reduce iteration scope
1515
+ 5. System config signals auto-deduplicate (no callback if value unchanged)
1516
+ 6. Physics and locomotion can run in Web Workers for heavy scenes
1517
+ 7. Use `PhysicsShapeType.Auto` to let IWSDK pick optimal collision shape
1518
+
1519
+ ## When Planning a New Feature
1520
+
1521
+ 1. **Determine feature flags** - What built-in features does this need? (locomotion, physics, grabbing, etc.)
1522
+ 2. **Check prerequisites** - If using locomotion, is collision geometry set up?
1523
+ 3. **Identify components needed** - What data does this feature require?
1524
+ 4. **Design queries** - How will systems find relevant entities?
1525
+ 5. **Plan reactivity** - What changes should trigger updates?
1526
+ 6. **Consider lifecycle** - When are entities created/destroyed?
1527
+ 7. **Map to existing systems** - Can built-in systems (grab, physics, etc.) help?
1528
+ 8. **VR vs AR** - Does this work differently in each mode?
1529
+ 9. **Input handling** - What controller/hand inputs are needed?
1530
+ 10. **Audio feedback** - What sounds should play on interactions?
1531
+ 11. **Select 3D assets** - What models are needed, and what are their licensing, provenance, and performance constraints?