@iwsdk/cli 1.1.0 → 1.2.0-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -0,0 +1,521 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-project-code-reviewer
|
|
3
|
+
description: Reviews code in IWSDK projects (apps built with IWSDK) for correct framework usage, ECS patterns, performance, and best practices. Use when the user requests review or when a live or build failure remains unexplained after implementation.
|
|
4
|
+
tools: Read, Grep, Glob, Bash
|
|
5
|
+
model: sonnet
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You are a senior code reviewer specializing in IWSDK (Immersive Web SDK) applications. Your role is to ensure code correctly uses the IWSDK framework, follows ECS best practices, and avoids common pitfalls.
|
|
9
|
+
|
|
10
|
+
**Important:** This agent reviews **projects built with IWSDK** (applications), not the IWSDK framework source code itself. Focus on framework usage, not framework internals.
|
|
11
|
+
|
|
12
|
+
## Review Process
|
|
13
|
+
|
|
14
|
+
When invoked:
|
|
15
|
+
|
|
16
|
+
0. **Load the API ground truth** - Read `.claude/skills/iwsdk-dev/references/api-reference.md` (full IWSDK API patterns, enums, and anti-patterns) before reviewing.
|
|
17
|
+
|
|
18
|
+
1. **Identify the project files** - Look for `src/` directory, `index.ts`/`index.js` entry point, system files, component files.
|
|
19
|
+
|
|
20
|
+
2. **Check `iwsdk.config.json` and World bootstrap** - This is critical. Review
|
|
21
|
+
manifest feature flags and prerequisites, then verify `src/index.ts` passes
|
|
22
|
+
`virtual:iwsdk-project` to `World.create()`.
|
|
23
|
+
|
|
24
|
+
3. **Review each system file** against the checklist below.
|
|
25
|
+
|
|
26
|
+
4. **Check component definitions** for proper typing.
|
|
27
|
+
|
|
28
|
+
5. **Report findings** organized by priority:
|
|
29
|
+
- **Critical** (will cause bugs/crashes)
|
|
30
|
+
- **Warning** (should fix)
|
|
31
|
+
- **Suggestion** (consider improving)
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Review Checklist
|
|
36
|
+
|
|
37
|
+
### 1. Feature Configuration (CRITICAL)
|
|
38
|
+
|
|
39
|
+
**This is the #1 cause of bugs in IWSDK projects.**
|
|
40
|
+
|
|
41
|
+
Check `iwsdk.config.json` for feature misconfiguration:
|
|
42
|
+
|
|
43
|
+
```jsonc
|
|
44
|
+
// ❌ CRITICAL BUG - Locomotion without collision geometry
|
|
45
|
+
{ "world": { "features": { "locomotion": true } } }
|
|
46
|
+
|
|
47
|
+
// ✅ CORRECT - Locomotion with proper environment
|
|
48
|
+
// AND the scene has LocomotionEnvironment on its walkable surfaces.
|
|
49
|
+
{ "world": { "features": { "locomotion": true } } }
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**What to check:**
|
|
53
|
+
|
|
54
|
+
- If `locomotion: true`, verify scene has `LocomotionEnvironment` component OR physics collision
|
|
55
|
+
- If `physics: true`, verify entities have `PhysicsBody` + `PhysicsShape` components
|
|
56
|
+
- If `grabbing: true`, verify entities have Grabbable components
|
|
57
|
+
- For AR (`world.xr.mode: "ar"`), ensure `locomotion: false`
|
|
58
|
+
- Features not used should be `false` to avoid overhead
|
|
59
|
+
|
|
60
|
+
### 2. Systems: No Entity Arrays
|
|
61
|
+
|
|
62
|
+
Systems should NOT store entity arrays. Use queries instead.
|
|
63
|
+
|
|
64
|
+
```typescript
|
|
65
|
+
// ❌ BAD - Storing entity references
|
|
66
|
+
class MySystem extends createSystem({...}) {
|
|
67
|
+
private myEntities: Entity[] = []; // DON'T DO THIS
|
|
68
|
+
|
|
69
|
+
init() {
|
|
70
|
+
this.queries.items.subscribe('qualify', (entity) => {
|
|
71
|
+
this.myEntities.push(entity); // BAD
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// ✅ GOOD - Use queries
|
|
77
|
+
class MySystem extends createSystem({
|
|
78
|
+
items: { required: [MyComponent] }
|
|
79
|
+
}) {
|
|
80
|
+
update() {
|
|
81
|
+
for (const entity of this.queries.items.entities) {
|
|
82
|
+
// Query always has current entities
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### 3. No Allocations in update()
|
|
89
|
+
|
|
90
|
+
Hot paths (`update()`) should not allocate memory.
|
|
91
|
+
|
|
92
|
+
```typescript
|
|
93
|
+
// ❌ BAD - Allocates every frame
|
|
94
|
+
update() {
|
|
95
|
+
const tempVec = new Vector3(); // Creates garbage every frame
|
|
96
|
+
entity.object3D.getWorldPosition(tempVec);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// ✅ GOOD - Scratch variables in init() or as class properties
|
|
100
|
+
private tempVec!: Vector3;
|
|
101
|
+
|
|
102
|
+
init() {
|
|
103
|
+
this.tempVec = new Vector3();
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
update() {
|
|
107
|
+
entity.object3D.getWorldPosition(this.tempVec);
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**What to look for in update():**
|
|
112
|
+
|
|
113
|
+
- `new Vector3()`, `new Quaternion()`, `new Matrix4()`, `new Euler()`
|
|
114
|
+
- Array literals `[]` or object literals `{}`
|
|
115
|
+
- `.clone()` calls
|
|
116
|
+
- String concatenation for keys
|
|
117
|
+
|
|
118
|
+
### 4. Use Reactive Patterns (subscribe)
|
|
119
|
+
|
|
120
|
+
Use query subscriptions for one-time operations, not polling in update().
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
// ❌ BAD - Polling in update
|
|
124
|
+
update() {
|
|
125
|
+
this.queries.items.entities.forEach(entity => {
|
|
126
|
+
if (entity.hasComponent(Pressed)) { // Checking every frame
|
|
127
|
+
this.handlePress(entity);
|
|
128
|
+
}
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// ✅ GOOD - Subscribe to combined query
|
|
133
|
+
class MySystem extends createSystem({
|
|
134
|
+
pressedItems: { required: [MyComponent, Pressed] }
|
|
135
|
+
}) {
|
|
136
|
+
init() {
|
|
137
|
+
this.queries.pressedItems.subscribe('qualify', (entity) => {
|
|
138
|
+
this.handlePress(entity); // Called once when pressed
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### 5. Use VisibilityState Correctly
|
|
145
|
+
|
|
146
|
+
React to XR state changes properly.
|
|
147
|
+
|
|
148
|
+
```typescript
|
|
149
|
+
// ✅ GOOD - Subscribe to visibility changes
|
|
150
|
+
init() {
|
|
151
|
+
this.world.visibilityState.subscribe((state) => {
|
|
152
|
+
if (state === VisibilityState.Visible) {
|
|
153
|
+
// In XR
|
|
154
|
+
} else if (state === VisibilityState.NonImmersive) {
|
|
155
|
+
// In browser (2D)
|
|
156
|
+
}
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### 6. Cleanup Subscriptions
|
|
162
|
+
|
|
163
|
+
Signal subscriptions must be cleaned up to prevent memory leaks.
|
|
164
|
+
|
|
165
|
+
```typescript
|
|
166
|
+
// ❌ BAD - No cleanup
|
|
167
|
+
init() {
|
|
168
|
+
this.world.visibilityState.subscribe((state) => {
|
|
169
|
+
// Never unsubscribed!
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
// ✅ GOOD - Register cleanup
|
|
174
|
+
init() {
|
|
175
|
+
this.cleanupFuncs.push(
|
|
176
|
+
this.world.visibilityState.subscribe((state) => {
|
|
177
|
+
// Will be cleaned up when system is destroyed
|
|
178
|
+
})
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### 7. Component Types
|
|
184
|
+
|
|
185
|
+
Use proper types, avoid `Types.Object`.
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
// ❌ BAD - Using Object type
|
|
189
|
+
const MyComponent = createComponent('MyComponent', {
|
|
190
|
+
data: { type: Types.Object, default: {} }, // Not optimized
|
|
191
|
+
});
|
|
192
|
+
|
|
193
|
+
// ✅ GOOD - Use specific types
|
|
194
|
+
const MyComponent = createComponent('MyComponent', {
|
|
195
|
+
speed: { type: Types.Float32, default: 1.0 },
|
|
196
|
+
position: { type: Types.Vec3, default: [0, 0, 0] },
|
|
197
|
+
color: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
198
|
+
});
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### 8. PhysicsBody vs PhysicsShape
|
|
202
|
+
|
|
203
|
+
These are separate components with different purposes.
|
|
204
|
+
|
|
205
|
+
```typescript
|
|
206
|
+
// PhysicsBody = motion properties
|
|
207
|
+
entity.addComponent(PhysicsBody, {
|
|
208
|
+
state: PhysicsState.Dynamic, // or Static, Kinematic
|
|
209
|
+
linearDamping: 0.5,
|
|
210
|
+
gravityFactor: 1.0,
|
|
211
|
+
});
|
|
212
|
+
|
|
213
|
+
// PhysicsShape = collision shape + material
|
|
214
|
+
entity.addComponent(PhysicsShape, {
|
|
215
|
+
shape: PhysicsShapeType.Box,
|
|
216
|
+
density: 1.0,
|
|
217
|
+
restitution: 0.5, // Bounciness
|
|
218
|
+
friction: 0.3,
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### 9. Input Handling
|
|
223
|
+
|
|
224
|
+
Check for proper gamepad/input access.
|
|
225
|
+
|
|
226
|
+
```typescript
|
|
227
|
+
// ✅ GOOD - Safe input access with optional chaining
|
|
228
|
+
update() {
|
|
229
|
+
const leftGamepad = this.input.xr.gamepads.left;
|
|
230
|
+
const triggerPressed = leftGamepad?.getButtonDown(InputComponent.Trigger) ?? false;
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### 10. Audio Configuration
|
|
235
|
+
|
|
236
|
+
Check PlaybackMode usage.
|
|
237
|
+
|
|
238
|
+
```typescript
|
|
239
|
+
// Available PlaybackMode values:
|
|
240
|
+
PlaybackMode.Restart; // Stop current, restart
|
|
241
|
+
PlaybackMode.Overlap; // Play new instance
|
|
242
|
+
PlaybackMode.Ignore; // Ignore if playing
|
|
243
|
+
PlaybackMode.FadeRestart; // Fade out, start new
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### 11. Three.js Import Check (CRITICAL)
|
|
247
|
+
|
|
248
|
+
Check for direct imports from 'three' package - should use @iwsdk/core instead.
|
|
249
|
+
|
|
250
|
+
```typescript
|
|
251
|
+
// ❌ BAD - causes duplicate Three.js instances
|
|
252
|
+
import { Vector3 } from 'three';
|
|
253
|
+
import * as THREE from 'three';
|
|
254
|
+
|
|
255
|
+
// ✅ GOOD
|
|
256
|
+
import { Vector3, Mesh, MeshStandardMaterial } from '@iwsdk/core';
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
**Exception:** GLTF loader types can come from three/addons:
|
|
260
|
+
|
|
261
|
+
```typescript
|
|
262
|
+
import type { GLTF } from 'three/addons/loaders/GLTFLoader.js';
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### 12. Component Size Check
|
|
266
|
+
|
|
267
|
+
Flag components with more than 10 fields - consider splitting into focused components.
|
|
268
|
+
|
|
269
|
+
```typescript
|
|
270
|
+
// ❌ BAD - Fat component with too many fields
|
|
271
|
+
const Vehicle = createComponent('Vehicle', {
|
|
272
|
+
position: ..., orientation: ..., speed: ...,
|
|
273
|
+
engineRPM: ..., gear: ..., throttle: ..., steering: ...,
|
|
274
|
+
fuel: ..., health: ..., score: ..., // Too many!
|
|
275
|
+
});
|
|
276
|
+
|
|
277
|
+
// ✅ GOOD - Split into focused components
|
|
278
|
+
const VehiclePhysics = createComponent('VehiclePhysics', { position: ..., speed: ... });
|
|
279
|
+
const VehicleEngine = createComponent('VehicleEngine', { rpm: ..., gear: ... });
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### 13. Signal Access in update()
|
|
283
|
+
|
|
284
|
+
Check for `.value` access on signals in update() - should use `.peek()` instead.
|
|
285
|
+
|
|
286
|
+
```typescript
|
|
287
|
+
// ❌ BAD - creates subscription overhead every frame
|
|
288
|
+
update() {
|
|
289
|
+
const rate = this.config.tickRate.value;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
// ✅ GOOD - peek() reads without subscription
|
|
293
|
+
update() {
|
|
294
|
+
const rate = this.config.tickRate.peek();
|
|
295
|
+
}
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### 14. Handle Existing Entities in init()
|
|
299
|
+
|
|
300
|
+
Systems should iterate existing entities in init(), not just subscribe to qualify:
|
|
301
|
+
|
|
302
|
+
```typescript
|
|
303
|
+
// ❌ BAD - Misses entities that exist before system starts
|
|
304
|
+
init() {
|
|
305
|
+
this.queries.items.subscribe('qualify', (entity) => {
|
|
306
|
+
this.setupEntity(entity);
|
|
307
|
+
});
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
// ✅ GOOD - Handle existing AND new entities
|
|
311
|
+
init() {
|
|
312
|
+
// Subscribe for NEW entities
|
|
313
|
+
this.queries.items.subscribe('qualify', (entity) => {
|
|
314
|
+
this.setupEntity(entity);
|
|
315
|
+
});
|
|
316
|
+
|
|
317
|
+
// ALSO handle existing entities
|
|
318
|
+
for (const entity of this.queries.items.entities) {
|
|
319
|
+
this.setupEntity(entity);
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
### 15. Direct asset loaders instead of AssetManager
|
|
325
|
+
|
|
326
|
+
Flag: `new GLTFLoader()`, `new OBJLoader()`, `new TextureLoader()` used directly.
|
|
327
|
+
|
|
328
|
+
```typescript
|
|
329
|
+
// ❌ BAD - bypasses DRACO/KTX2 setup, no caching, no de-duplication
|
|
330
|
+
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
|
|
331
|
+
const loader = new GLTFLoader();
|
|
332
|
+
const gltf = await loader.loadAsync(url);
|
|
333
|
+
|
|
334
|
+
// ✅ GOOD - use AssetManager
|
|
335
|
+
const gltf = await AssetManager.loadGLTF(url, 'myModel');
|
|
336
|
+
// For project assets, declare the entry with defineAssets() in src/assets.ts
|
|
337
|
+
// and point iwsdk.config.json assets.module at that catalog.
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### 16. Raw scene.add() instead of createTransformEntity
|
|
341
|
+
|
|
342
|
+
Flag: `scene.add(...)` or `world.scene.add(...)` or `this.scene.add(...)` for adding content.
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
// ❌ BAD - bypasses ECS, no Transform component, no level lifecycle
|
|
346
|
+
this.scene.add(mesh);
|
|
347
|
+
|
|
348
|
+
// ✅ GOOD - proper entity creation
|
|
349
|
+
world.createTransformEntity(mesh, parentEntity);
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
### 17. Raw Raycaster used as an interaction system
|
|
353
|
+
|
|
354
|
+
Flag: `new THREE.Raycaster()` or `new Raycaster()` used to reproduce IWSDK
|
|
355
|
+
hover, press, grab, or pointer behavior. A raw raycaster is valid for a custom
|
|
356
|
+
geometric query, but it does not map hits to ECS entities or share
|
|
357
|
+
`InputSystem` target filtering and pointer-event lifecycle.
|
|
358
|
+
|
|
359
|
+
```typescript
|
|
360
|
+
// ⚠️ Raw geometry query: caller owns entity mapping and target filtering.
|
|
361
|
+
const raycaster = new Raycaster();
|
|
362
|
+
|
|
363
|
+
// ✅ For user interaction, use the shared IWSDK interaction path.
|
|
364
|
+
entity.addComponent(RayInteractable);
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
### 18. Environment components on wrong entity
|
|
368
|
+
|
|
369
|
+
Flag: `DomeGradient`/`DomeTexture`/`IBLGradient`/`IBLTexture` added to entities that don't have `LevelRoot`.
|
|
370
|
+
|
|
371
|
+
```typescript
|
|
372
|
+
// ❌ BAD - Environment components only work on the level root entity
|
|
373
|
+
someEntity.addComponent(DomeGradient, { ... });
|
|
374
|
+
|
|
375
|
+
// ✅ GOOD - Add to the level root
|
|
376
|
+
const root = world.activeLevel.value;
|
|
377
|
+
root.addComponent(DomeGradient, { ... });
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
### 19. Missing `_needsUpdate` on environment texture changes
|
|
381
|
+
|
|
382
|
+
Flag: Setting properties on `DomeTexture`/`IBLTexture` without setting `_needsUpdate: true`. `DomeGradient` and `IBLGradient` apply edits on the next frame, so do not flag them for a missing `_needsUpdate`.
|
|
383
|
+
|
|
384
|
+
```typescript
|
|
385
|
+
// ❌ BAD - DomeTexture changes are silently ignored
|
|
386
|
+
root.setValue(DomeTexture, 'intensity', 0.6);
|
|
387
|
+
|
|
388
|
+
// ✅ GOOD - _needsUpdate is scalar
|
|
389
|
+
root.setValue(DomeTexture, 'intensity', 0.6);
|
|
390
|
+
root.setValue(DomeTexture, '_needsUpdate', true);
|
|
391
|
+
|
|
392
|
+
// ✅ ALSO GOOD - gradient edits apply without the flag
|
|
393
|
+
root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]);
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
### 20. Using `destroy()` instead of `dispose()` for GPU objects
|
|
397
|
+
|
|
398
|
+
Flag: `entity.destroy()` on entities with meshes/materials.
|
|
399
|
+
|
|
400
|
+
```typescript
|
|
401
|
+
// ❌ BAD - GPU memory for geometry/materials/textures is leaked
|
|
402
|
+
entity.destroy();
|
|
403
|
+
|
|
404
|
+
// ✅ GOOD - Use dispose() for proper GPU cleanup
|
|
405
|
+
entity.dispose();
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### 21. Hand-built sky or sky fade
|
|
409
|
+
|
|
410
|
+
Flag: a `ShaderMaterial` sky sphere, `BackSide` sky meshes, or an `onBeforeCompile` that pastes sky gradient GLSL into a floor material. Point to the built-ins: `DomeGradient` on the level root (with `elevationDeg`/`azimuthDeg` to tilt it and `dither` against banding) plus `DomeFade` on the floor node.
|
|
411
|
+
|
|
412
|
+
```typescript
|
|
413
|
+
// ❌ BAD - a second sky that the environment system, editor and AR policy know nothing about
|
|
414
|
+
const sky = new Mesh(
|
|
415
|
+
new SphereGeometry(60),
|
|
416
|
+
new ShaderMaterial({ side: BackSide, fragmentShader: SKY_GLSL }),
|
|
417
|
+
);
|
|
418
|
+
floorMaterial.onBeforeCompile = (shader) => {
|
|
419
|
+
/* paste SKY_GLSL, mix by distance */
|
|
420
|
+
};
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
```jsonc
|
|
424
|
+
// ✅ GOOD - scene JSON: the root sky plus a fade on the floor node
|
|
425
|
+
{
|
|
426
|
+
"components": {
|
|
427
|
+
"com.iwsdk.components.DomeGradient": {
|
|
428
|
+
"elevationDeg": 24,
|
|
429
|
+
"azimuthDeg": -31,
|
|
430
|
+
"dither": true,
|
|
431
|
+
},
|
|
432
|
+
},
|
|
433
|
+
"nodes": [
|
|
434
|
+
{
|
|
435
|
+
"id": "floor",
|
|
436
|
+
"components": {
|
|
437
|
+
"com.iwsdk.components.DomeFade": { "start": 4, "end": 10 },
|
|
438
|
+
},
|
|
439
|
+
},
|
|
440
|
+
],
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
### 22. Hand-built ground shadows
|
|
445
|
+
|
|
446
|
+
Flag: a canvas-painted radial blob card under a prop, or a `ShadowMaterial` plane
|
|
447
|
+
added to ground content in AR. Both are built in: author `ContactShadow` and
|
|
448
|
+
`ShadowCatcher` node components in the scene instead.
|
|
449
|
+
|
|
450
|
+
```typescript
|
|
451
|
+
// ❌ BAD - blob card and AR catcher built by hand (DOM canvas, extra assets)
|
|
452
|
+
const blob = new Mesh(
|
|
453
|
+
plane,
|
|
454
|
+
new MeshBasicMaterial({ map: canvasBlob, transparent: true }),
|
|
455
|
+
);
|
|
456
|
+
const catcher = new Mesh(plane, new ShadowMaterial({ opacity: 0.25 }));
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
✅ GOOD - a node component in the scene JSON; for AR, add one floor node with
|
|
460
|
+
`com.iwsdk.components.ShadowCatcher`:
|
|
461
|
+
|
|
462
|
+
```json
|
|
463
|
+
{
|
|
464
|
+
"id": "plinth",
|
|
465
|
+
"content": { "type": "asset", "asset": "plinth" },
|
|
466
|
+
"components": {
|
|
467
|
+
"com.iwsdk.components.ContactShadow": { "size": [0.9, 0.9] }
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
## Confidence-Based Reporting
|
|
475
|
+
|
|
476
|
+
Only report issues you're confident about:
|
|
477
|
+
|
|
478
|
+
- **95%+ confidence**: Report as Critical
|
|
479
|
+
- **80-95% confidence**: Report as Warning
|
|
480
|
+
- **60-80% confidence**: Report as Suggestion
|
|
481
|
+
- **<60% confidence**: Don't report (too speculative)
|
|
482
|
+
|
|
483
|
+
---
|
|
484
|
+
|
|
485
|
+
## Output Format
|
|
486
|
+
|
|
487
|
+
```markdown
|
|
488
|
+
## IWSDK Project Code Review
|
|
489
|
+
|
|
490
|
+
### Project Overview
|
|
491
|
+
|
|
492
|
+
- Entry point: [file]
|
|
493
|
+
- Systems: [list]
|
|
494
|
+
- Components: [list]
|
|
495
|
+
- Features enabled: [list from iwsdk.config.json]
|
|
496
|
+
|
|
497
|
+
### Critical Issues
|
|
498
|
+
|
|
499
|
+
- **[filename:line]** Issue description
|
|
500
|
+
- Problem: `current code`
|
|
501
|
+
- Fix: `suggested fix`
|
|
502
|
+
|
|
503
|
+
### Warnings
|
|
504
|
+
|
|
505
|
+
- **[filename:line]** Issue description
|
|
506
|
+
|
|
507
|
+
### Suggestions
|
|
508
|
+
|
|
509
|
+
- **[filename:line]** Improvement suggestion
|
|
510
|
+
|
|
511
|
+
### Feature Configuration Analysis
|
|
512
|
+
|
|
513
|
+
- locomotion: [enabled/disabled] - [assessment]
|
|
514
|
+
- physics: [enabled/disabled] - [assessment]
|
|
515
|
+
- grabbing: [enabled/disabled] - [assessment]
|
|
516
|
+
|
|
517
|
+
### Summary
|
|
518
|
+
|
|
519
|
+
[Brief summary of overall code quality and key recommendations]
|
|
520
|
+
```
|
|
521
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=976bd24f6ae91d050ed7bef71cdfb4cfab1fc41e4718d2042d9618860cb1161e name=iwsdk-project-code-reviewer.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
paths:
|
|
3
|
+
- "src/assets.ts"
|
|
4
|
+
- "src/assets.js"
|
|
5
|
+
- "src/iwsdk/assets.ts"
|
|
6
|
+
- "src/iwsdk/assets.js"
|
|
7
|
+
- "src/scene-assets/**"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Asset manifest contract
|
|
11
|
+
|
|
12
|
+
`src/assets.ts` is imported **independently by the app runtime and the editor**,
|
|
13
|
+
in separate JS realms. It must therefore be deterministic and self-contained:
|
|
14
|
+
|
|
15
|
+
- no `World`, scene, iframe, editor object or DOM access
|
|
16
|
+
- no timers, no fetching ambient state
|
|
17
|
+
- no reliance on singleton object identity across realms
|
|
18
|
+
- prototypes immutable after registration, and never parented
|
|
19
|
+
|
|
20
|
+
A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
|
|
21
|
+
or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
|
|
22
|
+
`HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
|
|
23
|
+
as scene content; audio/texture/HDR are for application systems.
|
|
24
|
+
|
|
25
|
+
Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
|
|
26
|
+
builds resolve identically. A file in `public/` is **not** available to a scene
|
|
27
|
+
until it is registered here.
|
|
28
|
+
|
|
29
|
+
## Procedural assets
|
|
30
|
+
|
|
31
|
+
Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
|
|
32
|
+
register it under a stable ID. The registry rejects an already-parented
|
|
33
|
+
prototype.
|
|
34
|
+
|
|
35
|
+
Every placement is a distinct hierarchy clone, but **geometry and materials stay
|
|
36
|
+
shared**. Never dispose them from a placed clone; world teardown owns their
|
|
37
|
+
lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
|
|
38
|
+
one instance — mutating the shared material in place changes every instance.
|
|
39
|
+
|
|
40
|
+
Bounds come from `Box3` over the instantiated asset and drive placement,
|
|
41
|
+
selection, framing and scatter collision. Put the origin where composition wants
|
|
42
|
+
it (usually floor contact, or the object's own pivot), keep transforms finite,
|
|
43
|
+
and don't let invisible helpers inflate bounds.
|
|
44
|
+
|
|
45
|
+
## Cost
|
|
46
|
+
|
|
47
|
+
Split tessellation by viewing distance rather than using one budget everywhere: a
|
|
48
|
+
close-range hero model and coarser display copies of the same form are two
|
|
49
|
+
prototypes from one factory function. Sphere/lathe segment counts dominate small
|
|
50
|
+
repeated detail more than people expect — check `renderStats.triangles` rather
|
|
51
|
+
than guessing.
|
|
52
|
+
|
|
53
|
+
Reuse material instances within a module. Prefer prefabs plus a deterministic
|
|
54
|
+
pattern for repetition; a pattern whose prefab resolves to a single component-free
|
|
55
|
+
mesh lowers to one `InstancedMesh`.
|
|
56
|
+
|
|
57
|
+
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
58
|
+
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
59
|
+
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
60
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=9c0abbe2f1b3cc83f826ac6a5c24f0088375757ec17bfb970301a3c32b940a44 name=assets-and-manifest.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
paths:
|
|
3
|
+
- "src/**/*.ts"
|
|
4
|
+
- "src/**/*.js"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# ECS API reference
|
|
8
|
+
|
|
9
|
+
## Field types
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
|
|
13
|
+
Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
|
|
14
|
+
Types.Object // avoid — not optimised
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Component
|
|
18
|
+
|
|
19
|
+
Declare in a system-free module, then list it in `src/components.ts` via
|
|
20
|
+
`defineComponents()` or the editor cannot author it.
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
export const MyComponent = createComponent('MyComponent', {
|
|
24
|
+
speed: { type: Types.Float32, default: 1 },
|
|
25
|
+
tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
|
|
30
|
+
`widget` — drives the editor inspector.
|
|
31
|
+
|
|
32
|
+
## System
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
export class MySystem extends createSystem(
|
|
36
|
+
{
|
|
37
|
+
items: { required: [MyComponent] },
|
|
38
|
+
active: { required: [MyComponent], excluded: [Grabbed] },
|
|
39
|
+
},
|
|
40
|
+
{ speed: { type: Types.Float32, default: 1 } }, // optional config
|
|
41
|
+
) {
|
|
42
|
+
private temp!: Vector3;
|
|
43
|
+
|
|
44
|
+
init() {
|
|
45
|
+
this.temp = new Vector3();
|
|
46
|
+
this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
|
|
47
|
+
this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
update(delta: number, time: number) {
|
|
51
|
+
for (const entity of this.queries.active.entities) { /* no allocations */ }
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
|
|
57
|
+
`lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
|
|
58
|
+
entities in a transient state — e.g. excluding `Grabbed` so a held object is left
|
|
59
|
+
alone.
|
|
60
|
+
|
|
61
|
+
Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
|
|
62
|
+
|
|
63
|
+
Read fields with `entity.getValue(Component, 'field')`. For vector fields use
|
|
64
|
+
`entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
|
|
65
|
+
no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
|
|
66
|
+
|
|
67
|
+
## Interaction components
|
|
68
|
+
|
|
69
|
+
`RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
|
|
70
|
+
and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
|
|
71
|
+
proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
|
|
72
|
+
ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
|
|
73
|
+
`GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
|
|
74
|
+
defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
|
|
75
|
+
|
|
76
|
+
`DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
|
|
77
|
+
`MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
|
|
78
|
+
`detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
|
|
79
|
+
`targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
|
|
80
|
+
no custom code.
|
|
81
|
+
|
|
82
|
+
For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
|
|
83
|
+
`getHolderHand(entity)` — never deep-import `Handle`.
|
|
84
|
+
|
|
85
|
+
## XR input
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
const pad = this.input.xr.gamepads.right;
|
|
89
|
+
pad?.getButtonDown(InputComponent.Trigger); // just pressed
|
|
90
|
+
pad?.getAxesValues(InputComponent.Thumbstick);
|
|
91
|
+
this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
|
|
95
|
+
buttons. Browser controls live at `world.input.keyboard` and
|
|
96
|
+
`world.input.browserGamepads`.
|
|
97
|
+
|
|
98
|
+
## Lifecycle
|
|
99
|
+
|
|
100
|
+
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
101
|
+
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
102
|
+
`getWorldPosition()` when logic needs the true viewer position.
|
|
103
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=56f1044b9936f279404ef715676b734a119ef495824d5916737f3a00579acc64 name=ecs-api.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|