@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +79 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
@@ -0,0 +1,152 @@
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
+ **Properties:**
17
+
18
+ | Property | Type | Default | Description |
19
+ | ---------------- | -------------- | -------------------------------- | ----------------------------------------------------- |
20
+ | `state` | `PhysicsState` | `Dynamic` | Motion type (see below) |
21
+ | `linearDamping` | `Float32` | `0.0` | Air resistance for translation (0 = none, 1 = heavy) |
22
+ | `angularDamping` | `Float32` | `0.0` | Air resistance for rotation |
23
+ | `gravityFactor` | `Float32` | `1.0` | Gravity multiplier (0 = floating, 2 = double gravity) |
24
+ | `centerOfMass` | `Vec3` | `[Infinity, Infinity, Infinity]` | Override center of mass; `Infinity` = auto-compute |
25
+
26
+ **Read-only properties** (updated each frame by `PhysicsSystem`):
27
+
28
+ | Property | Type | Description |
29
+ | ------------------ | ------ | ------------------------ |
30
+ | `_linearVelocity` | `Vec3` | Current linear velocity |
31
+ | `_angularVelocity` | `Vec3` | Current angular velocity |
32
+
33
+ ### PhysicsState Enum
34
+
35
+ ```typescript
36
+ PhysicsState.Static; // Immovable (walls, floors). Zero simulation cost.
37
+ PhysicsState.Dynamic; // Fully simulated. Responds to forces, gravity, collisions.
38
+ PhysicsState.Kinematic; // Programmatically moved. Pushes dynamic bodies but is not affected by them.
39
+ ```
40
+
41
+ **When to use each:**
42
+
43
+ - **Static** -- Environment geometry (walls, floors, tables). Objects that never move but block dynamic bodies.
44
+ - **Dynamic** -- Objects that respond to physics (balls, crates, interactive props). Default for most gameplay objects.
45
+ - **Kinematic** -- Moving platforms that won't be pushed by other physics bodies.
46
+
47
+ ## PhysicsShape Component Reference
48
+
49
+ Defines the collision geometry and material properties. Both `PhysicsShape` and `PhysicsBody` are required for physics simulation.
50
+
51
+ ```typescript
52
+ import { PhysicsShape, PhysicsShapeType } from '@iwsdk/core';
53
+
54
+ entity.addComponent(PhysicsShape, {
55
+ shape: PhysicsShapeType.Auto,
56
+ dimensions: [0, 0, 0],
57
+ density: 1.0,
58
+ restitution: 0.0,
59
+ friction: 0.5,
60
+ });
61
+ ```
62
+
63
+ **Properties:**
64
+
65
+ | Property | Type | Default | Description |
66
+ | ------------- | ------------------ | ----------- | ------------------------------------------------------------------------------------- |
67
+ | `shape` | `PhysicsShapeType` | `Auto` | Collision shape type |
68
+ | `dimensions` | `Vec3` | `[0, 0, 0]` | Shape-specific dimensions array. Not applicable when `PhysicsShapeType.Auto` is used. |
69
+ | `density` | `Float32` | `1.0` | Mass density (kg/m^3). Higher = heavier. |
70
+ | `restitution` | `Float32` | `0.0` | Bounciness (0 = no bounce, 1 = perfect bounce) |
71
+ | `friction` | `Float32` | `0.5` | Surface friction (0 = ice, 1 = rubber) |
72
+
73
+ ### PhysicsShapeType Enum
74
+
75
+ ```typescript
76
+ PhysicsShapeType.Sphere; // dimensions[0] = radius
77
+ PhysicsShapeType.Box; // dimensions = [width, height, depth]
78
+ PhysicsShapeType.Cylinder; // dimensions[0] = radius, dimensions[1] = height
79
+ PhysicsShapeType.Capsules; // dimensions[0] = radius, dimensions[1] = total height (>= 2 * radius)
80
+ PhysicsShapeType.ConvexHull; // Convex wrapper around mesh vertices (dimensions ignored)
81
+ PhysicsShapeType.TriMesh; // Exact mesh triangles (dimensions ignored). Expensive; use for static only.
82
+ PhysicsShapeType.Auto; // Auto-detect from Three.js geometry type
83
+ ```
84
+
85
+ ### Dimensions by Shape Type
86
+
87
+ The `dimensions` property is a `Vec3` (`[x, y, z]`) whose meaning changes depending on the selected shape:
88
+
89
+ | Shape Type | `dimensions[0]` | `dimensions[1]` | `dimensions[2]` | Example |
90
+ | ------------ | --------------- | --------------- | --------------- | ------------------------------- |
91
+ | `Sphere` | radius | _(unused)_ | _(unused)_ | `[0.5, 0, 0]` -- sphere r=0.5 |
92
+ | `Box` | width | height | depth | `[1, 2, 0.5]` -- 1×2×0.5 box |
93
+ | `Cylinder` | radius | height | _(unused)_ | `[0.3, 1.5, 0]` -- r=0.3, h=1.5 |
94
+ | `Capsules` | radius | total height | _(unused)_ | `[0.3, 1.5, 0]` -- r=0.3, h=1.5 |
95
+ | `ConvexHull` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Computed from mesh vertices |
96
+
97
+ Capsule total height is measured end to end and must be at least twice its
98
+ radius. A total height equal to the diameter produces a sphere-length capsule.
99
+ | `TriMesh` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Computed from mesh triangles |
100
+ | `Auto` | _(ignored)_ | _(ignored)_ | _(ignored)_ | Auto-detected from geometry |
101
+
102
+ For `ConvexHull`, `TriMesh`, and `Auto`, the dimensions array is not used -- the shape is derived directly from the entity's Three.js geometry.
103
+
104
+ **Auto-detection mapping:**
105
+
106
+ | Three.js Geometry | Detected Shape | Dimensions Source |
107
+ | ------------------------------- | -------------- | ----------------------------------------------- |
108
+ | `SphereGeometry` | Sphere | `radius` from geometry parameters |
109
+ | `BoxGeometry` | Box | `width, height, depth` from parameters |
110
+ | `PlaneGeometry` | Box | `width, height, 0.01` (thin box) |
111
+ | `CylinderGeometry` | Cylinder | Average of `radiusTop`/`radiusBottom`, `height` |
112
+ | `BufferGeometry` (generic/GLTF) | ConvexHull | From mesh vertices |
113
+ | Unknown | Box (fallback) | From bounding box |
114
+
115
+ **Performance guidance:**
116
+
117
+ - Sphere/Box/Cylinder: Fastest collision detection. Prefer these when possible.
118
+ - ConvexHull: Good balance for complex meshes. Default for GLTF models via Auto.
119
+ - TriMesh: Exact geometry collision. Use only for static objects (walls, floors, terrain).
120
+
121
+ ## PhysicsManipulation Component Reference
122
+
123
+ A **one-shot** component for applying forces and velocities. Automatically removed after one frame.
124
+
125
+ ```typescript
126
+ import { PhysicsManipulation } from '@iwsdk/core';
127
+
128
+ // Apply an impulse (removed automatically after 1 frame)
129
+ entity.addComponent(PhysicsManipulation, {
130
+ force: [0, 10, 0], // Impulse force vector
131
+ linearVelocity: [0, 0, 0], // Override linear velocity (0 = no change)
132
+ angularVelocity: [0, 0, 0], // Override angular velocity (0 = no change)
133
+ });
134
+ ```
135
+
136
+ **Properties:**
137
+
138
+ | Property | Type | Default | Description |
139
+ | ----------------- | ------ | ----------- | --------------------------------------- |
140
+ | `force` | `Vec3` | `[0, 0, 0]` | Impulse force applied at center of mass |
141
+ | `linearVelocity` | `Vec3` | `[0, 0, 0]` | Sets absolute linear velocity |
142
+ | `angularVelocity` | `Vec3` | `[0, 0, 0]` | Sets absolute angular velocity |
143
+
144
+ **The component is auto-removed** by `PhysicsSystem` after applying values. For sustained forces, re-add each frame:
145
+
146
+ ```typescript
147
+ update() {
148
+ if (!entity.hasComponent(PhysicsManipulation)) {
149
+ entity.addComponent(PhysicsManipulation, { force: [0, 5, 0] });
150
+ }
151
+ }
152
+ ```
@@ -0,0 +1,101 @@
1
+ ## Material Tuning Guide
2
+
3
+ Adjust `density`, `restitution`, and `friction` on `PhysicsShape` to simulate different materials:
4
+
5
+ | Material | Density | Restitution | Friction |
6
+ | ----------- | ------- | ----------- | -------- |
7
+ | Wood | 0.6 | 0.3 | 0.5 |
8
+ | Metal/Steel | 7.8 | 0.2 | 0.4 |
9
+ | Rubber | 1.1 | 0.8 | 0.9 |
10
+ | Ice | 0.9 | 0.1 | 0.05 |
11
+ | Concrete | 2.4 | 0.1 | 0.7 |
12
+ | Foam/Light | 0.05 | 0.1 | 0.6 |
13
+ | Bouncy ball | 1.0 | 0.95 | 0.5 |
14
+
15
+ ## System Priority Order
16
+
17
+ Physics runs in a carefully orchestrated sequence:
18
+
19
+ ```
20
+ Priority -5: LocomotionSystem (Player movement)
21
+ Priority -4: InputSystem (Controller/hand input)
22
+ Priority -3: GrabSystem (Grab interactions)
23
+ Priority -2: PhysicsSystem (Physics simulation)
24
+ Priority -1: SceneUnderstanding (AR plane/mesh updates)
25
+ ```
26
+
27
+ Register custom physics-related systems after the built-in PhysicsSystem (priority > -2) to read updated transforms:
28
+
29
+ ```typescript
30
+ world.registerSystem(MyPhysicsLogicSystem, { priority: 5 });
31
+ ```
32
+
33
+ ## PhysicsSystem Configuration
34
+
35
+ The project manifest accepts execution, frequency, and interpolation options:
36
+
37
+ ```jsonc
38
+ "physics": {
39
+ "useWorker": true,
40
+ "updateFrequency": 60,
41
+ "interpolation": true
42
+ }
43
+ ```
44
+
45
+ - `useWorker` defaults to `true`. Set it to `false` to run the same runtime and message protocol on the main thread.
46
+ - `updateFrequency` defaults to 60 Hz and is capped at 240 Hz.
47
+ - `interpolation` defaults to `true` and smooths rendered transforms between fixed physics snapshots.
48
+
49
+ The system also accepts a reactive `gravity` config (defaults to Earth gravity):
50
+
51
+ ```typescript
52
+ import { PhysicsSystem } from '@iwsdk/core';
53
+
54
+ const physicsSystem = world.getSystem(PhysicsSystem);
55
+ physicsSystem.config.gravity.value = [0, -9.81, 0]; // Earth gravity (default)
56
+ physicsSystem.config.gravity.value = [0, -1.62, 0]; // Moon gravity
57
+ physicsSystem.config.gravity.value = [0, 0, 0]; // Zero gravity
58
+ ```
59
+
60
+ ## Native Scene JSON Configuration
61
+
62
+ Physics components can be configured declaratively in native scene JSON files:
63
+
64
+ ```json
65
+ {
66
+ "id": "dynamic-box",
67
+ "content": { "type": "asset", "asset": "box" },
68
+ "transform": { "position": [0, 1.5, -1] },
69
+ "components": {
70
+ "PhysicsShape": {
71
+ "shape": "Box",
72
+ "dimensions": [1, 1, 1],
73
+ "density": 1,
74
+ "friction": 0.5,
75
+ "restitution": 0
76
+ },
77
+ "PhysicsBody": {
78
+ "state": "DYNAMIC",
79
+ "gravityFactor": 1,
80
+ "linearDamping": 0,
81
+ "angularDamping": 0
82
+ }
83
+ }
84
+ }
85
+ ```
86
+
87
+ **State enum values in scene JSON:**
88
+
89
+ - `STATIC`
90
+ - `DYNAMIC`
91
+ - `KINEMATIC`
92
+
93
+ **Shape enum values in scene JSON:**
94
+
95
+ - `Sphere`
96
+ - `Box`
97
+ - `Cylinder`
98
+ - `Capsules`
99
+ - `ConvexHull`
100
+ - `TriMesh`
101
+ - `Auto`
@@ -0,0 +1,303 @@
1
+ ## Common Workflows
2
+
3
+ ### Creating a Dynamic Physics Object
4
+
5
+ ```typescript
6
+ import {
7
+ Mesh,
8
+ SphereGeometry,
9
+ MeshStandardMaterial,
10
+ Color,
11
+ FrontSide,
12
+ } from 'three';
13
+ import {
14
+ PhysicsShape,
15
+ PhysicsShapeType,
16
+ PhysicsBody,
17
+ PhysicsState,
18
+ PhysicsManipulation,
19
+ } from '@iwsdk/core';
20
+
21
+ // 1. Create Three.js mesh
22
+ const ball = new Mesh(
23
+ new SphereGeometry(0.2),
24
+ new MeshStandardMaterial({ color: new Color(0xff4444), side: FrontSide }),
25
+ );
26
+ ball.position.set(0, 2, -1);
27
+
28
+ // 2. Wrap as ECS entity
29
+ const entity = world.createTransformEntity(ball);
30
+
31
+ // 3. Add physics components
32
+ entity.addComponent(PhysicsShape, {
33
+ shape: PhysicsShapeType.Sphere,
34
+ dimensions: [0.2, 0, 0],
35
+ restitution: 0.6, // Bouncy
36
+ });
37
+ entity.addComponent(PhysicsBody, { state: PhysicsState.Dynamic });
38
+
39
+ // 4. Optional: apply initial impulse
40
+ entity.addComponent(PhysicsManipulation, { force: [5, 2, 0] });
41
+ ```
42
+
43
+ ### Creating a Static Environment Collider
44
+
45
+ For walls, floors, and fixed scenery that block dynamic objects but never move:
46
+
47
+ ```typescript
48
+ // Ground plane
49
+ const ground = new Mesh(
50
+ new BoxGeometry(10, 0.1, 10),
51
+ new MeshStandardMaterial({ color: 0x888888 }),
52
+ );
53
+ ground.position.set(0, -0.05, 0);
54
+
55
+ const groundEntity = world.createTransformEntity(ground);
56
+ groundEntity.addComponent(PhysicsShape, {
57
+ shape: PhysicsShapeType.Box,
58
+ dimensions: [10, 0.1, 10],
59
+ friction: 0.8,
60
+ });
61
+ groundEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
62
+ ```
63
+
64
+ For complex static geometry (GLTF environments), use `TriMesh` for exact collision:
65
+
66
+ ```typescript
67
+ envEntity.addComponent(PhysicsShape, { shape: PhysicsShapeType.TriMesh });
68
+ envEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
69
+ ```
70
+
71
+ ### Creating a Kinematic Moving Platform
72
+
73
+ Kinematic bodies are moved by code and push dynamic objects:
74
+
75
+ ```typescript
76
+ // Setup
77
+ const platform = new Mesh(
78
+ new BoxGeometry(3, 0.2, 3),
79
+ new MeshStandardMaterial({ color: 0x4488ff }),
80
+ );
81
+
82
+ const platformEntity = world.createTransformEntity(platform);
83
+ platformEntity.addComponent(PhysicsShape, {
84
+ shape: PhysicsShapeType.Box,
85
+ dimensions: [3, 0.2, 3],
86
+ });
87
+ platformEntity.addComponent(PhysicsBody, { state: PhysicsState.Kinematic });
88
+
89
+ // In a system's update loop, move it:
90
+ update(delta, time) {
91
+ for (const entity of this.queries.platforms.entities) {
92
+ entity.object3D.position.y = 1 + Math.sin(time) * 2;
93
+ }
94
+ }
95
+ ```
96
+
97
+ ### Resetting or Teleporting an Existing Body
98
+
99
+ Do not remove/re-add physics components or write only to the Object3D of a dynamic
100
+ body. Use the live physics system so Havok and the render transform update together:
101
+
102
+ ```typescript
103
+ import { PhysicsSystem } from '@iwsdk/core';
104
+
105
+ const physics = world.getSystem(PhysicsSystem);
106
+ physics.setBodyTransform(entity, {
107
+ position: homePosition,
108
+ quaternion: homeQuaternion,
109
+ });
110
+ ```
111
+
112
+ Velocity is cleared by default. Pass `{ resetVelocity: false }` only when a teleport
113
+ must preserve motion. `gravityFactor`, `linearDamping`, and `angularDamping` can be
114
+ changed reactively with `entity.setValue`; changing motion state or shape requires
115
+ deliberate body lifecycle handling.
116
+
117
+ ### Making an Object Grabbable with Physics
118
+
119
+ Combine grab components with physics for throwable objects:
120
+
121
+ ```typescript
122
+ import {
123
+ RayInteractable,
124
+ OneHandGrabbable,
125
+ DistanceGrabbable,
126
+ } from '@iwsdk/core';
127
+
128
+ // Physics components
129
+ entity.addComponent(PhysicsShape, { shape: PhysicsShapeType.Auto });
130
+ entity.addComponent(PhysicsBody, { state: PhysicsState.Dynamic });
131
+
132
+ // Grab components
133
+ entity.addComponent(RayInteractable);
134
+ entity.addComponent(OneHandGrabbable);
135
+
136
+ // Optional: allow grabbing from a distance
137
+ entity.addComponent(DistanceGrabbable, {
138
+ rotate: true,
139
+ translate: true,
140
+ });
141
+ ```
142
+
143
+ When grabbed, the `GrabSystem` drives the held body kinematically (via `HP_Body_SetTargetQTransform`), making the object follow the hand. On release, the object resumes dynamic simulation with natural velocity for realistic throwing. Note: near-field grabs do not add `Hovered`/`Pressed` tags — assert grab behavior with ECS snapshot/diff, not tag queries.
144
+
145
+ ### Reading Velocity for Game Logic
146
+
147
+ ```typescript
148
+ const velocity = entity.getVectorView(PhysicsBody, '_linearVelocity');
149
+ const speed = Math.sqrt(velocity[0] ** 2 + velocity[1] ** 2 + velocity[2] ** 2);
150
+
151
+ if (speed > 5.0) {
152
+ // High-speed impact logic
153
+ }
154
+ ```
155
+
156
+ ### Explosion Pattern (Radial Force)
157
+
158
+ Apply outward force to all nearby physics objects:
159
+
160
+ ```typescript
161
+ const explosionPos = bomb.object3D.position;
162
+ const radius = 5.0;
163
+ const force = 50.0;
164
+
165
+ for (const target of this.queries.physicsObjects.entities) {
166
+ const dist = target.object3D.position.distanceTo(explosionPos);
167
+ if (dist < radius && dist > 0) {
168
+ const direction = target.object3D.position
169
+ .clone()
170
+ .sub(explosionPos)
171
+ .normalize();
172
+ const strength = force * (1 - dist / radius);
173
+ target.addComponent(PhysicsManipulation, {
174
+ force: direction.multiplyScalar(strength).toArray(),
175
+ });
176
+ }
177
+ }
178
+ ```
179
+
180
+ ## Custom Physics System Pattern
181
+
182
+ Create domain-specific components that interact with the physics system:
183
+
184
+ ```typescript
185
+ import {
186
+ createComponent,
187
+ createSystem,
188
+ Types,
189
+ PhysicsBody,
190
+ PhysicsManipulation,
191
+ } from '@iwsdk/core';
192
+
193
+ // 1. Define custom component
194
+ export const Buoyancy = createComponent('Buoyancy', {
195
+ waterLevel: { type: Types.Float32, default: 0.0 },
196
+ buoyancyForce: { type: Types.Float32, default: 15.0 },
197
+ });
198
+
199
+ // 2. Create system that applies physics forces
200
+ export class BuoyancySystem extends createSystem({
201
+ floaters: { required: [Buoyancy, PhysicsBody] },
202
+ }) {
203
+ update(delta) {
204
+ for (const entity of this.queries.floaters.entities) {
205
+ const waterLevel = entity.getValue(Buoyancy, 'waterLevel');
206
+ const force = entity.getValue(Buoyancy, 'buoyancyForce');
207
+ const y = entity.object3D.position.y;
208
+
209
+ if (y < waterLevel) {
210
+ const submersion = Math.min(1, (waterLevel - y) / 0.5);
211
+ if (!entity.hasComponent(PhysicsManipulation)) {
212
+ entity.addComponent(PhysicsManipulation, {
213
+ force: [0, force * submersion * delta, 0],
214
+ });
215
+ }
216
+ }
217
+ }
218
+ }
219
+ }
220
+
221
+ // 3. Register with world
222
+ world.registerComponent(Buoyancy);
223
+ world.registerSystem(BuoyancySystem, { priority: 5 });
224
+ ```
225
+
226
+
227
+ ## Complete Example: Physics Playground
228
+
229
+ ```typescript
230
+ import {
231
+ World,
232
+ PhysicsShape,
233
+ PhysicsShapeType,
234
+ PhysicsBody,
235
+ PhysicsState,
236
+ PhysicsManipulation,
237
+ RayInteractable,
238
+ OneHandGrabbable,
239
+ } from '@iwsdk/core';
240
+ import projectOptions from 'virtual:iwsdk-project';
241
+ import {
242
+ Mesh,
243
+ BoxGeometry,
244
+ SphereGeometry,
245
+ MeshStandardMaterial,
246
+ Color,
247
+ FrontSide,
248
+ } from 'three';
249
+
250
+ World.create(
251
+ document.getElementById('scene-container'),
252
+ projectOptions,
253
+ ).then((world) => {
254
+ // Static floor
255
+ const floor = new Mesh(
256
+ new BoxGeometry(10, 0.1, 10),
257
+ new MeshStandardMaterial({ color: 0x555555 }),
258
+ );
259
+ floor.position.set(0, -0.05, 0);
260
+ const floorEntity = world.createTransformEntity(floor);
261
+ floorEntity.addComponent(PhysicsShape, {
262
+ shape: PhysicsShapeType.Box,
263
+ dimensions: [10, 0.1, 10],
264
+ friction: 0.8,
265
+ });
266
+ floorEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
267
+
268
+ // Dynamic bouncy ball (grabbable)
269
+ const ball = new Mesh(
270
+ new SphereGeometry(0.15),
271
+ new MeshStandardMaterial({ color: new Color(0xff4444), side: FrontSide }),
272
+ );
273
+ ball.position.set(0, 1.5, -1);
274
+ const ballEntity = world.createTransformEntity(ball);
275
+ ballEntity.addComponent(PhysicsShape, {
276
+ shape: PhysicsShapeType.Sphere,
277
+ dimensions: [0.15, 0, 0],
278
+ restitution: 0.8,
279
+ friction: 0.5,
280
+ });
281
+ ballEntity.addComponent(PhysicsBody, { state: PhysicsState.Dynamic });
282
+ ballEntity.addComponent(RayInteractable);
283
+ ballEntity.addComponent(OneHandGrabbable);
284
+
285
+ // Dynamic box with initial impulse
286
+ const box = new Mesh(
287
+ new BoxGeometry(0.3, 0.3, 0.3),
288
+ new MeshStandardMaterial({ color: new Color(0x4488ff), side: FrontSide }),
289
+ );
290
+ box.position.set(0.5, 2, -1);
291
+ const boxEntity = world.createTransformEntity(box);
292
+ boxEntity.addComponent(PhysicsShape, {
293
+ shape: PhysicsShapeType.Box,
294
+ dimensions: [0.3, 0.3, 0.3],
295
+ restitution: 0.3,
296
+ });
297
+ boxEntity.addComponent(PhysicsBody, {
298
+ state: PhysicsState.Dynamic,
299
+ linearDamping: 0.1,
300
+ });
301
+ boxEntity.addComponent(PhysicsManipulation, { force: [-3, 5, 0] });
302
+ });
303
+ ```