@gg-web-engine/rapier3d 0.0.63 → 0.0.65

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './components/rapier-3d-rigid-body.component';
 export * from './components/rapier-3d-trigger.component';
 // export * from './components/rapier-3d-raycast-vehicle.component';
+export * from './components/rapier-3d-character-controller.component';
 export * from './components/rapier-3d-world.component';
 export * from './rapier-3d-factory';
 export * from './rapier-3d-loader';

package/dist/rapier-3d-factory.d.ts

@@ -1,7 +1,8 @@
-import { Body3DOptions, BodyShape3DDescriptor, IPhysicsBody3dComponentFactory, Point3, Point4, Shape3DDescriptor } from '@gg-web-engine/core';
+import { Body3DOptions, BodyShape3DDescriptor, CharacterController3dOptions, IPhysicsBody3dComponentFactory, Point3, Point4, Shape3DDescriptor } from '@gg-web-engine/core';
 import { ColliderDesc, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './components/rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './components/rapier-3d-trigger.component';
+import { Rapier3dCharacterControllerComponent } from './components/rapier-3d-character-controller.component';
 import { Rapier3dWorldComponent } from './components/rapier-3d-world.component';
 import { Rapier3dPhysicsTypeDocRepo } from './types';
 export declare class Rapier3dFactory implements IPhysicsBody3dComponentFactory<Rapier3dPhysicsTypeDocRepo> {
@@ -16,6 +17,10 @@ export declare class Rapier3dFactory implements IPhysicsBody3dComponentFactory<R
         rotation?: Point4;
     }): Rapier3dTriggerComponent;
     createRaycastVehicle(chassis: Rapier3dRigidBodyComponent): never;
+    createCharacterController(options: CharacterController3dOptions, transform?: {
+        position?: Point3;
+        rotation?: Point4;
+    }): Rapier3dCharacterControllerComponent;
     createColliderDescr(descriptor: Shape3DDescriptor): ColliderDesc[];
     createRigidBodyDescr(options: Partial<Body3DOptions>, transform?: {
         position?: Point3;

package/dist/rapier-3d-factory.js

@@ -2,6 +2,21 @@ import { Pnt3, Qtrn, } from '@gg-web-engine/core';
 import { ActiveEvents, ColliderDesc, Quaternion, RigidBodyDesc } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './components/rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './components/rapier-3d-trigger.component';
+import { Rapier3dCharacterControllerComponent } from './components/rapier-3d-character-controller.component';
+const DEFAULT_CHARACTER_CONTROLLER_OPTIONS = {
+    offset: 0.01,
+    maxStepHeight: 0.3,
+    minStepWidth: 0.2,
+    maxSlopeClimbAngleRad: (50 * Math.PI) / 180,
+    snapToGroundDistance: 0.3,
+    up: Pnt3.Z,
+    ownCollisionGroups: 'all',
+    interactWithCollisionGroups: 'all',
+    // `Rapier3dCharacterControllerComponent.addToWorld` wires this straight into Rapier's own
+    // `KinematicCharacterController.setCharacterMass` + `setApplyImpulsesToDynamicBodies(true)` -
+    // unlike the ammo adapter, no hand-rolled push logic needed, Rapier already computes it.
+    pushMass: 80,
+};
 export class Rapier3dFactory {
     constructor(world) {
         this.world = world;
@@ -20,6 +35,14 @@ export class Rapier3dFactory {
     createRaycastVehicle(chassis) {
         throw new Error('Raycast vehicle bindings for rapier3D are not implemented');
     }
+    createCharacterController(options, transform) {
+        const resolvedOptions = Object.assign(Object.assign(Object.assign({}, DEFAULT_CHARACTER_CONTROLLER_OPTIONS), { ownCollisionGroups: [this.world.mainCollisionGroup] }), options);
+        const bodyDescr = RigidBodyDesc.kinematicPositionBased();
+        const pos = (transform === null || transform === void 0 ? void 0 : transform.position) || Pnt3.O;
+        const rot = (transform === null || transform === void 0 ? void 0 : transform.rotation) || Qtrn.O;
+        bodyDescr.setTranslation(pos.x, pos.y, pos.z).setRotation(new Quaternion(rot.x, rot.y, rot.z, rot.w));
+        return new Rapier3dCharacterControllerComponent(this.world, resolvedOptions, bodyDescr);
+    }
     createColliderDescr(descriptor) {
         const yToZUp = Qtrn.rotAround(Qtrn.O, Pnt3.X, Math.PI / 2);
         switch (descriptor.shape) {

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { Rapier3dFactory } from './rapier-3d-factory';
 import { Rapier3dLoader } from './rapier-3d-loader';
 import { Rapier3dRigidBodyComponent } from './components/rapier-3d-rigid-body.component';
 import { Rapier3dTriggerComponent } from './components/rapier-3d-trigger.component';
+import { Rapier3dCharacterControllerComponent } from './components/rapier-3d-character-controller.component';
 import { Gg3dWorld, Gg3dWorldSceneTypeDocPPatch, Gg3dWorldTypeDocPPatch } from '@gg-web-engine/core';
 import { Rapier3dWorldComponent } from './components/rapier-3d-world.component';
 export type Rapier3dPhysicsTypeDocRepo = {
@@ -10,6 +11,7 @@ export type Rapier3dPhysicsTypeDocRepo = {
     rigidBody: Rapier3dRigidBodyComponent;
     trigger: Rapier3dTriggerComponent;
     raycastVehicle: never;
+    characterController: Rapier3dCharacterControllerComponent;
 };
 export type Rapier3dTypeDoc = Gg3dWorldTypeDocPPatch<Rapier3dPhysicsTypeDocRepo>;
 export type Rapier3dSceneTypeDoc = Gg3dWorldSceneTypeDocPPatch<Rapier3dPhysicsTypeDocRepo, Rapier3dWorldComponent>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gg-web-engine/rapier3d",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "description": "An attempt to create open source game engine for browser",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,7 @@
   "homepage": "https://github.com/AndyGura/gg-web-engine#readme",
   "devDependencies": {
     "@dimforge/rapier3d-compat": "0.20.0",
-    "@gg-web-engine/core": "0.0.63",
+    "@gg-web-engine/core": "0.0.65",
     "@types/jest": "^30.0.0",
     "@types/node": "^26.4.0",
     "jest": "^30.5.0",
@@ -40,7 +40,7 @@
   },
   "peerDependencies": {
     "@dimforge/rapier3d-compat": "0.20.0",
-    "@gg-web-engine/core": "0.0.63",
+    "@gg-web-engine/core": "0.0.65",
     "rxjs": "7.8.2"
   },
   "jest": {

package/test/components/rapier-3d-character-controller-freefall.spec.ts

@@ -0,0 +1,43 @@
+import { CharacterController3dEntity } from '@gg-web-engine/core';
+import { Rapier3dWorldComponent } from '../../src';
+
+describe('Rapier3dCharacterControllerComponent - free fall sanity', () => {
+  it('falls under gravity in empty space (no floor at all) at a physically plausible rate', async () => {
+    const world = new Rapier3dWorldComponent();
+    await world.init();
+    // Leave `world.gravity` at its default (-9.82 along z) and the entity's own `gravity` option
+    // unset (undefined) - this is the normal/default wiring (see `gravity`'s doc on
+    // `CharacterController3dEntityOptions`): `CharacterController3dEntity` reads
+    // `physicsWorld.gravity` live every tick and integrates it itself, since a kinematic character
+    // controller is never affected by the native engine's own gravity integration (that only
+    // applies to dynamic rigid bodies - see `ICharacterController3dComponent`'s doc), regardless of
+    // what `world.gravity` is set to. This test is what actually proves the character obeys world
+    // gravity by default, not just that an explicit numeric override falls correctly.
+
+    const startZ = 1000; // high up, nothing below at all - pure free fall, no ground anywhere
+    const characterController = world.factory.createCharacterController(
+      { radius: 0.4, centersDistance: 1.0 },
+      { position: { x: 0, y: 0, z: startZ } },
+    );
+    const entity = new CharacterController3dEntity({ radius: 0.4, centersDistance: 1.0 }, null, characterController);
+    entity.onSpawned({ physicsWorld: world } as any);
+
+    const dtMs = 16;
+    const steps = 60; // ~1 simulated second
+    for (let i = 0; i < steps; i++) {
+      entity.tick$.next([i * dtMs, dtMs]);
+    }
+
+    const elapsedSeconds = (steps * dtMs) / 1000;
+    const expectedDrop = 0.5 * 9.82 * elapsedSeconds * elapsedSeconds; // free fall from rest, ~4.9m after 1s
+    const actualDrop = startZ - entity.position.z;
+
+    console.log(`expected drop after ${elapsedSeconds}s: ~${expectedDrop.toFixed(2)}m, actual: ${actualDrop.toFixed(2)}m`);
+
+    // generous tolerance for discrete Euler integration - this is a sanity bound, not a physics
+    // precision test: it must catch "falls absurdly fast" (an order of magnitude or more off), not
+    // nitpick integration error
+    expect(actualDrop).toBeGreaterThan(expectedDrop * 0.5);
+    expect(actualDrop).toBeLessThan(expectedDrop * 2);
+  });
+});

package/test/components/rapier-3d-character-controller.component.spec.ts

@@ -0,0 +1,250 @@
+import { CharacterController3dOptions, Pnt3 } from '@gg-web-engine/core';
+import { Rapier3dFactory, Rapier3dWorldComponent } from '../../src';
+
+describe('Rapier3dCharacterControllerComponent', () => {
+  let world: Rapier3dWorldComponent;
+  let factory: Rapier3dFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new Rapier3dWorldComponent();
+    factory = new Rapier3dFactory(world);
+    await world.init();
+    world.gravity = Pnt3.O; // this component never relies on gravity - see the class doc
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  const CHAR_OPTIONS: CharacterController3dOptions = { 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 at
+  // world-space `topZ`.
+  const addFloor = (centerX: number, sizeX: number, topZ: number, thickness = 1) => {
+    const floor = factory.createRigidBody(
+      {
+        shape: { shape: 'BOX', dimensions: { x: sizeX, y: 20, z: thickness } },
+        body: { dynamic: false, mass: 0 },
+      },
+      { position: { x: centerX, y: 0, z: topZ - 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, z: 5 } },
+        body: { dynamic: false, mass: 0 },
+      },
+      { position: { x: x + thickness / 2, y: 0, z: 2.5 } },
+    );
+    wall.addToWorld({ physicsWorld: world } as any);
+    return wall;
+  };
+
+  // Rapier only registers a freshly-created collider's AABB with its broad-phase as part of running
+  // World.step() at least once (there is no manual "rebuild broad-phase now" call exposed on this
+  // build of @dimforge/rapier3d-compat) - so a collider created and never stepped is invisible to
+  // computeColliderMovement's sweep, exactly like it would be to a raycast (see
+  // Rapier3dWorldComponent's own raycast tests, which all call world.simulate() first for the same
+  // reason). A zero-length timestep step is enough to register geometry without moving anything, and
+  // stands in for "the world/level was already running before this character got added" - the one
+  // thing the synchronous `move()` contract does NOT need to hold is any *additional* simulate() call
+  // in between/after move() calls, which is what the tests below actually exercise.
+  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: 0, z: 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: 0, z: 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: 0, z: 5 } });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+
+    expect(character.isGrounded).toBe(false);
+
+    character.move({ x: 0, y: 0, z: -10 });
+
+    // resolved fully synchronously - no world.simulate() call happened after settleWorld() above
+    expect(character.isGrounded).toBe(true);
+    expect(character.position.z).toBeCloseTo(HALF_HEIGHT, 1);
+    expect(character.groundNormal).not.toBeNull();
+    expect(character.groundNormal!.z).toBeGreaterThan(0.9);
+  });
+
+  it('reports the real (steep) contact normal when resting against the flank of a sphere, not a flattened `up`', () => {
+    // A sphere resting on the floor, center at (0,0,1) - the character is placed a hair above the
+    // point on its flank at x=1.2 (well off the apex) and nudged down by a small amount, landing on
+    // a contact whose true outward normal is steep (~59° off `up`, past any reasonable
+    // `maxSlopeClimbAngleRad`), not flat. A large single downward move (like the flat-floor test
+    // above uses) would just slide the capsule all the way down and off the sphere onto the floor
+    // instead of stopping on the flank - not representative of the real symptom, which is a small
+    // per-tick settle move (as `CharacterController3dEntity`'s gravity integration does) landing in
+    // continued contact with the steep surface.
+    addFloor(0, 20, 0);
+    const sphere = factory.createRigidBody(
+      { shape: { shape: 'SPHERE', radius: 1 }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0, z: 1 } },
+    );
+    sphere.addToWorld({ physicsWorld: world } as any);
+    // touching distance between capsule (radius 0.4) and sphere (radius 1) centers is 1.4; at
+    // dx=1.2, dz = sqrt(1.4^2 - 1.2^2) ~= 0.721, so the capsule center touches at z ~= 1.721
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 1.2, y: 0, z: 1.73 } });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+
+    character.move({ x: 0, y: 0, z: -0.05 });
+
+    expect(character.isGrounded).toBe(true);
+    expect(character.groundNormal).not.toBeNull();
+    // the true contact normal here (capsule radius 0.4 against a unit sphere, touching along the
+    // line between their centers, combined radius 1.4) has a `z` around ~0.5 - well below both a
+    // flat-floor normal's z (~1) and the ~0.64 that a 50° maxSlopeClimbAngleRad would allow. An
+    // earlier version of computeGroundNormal() discarded any candidate normal with
+    // `dot(normal, up) <= 0.1` and fell back to the plain `up` vector instead - which would have
+    // reported `groundNormal.z` close to 1 here, exactly the bug this guards against (see
+    // gg-engine-physics-adapter-rapier's "computeGroundNormal" pitfall).
+    expect(character.groundNormal!.z).toBeGreaterThan(0.1);
+    expect(character.groundNormal!.z).toBeLessThan(0.6);
+  });
+
+  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: 0, z: HALF_HEIGHT + 0.5 },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    // settle onto the floor first
+    character.move({ x: 0, y: 0, z: -1 });
+    expect(character.isGrounded).toBe(true);
+
+    character.move({ x: 5, y: 0, z: 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('should step up a ledge shorter than maxStepHeight without getting stuck', () => {
+    const maxStepHeight = 0.3;
+    const stepZ = 0.2; // below maxStepHeight
+    addFloor(-5, 10, 0); // lower floor, spans x in [-10, 0]
+    addFloor(5, 10, stepZ); // upper ledge, spans x in [0, 10], step wall at x=0
+
+    const character = factory.createCharacterController(
+      { ...CHAR_OPTIONS, maxStepHeight },
+      { position: { x: -5, y: 0, z: HALF_HEIGHT + 0.5 } },
+    );
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    character.move({ x: 0, y: 0, z: -1 });
+    expect(character.isGrounded).toBe(true);
+    expect(character.position.z).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, z: -0.05 });
+    }
+
+    expect(character.isGrounded).toBe(true);
+    expect(character.position.x).toBeGreaterThan(2); // made meaningful forward progress past the step
+    expect(character.position.z).toBeCloseTo(stepZ + 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: 0, z: HALF_HEIGHT + 0.5 },
+    });
+    character.addToWorld({ physicsWorld: world } as any);
+    settleWorld();
+    character.move({ x: 0, y: 0, z: -1 });
+    expect(character.isGrounded).toBe(true);
+    const groundedZ = character.position.z;
+
+    // one tick's worth of a typical jumpSpeed (5 m/s) at 60fps - well under the 0.3 snapToGroundDistance
+    character.move({ x: 0, y: 0, z: 0.083 });
+
+    expect(character.position.z).toBeCloseTo(groundedZ + 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: 0, z: 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, z: 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, z: 3 } },
+    );
+    const clone = character.clone();
+    expect(clone.radius).toBe(character.radius);
+    expect(clone.centersDistance).toBe(character.centersDistance);
+    expect(clone.position).toEqual(character.position);
+    expect(clone.nativeBody).toBeNull();
+  });
+
+  it('should clone from the CURRENT position/rotation, not the construction-time spawn point', () => {
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: 0, z: 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 `_bodyDescr` stale once `_nativeBody` exists
+    character.position = { x: 10, y: 20, z: 30 };
+
+    const clone = character.clone();
+
+    expect(clone.position).toEqual(character.position);
+    expect(clone.position).not.toEqual({ x: 0, y: 0, z: 5 });
+  });
+
+  it('move() before addToWorld() should be a silent no-op, not throw', () => {
+    const character = factory.createCharacterController(CHAR_OPTIONS, { position: { x: 0, y: 0, z: 5 } });
+    expect(() => character.move({ x: 1, y: 0, z: 0 })).not.toThrow();
+    expect(character.position).toEqual({ x: 0, y: 0, z: 5 });
+  });
+
+  it('should normalize a non-unit-length up vector, matching the Ammo adapter', () => {
+    const character = factory.createCharacterController(
+      { ...CHAR_OPTIONS, up: { x: 0, y: 0, z: 2 } },
+      { position: { x: 0, y: 0, z: 5 } },
+    );
+    expect(character.up).toEqual({ x: 0, y: 0, z: 1 });
+
+    character.up = { x: 0, y: 0, z: 3 };
+    expect(character.up).toEqual({ x: 0, y: 0, z: 1 });
+  });
+});

package/test/components/rapier-3d-player-character-controller-integration.spec.ts

@@ -0,0 +1,181 @@
+import { CharacterController3dEntity, KeyboardInput, Pnt3, PlayerCharacterController, Qtrn } from '@gg-web-engine/core';
+import { Rapier3dWorldComponent } from '../../src';
+
+// A camera looking horizontally toward +Y - identity rotation would look straight down (local -Z
+// maps to world -Z at identity, in this Z-up engine), a degenerate/arbitrary case for
+// `PlayerCharacterController.reset()`'s yaw derivation; every real app sets an actual look
+// direction, so this is the representative case.
+const fakeCamera = () => ({ position: { x: 0, y: 0, z: 0 }, rotation: Qtrn.lookAt(Pnt3.O, Pnt3.Y) }) as any;
+
+const setup = async () => {
+  const world = new Rapier3dWorldComponent();
+  await world.init();
+  world.gravity = { x: 0, y: 0, z: 0 };
+  const floor = world.factory.createRigidBody(
+    { shape: { shape: 'BOX', dimensions: { x: 100, y: 100, z: 1 } }, body: { dynamic: false, mass: 0 } },
+    { position: { x: 0, y: 0, z: -0.5 } },
+  );
+  floor.addToWorld({ physicsWorld: world } as any);
+
+  const characterController = world.factory.createCharacterController(
+    { radius: 0.4, centersDistance: 1.0 },
+    { position: { x: 0, y: 0, z: 1.0 } },
+  );
+  const character = new CharacterController3dEntity(
+    { radius: 0.4, centersDistance: 1.0, walkSpeed: 4, jumpSpeed: 5, gravity: 9.82 },
+    null,
+    characterController,
+  );
+  character.onSpawned({ physicsWorld: world } as any);
+  world.simulate(1);
+
+  const keyboard = new KeyboardInput();
+  keyboard.start();
+  const camera = fakeCamera();
+  const controller = new PlayerCharacterController(keyboard, character, camera);
+  await controller.onSpawned({ physicsWorld: world } as any);
+
+  const tickBoth = (elapsed: number, dt: number) => {
+    character.tick$.next([elapsed, dt]);
+    controller.tick$.next([elapsed, dt]);
+  };
+
+  for (let i = 0; i < 10; i++) tickBoth(i * 16, 16);
+  expect(character.isGrounded).toBe(true);
+
+  return { world, character, keyboard, controller, tickBoth };
+};
+
+describe('PlayerCharacterController + Rapier3dCharacterControllerComponent - end-to-end', () => {
+  it('walks forward the expected distance and jumps when the real physics is driven through the real input controller', async () => {
+    const { character, keyboard, tickBoth } = await setup();
+    const settledY = character.position.y;
+    const settledZ = character.position.z;
+
+    keyboard.emulateKeyDown('KeyW');
+    const dtMs = 16;
+    const steps = 60;
+    const groundedThroughout: boolean[] = [];
+    for (let i = 0; i < steps; i++) {
+      tickBoth(i * dtMs, dtMs);
+      groundedThroughout.push(character.isGrounded);
+    }
+    keyboard.emulateKeyUp('KeyW');
+
+    const elapsedSeconds = (steps * dtMs) / 1000;
+    const expectedDistance = 4 * elapsedSeconds;
+    const actualDistance = character.position.y - settledY;
+    console.log(`forward: expected ~${expectedDistance.toFixed(2)}m, actual ${actualDistance.toFixed(2)}m`);
+    expect(groundedThroughout.every(g => g)).toBe(true);
+    expect(actualDistance).toBeGreaterThan(expectedDistance * 0.8);
+    expect(actualDistance).toBeLessThan(expectedDistance * 1.2);
+
+    expect(character.isGrounded).toBe(true);
+    keyboard.emulateKeyDown('Space');
+    keyboard.emulateKeyUp('Space');
+    let peakZ = character.position.z;
+    for (let i = 0; i < 30; i++) {
+      tickBoth((steps + i) * dtMs, dtMs);
+      peakZ = Math.max(peakZ, character.position.z);
+    }
+    console.log(`jump: settled z ${settledZ.toFixed(2)}, peak z during jump ${peakZ.toFixed(2)}`);
+    expect(peakZ).toBeGreaterThan(settledZ + 0.3);
+  });
+
+  it('walks backward the expected distance, without resistance', async () => {
+    const { character, keyboard, tickBoth } = await setup();
+    const settledY = character.position.y;
+
+    keyboard.emulateKeyDown('KeyS');
+    const dtMs = 16;
+    const steps = 60;
+    const groundedThroughout: boolean[] = [];
+    for (let i = 0; i < steps; i++) {
+      tickBoth(i * dtMs, dtMs);
+      groundedThroughout.push(character.isGrounded);
+    }
+    keyboard.emulateKeyUp('KeyS');
+
+    const elapsedSeconds = (steps * dtMs) / 1000;
+    const expectedDistance = 4 * elapsedSeconds;
+    const actualDistance = settledY - character.position.y;
+    console.log(`backward: expected ~${expectedDistance.toFixed(2)}m, actual ${actualDistance.toFixed(2)}m`);
+    expect(groundedThroughout.every(g => g)).toBe(true);
+    expect(actualDistance).toBeGreaterThan(expectedDistance * 0.8);
+    expect(actualDistance).toBeLessThan(expectedDistance * 1.2);
+  });
+
+  it.each([
+    ['right', 'KeyD', 1],
+    ['left', 'KeyA', -1],
+  ])('strafes %s the expected distance, without resistance', async (_label, key, sign) => {
+    const { character, keyboard, tickBoth } = await setup();
+    const settledX = character.position.x;
+
+    keyboard.emulateKeyDown(key);
+    const dtMs = 16;
+    const steps = 60;
+    const groundedThroughout: boolean[] = [];
+    for (let i = 0; i < steps; i++) {
+      tickBoth(i * dtMs, dtMs);
+      groundedThroughout.push(character.isGrounded);
+    }
+    keyboard.emulateKeyUp(key);
+
+    const elapsedSeconds = (steps * dtMs) / 1000;
+    const expectedDistance = 4 * elapsedSeconds;
+    const actualDistance = (character.position.x - settledX) * sign;
+    console.log(`strafe ${_label}: expected ~${expectedDistance.toFixed(2)}m, actual ${actualDistance.toFixed(2)}m`);
+    expect(groundedThroughout.every(g => g)).toBe(true);
+    expect(actualDistance).toBeGreaterThan(expectedDistance * 0.8);
+    expect(actualDistance).toBeLessThan(expectedDistance * 1.2);
+  });
+});
+
+describe('CharacterController3dEntity + Rapier3dCharacterControllerComponent - slope rejection', () => {
+  it('slides off a too-steep sphere flank under gravity instead of staying stuck with no input', async () => {
+    // No PlayerCharacterController/keyboard involved here - this is purely gravity vs.
+    // `isWalkableGround`, driven with real (nonzero) gravity, unlike this file's other tests.
+    const world = new Rapier3dWorldComponent();
+    await world.init();
+    world.gravity = { x: 0, y: 0, z: -9.82 };
+    const floor = world.factory.createRigidBody(
+      { shape: { shape: 'BOX', dimensions: { x: 100, y: 100, z: 1 } }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0, z: -0.5 } },
+    );
+    floor.addToWorld({ physicsWorld: world } as any);
+    const sphere = world.factory.createRigidBody(
+      { shape: { shape: 'SPHERE', radius: 1 }, body: { dynamic: false, mass: 0 } },
+      { position: { x: 0, y: 0, z: 1 } },
+    );
+    sphere.addToWorld({ physicsWorld: world } as any);
+
+    // touching position at dx=1.2 from sphere center: dz=sqrt(1.4^2-1.2^2)~=0.721 -> z~=1.721, a
+    // contact whose true outward normal is ~59° off `up` - past the default ~50°
+    // `maxSlopeClimbAngleRad`, so the character should slide straight off it, not stand there.
+    const characterController = world.factory.createCharacterController(
+      { radius: 0.4, centersDistance: 1.0 },
+      { position: { x: 1.2, y: 0, z: 1.73 } },
+    );
+    const character = new CharacterController3dEntity(
+      { radius: 0.4, centersDistance: 1.0, walkSpeed: 4, jumpSpeed: 4 },
+      null,
+      characterController,
+    );
+    character.onSpawned({ physicsWorld: world } as any);
+    world.simulate(1);
+
+    const dtMs = 16;
+    for (let i = 0; i < 200; i++) {
+      character.tick$.next([i * dtMs, dtMs]);
+      world.simulate(dtMs);
+    }
+
+    // must not remain perched on the sphere flank (z would stay well above the floor's resting
+    // height, ~0.91, if stuck) - regression test for computeGroundNormal() falling back to a flat
+    // `up` normal on the many idle ticks that find zero fresh collisions while still (correctly)
+    // grounded via snap - see gg-engine-physics-adapter-rapier's "computeGroundNormal" pitfall.
+    expect(character.position.z).toBeLessThan(1.2);
+    expect(character.isGrounded).toBe(true);
+  });
+});

package/test/rapier-3d-factory.spec.ts

@@ -0,0 +1,68 @@
+import { Pnt3 } from '@gg-web-engine/core';
+import { Rapier3dFactory, Rapier3dWorldComponent } from '../src';
+
+describe('Rapier3dFactory', () => {
+  let world: Rapier3dWorldComponent;
+  let factory: Rapier3dFactory;
+
+  beforeEach(async () => {
+    if (world) {
+      world.dispose();
+    }
+    world = new Rapier3dWorldComponent();
+    factory = new Rapier3dFactory(world);
+    await world.init();
+    world.gravity = Pnt3.O;
+  });
+
+  afterAll(() => {
+    world.dispose();
+  });
+
+  describe('createCharacterController', () => {
+    it('should produce a component usable without any extra setup', () => {
+      const character = factory.createCharacterController(
+        { radius: 0.4, centersDistance: 1.0 },
+        { position: { x: 0, y: 0, z: 5 } },
+      );
+      expect(character.radius).toBe(0.4);
+      expect(character.centersDistance).toBe(1.0);
+      expect(character.position).toEqual({ x: 0, y: 0, z: 5 });
+      expect(character.ownCollisionGroups).toEqual([world.mainCollisionGroup]);
+      expect(character.interactWithCollisionGroups).toEqual(Array.from({ length: 16 }, (_, i) => i)); // 'all' default
+
+      character.addToWorld({ physicsWorld: world } as any);
+      expect(character.nativeBody).not.toBeNull();
+      expect(character.nativeCollider).not.toBeNull();
+      expect(character.nativeController).not.toBeNull();
+
+      // works: a downward move against a floor grounds it, fully synchronously
+      const floor = factory.createRigidBody(
+        { shape: { shape: 'BOX', dimensions: { x: 20, y: 20, z: 1 } }, body: { dynamic: false, mass: 0 } },
+        { position: { x: 0, y: 0, z: -0.5 } },
+      );
+      floor.addToWorld({ physicsWorld: world } as any);
+      // a freshly-created static collider only enters Rapier's broad-phase as part of a world step;
+      // a zero-length step registers it without moving anything (see the character-controller spec
+      // for the full explanation)
+      world.simulate(0);
+      character.move({ x: 0, y: 0, z: -10 });
+      expect(character.isGrounded).toBe(true);
+
+      character.removeFromWorld({ physicsWorld: world } as any);
+      expect(character.nativeBody).toBeNull();
+    });
+
+    it('should respect explicit collision group overrides', () => {
+      const group = world.registerCollisionGroup();
+      const character = factory.createCharacterController({
+        radius: 0.4,
+        centersDistance: 1.0,
+        ownCollisionGroups: [group],
+        interactWithCollisionGroups: [group],
+      });
+      expect(character.ownCollisionGroups).toEqual([group]);
+      expect(character.interactWithCollisionGroups).toEqual([group]);
+    });
+  });
+});