@iwsdk/create 0.5.3 → 1.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli.js +7224 -216
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
- package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
- package/dist/guidance/claude/.claude/settings.json +6 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/CLAUDE.md +2 -141
- package/dist/guidance/codex/.codex/config.toml +1 -1
- package/dist/guidance/common/AGENTS.md +96 -37
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/public/ui/welcome.uikitml +0 -19
- package/dist/template/common/src/robot.ts +5 -0
- package/dist/template/common/vite.config.ts +18 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
- package/dist/template/common-js/src/robot.js +5 -0
- package/dist/template/common-js/vite.config.js +18 -0
- package/package.json +8 -7
- package/scripts/verify-release-ready.mjs +25 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
- /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# IWSDK API Reference & Best Practices
|
|
2
2
|
|
|
3
|
-
Ground-truth API patterns for IWSDK app development. This file
|
|
4
|
-
`iwsdk-
|
|
5
|
-
writing IWSDK code, or reviewing it. It contains no process guidance
|
|
6
|
-
|
|
7
|
-
|
|
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
8
|
|
|
9
9
|
**Version sensitivity:** this reference tracks the SDK at the time the skill
|
|
10
10
|
shipped. For any API your plan depends on, verify the signature against the
|
|
@@ -37,7 +37,7 @@ shared by runtime and editor. Build local public URLs from
|
|
|
37
37
|
`import.meta.env.BASE_URL`; literal `./...` URLs resolve against the managed
|
|
38
38
|
editor route during editor use and are not a safe project-wide convention.
|
|
39
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 `
|
|
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
41
|
|
|
42
42
|
## Critical Best Practices
|
|
43
43
|
|
|
@@ -85,7 +85,7 @@ Instead of polling or storing state, react to entity lifecycle events:
|
|
|
85
85
|
|
|
86
86
|
```typescript
|
|
87
87
|
export class ReactiveSystem extends createSystem({
|
|
88
|
-
interactables: { required: [
|
|
88
|
+
interactables: { required: [RayInteractable, Transform] },
|
|
89
89
|
}) {
|
|
90
90
|
init() {
|
|
91
91
|
// React when entities enter the query
|
|
@@ -177,7 +177,7 @@ Types.Object; // Any JS object (avoid if possible - not optimized)
|
|
|
177
177
|
import { createComponent, Types } from '@iwsdk/core';
|
|
178
178
|
|
|
179
179
|
// Tag component (no data, just marks entities)
|
|
180
|
-
export const
|
|
180
|
+
export const Targetable = createComponent('Targetable', {}, '');
|
|
181
181
|
|
|
182
182
|
// Data component with proper types
|
|
183
183
|
export const Health = createComponent('Health', {
|
|
@@ -336,8 +336,8 @@ this.player; // XROrigin (Group) - VR rig root
|
|
|
336
336
|
this.player.head; // Head tracking (viewer pose)
|
|
337
337
|
this.player.raySpaces.left; // Left controller ray origin
|
|
338
338
|
this.player.raySpaces.right; // Right controller ray origin
|
|
339
|
-
this.player.gripSpaces.left; // Left controller grip
|
|
340
|
-
this.player.gripSpaces.right; // Right controller grip
|
|
339
|
+
this.player.gripSpaces.left; // Left controller grip pose
|
|
340
|
+
this.player.gripSpaces.right; // Right controller grip pose
|
|
341
341
|
this.player.secondaryRaySpaces.left; // Secondary left ray
|
|
342
342
|
this.player.secondaryRaySpaces.right; // Secondary right ray
|
|
343
343
|
this.player.secondaryGripSpaces.left; // Secondary left grip
|
|
@@ -349,6 +349,10 @@ this.player.head.getWorldPosition(headPos);
|
|
|
349
349
|
|
|
350
350
|
const rightHandPos = new Vector3();
|
|
351
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);
|
|
352
356
|
```
|
|
353
357
|
|
|
354
358
|
### 10. Audio System
|
|
@@ -1007,7 +1011,8 @@ RaycastSpace.Screen; // Phone AR screen touch (tap-to-place)
|
|
|
1007
1011
|
|
|
1008
1012
|
### 23. Follower Component
|
|
1009
1013
|
|
|
1010
|
-
Makes an entity follow another Object3D
|
|
1014
|
+
Makes an entity follow another Object3D with thresholded, smoothed motion. It
|
|
1015
|
+
can keep compact global UI discoverable without rigidly head-locking it.
|
|
1011
1016
|
|
|
1012
1017
|
```typescript
|
|
1013
1018
|
import { Follower, FollowBehavior } from '@iwsdk/core';
|
|
@@ -1074,7 +1079,7 @@ CameraFacing.Unknown; // Any available camera (default)
|
|
|
1074
1079
|
CameraState.Inactive; // Not started
|
|
1075
1080
|
CameraState.Starting; // Async initialization in progress
|
|
1076
1081
|
CameraState.Active; // Stream running
|
|
1077
|
-
CameraState.Error; // Failed to start
|
|
1082
|
+
CameraState.Error; // Failed to start; terminal until explicitly restarted
|
|
1078
1083
|
```
|
|
1079
1084
|
|
|
1080
1085
|
**CameraUtils** static class:
|
|
@@ -1084,6 +1089,9 @@ CameraState.Error; // Failed to start
|
|
|
1084
1089
|
const devices = await CameraUtils.getDevices();
|
|
1085
1090
|
const backCam = CameraUtils.findByFacing(devices, CameraFacing.Back);
|
|
1086
1091
|
|
|
1092
|
+
// Retry after correcting a startup error or changing camera configuration
|
|
1093
|
+
CameraUtils.restart(cameraEntity);
|
|
1094
|
+
|
|
1087
1095
|
// Capture current frame as canvas (for snapshot/processing)
|
|
1088
1096
|
const canvas = CameraUtils.captureFrame(cameraEntity);
|
|
1089
1097
|
if (canvas) {
|
|
@@ -1091,7 +1099,7 @@ if (canvas) {
|
|
|
1091
1099
|
}
|
|
1092
1100
|
```
|
|
1093
1101
|
|
|
1094
|
-
**Requires:** `features: { camera: true }`.
|
|
1102
|
+
**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.
|
|
1095
1103
|
|
|
1096
1104
|
### 25. PhysicsManipulation Component
|
|
1097
1105
|
|
|
@@ -1187,7 +1195,7 @@ world.getPersistentRoot(); // Returns the scene Object3D
|
|
|
1187
1195
|
| Visibility | Show/hide objects |
|
|
1188
1196
|
| LevelTag | Marks level membership |
|
|
1189
1197
|
| LevelRoot | Level root marker |
|
|
1190
|
-
|
|
|
1198
|
+
| RayInteractable | Marks objects for ray and pointer interaction |
|
|
1191
1199
|
| Hovered | Currently hovered |
|
|
1192
1200
|
| Pressed | Currently pressed/grabbed |
|
|
1193
1201
|
| OneHandGrabbable | Single-hand manipulation |
|
|
@@ -1219,7 +1227,7 @@ world.getPersistentRoot(); // Returns the scene Object3D
|
|
|
1219
1227
|
| System | Priority | Purpose |
|
|
1220
1228
|
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
|
|
1221
1229
|
| LocomotionSystem | -5 | Movement (teleport/slide/turn) |
|
|
1222
|
-
| InputSystem | -4 |
|
|
1230
|
+
| InputSystem | -4 | Pointer interaction state management |
|
|
1223
1231
|
| GrabSystem | -3 | Grab handling |
|
|
1224
1232
|
| PhysicsSystem | -2 | Physics simulation |
|
|
1225
1233
|
| SceneUnderstandingSystem | -1 | AR plane/mesh detection |
|
|
@@ -1289,30 +1297,30 @@ Before writing custom code, check if IWSDK already provides the functionality. R
|
|
|
1289
1297
|
|
|
1290
1298
|
### Reinvention Risk Table
|
|
1291
1299
|
|
|
1292
|
-
| What you might build from scratch
|
|
1293
|
-
|
|
|
1294
|
-
| GLTF loading with GLTFLoader
|
|
1295
|
-
| Ray/line mesh for controller pointing
|
|
1296
|
-
| Hover/click
|
|
1297
|
-
| Custom skybox sphere
|
|
1298
|
-
| PBR environment lighting
|
|
1299
|
-
| Teleport arc + landing marker
|
|
1300
|
-
| Comfort vignette for motion
|
|
1301
|
-
| Controller 3D models
|
|
1302
|
-
| Hand tracking meshes
|
|
1303
|
-
| Object grab + manipulation
|
|
1304
|
-
| Hit-test against real world
|
|
1305
|
-
| Spatial audio
|
|
1306
|
-
| Camera feed texture
|
|
1307
|
-
| Depth occlusion shader
|
|
1308
|
-
| HUD / screen-space UI
|
|
1309
|
-
| Follow-head billboard
|
|
1310
|
-
| Scene cleanup on level change
|
|
1311
|
-
| Gamepad button debouncing
|
|
1312
|
-
| Manual GPU cleanup with traverse
|
|
1313
|
-
| Manual world-space positioning
|
|
1314
|
-
| Manual XR hit-test setup
|
|
1315
|
-
| Manual camera video feed
|
|
1300
|
+
| What you might build from scratch | What IWSDK already provides |
|
|
1301
|
+
| -------------------------------------- | ---------------------------------------------------------------------------- |
|
|
1302
|
+
| GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
|
|
1303
|
+
| Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
|
|
1304
|
+
| Hover/click interaction with Raycaster | `RayInteractable` + `Hovered` + `Pressed` components |
|
|
1305
|
+
| Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
|
|
1306
|
+
| PBR environment lighting | `IBLGradient` or `IBLTexture` component |
|
|
1307
|
+
| Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
|
|
1308
|
+
| Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
|
|
1309
|
+
| Controller 3D models | Auto-loaded from WebXR Input Profiles |
|
|
1310
|
+
| Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
|
|
1311
|
+
| Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
|
|
1312
|
+
| Hit-test against real world | `EnvironmentRaycastTarget` component |
|
|
1313
|
+
| Spatial audio | `AudioSource` component with pooling |
|
|
1314
|
+
| Camera feed texture | `CameraSource` component |
|
|
1315
|
+
| Depth occlusion shader | `DepthOccludable` component |
|
|
1316
|
+
| HUD / screen-space UI | `ScreenSpace` component with CSS units |
|
|
1317
|
+
| Follow-head billboard | `Follower` component |
|
|
1318
|
+
| Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
|
|
1319
|
+
| Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
|
|
1320
|
+
| Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
|
|
1321
|
+
| Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
|
|
1322
|
+
| Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
|
|
1323
|
+
| Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
|
|
1316
1324
|
|
|
1317
1325
|
### Asset Loading (AssetManager)
|
|
1318
1326
|
|
|
@@ -1404,17 +1412,17 @@ const hud = world.createTransformEntity(hudMesh, {
|
|
|
1404
1412
|
|
|
1405
1413
|
### Input & Interaction
|
|
1406
1414
|
|
|
1407
|
-
**
|
|
1415
|
+
**RayInteractable → Hovered/Pressed flow:**
|
|
1408
1416
|
|
|
1409
|
-
1. Add `
|
|
1417
|
+
1. Add `RayInteractable` component to any entity that should respond to pointer input
|
|
1410
1418
|
2. `InputSystem` automatically performs BVH-accelerated raycasting each frame
|
|
1411
|
-
3. When a ray hits
|
|
1419
|
+
3. When a ray hits a RayInteractable entity, `Hovered` tag is added
|
|
1412
1420
|
4. When the user presses the select button while hovering, `Pressed` tag is added
|
|
1413
1421
|
5. Query for `Hovered`/`Pressed` in your system to react to interactions
|
|
1414
1422
|
|
|
1415
1423
|
```typescript
|
|
1416
1424
|
// Setup
|
|
1417
|
-
entity.addComponent(
|
|
1425
|
+
entity.addComponent(RayInteractable);
|
|
1418
1426
|
|
|
1419
1427
|
// In your system — react to interactions
|
|
1420
1428
|
export class MyInteractionSystem extends createSystem({
|
|
@@ -1463,7 +1471,7 @@ These visuals are automatically created and managed by IWSDK systems:
|
|
|
1463
1471
|
10. **DON'T** confuse PhysicsBody (motion) with PhysicsShape (collision + material)
|
|
1464
1472
|
11. **DON'T** use raw `GLTFLoader`/`TextureLoader` — use `AssetManager` for caching, DRACO/KTX2 setup
|
|
1465
1473
|
12. **DON'T** use `scene.add()` — use `createTransformEntity()` for proper ECS integration
|
|
1466
|
-
13. **DON'T**
|
|
1474
|
+
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
|
|
1467
1475
|
14. **DON'T** add environment components (`DomeGradient`/`IBLTexture`/etc.) to arbitrary entities — must go on the level root (`world.activeLevel.value`)
|
|
1468
1476
|
15. **DON'T** forget `_needsUpdate` after changing environment properties — changes are silently ignored without `entity.setValue(DomeGradient, '_needsUpdate', true)`
|
|
1469
1477
|
16. **DON'T** use `entity.destroy()` for objects with GPU resources — use `entity.dispose()` which also cleans up geometry/materials/textures
|
|
@@ -1491,4 +1499,4 @@ These visuals are automatically created and managed by IWSDK systems:
|
|
|
1491
1499
|
8. **VR vs AR** - Does this work differently in each mode?
|
|
1492
1500
|
9. **Input handling** - What controller/hand inputs are needed?
|
|
1493
1501
|
10. **Audio feedback** - What sounds should play on interactions?
|
|
1494
|
-
11. **Select 3D assets** - What models are needed
|
|
1502
|
+
11. **Select 3D assets** - What models are needed, and what are their licensing, provenance, and performance constraints?
|
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
# Iterate path
|
|
2
|
+
|
|
3
|
+
Make the requested delta to the established app without reopening its product
|
|
4
|
+
definition. The existing working experience is the baseline and the requested
|
|
5
|
+
change is the scope boundary.
|
|
6
|
+
|
|
7
|
+
## Fast opening
|
|
8
|
+
|
|
9
|
+
To keep a bounded edit from turning into rediscovery, begin in this order:
|
|
10
|
+
|
|
11
|
+
1. Run the bounded source/scene/UI Bash command below.
|
|
12
|
+
2. Make a Write/Edit under `src/` or `public/` based only on that bundle. A
|
|
13
|
+
small safe skeleton such as the requested component or UI asset is enough;
|
|
14
|
+
finish it after typecheck if an API detail remains uncertain.
|
|
15
|
+
|
|
16
|
+
When the request names a state or component, prefer writing that exact
|
|
17
|
+
createComponent skeleton as the opening edit. Scene and UI schema details need
|
|
18
|
+
not block a safe scalar-state skeleton; let the first typecheck surface a real
|
|
19
|
+
API question. Do not reread root guidance or enumerate rule, skill, dependency,
|
|
20
|
+
or node_modules trees before the edit. If the harness did not automatically
|
|
21
|
+
load an applicable path-scoped instruction, include only that one instruction
|
|
22
|
+
in the bounded opening bundle. Preserve any authored view already present.
|
|
23
|
+
|
|
24
|
+
Do not insert unrelated discovery, CLI help, another skill, or broad reference
|
|
25
|
+
lookup between the bounded inspection and the first edit.
|
|
26
|
+
|
|
27
|
+
## Operating contract
|
|
28
|
+
|
|
29
|
+
- Do not create an experience brief, product plan, architecture document,
|
|
30
|
+
retrospective, or review artifact unless the user explicitly requests it.
|
|
31
|
+
- Preserve existing scene anchors, interactions, state, UI, visual language,
|
|
32
|
+
and behavior outside the requested delta. Do not replace the app with a new
|
|
33
|
+
concept or rebuild working systems for stylistic consistency.
|
|
34
|
+
- Inspect the smallest source/scene/UI bundle that establishes the affected
|
|
35
|
+
path and its immediate dependencies in one bounded shell call, then make the
|
|
36
|
+
mandatory opening edit before any additional discovery.
|
|
37
|
+
- Record the acceptance contract mentally or in the active response: requested
|
|
38
|
+
behavior, preserved behavior, observable state, and visual consequence. Do
|
|
39
|
+
not write a process document.
|
|
40
|
+
- Reuse the app's existing component, system, asset, naming, and UI patterns.
|
|
41
|
+
Introduce a new abstraction only when the requested change cannot fit the
|
|
42
|
+
current structure cleanly.
|
|
43
|
+
- Treat preserved ScreenSpace UI as occupying its authored transform in
|
|
44
|
+
immersive mode even when its browser presentation differs. Reuse established
|
|
45
|
+
panel scale and spacing. For the stock scaffold layout, a new front-facing
|
|
46
|
+
panel in the same horizontal band should start at 0.25-0.32 scale, at least
|
|
47
|
+
0.75 world meters above the preserved panel center, and at the same or greater
|
|
48
|
+
depth. Keep that separation during corrections; move laterally into clear
|
|
49
|
+
space rather than lowering it into the object interaction band.
|
|
50
|
+
- Invoke `iwsdk-build-model` before materially changing a model and
|
|
51
|
+
`iwsdk-compose-scene` before changing scene placement, lighting, environment,
|
|
52
|
+
or cameras. Invoke other matching specialists only after a concrete uncertainty
|
|
53
|
+
or the first failed required interaction. After that first failure, do not sweep
|
|
54
|
+
coordinates, read screenshots for interaction debugging, or inspect pointer,
|
|
55
|
+
input, grab, ray, or UIKit internals in `node_modules`; use the specialist and
|
|
56
|
+
measured ECS/UI state.
|
|
57
|
+
- Before the first typecheck, do not read specialist references or inspect
|
|
58
|
+
`node_modules`. Import IWSDK ECS, UIKit, interaction, material, and Three.js
|
|
59
|
+
re-exports from `@iwsdk/core`; use
|
|
60
|
+
`createComponent('Name', {field: {type: Types.Int8, default: 0}})` directly.
|
|
61
|
+
Let `npm run --if-present typecheck` produce the exact remaining API question.
|
|
62
|
+
|
|
63
|
+
Use this opening command shape directly, tolerating missing paths and keeping
|
|
64
|
+
the output bounded. The existing scaffold rules are already in context:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
{
|
|
68
|
+
for f in iwsdk.config.json package.json \
|
|
69
|
+
$(find src -maxdepth 2 -type f \
|
|
70
|
+
\( -name '*.ts' -o -name '*.tsx' \) 2>/dev/null | sort) \
|
|
71
|
+
$(find public/ui -maxdepth 2 -type f \
|
|
72
|
+
\( -name '*.uikitml' -o -name '*.json' \) 2>/dev/null | sort) \
|
|
73
|
+
$(find public/scenes -maxdepth 2 -type f \
|
|
74
|
+
-name '*.json' 2>/dev/null | sort); do
|
|
75
|
+
if [ -f "$f" ]; then
|
|
76
|
+
echo "=== $f ==="
|
|
77
|
+
sed -n '1,220p' "$f"
|
|
78
|
+
fi
|
|
79
|
+
done
|
|
80
|
+
} | head -c 32000
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Implementation loop
|
|
84
|
+
|
|
85
|
+
1. Inspect the affected files plus the active scene and UI in one bounded call.
|
|
86
|
+
2. Identify the current behavior that must remain unchanged.
|
|
87
|
+
3. Implement the smallest complete vertical delta, including state/UI feedback
|
|
88
|
+
and recovery when the request needs them.
|
|
89
|
+
4. Run one batched typecheck and fix errors together.
|
|
90
|
+
5. Start the managed runtime directly with
|
|
91
|
+
`npx @iwsdk/cli dev up --headless --timeout 45000`.
|
|
92
|
+
6. Exercise the changed path with real user input and query only the named state
|
|
93
|
+
needed to prove it. Direct ECS mutation may prepare/reset a scenario but is
|
|
94
|
+
not interaction proof.
|
|
95
|
+
7. Run one focused regression smoke for the preserved behavior most likely to
|
|
96
|
+
have been affected.
|
|
97
|
+
8. Run the production build and stop.
|
|
98
|
+
|
|
99
|
+
Use the known CLI surface without help discovery: `xr status|enter|look-at|select`,
|
|
100
|
+
`ecs find|query`, `browser screenshot`, and `scene render-file`. These call
|
|
101
|
+
shapes are authoritative; substitute the requested target, entity index, and
|
|
102
|
+
artifact name instead of running family-level or subcommand `--help`:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx @iwsdk/cli xr enter --input-json '{}'
|
|
106
|
+
npx @iwsdk/cli xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1.5,"z":-2}}'
|
|
107
|
+
npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
|
|
108
|
+
npx @iwsdk/cli ecs find --input-json '{"namePattern":"Requested Name","limit":10}'
|
|
109
|
+
npx @iwsdk/cli ecs query --input-json '{"entityIndex":1,"components":["RequestedState"]}'
|
|
110
|
+
npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/final.png
|
|
111
|
+
npx @iwsdk/cli scene render-file --input-json '{"path":"public/scenes/main.iwsdk.scene.json","viewId":"hero","width":800,"height":800}' --output-file artifacts/hero.png
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
After `dev up`, target at most 32 Bash calls for all interaction and visual
|
|
115
|
+
verification. Batch each look-at, input, and state query into one shell call.
|
|
116
|
+
Run the full end-to-end sequence once; after a measured failure, patch the
|
|
117
|
+
cause and rerun only the affected path.
|
|
118
|
+
|
|
119
|
+
## Efficiency budget
|
|
120
|
+
|
|
121
|
+
Treat 90 total tool calls, 36 shell calls after dev startup, two image
|
|
122
|
+
previews, two runtime restarts, and two authored-scene renders as default upper
|
|
123
|
+
bounds for a bounded edit. Avoid CLI help calls when the known command shapes
|
|
124
|
+
below apply. These guardrails prevent verification from becoming open-ended;
|
|
125
|
+
they do not justify omitting required acceptance evidence.
|
|
126
|
+
|
|
127
|
+
At roughly 70 tool calls, drop optional diagnostics and finish only missing
|
|
128
|
+
evidence. At 80, freeze optional polish, save required artifacts once, run the
|
|
129
|
+
production build, and close the task.
|
|
130
|
+
|
|
131
|
+
For
|
|
132
|
+
`DistanceGrabbable`, hold/release gamepad button index `0`; for proximity
|
|
133
|
+
`OneHandGrabbable`/`TwoHandsGrabbable`, use squeeze button index `1`.
|
|
134
|
+
The focused distance-grab smoke is not another `xr select`: aim at the preserved
|
|
135
|
+
object, run
|
|
136
|
+
`npx @iwsdk/cli xr set-gamepad-state --input-json '{"device":"controller-right","buttons":[{"index":0,"value":1}]}'`,
|
|
137
|
+
observe `Grabbed` or movement, then repeat with `value:0` to release.
|
|
138
|
+
|
|
139
|
+
If a scene/source/UI edit happens after the managed runtime started and live
|
|
140
|
+
state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
|
|
141
|
+
loop on browser reload. Run one
|
|
142
|
+
`npx @iwsdk/cli dev restart --headless --timeout 60000`, then resume the named-state
|
|
143
|
+
check. One failed restart may be diagnosed once; do not enter a recovery loop.
|
|
144
|
+
|
|
145
|
+
Do not perform a full product replay when the edit affects one bounded path.
|
|
146
|
+
Expand verification only when a measured failure shows broader impact.
|
|
147
|
+
|
|
148
|
+
## Visual comparison
|
|
149
|
+
|
|
150
|
+
Use the supplied pre-edit baseline when present. Pixel reads have a hard ceiling
|
|
151
|
+
of two: one bounded baseline or final comparison and one replacement after a
|
|
152
|
+
focused correction. Never read aim, hover, panel, coordinate, or duplicate debug
|
|
153
|
+
screenshots. Debug interactions with state, not pixels.
|
|
154
|
+
|
|
155
|
+
Never load a full-resolution PNG into model context. Preserve deliverable
|
|
156
|
+
images unchanged, but create a temporary JPEG preview no wider than 600 pixels
|
|
157
|
+
at about 70% quality with an image tool already available in the environment.
|
|
158
|
+
Do not install a dependency only to resize evidence, and delete the temporary
|
|
159
|
+
preview after the visual decision.
|
|
160
|
+
|
|
161
|
+
Do not use repeated `scene render-file` calls to discover framing. When an
|
|
162
|
+
authored hero view must be checked, run it once and read
|
|
163
|
+
`data.result.renderStats.visibleNodeIds`; make at most one focused camera or
|
|
164
|
+
composition correction from that result. The second render is the final hero
|
|
165
|
+
attempt even if it fails; do not issue a third `scene render-file` call.
|
|
166
|
+
|
|
167
|
+
Do not reconcile hero and default-player framing with trigonometry, coordinate
|
|
168
|
+
sweeps, repeated screenshots, or browser logs. Keep the panel identity-rotated
|
|
169
|
+
for the player. If the one hero check misses it, move only the existing hero
|
|
170
|
+
camera to the same side of the panel as the default player, check once more,
|
|
171
|
+
and freeze. Inspect browser logs at most once and only after a command returns
|
|
172
|
+
an explicit runtime error; never create a log-debugging loop.
|
|
173
|
+
|
|
174
|
+
Preserve the existing composition and visual language unless the request asks
|
|
175
|
+
to change them. When it does, compare the same viewpoint before and after and
|
|
176
|
+
make one focused correction for clipping, legibility, contrast, or hierarchy.
|
|
177
|
+
When adding a new primary spatial panel, it must be readable at the default
|
|
178
|
+
runtime viewpoint rather than a tiny accessory: keep its visible bounds at
|
|
179
|
+
least roughly 12% of frame width and 8% of frame height, but normally below 70%
|
|
180
|
+
of frame width and 40% of frame height, while staying fully inside the frame.
|
|
181
|
+
It must not cover the preserved product primary object, existing primary UI,
|
|
182
|
+
or focused regression object. Readability alone is insufficient: visible
|
|
183
|
+
bounds must not touch or overlap. Leave roughly 3% of the frame as clear
|
|
184
|
+
separation. If the first preview shows contact, move the new panel into the
|
|
185
|
+
largest empty region above or beside the preserved composition.
|
|
186
|
+
|
|
187
|
+
Use an opaque or strongly contrasting panel surface. Primary copy must be dark
|
|
188
|
+
on light or light on dark; white or pale text on translucent white, sky, or
|
|
189
|
+
another bright background fails even when the glyphs are technically present.
|
|
190
|
+
For the scaffold's Horizon `<Panel>`, assume the kit's opaque white surface
|
|
191
|
+
wins over a custom root `background-color`; use dark primary and secondary text
|
|
192
|
+
on the first attempt. Use light text only after a compact runtime preview proves
|
|
193
|
+
the actual rendered panel surface is dark. Do not spend a restart discovering
|
|
194
|
+
white-on-white text that the stock kit behavior already predicts.
|
|
195
|
+
|
|
196
|
+
Reuse the established app panel scale and spacing when available. In the stock
|
|
197
|
+
starter-scale composition, a new front-facing UIKitML panel should begin at
|
|
198
|
+
0.25-0.32 scale. If it shares the central horizontal band, place its center at
|
|
199
|
+
least 0.75 world meters above the preserved panel and at the same or greater
|
|
200
|
+
depth; side-by-side placement needs a clear gap beyond both half-widths. Keep
|
|
201
|
+
that separation through the one allowed correction.
|
|
202
|
+
|
|
203
|
+
On the first final preview, inspect the whole change together: new UI is fully
|
|
204
|
+
inside the frame; a visible gap separates it from existing primary UI and
|
|
205
|
+
objects; important copy and controls remain readable at preview size; and text
|
|
206
|
+
has strong contrast against its actual rendered surface. Batch one correction
|
|
207
|
+
for all failures, then take the second and final preview.
|
|
208
|
+
|
|
209
|
+
Keep primary added UI away from fragile frame edges unless the established
|
|
210
|
+
composition reserves a stable edge region. XR captures may use a square or
|
|
211
|
+
otherwise narrower aspect ratio than the browser. Prefer an above-central
|
|
212
|
+
placement over pushing a panel to the side, and retain a generous lateral
|
|
213
|
+
margin before accepting the final preview.
|
|
214
|
+
|
|
215
|
+
Progress and completion evidence must remain distinguishable at the compact
|
|
216
|
+
600-pixel preview scale. Do not rely on changing only one short status sentence.
|
|
217
|
+
Use one coarse, deliberate milestone change such as a large status chip or bar,
|
|
218
|
+
clearly marked step indicators, or a strong color/state change on both the
|
|
219
|
+
panel and the affected object. The changed treatment should occupy a visible
|
|
220
|
+
region of the panel and make completion obvious without reading fine print.
|
|
221
|
+
|
|
222
|
+
For a front-facing UIKitML panel in the stock starter layout, keep rotationDeg
|
|
223
|
+
absent unless the existing app establishes another convention. Do not calculate
|
|
224
|
+
a look-at yaw solely to face the default player: the stock panel front is
|
|
225
|
+
face-on at identity. Judge the final result from a fresh default runtime
|
|
226
|
+
viewpoint, without custom headset repositioning before capture.
|
|
227
|
+
|
|
228
|
+
For XR work, keep the immersive session active through the final browser
|
|
229
|
+
screenshot. Immediately before capture, check XR status and enter once if the
|
|
230
|
+
session is inactive. A non-immersive browser camera is not placement evidence
|
|
231
|
+
for world-space UI; return to the default immersive viewpoint instead of moving
|
|
232
|
+
correctly placed content to satisfy the unrelated browser view.
|
|
233
|
+
|
|
234
|
+
## Stop rule
|
|
235
|
+
|
|
236
|
+
Stop when the requested delta works through real input, the named state/UI
|
|
237
|
+
evidence passes, the focused preserved-path smoke passes, the production build
|
|
238
|
+
passes, and required evidence files exist. Do not reopen unrelated polish or
|
|
239
|
+
review after those gates pass.
|