@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -0,0 +1,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?
|