@ignifx/physics 0.0.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.
package/package.json ADDED
@@ -0,0 +1,74 @@
1
+ {
2
+ "name": "@ignifx/physics",
3
+ "version": "0.0.0",
4
+ "description": "ignifx 3D physics on Havok through Babylon Lite: rigidbodies, colliders, triggers, character controller, queries.",
5
+ "keywords": [
6
+ "ignifx",
7
+ "ignifx-extension"
8
+ ],
9
+ "homepage": "https://ignifx.com",
10
+ "license": "Apache-2.0",
11
+ "author": "Astrum Forge Studios",
12
+ "files": [
13
+ "dist",
14
+ "skills"
15
+ ],
16
+ "type": "module",
17
+ "sideEffects": false,
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ },
23
+ "./package.json": "./package.json"
24
+ },
25
+ "publishConfig": {
26
+ "access": "public",
27
+ "provenance": true
28
+ },
29
+ "scripts": {
30
+ "build": "tsdown",
31
+ "typecheck": "tsc --build tsconfig.json tsconfig.test.json",
32
+ "test": "vitest run --project node --root ../.. packages/physics",
33
+ "api-report": "api-extractor run --verbose",
34
+ "docs:api": "typedoc",
35
+ "api-report:update": "api-extractor run --local --verbose",
36
+ "pack-check": "publint && attw --pack . --profile esm-only"
37
+ },
38
+ "devDependencies": {
39
+ "@arethetypeswrong/cli": "catalog:",
40
+ "@babylonjs/havok": "catalog:",
41
+ "@babylonjs/lite": "catalog:",
42
+ "@ignifx/core": "workspace:*",
43
+ "@microsoft/api-extractor": "catalog:",
44
+ "@types/node": "catalog:",
45
+ "@types/webxr": "catalog:",
46
+ "@webgpu/types": "catalog:",
47
+ "publint": "catalog:",
48
+ "tsdown": "catalog:",
49
+ "typedoc": "catalog:",
50
+ "typedoc-plugin-markdown": "catalog:",
51
+ "typescript-native": "catalog:",
52
+ "vitest": "catalog:"
53
+ },
54
+ "peerDependencies": {
55
+ "@babylonjs/havok": "catalog:",
56
+ "@babylonjs/lite": "catalog:",
57
+ "@ignifx/core": "workspace:*"
58
+ },
59
+ "ignifx": {
60
+ "extension": true,
61
+ "engine": ">=0.0.0 <1.0.0",
62
+ "requires": [],
63
+ "optional": [
64
+ "@ignifx/devtools"
65
+ ],
66
+ "capabilities": [],
67
+ "skill": "./skills/physics/SKILL.md",
68
+ "assets": {
69
+ "public": [
70
+ "node_modules/@babylonjs/havok/lib/esm/HavokPhysics.wasm"
71
+ ]
72
+ }
73
+ }
74
+ }
@@ -0,0 +1,248 @@
1
+ ---
2
+ name: physics
3
+ description: Adds 3D physics to an ignifx game with @ignifx/physics: Havok simulation on a separate headless scene, Rigidbody, box/sphere/capsule/mesh colliders, physics materials, triggers, CharacterController, raycasts and shape queries, the collision layer matrix, and render interpolation. Use when adding or editing 3D physics bodies, colliders, triggers, character movement, or physics queries in an ignifx project, or when the user mentions @ignifx/physics, Rigidbody, Havok, or collision layers.
4
+ license: Apache-2.0
5
+ metadata:
6
+ ignifx-version: "0.0.0-unreleased"
7
+ ---
8
+
9
+ # @ignifx/physics
10
+
11
+ ## What this is / when to use
12
+
13
+ `@ignifx/physics` is the ignifx extension that simulates 3D rigid bodies with Havok, through Babylon
14
+ Lite. Add a collider to make an entity solid, add a `Rigidbody` to make it move, and read the result
15
+ off `entity.transform` like any other pose — the body and the renderer share one scene node.
16
+
17
+ The simulation runs on its **own** null-engine scene, stepped by ignifx's fixed loop, so it advances
18
+ at a fixed rate no matter what the frame rate does, it is deterministic on one platform and build,
19
+ and it runs headless with no GPU. Use it for anything that falls, collides, is pushed, is walked
20
+ through, or has to be asked "what is under the crosshair".
21
+
22
+ ## Environment
23
+
24
+ - Engine: ignifx `0.0.0-unreleased`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
25
+ - Peer dependencies: `@babylonjs/lite` (exactly `1.27.0`) and `@babylonjs/havok` (`^1.3.0`).
26
+ - Browsers, Electron, and Node. The Vite plugin copies `HavokPhysics.wasm` into the public asset
27
+ path, so the browser loads it from `assets/HavokPhysics.wasm`; under Node the extension reads the
28
+ binary out of the installed `@babylonjs/havok` package, so a headless test needs no setup.
29
+ - Register it like any extension; nothing happens at import time.
30
+
31
+ ```ts
32
+ import { createApp, physics } from "ignifx";
33
+
34
+ const app = await createApp({ headless: true, extensions: [physics()] });
35
+ await app.start();
36
+ ```
37
+
38
+ `ignifx.config.ts` carries the settings under `physics`:
39
+
40
+ | Setting | Default | Meaning |
41
+ | ----------------- | ---------------------- | ------------------------------------------------------------------ |
42
+ | `gravity` | `{x:0,y:-9.81,z:0}` | World gravity, m/s² |
43
+ | `collisionMatrix` | `{}` | `{ layerName: [layerNames] }`; an unlisted layer collides with all |
44
+ | `defaultMaterial` | friction `0.6` | The surface a collider with no material of its own uses |
45
+ | `velocityLimits` | `{linear:0,angular:0}` | World speed clamps; `0` leaves Havok's own defaults |
46
+ | `interpolation` | `true` | Whether dynamic bodies interpolate between fixed steps |
47
+ | `havokWasm` | `"auto"` | `"auto"` resolves through the asset manifest, or give a URL |
48
+
49
+ `fixedDeltaTime` is **not** here: the step comes from the core `time` section and `app.time`.
50
+
51
+ ## Mental model
52
+
53
+ ```
54
+ app.physics (PhysicsService) gravity · raycast · shapeCast · overlap · debugViewer · lite
55
+ │
56
+ ├─ Rigidbody dynamic | kinematic | static, one per entity
57
+ ├─ Box/Sphere/Capsule/Cylinder/Mesh/HeightfieldCollider several per entity form one compound
58
+ └─ CharacterController kinematic capsule, collide-and-slide
59
+
60
+ per fixed step:
61
+ Systems(FixedUpdate, -100) restore the authoritative pose of interpolated bodies
62
+ scripts.fixedUpdate(dt) forces, velocities, controller.move()
63
+ Systems(FixedUpdate, 100) step Havok · snapshot poses · dispatch collision and trigger events
64
+ Systems(PreRender, -500) write lerp(previous, current, time.fixedStepAlpha)
65
+ ```
66
+
67
+ - Colliders and bodies are (re)built at the **start of the next fixed step**, never mid-frame, so
68
+ body creation order — and therefore Havok's internal order — follows entity creation order.
69
+ - An entity with colliders and no `Rigidbody` gets an implicit **static** body placed once. Moving
70
+ it afterwards logs `IGX-0901`; anything that moves needs a kinematic `Rigidbody`.
71
+ - A body's entity must be a **root** entity: Havok writes the node's local pose, so a parented body
72
+ would be simulated in its parent's space (`IGX-0907`).
73
+
74
+ ## First app
75
+
76
+ ```ts
77
+ import { BoxCollider, createApp, physics, Rigidbody } from "ignifx";
78
+
79
+ const app = await createApp({ headless: true, extensions: [physics()] });
80
+ await app.start();
81
+
82
+ const floor = app.world.createEntity("Floor");
83
+ floor.addComponent(BoxCollider, { size: { x: 20, y: 1, z: 20 } });
84
+
85
+ const crate = app.world.createEntity("Crate");
86
+ crate.transform.position = { x: 0, y: 5, z: 0 };
87
+ crate.addComponent(BoxCollider, { size: { x: 1, y: 1, z: 1 } });
88
+ crate.addComponent(Rigidbody, { mass: 2 });
89
+
90
+ for (let step = 0; step < 60; step += 1) {
91
+ app.step(1 / 60);
92
+ }
93
+ app.log.info("crate at y={y}", crate.transform.position.y);
94
+ ```
95
+
96
+ ## Core APIs
97
+
98
+ ### `app.physics`
99
+
100
+ | Member | What it does |
101
+ | ----------------------------------------------------------- | --------------------------------------------------------------- |
102
+ | `gravity` | World gravity; assigning it takes effect on the next step |
103
+ | `raycast(origin, direction, maxDistance?, options?)` | First entity along a ray, with point, normal, and distance |
104
+ | `shapeCast(shape, from, to, options?)` | Sweeps a sphere/box/capsule and reports the first contact |
105
+ | `overlap(shape, position, rotation?, options?)` | Entities whose world bounds the shape touches (array is reused) |
106
+ | `distanceToNearest(shape, position, maxDistance, options?)` | Distance to the closest body, or `Infinity` |
107
+ | `debugViewer.enabled` | Lite's wireframe overlay on the render scene (needs a GPU) |
108
+ | `lite` | Unstable escape hatch: the Havok world and the simulation scene |
109
+
110
+ Every query needs at least one completed fixed step — Havok builds its broadphase there — and
111
+ reports `IGX-0902` before that.
112
+
113
+ ### `Rigidbody`
114
+
115
+ | Field / member | Default | Meaning |
116
+ | ----------------------------------------------- | --------------- | --------------------------------------------------- |
117
+ | `bodyType` | `"dynamic"` | `"dynamic"`, `"kinematic"`, or `"static"` |
118
+ | `mass` | `1` | Kilograms; dynamic bodies only |
119
+ | `startAsleep` | `false` | Whether Havok starts it asleep |
120
+ | `freezeRotation` | all `false` | Locks rotation about X, Y, or Z |
121
+ | `interpolation` | `"interpolate"` | `"none"` pins the display pose to the last step |
122
+ | `collisionEvents` | `"auto"` | `"auto"` follows the scripts on the entity |
123
+ | `kinematicSync` | `"teleport"` | `"velocity"` drags resting bodies along instead |
124
+ | `linearVelocity` / `angularVelocity` | — | Read and write; `…ToRef` variants allocate nothing |
125
+ | `addForce(f, point?)` / `addImpulse(i, point?)` | — | Call from `fixedUpdate` |
126
+ | `teleport(position, rotation?)` | — | Moves without integrating, and resets interpolation |
127
+
128
+ ### Colliders
129
+
130
+ `BoxCollider { size }` · `SphereCollider { radius }` · `CapsuleCollider { radius, height, direction }`
131
+ · `CylinderCollider { radius, height }` · `MeshCollider { mesh, convex, includeChildren }` ·
132
+ `HeightfieldCollider { heights, samplesX, samplesZ, size }`.
133
+
134
+ All of them share `center`, `isTrigger`, `material` (a `.physicsmaterial.json` asset),
135
+ `inlineMaterial`, and `layerOverride`. Sizes are authored in local units and multiplied by the
136
+ entity's lossy scale when the shape is built; changing the scale afterwards needs
137
+ `collider.rebuild()`.
138
+
139
+ ### `CharacterController`
140
+
141
+ `move(displacement)` from `fixedUpdate` (displacements accumulate), then read `isGrounded`,
142
+ `supportState`, `groundNormal`, and `velocity`. `setHeight(h, preserveFeet?)` crouches,
143
+ `teleport(position)` relocates, and `onCollided` reports every dynamic body the capsule pushed.
144
+ Gravity is **not** applied for you — a bare controller is purely kinematic.
145
+
146
+ ## Recipes
147
+
148
+ ### A trigger volume
149
+
150
+ ```ts
151
+ import { BoxCollider, createApp, physics, Rigidbody, Script } from "ignifx";
152
+ import type { ScriptCallbacks, TriggerEvent } from "ignifx";
153
+
154
+ class Pickup extends Script implements ScriptCallbacks {
155
+ static typeId = "mygame/Pickup";
156
+
157
+ onTriggerEnter(trigger: unknown): void {
158
+ const event = trigger as TriggerEvent;
159
+ this.app.log.info("{name} entered the zone", event.other?.name ?? "something");
160
+ }
161
+ }
162
+
163
+ const app = await createApp({ headless: true, extensions: [physics()] });
164
+ app.registerComponents([Pickup]);
165
+ await app.start();
166
+
167
+ const zone = app.world.createEntity("Zone");
168
+ zone.transform.position = { x: 0, y: 2, z: 0 };
169
+ zone.addComponent(BoxCollider, { size: { x: 4, y: 1, z: 4 }, isTrigger: true });
170
+ zone.addComponent(Pickup);
171
+
172
+ const ball = app.world.createEntity("Ball");
173
+ ball.transform.position = { x: 0, y: 6, z: 0 };
174
+ ball.addComponent(BoxCollider);
175
+ ball.addComponent(Rigidbody);
176
+
177
+ for (let step = 0; step < 120; step += 1) {
178
+ app.step(1 / 60);
179
+ }
180
+ ```
181
+
182
+ ### A raycast under the crosshair
183
+
184
+ ```ts
185
+ import { BoxCollider, createApp, LayerMask, physics } from "ignifx";
186
+
187
+ const app = await createApp({ headless: true, extensions: [physics()] });
188
+ await app.start();
189
+ app.world.createEntity("Ground").addComponent(BoxCollider, { size: { x: 20, y: 1, z: 20 } });
190
+ app.step(1 / 60);
191
+
192
+ const hit = app.physics.raycast({ x: 0, y: 10, z: 0 }, { x: 0, y: -1, z: 0 }, 20, {
193
+ layerMask: LayerMask.everything(),
194
+ });
195
+ if (hit !== null) {
196
+ app.log.info("hit {name} at y={y}", hit.entity.name, hit.point.y);
197
+ }
198
+ ```
199
+
200
+ ### Layers that ignore each other
201
+
202
+ ```ts
203
+ // ignifx.config.ts
204
+ export default {
205
+ layers: ["Default", "Ground", "Ghost"],
206
+ physics: { collisionMatrix: { Ghost: ["Ghost"] } },
207
+ };
208
+ ```
209
+
210
+ A layer that appears as a key collides only with the layers it lists; a layer that appears nowhere
211
+ collides with everything. Havok tests a pair in both directions, so one side refusing is enough.
212
+ `entity.layer` changes take effect on the next fixed step.
213
+
214
+ ## File formats
215
+
216
+ - `*.physicsmaterial.json` — `ignifx.physicsmaterial`: `friction`, `staticFriction`, `restitution`.
217
+ See `skills/ignifx/references/formats/ignifx.physicsmaterial.md`.
218
+ - Component fields as they appear in a scene file: `skills/ignifx/references/formats/components.md`.
219
+
220
+ ## Gotchas
221
+
222
+ - **Queries before the first step return `IGX-0902`.** Step once after building the scene.
223
+ - **`MeshCollider` needs a GPU app.** Babylon Lite cannot build mesh or convex-hull shapes on the
224
+ null engine and a headless `MeshAsset` uploads no geometry, so a headless mesh collider reports
225
+ `IGX-0906`. Use a primitive collider in headless tests.
226
+ - **`collision.other` is `null` by default.** `@babylonjs/lite@1.27.0` reports collisions without
227
+ body identities. Trigger events _do_ carry both entities, so they are the documented mechanism for
228
+ gameplay reactions; `physics({ collisionIdentities: "internal" })` opts into the ADR-0013 waiver
229
+ that recovers the identities.
230
+ - **Event objects are pooled.** `TriggerEvent` and `Collision` (and its `contacts`) are reused for
231
+ every event of a step: copy anything you keep past the callback.
232
+ - **`overlap` returns a reused array**, and it is bounds-accurate rather than shape-accurate,
233
+ because Lite's `shapeProximity` reports neither a body identity nor more than one hit.
234
+ - **A body's entity must be a root entity** (`IGX-0907`), and a moving collider needs a
235
+ `Rigidbody` (`IGX-0901`).
236
+ - **Interpolated poses are display-only.** Read `transform.position` in `fixedUpdate` when you need
237
+ the authoritative pose; `update` and `PreRender` see the interpolated one.
238
+ - **A resting body sleeps.** Changing `app.physics.gravity` does not wake it; apply an impulse.
239
+
240
+ ## Deprecated (current window)
241
+
242
+ None (pre-1.0: no deprecation window; breaking changes are listed in the changelog).
243
+
244
+ ## Where to look next
245
+
246
+ `skills/ignifx/SKILL.md` for the engine entry skill · `skills/ignifx/references/api/physics.md` for
247
+ the generated API · `docs/architecture/09-physics.md` and ADR-0003 / ADR-0013 for the design
248
+ rationale.