@iwsdk/create 0.4.2 → 0.5.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/README.md +103 -41
  2. package/dist/cli.js +1003 -3418
  3. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  9. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  10. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
  11. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
  12. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
  13. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
  14. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
  15. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
  16. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
  19. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  24. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  25. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
  27. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
  28. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
  29. package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
  30. package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
  31. package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
  32. package/dist/guidance/claude/.claude/settings.json +19 -0
  33. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
  34. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  35. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
  36. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
  43. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
  44. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
  45. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
  46. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
  47. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
  48. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
  49. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  50. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  53. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
  57. package/dist/guidance/claude/CLAUDE.md +142 -0
  58. package/dist/guidance/codex/.codex/config.toml +2 -0
  59. package/dist/guidance/common/AGENTS.md +151 -0
  60. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
  61. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
  62. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
  63. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
  64. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
  65. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
  66. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
  67. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
  68. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
  69. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
  70. package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
  71. package/dist/template/common/README.md +13 -0
  72. package/dist/template/common/gitignore.template +45 -0
  73. package/dist/template/common/index.html +16 -0
  74. package/dist/template/common/nvmrc.template +1 -0
  75. package/dist/template/common/public/audio/chime.mp3 +0 -0
  76. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
  77. package/dist/template/common/public/textures/webxr.png +0 -0
  78. package/dist/template/common/public/ui/welcome.uikitml +98 -0
  79. package/dist/template/common/src/assets.ts +54 -0
  80. package/dist/template/common/src/components.ts +11 -0
  81. package/dist/template/common/src/index.ts +19 -0
  82. package/dist/template/common/src/panel.ts +38 -0
  83. package/dist/template/common/src/robot-component.ts +10 -0
  84. package/dist/template/common/src/robot.ts +38 -0
  85. package/dist/template/common/src/vite-env.d.ts +2 -0
  86. package/dist/template/common/tsconfig.json +15 -0
  87. package/dist/template/common/vite.config.ts +27 -0
  88. package/dist/template/common-js/README.md +13 -0
  89. package/dist/template/common-js/gitignore.template +45 -0
  90. package/dist/template/common-js/index.html +16 -0
  91. package/dist/template/common-js/nvmrc.template +1 -0
  92. package/dist/template/common-js/public/audio/chime.mp3 +0 -0
  93. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
  94. package/dist/template/common-js/public/textures/webxr.png +0 -0
  95. package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
  96. package/dist/template/common-js/src/assets.js +45 -0
  97. package/dist/template/common-js/src/components.js +9 -0
  98. package/dist/template/common-js/src/index.js +14 -0
  99. package/dist/template/common-js/src/panel.js +31 -0
  100. package/dist/template/common-js/src/robot-component.js +8 -0
  101. package/dist/template/common-js/src/robot.js +37 -0
  102. package/dist/template/common-js/vite.config.js +25 -0
  103. package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
  104. package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
  105. package/package.json +17 -12
  106. package/scripts/verify-release-ready.mjs +76 -0
@@ -0,0 +1,96 @@
1
+ ---
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]'
5
+ ---
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.
96
+
@@ -0,0 +1,135 @@
1
+ ---
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]'
5
+ ---
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;
106
+ ```
107
+
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.
@@ -0,0 +1,129 @@
1
+ ---
2
+ name: iwsdk-grab
3
+ description: Grab an object in the WebXR scene using emulated controllers. Use when the user wants to pick up, move, or test grabbing an object. Supports OneHandGrabbable and TwoHandsGrabbable components which use proximity-based grip (squeeze button), not trigger.
4
+ argument-hint: <object-name> [destination]
5
+ ---
6
+
7
+ # Grab Object
8
+
9
+ Grab an object in the XR scene using the IWER emulated controllers. The workflow has a **required core** (steps 1-5) that must always execute, and **optional extensions** (steps 6-9) that depend on the user's intent.
10
+
11
+ User request is in `$ARGUMENTS`.
12
+
13
+ ## Required Core
14
+
15
+ These steps always execute in order. A grab cannot succeed without them.
16
+
17
+ ### Step 1: Enter XR
18
+
19
+ Check session status. If not in an active XR session, accept and enter.
20
+
21
+ ```
22
+ xr_get_session_status → if not sessionActive → xr_accept_session
23
+ ```
24
+
25
+ ### Step 2: Locate the target
26
+
27
+ Find the live entity by name or grabbable component, then query its component data.
28
+
29
+ ```
30
+ ecs_find_entities({namePattern: target}) → ecs_query_entity(entityIndex)
31
+ ```
32
+
33
+ If the object is not found, search `OneHandGrabbable` and `TwoHandsGrabbable`
34
+ entities, report the available matches, and stop.
35
+
36
+ ### Step 3: Get its transform
37
+
38
+ Read the object's Transform position from the queried entity.
39
+
40
+ ```
41
+ ecs_query_entity(entityIndex) → Transform.position
42
+ ```
43
+
44
+ ### Step 4: Animate controller to target
45
+
46
+ Animate the controller to the object's position. Default to `"controller-right"` unless the user specified left.
47
+
48
+ ```
49
+ xr_animate_to({
50
+ device: "controller-right",
51
+ position: { x, y, z },
52
+ duration: 0.5,
53
+ })
54
+ ```
55
+
56
+ ### Step 5: Engage grip
57
+
58
+ OneHandGrabbable and TwoHandsGrabbable are proximity-based and use the **squeeze/grip button (index 1)**, not the trigger.
59
+
60
+ ```
61
+ xr_set_gamepad_state({
62
+ device: "controller-right",
63
+ buttons: [{ index: 1, value: 1 }],
64
+ })
65
+ ```
66
+
67
+ The object is now grabbed. If the user only asked to grab (not move), stop here.
68
+
69
+ ## Optional Extensions
70
+
71
+ Apply these based on the user's request.
72
+
73
+ ### Step 6: Move to destination
74
+
75
+ If the user specified a destination position, animate the controller there. If no position was given but the user asked to "move" the object, animate it to in front of the headset.
76
+
77
+ To find "in front of headset": `xr_get_transform({ "device": "headset" })` → place at `(head.x, head.y - 0.2, head.z - 0.5)` adjusted for head orientation.
78
+
79
+ ```
80
+ xr_animate_to({
81
+ device: "controller-right",
82
+ position: { x, y, z },
83
+ duration: 0.5,
84
+ })
85
+ ```
86
+
87
+ ### Step 7: Release grip
88
+
89
+ Release the squeeze button to drop the object.
90
+
91
+ ```
92
+ xr_set_gamepad_state({
93
+ device: "controller-right",
94
+ buttons: [{ index: 1, value: 0 }],
95
+ })
96
+ ```
97
+
98
+ ### Step 8: Return controller
99
+
100
+ Animate the controller back to its resting position so it's not overlapping the dropped object.
101
+
102
+ ```
103
+ xr_animate_to({
104
+ device: "controller-right",
105
+ position: { x: 0.2, y: 1.4, z: -0.3 },
106
+ duration: 0.5,
107
+ })
108
+ ```
109
+
110
+ Default resting positions: right `(0.2, 1.4, -0.3)`, left `(-0.2, 1.4, -0.3)`.
111
+
112
+ ### Step 9: Verify
113
+
114
+ Take a screenshot to confirm the result.
115
+
116
+ ```
117
+ browser_screenshot
118
+ ```
119
+
120
+ The screenshot command is runtime-only. If the editor is visible, the managed
121
+ workspace switches to runtime before capture.
122
+
123
+ ## Notes
124
+
125
+ - **Never use `xr_set_device_state` to move controllers** — it teleports instead of animating, which can break grab state.
126
+ - **Never use `xr_select` or trigger (button index 0) for grabs** — OneHandGrabbable/TwoHandsGrabbable respond to squeeze (button index 1).
127
+ - **DistanceGrabbable is different** — it uses ray-based selection, not proximity. This skill does not cover DistanceGrabbable.
128
+ - If the object lacks a name in the hierarchy, suggest adding `mesh.name = "MyObject"` in code before `createTransformEntity`.
129
+
@@ -0,0 +1,92 @@
1
+ ---
2
+ name: iwsdk-physics
3
+ description: Guide for implementing physics in IWSDK projects. Use when adding physics simulation, configuring rigid bodies, collision shapes, applying forces, creating grabbable physics objects, or troubleshooting physics behavior.
4
+ ---
5
+
6
+ # IWSDK Physics System Guide
7
+
8
+ This skill provides the complete reference and workflow for implementing Havok-powered physics simulation in IWSDK applications. Physics is built on three ECS components (`PhysicsBody`, `PhysicsShape`, `PhysicsManipulation`) orchestrated by the `PhysicsSystem`.
9
+
10
+ ## Enabling Physics
11
+
12
+ Enable physics in `iwsdk.config.json` with the `physics` feature flag:
13
+
14
+ ```jsonc
15
+ {
16
+ "scene": "./public/scenes/physics.iwsdk.scene.json",
17
+ "world": {
18
+ "xr": { "mode": "vr" },
19
+ "features": {
20
+ "physics": true,
21
+ "grabbing": true,
22
+ "locomotion": true
23
+ }
24
+ }
25
+ }
26
+ ```
27
+
28
+ Setting `physics: true` automatically registers `PhysicsBody`, `PhysicsShape`, `PhysicsManipulation` components and the `PhysicsSystem` at priority `-2`.
29
+
30
+ **Only enable physics when needed.** If no objects require dynamic simulation, omit it to avoid overhead.
31
+
32
+
33
+ ## Reference files
34
+
35
+ Read the one the task needs; each is complete on its own.
36
+
37
+ - **Component fields, enums and shape dimensions** → [references/component-reference.md](references/component-reference.md)
38
+ - **Workflows** — dynamic bodies, static colliders, kinematic platforms, grabbables, forces, custom systems, a full playground example → [references/workflows.md](references/workflows.md)
39
+ - **Material tuning, system priority, `PhysicsSystem` config, scene JSON** → [references/tuning-and-config.md](references/tuning-and-config.md)
40
+
41
+ ## Troubleshooting
42
+
43
+ **Objects fall through the floor:**
44
+
45
+ - Ensure the floor entity has both `PhysicsShape` and `PhysicsBody` with `state: PhysicsState.Static`
46
+ - Verify the shape type and dimensions match the visual geometry
47
+ - If the `Auto` or `ConvexHull` is selected for the PhysicsShape of static objects, try to change into `TriMesh`
48
+ - Check that `physics: true` is set in `iwsdk.config.json` world features
49
+
50
+ **Objects don't move:**
51
+
52
+ - Confirm `state` is `PhysicsState.Dynamic` (not Static or Kinematic)
53
+ - Check `gravityFactor` is > 0
54
+ - Verify both `PhysicsShape` and `PhysicsBody` are added (both are required)
55
+
56
+ **Objects are too bouncy or slide too much:**
57
+
58
+ - Lower `restitution` to reduce bouncing (0 = no bounce)
59
+ - Increase `friction` to reduce sliding (0.8+ for grippy surfaces)
60
+
61
+ **Objects move too slowly or feel sluggish:**
62
+
63
+ - Reduce `linearDamping` (0 = no air resistance)
64
+ - Check `density` is not too high (high density = heavy = resists force)
65
+
66
+ **Poor frame rate with many physics objects:**
67
+
68
+ - Use simpler shape types (Sphere/Box instead of ConvexHull/TriMesh)
69
+ - Use `TriMesh` only for static objects
70
+ - Explicitly set shape types instead of `Auto` to avoid detection overhead
71
+ - Reduce the number of dynamic bodies; make non-essential objects static
72
+
73
+ **Grabbed object doesn't follow hand:**
74
+
75
+ - Ensure `grabbing: true` in features
76
+ - Verify the entity has `RayInteractable` and a grabbable component (`OneHandGrabbable`, `TwoHandsGrabbable`, or `DistanceGrabbable`)
77
+
78
+ **PhysicsManipulation has no effect:**
79
+
80
+ - The entity must have a `PhysicsBody` with an active engine body (`_engineBody != 0`)
81
+ - The component is auto-removed after one frame; re-add it for sustained effects
82
+ - Force values may need to be larger; they are scaled by frame delta time
83
+
84
+ ## Performance Tips
85
+
86
+ 1. **Use primitive shapes** (Sphere, Box, Cylinder) over ConvexHull/TriMesh whenever acceptable
87
+ 2. **Use `PhysicsState.Static`** for all non-moving objects; static bodies have zero simulation cost
88
+ 3. **Explicitly set shape types** in production; avoid `Auto` detection overhead
89
+ 4. **Minimize dynamic body count** -- each dynamic body requires per-frame transform sync
90
+ 5. **Use damping** to settle objects faster and reduce ongoing simulation work
91
+ 6. **TriMesh is for static only** -- it is computationally expensive and should never be used on dynamic bodies
92
+
@@ -0,0 +1,154 @@
1
+ ## PhysicsBody Component Reference
2
+
3
+ Defines the motion behavior of a physics entity. Import from `@iwsdk/core`.
4
+
5
+ ```typescript
6
+ import { PhysicsBody, PhysicsState } from '@iwsdk/core';
7
+
8
+ entity.addComponent(PhysicsBody, {
9
+ state: PhysicsState.Dynamic,
10
+ linearDamping: 0.0,
11
+ angularDamping: 0.0,
12
+ gravityFactor: 1.0,
13
+ centerOfMass: [Infinity, Infinity, Infinity], // Infinity = auto-compute from shape
14
+ });
15
+ ```
16
+
17
+ **Properties:**
18
+
19
+ | Property | Type | Default | Description |
20
+ | ---------------- | -------------- | -------------------------------- | ----------------------------------------------------- |
21
+ | `state` | `PhysicsState` | `Dynamic` | Motion type (see below) |
22
+ | `linearDamping` | `Float32` | `0.0` | Air resistance for translation (0 = none, 1 = heavy) |
23
+ | `angularDamping` | `Float32` | `0.0` | Air resistance for rotation |
24
+ | `gravityFactor` | `Float32` | `1.0` | Gravity multiplier (0 = floating, 2 = double gravity) |
25
+ | `centerOfMass` | `Vec3` | `[Infinity, Infinity, Infinity]` | Override center of mass; `Infinity` = auto-compute |
26
+
27
+ **Read-only properties** (updated each frame by `PhysicsSystem`):
28
+
29
+ | Property | Type | Description |
30
+ | ------------------ | ------ | ------------------------ |
31
+ | `_linearVelocity` | `Vec3` | Current linear velocity |
32
+ | `_angularVelocity` | `Vec3` | Current angular velocity |
33
+
34
+ ### PhysicsState Enum
35
+
36
+ ```typescript
37
+ PhysicsState.Static; // Immovable (walls, floors). Zero simulation cost.
38
+ PhysicsState.Dynamic; // Fully simulated. Responds to forces, gravity, collisions.
39
+ PhysicsState.Kinematic; // Programmatically moved. Pushes dynamic bodies but is not affected by them.
40
+ ```
41
+
42
+ **When to use each:**
43
+
44
+ - **Static** -- Environment geometry (walls, floors, tables). Objects that never move but block dynamic bodies.
45
+ - **Dynamic** -- Objects that respond to physics (balls, crates, interactive props). Default for most gameplay objects.
46
+ - **Kinematic** -- Moving platforms that won't be pushed by other physics bodies.
47
+
48
+ ## PhysicsShape Component Reference
49
+
50
+ Defines the collision geometry and material properties. Both `PhysicsShape` and `PhysicsBody` are required for physics simulation.
51
+
52
+ ```typescript
53
+ import { PhysicsShape, PhysicsShapeType } from '@iwsdk/core';
54
+
55
+ entity.addComponent(PhysicsShape, {
56
+ shape: PhysicsShapeType.Auto,
57
+ dimensions: [0, 0, 0],
58
+ density: 1.0,
59
+ restitution: 0.0,
60
+ friction: 0.5,
61
+ });
62
+ ```
63
+
64
+ **Properties:**
65
+
66
+ | Property | Type | Default | Description |
67
+ | ------------- | ------------------ | ----------- | ------------------------------------------------------------------------------------- |
68
+ | `shape` | `PhysicsShapeType` | `Auto` | Collision shape type |
69
+ | `dimensions` | `Vec3` | `[0, 0, 0]` | Shape-specific dimensions array. Not applicable when `PhysicsShapeType.Auto` is used. |
70
+ | `density` | `Float32` | `1.0` | Mass density (kg/m^3). Higher = heavier. |
71
+ | `restitution` | `Float32` | `0.0` | Bounciness (0 = no bounce, 1 = perfect bounce) |
72
+ | `friction` | `Float32` | `0.5` | Surface friction (0 = ice, 1 = rubber) |
73
+
74
+ ### PhysicsShapeType Enum
75
+
76
+ ```typescript
77
+ PhysicsShapeType.Sphere; // dimensions[0] = radius
78
+ PhysicsShapeType.Box; // dimensions = [width, height, depth]
79
+ PhysicsShapeType.Cylinder; // dimensions[0] = radius, dimensions[1] = height
80
+ PhysicsShapeType.Capsules; // dimensions[0] = radius, dimensions[1] = total height (>= 2 * radius)
81
+ PhysicsShapeType.ConvexHull; // Convex wrapper around mesh vertices (dimensions ignored)
82
+ PhysicsShapeType.TriMesh; // Exact mesh triangles (dimensions ignored). Expensive; use for static only.
83
+ PhysicsShapeType.Auto; // Auto-detect from Three.js geometry type
84
+ ```
85
+
86
+ ### Dimensions by Shape Type
87
+
88
+ The `dimensions` property is a `Vec3` (`[x, y, z]`) whose meaning changes depending on the selected shape:
89
+
90
+ | Shape Type | `dimensions[0]` | `dimensions[1]` | `dimensions[2]` | Example |
91
+ | ------------ | --------------- | --------------- | --------------- | ------------------------------- |
92
+ | `Sphere` | radius | _(unused)_ | _(unused)_ | `[0.5, 0, 0]` -- sphere r=0.5 |
93
+ | `Box` | width | height | depth | `[1, 2, 0.5]` -- 1×2×0.5 box |
94
+ | `Cylinder` | radius | height | _(unused)_ | `[0.3, 1.5, 0]` -- r=0.3, h=1.5 |
95
+ | `Capsules` | radius | total height | _(unused)_ | `[0.3, 1.5, 0]` -- r=0.3, h=1.5 |
96
+ | `ConvexHull` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Computed from mesh vertices |
97
+
98
+ Capsule total height is measured end to end and must be at least twice its
99
+ radius. A total height equal to the diameter produces a sphere-length capsule.
100
+ | `TriMesh` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Computed from mesh triangles |
101
+ | `Auto` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Auto-detected from geometry |
102
+
103
+ For `ConvexHull`, `TriMesh`, and `Auto`, the dimensions array is not used -- the shape is derived directly from the entity's Three.js geometry.
104
+
105
+ **Auto-detection mapping:**
106
+
107
+ | Three.js Geometry | Detected Shape | Dimensions Source |
108
+ | ------------------------------- | -------------- | ----------------------------------------------- |
109
+ | `SphereGeometry` | Sphere | `radius` from geometry parameters |
110
+ | `BoxGeometry` | Box | `width, height, depth` from parameters |
111
+ | `PlaneGeometry` | Box | `width, height, 0.01` (thin box) |
112
+ | `CylinderGeometry` | Cylinder | Average of `radiusTop`/`radiusBottom`, `height` |
113
+ | `BufferGeometry` (generic/GLTF) | ConvexHull | From mesh vertices |
114
+ | Unknown | Box (fallback) | From bounding box |
115
+
116
+ **Performance guidance:**
117
+
118
+ - Sphere/Box/Cylinder: Fastest collision detection. Prefer these when possible.
119
+ - ConvexHull: Good balance for complex meshes. Default for GLTF models via Auto.
120
+ - TriMesh: Exact geometry collision. Use only for static objects (walls, floors, terrain).
121
+
122
+ ## PhysicsManipulation Component Reference
123
+
124
+ A **one-shot** component for applying forces and velocities. Automatically removed after one frame.
125
+
126
+ ```typescript
127
+ import { PhysicsManipulation } from '@iwsdk/core';
128
+
129
+ // Apply an impulse (removed automatically after 1 frame)
130
+ entity.addComponent(PhysicsManipulation, {
131
+ force: [0, 10, 0], // Impulse force vector
132
+ linearVelocity: [0, 0, 0], // Override linear velocity (0 = no change)
133
+ angularVelocity: [0, 0, 0], // Override angular velocity (0 = no change)
134
+ });
135
+ ```
136
+
137
+ **Properties:**
138
+
139
+ | Property | Type | Default | Description |
140
+ | ----------------- | ------ | ----------- | --------------------------------------- |
141
+ | `force` | `Vec3` | `[0, 0, 0]` | Impulse force applied at center of mass |
142
+ | `linearVelocity` | `Vec3` | `[0, 0, 0]` | Sets absolute linear velocity |
143
+ | `angularVelocity` | `Vec3` | `[0, 0, 0]` | Sets absolute angular velocity |
144
+
145
+ **The component is auto-removed** by `PhysicsSystem` after applying values. For sustained forces, re-add each frame:
146
+
147
+ ```typescript
148
+ update() {
149
+ if (!entity.hasComponent(PhysicsManipulation)) {
150
+ entity.addComponent(PhysicsManipulation, { force: [0, 5, 0] });
151
+ }
152
+ }
153
+ ```
154
+