@ignifx/physics-2d 0.21.0 → 0.22.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/README.md +22 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +5 -5
- package/dist/index.js.map +1 -1
- package/package.json +5 -5
- package/skills/physics-2d/SKILL.md +29 -28
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/physics-2d",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.22.0",
|
|
4
4
|
"description": "ignifx 2D physics: Rigidbody2D, 2D colliders, CharacterController2D, queries.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ignifx",
|
|
@@ -45,12 +45,12 @@
|
|
|
45
45
|
"typedoc-plugin-markdown": "^4.13.0",
|
|
46
46
|
"typescript-native": "npm:typescript@7.0.2",
|
|
47
47
|
"vitest": "^5.0.0",
|
|
48
|
-
"@ignifx/2d": "0.
|
|
49
|
-
"@ignifx/core": "0.
|
|
48
|
+
"@ignifx/2d": "0.22.0",
|
|
49
|
+
"@ignifx/core": "0.22.0"
|
|
50
50
|
},
|
|
51
51
|
"peerDependencies": {
|
|
52
|
-
"@ignifx/2d": "0.
|
|
53
|
-
"@ignifx/core": "0.
|
|
52
|
+
"@ignifx/2d": "0.22.0",
|
|
53
|
+
"@ignifx/core": "0.22.0"
|
|
54
54
|
},
|
|
55
55
|
"peerDependenciesMeta": {
|
|
56
56
|
"@ignifx/2d": {
|
|
@@ -3,7 +3,7 @@ name: physics-2d
|
|
|
3
3
|
description: Adds 2D physics to an ignifx game with @ignifx/physics-2d: Rapier 2D simulation on the fixed loop, Rigidbody2D, box/circle/capsule/polygon/edge/tilemap colliders, physics materials, 2D triggers, CharacterController2D with slopes, autostep, snap-to-ground and one-way platforms, 2D raycasts and shape queries, the collision layer matrix, and render interpolation. Use when adding or editing 2D physics bodies, 2D colliders, platformer movement, 2D triggers, or 2D queries in an ignifx project, or when the user mentions @ignifx/physics-2d, Rigidbody2D, Rapier, or CharacterController2D.
|
|
4
4
|
license: Apache-2.0
|
|
5
5
|
metadata:
|
|
6
|
-
ignifx-version: "0.
|
|
6
|
+
ignifx-version: "0.22.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# @ignifx/physics-2d
|
|
@@ -11,12 +11,12 @@ metadata:
|
|
|
11
11
|
## What this is / when to use
|
|
12
12
|
|
|
13
13
|
`@ignifx/physics-2d` is the ignifx extension that simulates 2D rigid bodies with **Rapier 2D**
|
|
14
|
-
(`@dimforge/rapier2d-compat`, Apache-2.0
|
|
14
|
+
(`@dimforge/rapier2d-compat`, Apache-2.0). Add a 2D collider to make an entity solid, add
|
|
15
15
|
a `Rigidbody2D` to make it move, and read the result off `entity.transform.position2D` /
|
|
16
16
|
`rotation2D` like any other pose.
|
|
17
17
|
|
|
18
18
|
Units are **metres and seconds**, +Y is up, and `rotation2D` is degrees counter-clockwise about +Z.
|
|
19
|
-
Pixels-per-unit affects only rendering
|
|
19
|
+
Pixels-per-unit affects only rendering. The simulation is
|
|
20
20
|
stepped directly by ignifx's fixed loop — there is no Babylon Lite scene involved — so it advances
|
|
21
21
|
at a fixed rate whatever the frame rate does, and it runs headless with no GPU.
|
|
22
22
|
|
|
@@ -24,7 +24,7 @@ A world uses **either** `physics()` **or** `physics2d()`. Registering both throw
|
|
|
24
24
|
|
|
25
25
|
## Environment
|
|
26
26
|
|
|
27
|
-
- Engine: ignifx `0.
|
|
27
|
+
- Engine: ignifx `0.22.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
|
|
28
28
|
- Dependency: `@dimforge/rapier2d-compat` `^0.20.0`. The `-compat` build **inlines** its WebAssembly
|
|
29
29
|
as base64, so nothing has to be served and Node, the browser, and Electron all take the same path.
|
|
30
30
|
- `@ignifx/2d` is an **optional** peer: you need it only for `TilemapCollider2D`'s tilemap, so a
|
|
@@ -41,13 +41,13 @@ await app.start();
|
|
|
41
41
|
|
|
42
42
|
`ignifx.config.ts` carries the settings under `physics2d`:
|
|
43
43
|
|
|
44
|
-
| Setting
|
|
45
|
-
|
|
|
46
|
-
| `gravity`
|
|
47
|
-
| `collisionMatrix`
|
|
48
|
-
| `defaultMaterial`
|
|
49
|
-
| `velocityIterations` | `0`
|
|
50
|
-
| `interpolation`
|
|
44
|
+
| Setting | Default | Meaning |
|
|
45
|
+
| --- | --- | --- |
|
|
46
|
+
| `gravity` | `{x:0,y:-9.81}` | World gravity, m/s²; +Y is up |
|
|
47
|
+
| `collisionMatrix` | `{}` | `{ layerName: [layerNames] }`; an unlisted layer collides with all |
|
|
48
|
+
| `defaultMaterial` | friction `0.6` | The surface a collider with no material of its own uses |
|
|
49
|
+
| `velocityIterations` | `0` | Rapier solver iterations; `0` leaves Rapier's own default of 4 |
|
|
50
|
+
| `interpolation` | `true` | Whether dynamic bodies interpolate between fixed steps |
|
|
51
51
|
|
|
52
52
|
`fixedDeltaTime` is **not** here: the step comes from the core `time` section and `app.time`.
|
|
53
53
|
|
|
@@ -117,13 +117,13 @@ means "weigh the colliders at 1 kg/m²"), `gravityScale`, `linearDamping`, `angu
|
|
|
117
117
|
Colliders share `offset`, `isTrigger`, `material` (a `.physicsmaterial.json` asset), the
|
|
118
118
|
`inlineMaterial` fallback, `frictionCombine` / `restitutionCombine`, `oneWay`, and `layerOverride`:
|
|
119
119
|
|
|
120
|
-
| Collider
|
|
121
|
-
|
|
|
122
|
-
| `BoxCollider2D`
|
|
123
|
-
| `CircleCollider2D`
|
|
124
|
-
| `CapsuleCollider2D` | `radius`, `height` (tip to tip), `direction` (`"x" \| "y"`)
|
|
125
|
-
| `PolygonCollider2D` | `points` → the **convex hull** of the list
|
|
126
|
-
| `EdgeCollider2D`
|
|
120
|
+
| Collider | Geometry |
|
|
121
|
+
| --- | --- |
|
|
122
|
+
| `BoxCollider2D` | `size` — an axis-aligned rectangle |
|
|
123
|
+
| `CircleCollider2D` | `radius`; the larger scale axis wins |
|
|
124
|
+
| `CapsuleCollider2D` | `radius`, `height` (tip to tip), `direction` (`"x" \| "y"`) |
|
|
125
|
+
| `PolygonCollider2D` | `points` → the **convex hull** of the list |
|
|
126
|
+
| `EdgeCollider2D` | `points` → an open chain; infinitely thin |
|
|
127
127
|
| `TilemapCollider2D` | the `Tilemap` on the same entity, or assigned `collisionData` |
|
|
128
128
|
|
|
129
129
|
`CharacterController2D` — `shape` (`"capsule" | "box"`), `radius`, `height`, `offset`, `slopeLimit`
|
|
@@ -134,7 +134,7 @@ Colliders share `offset`, `isTrigger`, `material` (a `.physicsmaterial.json` ass
|
|
|
134
134
|
`app.physics2d` — `gravity`, `raycast`, `raycastAll`, `overlapCircle`, `overlapBox`, `shapeCast`,
|
|
135
135
|
`colliderOutlines(entity)` (Rapier's drawing of each collider as world-space XY segments, for an
|
|
136
136
|
editor's gizmos), and `rapier` (the unstable escape hatch). Full signatures:
|
|
137
|
-
`skills/ignifx/references/api/physics-2d.md
|
|
137
|
+
`skills/ignifx/references/api/physics-2d.md` in the `ignifx` package.
|
|
138
138
|
|
|
139
139
|
## Recipes
|
|
140
140
|
|
|
@@ -274,11 +274,11 @@ app.step(1 / 60);
|
|
|
274
274
|
## File formats
|
|
275
275
|
|
|
276
276
|
`ignifx.physicsmaterial` — the **same** `.physicsmaterial.json` document 3D physics reads
|
|
277
|
-
(`skills/ignifx/references/formats/ignifx.physicsmaterial.md`): `{ "format":
|
|
277
|
+
(`skills/ignifx/references/formats/ignifx.physicsmaterial.md` in the `ignifx` package): `{ "format":
|
|
278
278
|
"ignifx.physicsmaterial", "friction": 0.6, "restitution": 0 }`. `staticFriction` is ignored, because
|
|
279
279
|
Rapier 2D has one friction coefficient. The combine rules are collider fields, not asset fields.
|
|
280
280
|
|
|
281
|
-
Component field tables: `
|
|
281
|
+
Component field tables: `components.md` beside it.
|
|
282
282
|
|
|
283
283
|
## Gotchas
|
|
284
284
|
|
|
@@ -288,25 +288,25 @@ Component field tables: `skills/ignifx/references/formats/components.md`.
|
|
|
288
288
|
- **Queries need one completed step.** Rapier builds its broadphase inside `step`, so a query before
|
|
289
289
|
the first fixed step throws `IGX-1153`. Call `app.step(1 / 60)` once first.
|
|
290
290
|
- **Autostep needs a box.** `stepOffset` clears a 0.3 m step with `shape: "box"`; with the default
|
|
291
|
-
capsule of radius 0.2 it clears about 0.15 m and no more
|
|
291
|
+
capsule of radius 0.2 it clears about 0.15 m and no more. Give a
|
|
292
292
|
stair-climbing character `shape: "box"`.
|
|
293
293
|
- **A trigger is never an obstacle to a character controller.** `CharacterController2D` filters
|
|
294
294
|
sensors out of its collide-and-slide sweep, so it passes through an `isTrigger` collider without
|
|
295
295
|
slowing and the trigger callbacks fire on both entities. The flip side: a sensor never shows up in
|
|
296
296
|
`CharacterController2D.onCollided` — use `onTriggerEnter`/`onTriggerExit` for pickups and zones,
|
|
297
297
|
and `onCollided` only for the walls and floors the character actually pushed against. (Rapier's
|
|
298
|
-
controller counts sensors as walls unless `QueryFilterFlags.EXCLUDE_SENSORS` is passed
|
|
299
|
-
|
|
298
|
+
own controller counts sensors as walls unless `QueryFilterFlags.EXCLUDE_SENSORS` is passed, which
|
|
299
|
+
`CharacterController2D` does.)
|
|
300
300
|
- **One-way platforms are a character-controller feature.** `oneWay` changes what
|
|
301
301
|
`CharacterController2D` collides with; rigid bodies fall through such a collider in both
|
|
302
|
-
directions
|
|
302
|
+
directions.
|
|
303
303
|
- **`PolygonCollider2D` is convex.** Rapier builds the convex hull of the points, so a concave
|
|
304
304
|
outline is silently filled in. Use several polygons on one entity, or an `EdgeCollider2D`.
|
|
305
305
|
- **`EdgeCollider2D` is infinitely thin.** A fast body can tunnel through it and a body that starts
|
|
306
306
|
inside it is not pushed out. It is for static level geometry.
|
|
307
307
|
- **Determinism is same-machine only.** `@dimforge/rapier2d-compat` is Rapier's main build, which
|
|
308
308
|
promises local determinism, not cross-platform bit-exactness; the
|
|
309
|
-
`-deterministic-` builds are the ones that do
|
|
309
|
+
`-deterministic-` builds are the ones that do.
|
|
310
310
|
- **`angularVelocity` is degrees per second**, matching `Transform.rotation2D`, while Rapier's own
|
|
311
311
|
API is radians. The `rapier` escape hatch gives you radians.
|
|
312
312
|
- **Interpolated poses are display-only.** Read `transform.position` in `fixedUpdate` when you need
|
|
@@ -325,5 +325,6 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
|
|
|
325
325
|
|
|
326
326
|
## Where to look next
|
|
327
327
|
|
|
328
|
-
`skills/ignifx/SKILL.md`
|
|
329
|
-
|
|
328
|
+
The entry skill is `skills/ignifx/SKILL.md` in the `ignifx` package: `node_modules/ignifx/` in an
|
|
329
|
+
installed project, the repository root in the engine repository. Under it, `references/api/physics-2d.md` has every exact signature and `references/formats/` the
|
|
330
|
+
physics material and component field tables.
|