@gg-web-engine/matter 0.0.72 → 0.0.74

package/test/components/matter-character-controller.component.spec.ts

@@ -0,0 +1,298 @@
+import { CharacterController2dOptions, Pnt2 } from '@gg-web-engine/core';
+import { MatterFactory, MatterWorldComponent } from '../../src';
+
+describe('MatterCharacterControllerComponent', () => {
+  let world: MatterWorldComponent;
+  let factory: MatterFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new MatterWorldComponent();
+    factory = new MatterFactory(world);
+    await world.init();
+    world.gravity = Pnt2.O; // this component never relies on gravity - see the interface's own doc
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  const CHAR_OPTIONS: CharacterController2dOptions = { radius: 0.4, centersDistance: 1.0 };
+  // center-to-feet distance for the capsule above: radius + centersDistance / 2
+  const HALF_HEIGHT = CHAR_OPTIONS.radius + CHAR_OPTIONS.centersDistance / 2;
+
+  // A static floor slab spanning [centerX - sizeX/2, centerX + sizeX/2] on X, with its top face (the
+  // side facing `up` = `{x:0,y:-1}`, i.e. the smaller-Y side) at world-space `topY`.
+  const addFloor = (centerX: number, sizeX: number, topY: number, thickness = 1) => {
+    const floor = factory.createRigidBody(
+      {
+        shape: { shape: 'BOX', dimensions: { x: sizeX, y: thickness } },
+        body: { bodyType: 'static', mass: 0 },
+      },
+      { position: { x: centerX, y: topY + thickness / 2 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+    return floor;
+  };
+
+  // A static vertical wall whose near face is at world-space X `x`.
+  const addWall = (x: number, thickness = 1) => {
+    const wall = factory.createRigidBody(
+      {
+        shape: { shape: 'BOX', dimensions: { x: thickness, y: 20 } },
+        body: { bodyType: 'static', mass: 0 },
+      },
+      { position: { x: x + thickness / 2, y: 0 } },
+    );
+    wall.addToWorld({ physicsWorld: world } as any);
+    return wall;
+  };
+
+  // Unlike Ammo/Rapier, matter-js has no broad-phase-registration lag at all - `Composite.add`
+  // synchronously updates `Composite.allBodies`, which is exactly what this component's own
+  // `Query.collides`-based queries read - so there is no "world hasn't stepped yet" pitfall here to
+  // work around with a settle call. Kept only as a documented no-op for structural parity with the
+  // other adapters' test suites.
+  const settleWorld = () => world.simulate(0);
+
+  it('should create a character controller and add it to the world', () => {
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: -5 } });
+    expect(character.radius).toBe(0.4);
+    expect(character.centersDistance).toBe(1.0);
+    character.addToWorld({ physicsWorld: world } as any);
+    expect(world.children).toContain(character);
+    expect(character.position).toEqual({ x: 0, y: -5 });
+  });
+
+  it('should settle on a flat floor and report grounded state', () => {
+    addFloor(0, 20, 0);
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: -5 } });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+
+    expect(character.isGrounded).toBe(false);
+
+    character.move({ x: 0, y: 10 });
+
+    // resolved fully synchronously - no world.simulate() call happened after settleWorld() above
+    expect(character.isGrounded).toBe(true);
+    expect(character.position.y).toBeCloseTo(-HALF_HEIGHT, 1);
+    expect(character.groundNormal).not.toBeNull();
+    expect(character.groundNormal!.y).toBeLessThan(-0.9);
+  });
+
+  it('should slide to a stop against a wall instead of passing through it', () => {
+    addFloor(0, 20, 0);
+    addWall(2);
+    const character = factory.createCharacterController(CHAR_OPTIONS, {
+      position: { x: 0, y: -(HALF_HEIGHT + 0.5) },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    // settle onto the floor first
+    character.move({ x: 0, y: 1 });
+    expect(character.isGrounded).toBe(true);
+
+    character.move({ x: 5, y: 0 });
+
+    // wall's near face is at x=2; the capsule (radius 0.4) plus its skin offset must stop short of it
+    expect(character.position.x).toBeLessThan(1.6);
+    expect(character.position.x).toBeGreaterThan(0.5);
+    // remained grounded throughout - sliding along the wall, not falling
+    expect(character.isGrounded).toBe(true);
+  });
+
+  it(
+    'two character controllers should block each other instead of passing through (regression: a ' +
+      "character's own phantom body is never added to Composite/engine.world, so it was invisible to " +
+      "any other character's obstacle collection, which only ever enumerated Composite.allBodies)",
+    () => {
+      addFloor(0, 20, 0);
+      const characterA = factory.createCharacterController(CHAR_OPTIONS, {
+        position: { x: 0, y: -(HALF_HEIGHT + 0.5) },
+      });
+      const characterB = factory.createCharacterController(CHAR_OPTIONS, {
+        position: { x: 3, y: -(HALF_HEIGHT + 0.5) },
+      });
+      characterA.addToWorld({ physicsWorld: world } as any);
+      characterB.addToWorld({ physicsWorld: world } as any);
+      settleWorld();
+      characterA.move({ x: 0, y: 1 });
+      characterB.move({ x: 0, y: 1 });
+
+      for (let i = 0; i < 20; i++) {
+        characterA.move({ x: 0.2, y: 0 });
+      }
+
+      // characterB sits at x=3 and never moves - characterA must be blocked well short of it, not
+      // walk straight through to make its full requested 4 units of horizontal progress.
+      expect(characterA.position.x).toBeLessThan(2.5);
+      expect(characterB.position.x).toBe(3);
+    },
+  );
+
+  it(
+    'walks straight through a body added to ignoredBodies instead of sliding to a stop against it ' +
+      "(regression: collision groups alone can't express excluding just one specific body while both " +
+      'it and the character still need to collide with the rest of the world - see ' +
+      '`ICharacterController2dComponent.ignoredBodies`\'s doc)',
+    () => {
+      addFloor(0, 20, 0);
+      const wall = addWall(2);
+      const character = factory.createCharacterController(CHAR_OPTIONS, {
+        position: { x: 0, y: -(HALF_HEIGHT + 0.5) },
+      });
+      character.addToWorld({ physicsWorld: world } as any);
+      character.ignoredBodies.add(wall);
+      settleWorld();
+      character.move({ x: 0, y: 1 });
+
+      character.move({ x: 5, y: 0 });
+
+      // unlike the baseline test above, nothing stopped it short of the wall's x=2 near face
+      expect(character.position.x).toBeCloseTo(5);
+    },
+  );
+
+  it('removing a body from ignoredBodies makes it block the character again', () => {
+    addFloor(0, 20, 0);
+    const wall = addWall(2);
+    const character = factory.createCharacterController(CHAR_OPTIONS, {
+      position: { x: 0, y: -(HALF_HEIGHT + 0.5) },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    character.ignoredBodies.add(wall);
+    character.ignoredBodies.delete(wall);
+    settleWorld();
+    character.move({ x: 0, y: 1 });
+
+    character.move({ x: 5, y: 0 });
+
+    expect(character.position.x).toBeLessThan(1.6);
+  });
+
+  it('should step up a ledge shorter than maxStepHeight without getting stuck', () => {
+    const maxStepHeight = 0.3;
+    const stepHeight = 0.2; // below maxStepHeight
+    addFloor(-5, 10, 0); // lower floor, spans x in [-10, 0]
+    addFloor(5, 10, -stepHeight); // upper ledge, spans x in [0, 10], step wall at x=0
+
+    const character = factory.createCharacterController(
+      { ...CHAR_OPTIONS, maxStepHeight },
+      { position: { x: -5, y: -(HALF_HEIGHT + 0.5) } },
+    );
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    character.move({ x: 0, y: 1 });
+    expect(character.isGrounded).toBe(true);
+    expect(character.position.y).toBeCloseTo(-HALF_HEIGHT, 1);
+
+    // walk forward across the step in small increments, each with a slight downward bias so the
+    // character does not need to rely on gravity (which this component never applies itself)
+    for (let i = 0; i < 60; i++) {
+      character.move({ x: 0.15, y: 0.05 });
+    }
+
+    expect(character.isGrounded).toBe(true);
+    expect(character.position.x).toBeGreaterThan(2); // made meaningful forward progress past the step
+    expect(character.position.y).toBeCloseTo(-(stepHeight + HALF_HEIGHT), 1); // stepped up onto the ledge
+  });
+
+  it('a small upward move (a jump takeoff tick) actually rises instead of being snapped back to the floor, even though it stays well within the default snapToGroundDistance of 0.3', () => {
+    addFloor(0, 20, 0);
+    const character = factory.createCharacterController(CHAR_OPTIONS, {
+      position: { x: 0, y: -(HALF_HEIGHT + 0.5) },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    character.move({ x: 0, y: 1 });
+    expect(character.isGrounded).toBe(true);
+    const groundedY = character.position.y;
+
+    // one tick's worth of a typical jumpSpeed (5 units/s) at 60fps - well under the 0.3 snapToGroundDistance
+    character.move({ x: 0, y: -0.083 });
+
+    expect(character.position.y).toBeCloseTo(groundedY - 0.083, 2);
+    expect(character.isGrounded).toBe(false);
+  });
+
+  it("move()'s effects must be visible immediately, without an extra world.step() in between", () => {
+    addFloor(0, 20, 0);
+    addWall(1);
+    const character = factory.createCharacterController(CHAR_OPTIONS, {
+      position: { x: 0, y: -(HALF_HEIGHT + 0.01) },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+
+    // no world.simulate() call below this point - move() alone must fully resolve state
+    character.move({ x: 10, y: 0 });
+
+    expect(character.position.x).toBeLessThan(0.6);
+    expect(character.position.x).toBeGreaterThan(-0.1);
+  });
+
+  it('should clone with the same shape/options but independent from the world', () => {
+    const character = factory.createCharacterController(
+      { radius: 0.3, centersDistance: 0.8, maxStepHeight: 0.25 },
+      { position: { x: 1, y: 2 } },
+    );
+    const clone = character.clone();
+    expect(clone.radius).toBe(character.radius);
+    expect(clone.centersDistance).toBe(character.centersDistance);
+    expect(clone.position).toEqual(character.position);
+  });
+
+  it('should clone from the CURRENT position/rotation, not the construction-time spawn point', () => {
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: -5 } });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    // move the character away from its construction-time position via the position setter, the
+    // same code path that leaves any construction-time transform stale once the component is added
+    // to a world and driven directly
+    character.position = { x: 10, y: 20 };
+
+    const clone = character.clone();
+
+    expect(clone.position).toEqual(character.position);
+    expect(clone.position).not.toEqual({ x: 0, y: -5 });
+  });
+
+  it(
+    'should clone from the CURRENT up/ownCollisionGroups/interactWithCollisionGroups, not whatever ' +
+      'was passed at construction time (regression: clone() used to rebuild from the frozen ' +
+      "construction-time options object, silently discarding any of these three fields' live " +
+      'mutations via their own setters)',
+    () => {
+      const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: -5 } });
+      character.up = { x: 1, y: 0 };
+      character.ownCollisionGroups = [world.registerCollisionGroup()];
+      character.interactWithCollisionGroups = [world.registerCollisionGroup()];
+
+      const clone = character.clone();
+
+      expect(clone.up).toEqual(character.up);
+      expect(clone.ownCollisionGroups).toEqual(character.ownCollisionGroups);
+      expect(clone.interactWithCollisionGroups).toEqual(character.interactWithCollisionGroups);
+    },
+  );
+
+  it('move() before addToWorld() should be a silent no-op, not throw', () => {
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: -5 } });
+    expect(() => character.move({ x: 1, y: 0 })).not.toThrow();
+    expect(character.position).toEqual({ x: 0, y: -5 });
+  });
+
+  it('should normalize a non-unit-length up vector, matching the 3D adapter', () => {
+    const character = factory.createCharacterController(
+      { ...CHAR_OPTIONS, up: { x: 0, y: 2 } },
+      { position: { x: 0, y: -5 } },
+    );
+    expect(character.up).toEqual({ x: 0, y: 1 });
+
+    character.up = { x: 0, y: 3 };
+    expect(character.up).toEqual({ x: 0, y: 1 });
+  });
+});

package/test/components/matter-rigid-body-collision.spec.ts

@@ -22,7 +22,7 @@ describe('MatterRigidBodyComponent collision events', () => {
   it('should fire onCollisionStart reciprocally, with a sane position/normal, when a falling body lands on a floor', () => {
     // static floor, top edge sits at y = -5
     const floor = factory.createRigidBody(
-      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
+      { shape: { shape: 'BOX', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
       { position: { x: 0, y: 0 } },
     );
     floor.addToWorld({ physicsWorld: world } as any);
@@ -67,18 +67,25 @@ describe('MatterRigidBodyComponent collision events', () => {
 
   it('should not keep re-firing onCollisionStart while a body rests stably on another', () => {
     const floor = factory.createRigidBody(
-      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
+      { shape: { shape: 'BOX', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
       { position: { x: 0, y: 0 } },
     );
     floor.addToWorld({ physicsWorld: world } as any);
 
+    // A BOX, not a CIRCLE: a circle has no flat resting face, so under this engine's default (no
+    // sleeping - see `gg-engine-physics-adapter-matter`'s own note) it keeps finding tiny amounts of
+    // torque to roll away on indefinitely instead of ever truly settling, which is exactly the kind
+    // of never-stops-touching-and-un-touching motion this test's own premise ("rests stably") needs
+    // to rule out by construction. Also left at matter's own default `frictionAir` (not zeroed like
+    // the other tests in this file) - some velocity damping is what actually lets a resting body's
+    // energy bleed off instead of slowly building up over many hundreds of steps (see this file's own
+    // history for how thoroughly this was verified empirically).
     const ball = factory.createRigidBody(
-      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
+      { shape: { shape: 'BOX', dimensions: { x: 2, y: 2 } }, body: { bodyType: 'dynamic', mass: 1 } },
       { position: { x: 0, y: -20 } },
     );
     ball.addToWorld({ physicsWorld: world } as any);
     ball.linearVelocity = { x: 0, y: 10 };
-    ball.nativeBody.frictionAir = 0;
 
     world.gravity = { x: 0, y: 1 };
 
@@ -101,28 +108,35 @@ describe('MatterRigidBodyComponent collision events', () => {
 
   it('should fire onCollisionEnd when a body is knocked away and separates', () => {
     const floor = factory.createRigidBody(
-      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
+      { shape: { shape: 'BOX', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
       { position: { x: 0, y: 0 } },
     );
     floor.addToWorld({ physicsWorld: world } as any);
 
+    // BOX, not CIRCLE - see the previous test's own doc for why.
     const ball = factory.createRigidBody(
-      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
+      { shape: { shape: 'BOX', dimensions: { x: 2, y: 2 } }, body: { bodyType: 'dynamic', mass: 1 } },
       { position: { x: 0, y: -20 } },
     );
     ball.addToWorld({ physicsWorld: world } as any);
     ball.linearVelocity = { x: 0, y: 10 };
-    ball.nativeBody.frictionAir = 0;
 
     let endEvents: (MatterRigidBodyComponent | null)[] = [];
+    // Knock it away the instant it actually touches the floor (rather than after some fixed,
+    // speed/distance-dependent step count guessed to be "enough time to have touched by now") - the
+    // exact number of steps a fall of this distance/speed takes to make real contact isn't this
+    // test's concern and shouldn't be baked into a magic constant.
+    let knocked = false;
+    ball.onCollisionStart.subscribe(() => {
+      if (!knocked) {
+        knocked = true;
+        ball.linearVelocity = { x: 0, y: -10 };
+      }
+    });
     ball.onCollisionEnd.subscribe(e => endEvents.push(e));
 
     for (let i = 0; i < 200 && endEvents.length === 0; i++) {
       world.simulate(16);
-      if (i === 50) {
-        // knock it straight back up, away from the floor, once it's had a chance to touch
-        ball.linearVelocity = { x: 0, y: -10 };
-      }
     }
 
     expect(endEvents.length).toBeGreaterThan(0);
@@ -131,7 +145,7 @@ describe('MatterRigidBodyComponent collision events', () => {
 
   it('should emit onCollisionEnd(null) on the remaining body when the other body is removed from the world while still touching', () => {
     const floor = factory.createRigidBody(
-      { shape: { shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
+      { shape: { shape: 'BOX', dimensions: { x: 50, y: 10 } }, body: { bodyType: 'static', mass: 0 } },
       { position: { x: 0, y: 0 } },
     );
     floor.addToWorld({ physicsWorld: world } as any);
@@ -161,7 +175,7 @@ describe('MatterRigidBodyComponent collision events', () => {
   });
 
   it('should not fire the rigid body onCollisionStart for a trigger overlapping a rigid body', () => {
-    const trigger = factory.createTrigger({ shape: 'SQUARE', dimensions: { x: 50, y: 10 } }, { position: { x: 0, y: 0 } });
+    const trigger = factory.createTrigger({ shape: 'BOX', dimensions: { x: 50, y: 10 } }, { position: { x: 0, y: 0 } });
     trigger.addToWorld({ physicsWorld: world } as any);
 
     const ball = factory.createRigidBody(

package/test/components/matter-rigid-body-sleep.spec.ts

@@ -0,0 +1,79 @@
+import { Pnt2 } from '@gg-web-engine/core';
+import { MatterFactory, MatterWorldComponent } from '../../src';
+
+describe('MatterRigidBodyComponent sleep API', () => {
+  let world: MatterWorldComponent;
+  let factory: MatterFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new MatterWorldComponent();
+    factory = new MatterFactory(world);
+    await world.init();
+    world.gravity = Pnt2.O;
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it('reports a fresh dynamic body as not sleeping', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    expect(body.isSleeping).toBe(false);
+  });
+
+  it('sleep() forces isSleeping true, wakeUp() flips it back - regardless of the world engine\'s enableSleeping setting', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    body.sleep();
+    expect(body.isSleeping).toBe(true);
+
+    body.wakeUp();
+    expect(body.isSleeping).toBe(false);
+  });
+
+  it('a position write on a sleeping body does NOT wake it back up - unlike every other adapter', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 1 } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    body.sleep();
+    expect(body.isSleeping).toBe(true);
+
+    body.position = { x: 1, y: 2 };
+    expect(body.isSleeping).toBe(true);
+    // the write itself is not silently dropped - a caller that must write state on a sleeping
+    // body without waking it (the whole point of this adapter's setters preserving sleep state)
+    // still sees the new position take effect.
+    expect(body.position).toEqual({ x: 1, y: 2 });
+  });
+
+  it('a static body always reports not sleeping, and sleep()/wakeUp() are no-ops', () => {
+    const floor = factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 10, y: 1 } }, body: { bodyType: 'static' } },
+      { position: { x: 0, y: 0 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+
+    expect(floor.isSleeping).toBe(false);
+
+    floor.sleep();
+    expect(floor.isSleeping).toBe(false);
+
+    floor.wakeUp();
+    expect(floor.isSleeping).toBe(false);
+  });
+});

package/test/components/matter-rigid-body.component.spec.ts

@@ -0,0 +1,98 @@
+import { Pnt2 } from '@gg-web-engine/core';
+import { MatterFactory, MatterWorldComponent } from '../../src';
+
+describe('MatterRigidBodyComponent.bodyOptions', () => {
+  let world: MatterWorldComponent;
+  let factory: MatterFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new MatterWorldComponent();
+    factory = new MatterFactory(world);
+    await world.init();
+    world.gravity = Pnt2.O;
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it('reads back the mass/friction/restitution a dynamic body was actually created with', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'dynamic', mass: 5, friction: 0.3, restitution: 0.7 } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    expect(body.bodyOptions.bodyType).toBe('dynamic');
+    expect(body.bodyOptions.mass).toBe(5);
+    expect(body.bodyOptions.friction).toBe(0.3);
+    expect(body.bodyOptions.restitution).toBe(0.7);
+    expect(body.bodyOptions.ccd).toBe(false);
+  });
+
+  it('echoes the originally-requested bodyType/ccd even though matter-js degrades both', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 1, y: 1 } }, body: { bodyType: 'kinematic_pos', mass: 1, ccd: true } },
+      { position: { x: 0, y: 0 } },
+    );
+
+    expect(body.bodyOptions.bodyType).toBe('kinematic_pos');
+    expect(body.bodyOptions.ccd).toBe(true);
+  });
+
+  it('reflects a mutated ownCollisionGroups/interactWithCollisionGroups live', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'CIRCLE', radius: 1 }, body: { bodyType: 'static', mass: 0 } },
+      { position: { x: 0, y: 0 } },
+    );
+
+    body.ownCollisionGroups = [3];
+    body.interactWithCollisionGroups = [5, 6];
+
+    expect(body.bodyOptions.ownCollisionGroups).toEqual([3]);
+    expect(body.bodyOptions.interactWithCollisionGroups).toEqual([5, 6]);
+  });
+});
+
+describe('MatterRigidBodyComponent.rotation', () => {
+  let world: MatterWorldComponent;
+  let factory: MatterFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new MatterWorldComponent();
+    factory = new MatterFactory(world);
+    await world.init();
+    world.gravity = Pnt2.O;
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  it('rotates via Body.setAngle, preserving angular velocity and actually rotating the vertices', () => {
+    const body = factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 2, y: 1 } }, body: { bodyType: 'dynamic', mass: 1 } },
+      { position: { x: 0, y: 0 } },
+    );
+    body.addToWorld({ physicsWorld: world } as any);
+
+    body.rotation = Math.PI / 2;
+    world.simulate(60);
+
+    expect(body.rotation).toBeCloseTo(Math.PI / 2);
+    expect(body.angularVelocity).toBeCloseTo(0);
+
+    // A 2x1 box rotated 90 degrees should report swapped width/height bounds - proof the
+    // underlying vertices were actually rotated, not just the `.angle` field bumped.
+    const width = body.nativeBody.bounds.max.x - body.nativeBody.bounds.min.x;
+    const height = body.nativeBody.bounds.max.y - body.nativeBody.bounds.min.y;
+    expect(width).toBeCloseTo(1);
+    expect(height).toBeCloseTo(2);
+  });
+});