@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.
Files changed (106) hide show
  1. package/dist/cli.js +7224 -216
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/package.json +8 -7
  82. package/scripts/verify-release-ready.mjs +25 -0
  83. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  89. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  94. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  100. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  105. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  106. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -1,95 +1,73 @@
1
1
  ---
2
2
  name: iwsdk-debug
3
- description: Debug continuous behavior in WebXR scenes — physics, animations, collisions, game loops, or any real-time interaction that happens too fast for an agent to observe. Uses ECS pause/step/snapshot/diff to freeze time and inspect state frame by frame.
4
- argument-hint: '[description of behavior to debug]'
3
+ description: Diagnose and verify real-time IWSDK behavior with bounded ECS pause, query, snapshot, step, and diff loops. Use for physics, animation, collision, interaction, or state bugs that cannot be proven from a screenshot.
4
+ argument-hint: '(use the current request)'
5
5
  ---
6
6
 
7
- # Debug Continuous Behavior
8
-
9
- Real-time behavior (physics, animations, collisions, game loops) happens too fast for an agent to observe directly. By the time you take a screenshot, the action is over. This skill uses ECS time-control tools to freeze, step, and diff state frame by frame.
10
-
11
- User request is in `$ARGUMENTS`.
12
-
13
- ## Core Workflow
14
-
15
- Every debugging session follows this pattern:
16
-
17
- 1. **Set up** the scenario (position objects, aim controllers, etc.)
18
- 2. **`ecs_pause`** — freeze ECS updates right before the interesting moment
19
- 3. **`ecs_snapshot({ "label": "before" })`** — capture state before the action
20
- 4. **Trigger** the action (release grip, apply force, start animation, etc.)
21
- 5. **`ecs_step(count, delta)`** — advance a few frames at fixed timestep
22
- 6. **`browser_screenshot`** — visually verify what happened
23
- 7. **`ecs_snapshot({ "label": "after" })`** — capture state after stepping
24
- 8. **`ecs_diff({ "from": "before", "to": "after" })`** — see exactly what changed
25
- 9. **Repeat** steps 5-8, stepping further until the behavior completes
26
- 10. **`ecs_resume`** — return to normal execution when done
27
-
28
- The key insight: **pause BEFORE triggering the action**, not after. If you pause after, you've already missed the first frames.
29
-
30
- ## Tool Reference
31
-
32
- | Tool | Purpose |
33
- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
34
- | `ecs_pause` | Freeze all ECS system updates. Render loop continues — screenshots still work. |
35
- | `ecs_step({"count":N,"delta":SECONDS})` | Advance N frames with fixed timestep (seconds). Must pause first. |
36
- | `ecs_resume` | Resume normal execution. First frame uses capped delta to avoid physics explosions. |
37
- | `ecs_snapshot({"label":"..."})` | Capture full ECS state. Stores up to 2 snapshots. |
38
- | `ecs_diff({"from":"...","to":"..."})` | Compare two snapshots. Shows added/removed entities and field-level value changes. |
39
- | `ecs_toggle_system({"name":"...","paused":true})` | Pause/resume a single system. Use `ecs_list_systems` to discover names. |
40
- | `browser_screenshot` | Runtime visual verification — works while paused and auto-switches from editor view. |
41
-
42
- ## Stepping Guidelines
43
-
44
- - **`delta`** is in seconds. Common values: `0.016` (60fps), `0.0139` (72fps/Quest refresh rate).
45
- - **Start small** — step 1-3 frames first to catch the initial moment, then step more.
46
- - **Don't overshoot** — stepping 100 frames at once defeats the purpose. Step in batches of 5-20.
47
-
48
- ## Patterns
49
-
50
- Short domain-specific tips. Apply the core workflow above, plus these hints.
51
-
52
- ### Physics (falling, bouncing, collisions)
53
-
54
- - Pause BEFORE releasing the object or applying force.
55
- - Step 1-3 frames at `delta: 0.016` to catch initial acceleration.
56
- - In diffs, check `PhysicsBody._linearVelocity` and `PhysicsBody._angularVelocity` to see motion direction and speed.
57
- - Check `Transform.position` to track movement.
58
- - If an object falls through a surface: verify the surface entity has both `PhysicsBody` (Static) and `PhysicsShape` (TriMesh for complex geometry).
59
- - Use `ecs_query_entity` to inspect `PhysicsShape` and `PhysicsBody` on both the falling object and the surface.
60
-
61
- ### Grab and Throw
62
-
63
- - Pause while the object is still held (trigger/grip engaged).
64
- - Release the input (set button value to 0) while paused.
65
- - Step frame by frame to observe the release velocity.
66
- - In diffs, `PhysicsBody._linearVelocity` shows the throw direction and speed.
67
- - If the object doesn't move after release: check that it has `PhysicsBody` with `state: Dynamic`.
68
-
69
- ### Animations and Transitions
70
-
71
- - Step 1 frame at a time with `delta` matching your target framerate.
72
- - Compare `Transform.position`, `Transform.orientation`, and `Transform.scale` across snapshots to track interpolation.
73
- - Use screenshots between steps to observe visual progression.
74
-
75
- ### Collision Detection
76
-
77
- - Pause just before two objects meet.
78
- - Step 1 frame at a time.
79
- - Watch for `PhysicsBody._linearVelocity` sign changes (indicates bounce/impact).
80
- - Watch for `PhysicsBody._angularVelocity` spikes (indicates tumbling from impact).
81
- - If objects pass through each other: check `PhysicsShape` exists on both entities, and verify shape types are appropriate (use `TriMesh` for complex static geometry).
82
-
83
- ### System Isolation
84
-
85
- - Use `ecs_list_systems` to see all systems and their priorities.
86
- - Use `ecs_toggle_system({ "name": "SystemName", "paused": true })` to pause a suspect system while others run.
87
- - Step forward and observe — if the bug disappears, that system is the cause.
88
- - Remember to unpause the system when done.
89
-
90
- ## Notes
91
-
92
- - **Snapshots overwrite** — only 2 are stored. Label them clearly ("before"/"after") and diff before taking new ones.
93
- - **Resume is safe** — the first frame after resume uses a capped delta to prevent physics explosions from accumulated time.
94
- - **Render loop continues while paused** — screenshots always work, and the XR session stays alive.
95
- - **Stepping requires pause** — `ecs_step` will fail if you haven't called `ecs_pause` first.
7
+ # IWSDK Runtime Debugging
8
+
9
+ Use the current request. The goal is a reproducible observation, the smallest
10
+ supported fix, and one matching replay—not an open-ended trace session.
11
+
12
+ ## 1. Establish one failing observation
13
+
14
+ Start the managed app once and enter XR only if required. Locate and query the
15
+ named entities and relevant systems. Freeze time as early as possible:
16
+
17
+ 1. `ecs_pause`
18
+ 2. `ecs_snapshot` with label `before`
19
+ 3. trigger or prepare the failing transition
20
+ 4. `ecs_step` for 1-3 frames at `0.016`
21
+ 5. `ecs_snapshot` with label `after`
22
+ 6. `ecs_diff` from `before` to `after`
23
+
24
+ Query the affected entity after the diff. For a startup failure that has already
25
+ occurred, record the bad live transform first, then use the next clean restart
26
+ for the frame-stepped observation. A screenshot can clarify geometry but is not
27
+ a substitute for ECS evidence.
28
+
29
+ ## 2. Form and test one hypothesis
30
+
31
+ Inspect only the configuration, scene node, component, or system implicated by
32
+ the measured change. Check the invariant before editing: colliders need both
33
+ body and shape, dynamic motion needs the correct state, interactions need the
34
+ matching input/component path, and animations need the responsible system to
35
+ be running. Do not browse framework internals while an authored invariant
36
+ already explains the evidence.
37
+
38
+ Use the common authored physics forms directly instead of dumping scene
39
+ capabilities: a detailed static environment normally pairs
40
+ `PhysicsBody: { "state": "STATIC" }` with
41
+ `PhysicsShape: { "shape": "TriMesh" }`; dynamic objects use a supported convex
42
+ or primitive shape. Query live components after reload to verify registration.
43
+
44
+ Make the smallest project edit that restores that invariant. Avoid unrelated
45
+ cleanup, visual redesign, or defensive rewrites.
46
+
47
+ Do not inspect IWSDK framework source, Vite plugin internals, or CLI help when a
48
+ missing authored component already explains the measured state. Use public
49
+ component data and the project files as the debugging boundary.
50
+ For a local authored-component fix, do not request the full scene capability or
51
+ scene-state payload; the source diff, production build, and focused live entity
52
+ query provide the required evidence.
53
+
54
+ ## 3. Replay the same probe
55
+
56
+ After editing, do not run an intermediate replay. Run the production build,
57
+ restart once, and repeat the same pause → snapshot → step → snapshot → diff
58
+ sequence with the same labels and timestep. Compare the same fields and query
59
+ the final entity. This gives exactly two probes: one failing observation and one
60
+ post-build replay. Capture one final runtime screenshot if position or collision
61
+ is visually relevant.
62
+
63
+ The build is the production-build proof; do not launch a second Vite preview
64
+ server. Replay with the same managed IWSDK dev runtime. Save file evidence with
65
+ `npx @iwsdk/cli browser screenshot --output-file <path>` rather than discovering the
66
+ screenshot CLI after the debug loop. When ECS evidence already proves the fix,
67
+ do not open or read the PNG back into model context; leave it for evaluator or
68
+ human review. Inspect one compact image only when the spatial result cannot be
69
+ established from the measured state.
70
+
71
+ Make at most one focused correction. Stop when the original symptom no longer
72
+ reproduces and the measured state agrees with the intended behavior. Call
73
+ `ecs_resume` before finishing and leave input buttons released.
@@ -1,135 +1,87 @@
1
1
  ---
2
2
  name: iwsdk-depth-occlusion
3
- description: Guide for implementing depth sensing and occlusion in IWSDK projects. Use when adding depth-based occlusion to hide virtual objects behind real-world surfaces, configuring DepthSensingSystem, choosing occlusion modes, or troubleshooting objects that disappear or fail to occlude.
4
- argument-hint: '[description of depth occlusion task]'
3
+ description: Add or repair IWSDK WebXR depth sensing and real-world occlusion in AR. Use for DepthSensingSystem, DepthOccludable, occlusion modes, or passthrough depth troubleshooting.
4
+ argument-hint: '(use the current request)'
5
5
  ---
6
6
 
7
- # Depth Occlusion
8
-
9
- Hide virtual objects behind real-world surfaces using WebXR depth sensing. The system samples a per-pixel depth texture from the XR device and compares it against each virtual fragment's depth — if the real surface is closer, the fragment is faded out.
10
-
11
- ## Setup
12
-
13
- Three things are required: XR session depth config, the system, and the component.
14
-
15
- ### 1. Enable depth sensing on the XR session
16
-
17
- ```jsonc
18
- // iwsdk.config.json
19
- {
20
- "world": {
21
- "xr": {
22
- "mode": "ar",
23
- "referenceSpace": "unbounded",
24
- "features": {
25
- "depthSensing": {
26
- "required": true,
27
- "usage": "gpu-optimized",
28
- "format": "float32"
29
- },
30
- "hitTest": { "required": true },
31
- "anchors": { "required": true },
32
- "unbounded": { "required": true }
33
- }
34
- }
35
- }
36
- }
37
- ```
38
-
39
- ### 2. Register `DepthSensingSystem` and `DepthOccludable`
40
-
41
- ```typescript
42
- import { DepthSensingSystem, DepthOccludable } from '@iwsdk/core';
43
-
44
- world
45
- .registerSystem(DepthSensingSystem, {
46
- configData: {
47
- enableDepthTexture: true,
48
- enableOcclusion: true,
49
- useFloat32: true,
50
- blurRadius: 20.0,
51
- },
52
- });
53
- ```
54
-
55
- ### 3. Add `DepthOccludable` to entities
56
-
57
- ```typescript
58
- import { DepthOccludable, OcclusionShadersMode } from '@iwsdk/core';
59
-
60
- // Soft occlusion (default) — smooth edges via 13-tap blur
61
- entity.addComponent(DepthOccludable);
62
-
63
- // Hard occlusion — sharp edges, single depth sample
64
- entity.addComponent(DepthOccludable, {
65
- mode: OcclusionShadersMode.HardOcclusion,
66
- });
67
-
68
- // MinMax occlusion — best quality, extra preprocessing pass
69
- entity.addComponent(DepthOccludable, {
70
- mode: OcclusionShadersMode.MinMaxSoftOcclusion,
71
- });
72
- ```
73
-
74
- The material must have `transparent: true`. The system sets this automatically, but verify it on custom materials.
75
-
76
- ## Occlusion Modes
77
-
78
- | Mode | Quality | Cost | Best For |
79
- | --------------------- | ------- | ------ | ----------------------------------------------------------------- |
80
- | `SoftOcclusion` | Good | Low | Most objects — smooth edges, hides depth aliasing |
81
- | `HardOcclusion` | Basic | Lowest | Small objects or when sharp edges are acceptable |
82
- | `MinMaxSoftOcclusion` | Best | Medium | Large objects with complex silhouettes against varied backgrounds |
83
-
84
- ## DepthSensingSystem Config
85
-
86
- | Property | Type | Default | Description |
87
- | -------------------- | ------- | ------- | ----------------------------------------- |
88
- | `enableOcclusion` | Boolean | `true` | Master switch for all occlusion |
89
- | `enableDepthTexture` | Boolean | `true` | Create GPU textures from depth data |
90
- | `useFloat32` | Boolean | `true` | Float32 depth textures (higher precision) |
91
- | `blurRadius` | Float32 | `20.0` | Blur radius for soft occlusion (pixels) |
92
-
93
- ## Depth Sensing Modes
94
-
95
- | Mode | When to use |
96
- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97
- | `cpu-optimized` | Simpler, works everywhere. Depth as linear meters in a DataArrayTexture. |
98
- | `gpu-optimized` | **Recommended.** Matches Quest hardware format. Depth as reverse-Z inverse depth in an ExternalTexture. Required for production parity with on-device behavior. Note that Quest devices only support this mode. |
99
-
100
- ## AR Session Requirements
101
-
102
- Depth occlusion only works in AR mode. The scene background must be `null` for passthrough:
103
-
104
- ```typescript
105
- scene.background = null;
7
+ # IWSDK Depth Occlusion
8
+
9
+ Depth occlusion has three independent requirements: the AR session requests
10
+ depth, one depth system is registered, and only intended virtual entities carry
11
+ `DepthOccludable`.
12
+
13
+ ## Implement
14
+
15
+ 1. Inspect `iwsdk.config.json`, `src/index.ts`, and the active scene in one
16
+ bounded pass, then make the complete config/system/scene edit before starting
17
+ the dev server. The contracts below are sufficient for the normal path: do
18
+ not call scene capabilities, CLI `--help`, inspect `node_modules`, or read
19
+ generated declarations unless a concrete build/runtime error remains.
20
+ 2. Keep `world.xr.mode` as `"ar"`. Under `world.xr.features`, request:
21
+
22
+ ```json
23
+ "depthSensing": {
24
+ "required": true,
25
+ "usage": "gpu-optimized",
26
+ "format": "float32"
27
+ }
28
+ ```
29
+
30
+ Preserve other required AR features. Use the living-room emulator (or the
31
+ environment requested by the task) so runtime depth exists.
32
+ 3. Import and register `DepthSensingSystem` exactly once after `World.create`:
33
+
34
+ ```ts
35
+ world.registerSystem(DepthSensingSystem, {
36
+ configData: {
37
+ enableDepthTexture: true,
38
+ enableOcclusion: true,
39
+ useFloat32: true,
40
+ blurRadius: 20,
41
+ },
42
+ });
43
+ ```
44
+
45
+ `DepthOccludable` is built in. Do not call `registerComponent` for it.
46
+ 4. Add `DepthOccludable` only to the requested scene nodes. These scene payloads
47
+ are exact: `{}` means soft occlusion and `{ "mode": "HardOcclusion" }` means
48
+ sharp low-cost occlusion. Use `"MinMaxSoftOcclusion"` only when the task needs
49
+ the higher-quality path. Write the literal scene value directly; do not load
50
+ the scene-composer format reference, import `OcclusionShadersMode`, or inspect
51
+ its declaration to reconfirm it.
52
+ 5. Leave a deliberate non-occludable reference object when comparison is part
53
+ of the request. Do not mark UI or guidance surfaces occludable by default.
54
+
55
+ ## Verify
56
+
57
+ Run the production build once, start the AR app once, enter XR, and query the
58
+ named entities and registered systems. Check the console for missing
59
+ depth-sensing warnings. Capture one runtime screenshot in the configured room;
60
+ source inspection or an authored scene render alone cannot prove passthrough
61
+ occlusion. Make one focused correction if the measured runtime disagrees, then
62
+ stop. Do not repeatedly restart the emulator or tune blur from screenshots when
63
+ the session never exposed depth data.
64
+
65
+ Use one XR entry, one bounded entity/system query set, and one console check.
66
+ Save the final live screenshot but do not read it back when those runtime checks
67
+ already prove that depth was requested, the system is live, and the intended
68
+ entities carry the correct occlusion modes.
69
+
70
+ Use the CLI action names below; do not substitute MCP method names or probe
71
+ `--help` first:
72
+
73
+ ```bash
74
+ npx @iwsdk/cli xr enter
75
+ npx @iwsdk/cli xr status
76
+ npx @iwsdk/cli ecs find --input-json '{"namePattern":"<requested node regex>"}'
77
+ npx @iwsdk/cli ecs query --input-json '{"entityIndex":<index from find>}'
78
+ npx @iwsdk/cli ecs systems
79
+ npx @iwsdk/cli browser logs --count 80
80
+ npx @iwsdk/cli browser screenshot --output-file artifacts/<name>.png
106
81
  ```
107
82
 
108
- ## Troubleshooting
109
-
110
- **Objects never occlude (always visible on top)**
111
-
112
- - Verify the entity has `DepthOccludable` component
113
- - Verify `DepthSensingSystem` is registered with `enableOcclusion: true`
114
- - Check that `depthSensing` is in the XR features config
115
-
116
- **Objects always invisible in IWER**
117
-
118
- - In the IWER emulator, the SEM must have loaded environment geometry. If no room is loaded, no depth data is produced.
119
- - Check the console for "Warning: depth-sensing feature not enabled"
120
-
121
- **Flickering or noisy occlusion edges**
122
-
123
- - Increase `blurRadius` (try 30-40)
124
- - Switch from `HardOcclusion` to `SoftOcclusion`
125
- - Use `MinMaxSoftOcclusion` for best edge quality
126
-
127
- ## Notes
128
-
129
- - **Only works in AR mode** — set `world.xr.mode` to `"ar"` and configure
130
- `world.xr.features.depthSensing` in `iwsdk.config.json`.
131
- - **`DepthOccludable` may be incompatible with custom shaders** that override `diffuse` or `fog_vertex` includes, since the occlusion code is injected at those shader hook points.
132
- - **Non-occludable objects** are simply entities without `DepthOccludable` — they render normally on top of everything.
133
- - **`DepthOccludable` is built into IWSDK** and is already registered — it appears
134
- in `scene_get_capabilities` under `registeredComponents`. Do not call
135
- `world.registerComponent()` for it; only the system needs registering.
83
+ Use `npx @iwsdk/cli browser screenshot --output-file <path>` for file evidence. Do
84
+ not alter the project camera or render extra authored angles to manufacture an
85
+ occlusion view; stage the requested nodes once, then judge the live AR capture.
86
+ Do not inspect framework source when the build, registered-system query, entity
87
+ components, and console warnings already establish the failing layer.
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: iwsdk-dev
3
+ description: Single entry point for IWSDK development. Invoke first for every IWSDK implementation request. Routes fresh builds to an internal planning playbook and bounded changes to an established app to an internal iteration playbook.
4
+ argument-hint: '[IWSDK development request]'
5
+ ---
6
+
7
+ # IWSDK Dev
8
+
9
+ Route the current request before inspecting files, planning, invoking a
10
+ specialist, or editing code. This file is only the entry point; after choosing,
11
+ load exactly one internal playbook and follow it for the rest of the task.
12
+
13
+ ## Route
14
+
15
+ Choose the **iterate path** only when the workspace already contains an established
16
+ experience and the request asks to preserve that product while changing,
17
+ extending, fixing, tuning, or polishing a bounded part of it.
18
+
19
+ Choose the **planner path** for a fresh scaffold, a new experience, a replacement of
20
+ the current product loop, or a request whose implementation requires defining
21
+ the product rather than preserving it. A detailed acceptance contract does not
22
+ turn a greenfield build into an iteration.
23
+
24
+ Observable workspace state wins over wording:
25
+
26
+ - starter/demo files in a fresh generated scaffold are not an established user
27
+ product when the request asks to build a new named experience;
28
+ - an existing coherent scene/source/UI implementation that the request calls a
29
+ baseline, approved experience, or current app is an iteration;
30
+ - when the request replaces most of the loop, route to the planner even if files
31
+ already exist;
32
+ - explicit user selection of a child route overrides automatic routing.
33
+
34
+ ## Internal handoff
35
+
36
+ 1. State the selected route in one sentence.
37
+ 2. Read exactly one internal playbook immediately:
38
+ - planner path: references/planner.md
39
+ - iterate path: references/iterate.md
40
+ 3. Do not read project files, call Bash, create a plan, or invoke a specialist
41
+ between this router and the selected playbook.
42
+ 4. Never load the other playbook later, including after context compaction.
43
+
44
+ iwsdk-dev does not add another implementation phase. The selected playbook owns
45
+ the work, evidence budget, specialist routing, verification, and stopping rule.