@gg-web-engine/matter 0.0.70 → 0.0.71

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 (7) hide show
  1. package/dist/components/matter-rigid-body.component.js +5 -0
  2. package/dist/matter-factory.d.ts +13 -0
  3. package/dist/matter-factory.js +37 -1
  4. package/package.json +3 -3
  5. package/test/components/matter-rigid-body-collision.spec.ts +9 -9
  6. package/test/components/matter-trigger.component.spec.ts +5 -5
  7. package/test/components/matter-world.component.spec.ts +14 -14
package/dist/components/matter-rigid-body.component.js CHANGED
@@ -39,6 +39,11 @@ export class MatterRigidBodyComponent {
39
39
  this.shape = shape;
40
40
  this.name = '';
41
41
  this.entity = null;
42
+ // matter-js has no native kinematic body - a body requested as `kinematic_pos`/`kinematic_vel`
43
+ // is physically an ordinary `isStatic: true` body under the hood (see `MatterFactory
44
+ // .transformOptions`'s own doc), so the debug view reports what it actually *is* (`RIGID_STATIC`)
45
+ // rather than what an app originally asked for - the console warning at creation time is what
46
+ // tells a developer their kinematic request wasn't honored, not this view.
42
47
  this.debugBodySettings = new DebugBody2DSettings(isFinite(this.nativeBody.mass)
43
48
  ? { type: 'RIGID_DYNAMIC', sleeping: () => this.nativeBody.isSleeping }
44
49
  : { type: 'RIGID_STATIC' }, this.shape);
package/dist/matter-factory.d.ts CHANGED
@@ -14,5 +14,18 @@ export declare class MatterFactory implements IPhysicsBody2dComponentFactory<Mat
14
14
  position?: Point2;
15
15
  rotation?: number;
16
16
  }): MatterTriggerComponent;
17
+ /**
18
+ * matter-js's own body model only has `isStatic` - no distinct kinematic body type (position-
19
+ * driven, but still pushes/wakes dynamic bodies it moves into) and no continuous collision
20
+ * detection at all, at any level. Both are long-standing, documented upstream limitations, not
21
+ * something this adapter package failed to wire up - see `BodyOptions.kinematic_pos`/
22
+ * `ccd`'s own doc in `packages/core` for what each is supposed to do.
23
+ *
24
+ * `kinematic_pos`/`kinematic_vel` fall back to `isStatic: true` - the closest matter-js has - so
25
+ * a caller gets *a* body rather than a thrown error, but with the exact same caveat as
26
+ * teleporting a `static` body's position by hand (see that doc): resting bodies on top won't be
27
+ * pushed or woken correctly. `ccd: true` is silently accepted as a no-op beyond the warning below -
28
+ * a fast-moving or fast-driven body can still tunnel clean through thin geometry in one step.
29
+ */
17
30
  private transformOptions;
18
31
  }
package/dist/matter-factory.js CHANGED
@@ -1,6 +1,19 @@
1
+ import { warnOnce, } from '@gg-web-engine/core';
1
2
  import { MatterRigidBodyComponent } from './components/matter-rigid-body.component';
2
3
  import { MatterTriggerComponent } from './components/matter-trigger.component';
3
4
  import { Bodies, Vector } from 'matter-js';
5
+ /**
6
+ * `kinematic_pos`/`kinematic_vel`/`ccd` have no native matter-js equivalent at all - unlike
7
+ * `packages/ammo`/`packages/rapier2d`/`packages/rapier3d`, this package can only warn and fall
8
+ * back rather than actually implement either (see `transformOptions`'s own doc). Warned once per
9
+ * distinct message (via core's `warnOnce`) rather than once per body/tick - an app that spawns many
10
+ * kinematic props (or requests `ccd` on many fast-moving bodies) would otherwise flood the console
11
+ * with an identical warning on every single one, which teaches a developer to ignore the console
12
+ * rather than to fix the one call site that needs it.
13
+ */
14
+ function warnUnsupportedOnce(message) {
15
+ warnOnce(`[@gg-web-engine/matter] ${message}`);
16
+ }
4
17
  export class MatterFactory {
5
18
  constructor(world) {
6
19
  this.world = world;
@@ -45,9 +58,32 @@ export class MatterFactory {
45
58
  }
46
59
  return new MatterTriggerComponent(nativeBody, descriptor, this.world);
47
60
  }
61
+ /**
62
+ * matter-js's own body model only has `isStatic` - no distinct kinematic body type (position-
63
+ * driven, but still pushes/wakes dynamic bodies it moves into) and no continuous collision
64
+ * detection at all, at any level. Both are long-standing, documented upstream limitations, not
65
+ * something this adapter package failed to wire up - see `BodyOptions.kinematic_pos`/
66
+ * `ccd`'s own doc in `packages/core` for what each is supposed to do.
67
+ *
68
+ * `kinematic_pos`/`kinematic_vel` fall back to `isStatic: true` - the closest matter-js has - so
69
+ * a caller gets *a* body rather than a thrown error, but with the exact same caveat as
70
+ * teleporting a `static` body's position by hand (see that doc): resting bodies on top won't be
71
+ * pushed or woken correctly. `ccd: true` is silently accepted as a no-op beyond the warning below -
72
+ * a fast-moving or fast-driven body can still tunnel clean through thin geometry in one step.
73
+ */
48
74
  transformOptions(options) {
75
+ if (options.bodyType === 'kinematic_pos' || options.bodyType === 'kinematic_vel') {
76
+ warnUnsupportedOnce(`bodyType: '${options.bodyType}' has no matter-js equivalent - falling back to a plain static ` +
77
+ "body. Resting bodies won't be pushed or woken when you move it, the same as manually " +
78
+ "teleporting a static body's position. See Body2DOptions.kinematic_pos/kinematic_vel's doc.");
79
+ }
80
+ if (options.ccd) {
81
+ warnUnsupportedOnce('ccd: true has no matter-js equivalent (no continuous collision detection at all) - ignored. ' +
82
+ 'A fast-moving or fast-driven body can still tunnel through thin geometry. See ' +
83
+ "Body2DOptions.ccd's doc.");
84
+ }
49
85
  const res = {
50
- isStatic: options.dynamic !== undefined ? !options.dynamic : !options.mass,
86
+ isStatic: options.bodyType !== undefined ? options.bodyType != 'dynamic' : !options.mass,
51
87
  mass: options.mass,
52
88
  restitution: options.restitution,
53
89
  friction: options.friction,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gg-web-engine/matter",
3
- "version": "0.0.70",
3
+ "version": "0.0.71",
4
4
  "description": "An attempt to create open source game engine for browser",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -30,7 +30,7 @@
30
30
  },
31
31
  "devDependencies": {
32
32
  "@types/matter-js": "0.20.2",
33
- "@gg-web-engine/core": "0.0.70",
33
+ "@gg-web-engine/core": "0.0.71",
34
34
  "@types/jest": "^30.0.0",
35
35
  "@types/node": "^26.4.0",
36
36
  "jest": "^30.5.0",
@@ -42,7 +42,7 @@
42
42
  "typescript": "~6.0.3"
43
43
  },
44
44
  "peerDependencies": {
45
- "@gg-web-engine/core": "0.0.70",
45
+ "@gg-web-engine/core": "0.0.71",
46
46
  "matter-js": "0.20.0",
47
47
  "rxjs": "7.8.2"
48
48
  },
package/test/components/matter-rigid-body-collision.spec.ts CHANGED
@@ -22,13 +22,13 @@ describe('MatterRigidBodyComponent collision events', () => {
22
22
  it('should fire onCollisionStart reciprocally, with a sane position/normal, when a falling body lands on a floor', () => {
23
23
  // static floor, top edge sits at y = -5
24
24
  const floor = factory.createRigidBody(
25
- { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
25
+ { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
26
26
  { position: { x: 0, y: 0 } },
27
27
  );
28
28
  floor.addToWorld({ physicsWorld: world } as any);
29
29
 
30
30
  const ball = factory.createRigidBody(
31
- { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
31
+ { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
32
32
  { position: { x: 0, y: -20 } },
33
33
  );
34
34
  ball.addToWorld({ physicsWorld: world } as any);
@@ -67,13 +67,13 @@ describe('MatterRigidBodyComponent collision events', () => {
67
67
 
68
68
  it('should not keep re-firing onCollisionStart while a body rests stably on another', () => {
69
69
  const floor = factory.createRigidBody(
70
- { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
70
+ { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
71
71
  { position: { x: 0, y: 0 } },
72
72
  );
73
73
  floor.addToWorld({ physicsWorld: world } as any);
74
74
 
75
75
  const ball = factory.createRigidBody(
76
- { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
76
+ { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
77
77
  { position: { x: 0, y: -20 } },
78
78
  );
79
79
  ball.addToWorld({ physicsWorld: world } as any);
@@ -101,13 +101,13 @@ describe('MatterRigidBodyComponent collision events', () => {
101
101
 
102
102
  it('should fire onCollisionEnd when a body is knocked away and separates', () => {
103
103
  const floor = factory.createRigidBody(
104
- { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
104
+ { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
105
105
  { position: { x: 0, y: 0 } },
106
106
  );
107
107
  floor.addToWorld({ physicsWorld: world } as any);
108
108
 
109
109
  const ball = factory.createRigidBody(
110
- { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
110
+ { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
111
111
  { position: { x: 0, y: -20 } },
112
112
  );
113
113
  ball.addToWorld({ physicsWorld: world } as any);
@@ -131,13 +131,13 @@ describe('MatterRigidBodyComponent collision events', () => {
131
131
 
132
132
  it('should emit onCollisionEnd(null) on the remaining body when the other body is removed from the world while still touching', () => {
133
133
  const floor = factory.createRigidBody(
134
- { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { dynamic: false, mass: 0 } },
134
+ { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
135
135
  { position: { x: 0, y: 0 } },
136
136
  );
137
137
  floor.addToWorld({ physicsWorld: world } as any);
138
138
 
139
139
  const ball = factory.createRigidBody(
140
- { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
140
+ { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
141
141
  { position: { x: 0, y: -20 } },
142
142
  );
143
143
  ball.addToWorld({ physicsWorld: world } as any);
@@ -165,7 +165,7 @@ describe('MatterRigidBodyComponent collision events', () => {
165
165
  trigger.addToWorld({ physicsWorld: world } as any);
166
166
 
167
167
  const ball = factory.createRigidBody(
168
- { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
168
+ { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
169
169
  { position: { x: 0, y: -20 } },
170
170
  );
171
171
  ball.addToWorld({ physicsWorld: world } as any);
package/test/components/matter-trigger.component.spec.ts CHANGED
@@ -28,7 +28,7 @@ describe(`MatterTriggerComponent`, () => {
28
28
  trigger.addToWorld({ physicsWorld: world } as any);
29
29
  const circle = factory.createRigidBody({
30
30
  shape: { shape: 'CIRCLE', radius: 1 },
31
- body: { dynamic: true, mass: 1 },
31
+ body: { bodyType: 'dynamic', mass: 1 },
32
32
  }, { position: { x: 0, y: 12 } });
33
33
  circle.addToWorld({ physicsWorld: world } as any);
34
34
  circle.linearVelocity = { x: 0, y: -10 };
@@ -57,7 +57,7 @@ describe(`MatterTriggerComponent`, () => {
57
57
  trigger.addToWorld({ physicsWorld: world } as any);
58
58
  const circle = factory.createRigidBody({
59
59
  shape: { shape: 'CIRCLE', radius: 1 },
60
- body: { dynamic: true, mass: 1 },
60
+ body: { bodyType: 'dynamic', mass: 1 },
61
61
  }, { position: { x: 0, y: 12 } });
62
62
  circle.addToWorld({ physicsWorld: world } as any);
63
63
  circle.linearVelocity = { x: 0, y: -10 };
@@ -79,7 +79,7 @@ describe(`MatterTriggerComponent`, () => {
79
79
  trigger.addToWorld({ physicsWorld: world } as any);
80
80
  const circle = factory.createRigidBody({
81
81
  shape: { shape: 'CIRCLE', radius: 1 },
82
- body: { dynamic: true, mass: 1 },
82
+ body: { bodyType: 'dynamic', mass: 1 },
83
83
  }, { position: Pnt2.O });
84
84
  circle.addToWorld({ physicsWorld: world } as any);
85
85
  let enterRegistered = false;
@@ -96,7 +96,7 @@ describe(`MatterTriggerComponent`, () => {
96
96
  trigger.addToWorld({ physicsWorld: world } as any);
97
97
  const circle = factory.createRigidBody({
98
98
  shape: { shape: 'CIRCLE', radius: 1 },
99
- body: { dynamic: true, mass: 1 },
99
+ body: { bodyType: 'dynamic', mass: 1 },
100
100
  }, { position: Pnt2.O });
101
101
  circle.addToWorld({ physicsWorld: world } as any);
102
102
  let exitRegistered = false;
@@ -114,7 +114,7 @@ describe(`MatterTriggerComponent`, () => {
114
114
  trigger.addToWorld({ physicsWorld: world } as any);
115
115
  const circle = factory.createRigidBody({
116
116
  shape: { shape: 'CIRCLE', radius: 1 },
117
- body: { dynamic: true, mass: 1 },
117
+ body: { bodyType: 'dynamic', mass: 1 },
118
118
  }, { position: Pnt2.O });
119
119
  circle.addToWorld({ physicsWorld: world } as any);
120
120
  let exitRegistered = false;
package/test/components/matter-world.component.spec.ts CHANGED
@@ -22,7 +22,7 @@ describe('MatterWorldComponent', () => {
22
22
  const circle = world.factory.createRigidBody(
23
23
  {
24
24
  shape: { shape: 'CIRCLE', radius: 1 },
25
- body: { dynamic: true, mass: 5 },
25
+ body: { bodyType: 'dynamic', mass: 5 },
26
26
  },
27
27
  { position: { x: -5, y: 0 } },
28
28
  );
@@ -41,7 +41,7 @@ describe('MatterWorldComponent', () => {
41
41
  const circle0 = world.factory.createRigidBody(
42
42
  {
43
43
  shape: { shape: 'CIRCLE', radius: 1 },
44
- body: { dynamic: true, mass: 5 },
44
+ body: { bodyType: 'dynamic', mass: 5 },
45
45
  },
46
46
  { position: { x: -5, y: 0 } },
47
47
  );
@@ -52,7 +52,7 @@ describe('MatterWorldComponent', () => {
52
52
  const circle1 = world.factory.createRigidBody(
53
53
  {
54
54
  shape: { shape: 'CIRCLE', radius: 1 },
55
- body: { dynamic: true, mass: 5 },
55
+ body: { bodyType: 'dynamic', mass: 5 },
56
56
  },
57
57
  { position: { x: 5, y: 0 } },
58
58
  );
@@ -70,7 +70,7 @@ describe('MatterWorldComponent', () => {
70
70
 
71
71
  it('keeps handleIdEntityMap (the O(1) findRigidBody lookup) in sync with children on add/remove', () => {
72
72
  const circle = world.factory.createRigidBody(
73
- { shape: { shape: 'CIRCLE', radius: 1 }, body: { dynamic: true, mass: 1 } },
73
+ { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
74
74
  { position: { x: 0, y: 0 } },
75
75
  );
76
76
  circle.addToWorld({ physicsWorld: world } as any);
@@ -87,7 +87,7 @@ describe('MatterWorldComponent', () => {
87
87
  const circle0 = world.factory.createRigidBody(
88
88
  {
89
89
  shape: { shape: 'CIRCLE', radius: 1 },
90
- body: { dynamic: true, mass: 5 },
90
+ body: { bodyType: 'dynamic', mass: 5 },
91
91
  },
92
92
  { position: { x: -5, y: 0 } },
93
93
  );
@@ -100,7 +100,7 @@ describe('MatterWorldComponent', () => {
100
100
  const circle1 = world.factory.createRigidBody(
101
101
  {
102
102
  shape: { shape: 'CIRCLE', radius: 1 },
103
- body: { dynamic: true, mass: 5 },
103
+ body: { bodyType: 'dynamic', mass: 5 },
104
104
  },
105
105
  { position: { x: 5, y: 0 } },
106
106
  );
@@ -124,7 +124,7 @@ describe('MatterWorldComponent', () => {
124
124
  const square = world.factory.createRigidBody(
125
125
  {
126
126
  shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
127
- body: { dynamic: false, mass: 0 },
127
+ body: { bodyType: 'static', mass: 0 },
128
128
  },
129
129
  { position: { x: 10, y: 10 } },
130
130
  );
@@ -150,7 +150,7 @@ describe('MatterWorldComponent', () => {
150
150
  const square = world.factory.createRigidBody(
151
151
  {
152
152
  shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
153
- body: { dynamic: false, mass: 0 },
153
+ body: { bodyType: 'static', mass: 0 },
154
154
  },
155
155
  { position: { x: 0, y: -5 } },
156
156
  );
@@ -188,7 +188,7 @@ describe('MatterWorldComponent', () => {
188
188
  {
189
189
  shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
190
190
  body: {
191
- dynamic: false,
191
+ bodyType: 'static',
192
192
  mass: 0,
193
193
  ownCollisionGroups: [group1],
194
194
  interactWithCollisionGroups: [group1, group2],
@@ -229,7 +229,7 @@ describe('MatterWorldComponent', () => {
229
229
  const square = world.factory.createRigidBody(
230
230
  {
231
231
  shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
232
- body: { dynamic: false, mass: 0 },
232
+ body: { bodyType: 'static', mass: 0 },
233
233
  },
234
234
  { position: { x: 0, y: -5 } },
235
235
  );
@@ -261,7 +261,7 @@ describe('MatterWorldComponent', () => {
261
261
  {
262
262
  shape: { shape: 'SQUARE', dimensions: { x: 2, y: 2 } },
263
263
  body: {
264
- dynamic: false,
264
+ bodyType: 'static',
265
265
  mass: 0,
266
266
  ownCollisionGroups: [group1],
267
267
  interactWithCollisionGroups: [group1, group2],
@@ -290,7 +290,7 @@ describe('MatterWorldComponent', () => {
290
290
  const square1 = world.factory.createRigidBody(
291
291
  {
292
292
  shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
293
- body: { dynamic: false, mass: 0 },
293
+ body: { bodyType: 'static', mass: 0 },
294
294
  },
295
295
  { position: { x: 0, y: -3 } },
296
296
  );
@@ -299,7 +299,7 @@ describe('MatterWorldComponent', () => {
299
299
  const square2 = world.factory.createRigidBody(
300
300
  {
301
301
  shape: { shape: 'SQUARE', dimensions: { x: 1, y: 1 } },
302
- body: { dynamic: false, mass: 0 },
302
+ body: { bodyType: 'static', mass: 0 },
303
303
  },
304
304
  { position: { x: 0, y: -7 } },
305
305
  );
@@ -324,7 +324,7 @@ describe('MatterWorldComponent', () => {
324
324
  const square = world.factory.createRigidBody(
325
325
  {
326
326
  shape: { shape: 'SQUARE', dimensions: { x: 4, y: 4 } },
327
- body: { dynamic: false, mass: 0 },
327
+ body: { bodyType: 'static', mass: 0 },
328
328
  },
329
329
  { position: { x: 0, y: 0 } },
330
330
  );