@iwsdk/create 0.4.1 → 0.5.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 (107) 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 +23 -17
  106. package/scripts/verify-release-ready.mjs +76 -0
  107. package/LICENSE +0 -21
@@ -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
+
@@ -0,0 +1,88 @@
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 system accepts a `gravity` config (defaults to Earth gravity):
36
+
37
+ ```typescript
38
+ import { PhysicsSystem } from '@iwsdk/core';
39
+
40
+ const physicsSystem = world.getSystem(PhysicsSystem);
41
+ physicsSystem.config.gravity.value = [0, -9.81, 0]; // Earth gravity (default)
42
+ physicsSystem.config.gravity.value = [0, -1.62, 0]; // Moon gravity
43
+ physicsSystem.config.gravity.value = [0, 0, 0]; // Zero gravity
44
+ ```
45
+
46
+ ## Native Scene JSON Configuration
47
+
48
+ Physics components can be configured declaratively in native scene JSON files:
49
+
50
+ ```json
51
+ {
52
+ "id": "dynamic-box",
53
+ "content": { "type": "asset", "asset": "box" },
54
+ "transform": { "position": [0, 1.5, -1] },
55
+ "components": {
56
+ "PhysicsShape": {
57
+ "shape": "Box",
58
+ "dimensions": [1, 1, 1],
59
+ "density": 1,
60
+ "friction": 0.5,
61
+ "restitution": 0
62
+ },
63
+ "PhysicsBody": {
64
+ "state": "DYNAMIC",
65
+ "gravityFactor": 1,
66
+ "linearDamping": 0,
67
+ "angularDamping": 0
68
+ }
69
+ }
70
+ }
71
+ ```
72
+
73
+ **State enum values in scene JSON:**
74
+
75
+ - `STATIC`
76
+ - `DYNAMIC`
77
+ - `KINEMATIC`
78
+
79
+ **Shape enum values in scene JSON:**
80
+
81
+ - `Sphere`
82
+ - `Box`
83
+ - `Cylinder`
84
+ - `Capsules`
85
+ - `ConvexHull`
86
+ - `TriMesh`
87
+ - `Auto`
88
+
@@ -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
+ ```