@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/dist/index.d.ts +1770 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +4493 -0
- package/dist/index.js.map +1 -0
- package/package.json +74 -0
- package/skills/physics/SKILL.md +248 -0
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.
|