@gg-web-engine/rapier3d 0.0.63 → 0.0.64

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

@@ -0,0 +1,131 @@
+import { CharacterController3dOptions, CollisionGroup, DebugBody3DSettings, Entity3d, ICharacterController3dComponent, Point3, Point4 } from '@gg-web-engine/core';
+import { Collider, InteractionGroups, KinematicCharacterController, RigidBody, RigidBodyDesc } from '@dimforge/rapier3d-compat';
+import { Rapier3dWorldComponent } from './rapier-3d-world.component';
+import { Rapier3dGgWorld, Rapier3dPhysicsTypeDocRepo } from '../types';
+/**
+ * A capsule-shaped kinematic character controller backed by Rapier's own `KinematicCharacterController`
+ * (`world.createCharacterController`). `move()` is made fully synchronous (see
+ * `ICharacterController3dComponent`'s doc for why this matters) by never relying on
+ * `setNextKinematicTranslation` + a later `world.step()` to actually reposition the body - the plain
+ * (non-"next") `RigidBody.setTranslation`/`setRotation` is used instead, immediately followed by
+ * `World.propagateModifiedBodyPositionsToColliders` so the capsule's new position is visible to
+ * Rapier's collider state (and thus to the *next* `move()` call, or to any raycast) without needing a
+ * simulation step in between. `setNextKinematicTranslation`/`setNextKinematicRotation` are
+ * additionally set to the same target so that dynamic bodies pushed by the character still get a
+ * reasonable velocity estimate on whatever `world.step()` happens to run afterwards - this is a
+ * nice-to-have, not load-bearing for the synchronous contract.
+ *
+ * Note: a collider only enters Rapier's broad-phase as part of a `World.step()` - a level's static
+ * geometry (or this character itself) created and never stepped even once is invisible to `move()`'s
+ * sweep test, exactly as it would be to `world.raycast()`. This is a pre-existing engine property, not
+ * specific to this component; a normal per-frame game loop that calls `physicsWorld.simulate()`
+ * every tick already satisfies it after the first tick.
+ *
+ * Note: unlike `Rapier3dRigidBodyComponent`/`Rapier3dTriggerComponent`, this component's native body
+ * handle is *not* registered in `Rapier3dWorldComponent.handleIdEntityMap` - `world.raycast()` cannot
+ * currently resolve a hit against a character controller back to this component (it will simply be
+ * absent from `RaycastResult.hitBody`). Wiring that up would require widening the reverse-map's and
+ * `raycast()`'s return-type generics repo-wide for a corner case outside this interface's contract;
+ * left as a documented limitation rather than done speculatively.
+ */
+export declare class Rapier3dCharacterControllerComponent implements ICharacterController3dComponent<Rapier3dPhysicsTypeDocRepo> {
+    protected readonly world: Rapier3dWorldComponent;
+    protected readonly options: Required<CharacterController3dOptions>;
+    protected _bodyDescr: RigidBodyDesc;
+    entity: Entity3d | null;
+    name: string;
+    readonly radius: number;
+    readonly centersDistance: number;
+    private _up;
+    get up(): Point3;
+    set up(value: Point3);
+    private _isGrounded;
+    get isGrounded(): boolean;
+    private _groundNormal;
+    get groundNormal(): Point3 | null;
+    private static warnedMissingDtForPush;
+    protected _nativeBody: RigidBody | null;
+    protected _nativeCollider: Collider | null;
+    protected _nativeController: KinematicCharacterController | null;
+    get nativeBody(): RigidBody | null;
+    get nativeCollider(): Collider | null;
+    get nativeController(): KinematicCharacterController | null;
+    readonly debugBodySettings: DebugBody3DSettings;
+    get position(): Point3;
+    set position(value: Point3);
+    get rotation(): Point4;
+    set rotation(value: Point4);
+    protected collisionGroups: InteractionGroups;
+    get interactWithCollisionGroups(): ReadonlyArray<CollisionGroup>;
+    set interactWithCollisionGroups(value: ReadonlyArray<CollisionGroup> | 'all');
+    get ownCollisionGroups(): ReadonlyArray<CollisionGroup>;
+    set ownCollisionGroups(value: ReadonlyArray<CollisionGroup> | 'all');
+    constructor(world: Rapier3dWorldComponent, options: Required<CharacterController3dOptions>, _bodyDescr: RigidBodyDesc);
+    /**
+     * Makes any position/rotation change applied directly to `_nativeBody` (outside of `move()`, e.g.
+     * via the `position`/`rotation` setters) immediately visible to Rapier's collider state, without
+     * requiring a `world.step()` - see the class doc for why this matters. The pinned
+     * `@dimforge/rapier3d-compat` build only exposes `propagateModifiedBodyPositionsToColliders()` for
+     * this (no separate `QueryPipeline`/`updateSceneQueries` object to rebuild - the character
+     * controller queries `World`'s live `broadPhase`/`narrowPhase` directly), so that's the only call
+     * needed here.
+     */
+    private syncColliderTransform;
+    move(desiredTranslation: Point3, dt?: number): void;
+    /**
+     * Shoves any dynamic body this tick's sweep bumped into - see `addToWorld`'s doc for why this is
+     * hand-rolled rather than Rapier's own `setApplyImpulsesToDynamicBodies`. Mirrors
+     * `AmmoCharacterControllerComponent.pushDynamicBody` exactly: models the contact as a simple
+     * inelastic collision against a virtual body of mass `options.pushMass` moving at `characterSpeed`
+     * (this tick's *horizontal* displacement - vertical/jump motion never pushes anything sideways -
+     * converted to a real m/s via `dt`, not a raw per-tick distance), driving the hit body's velocity
+     * along the push direction towards `characterSpeed * pushMass / (pushMass + bodyMass)` and only
+     * ever adding forward velocity, never removing any (so a body already outrunning the character in
+     * that direction is left alone). `computedCollision()` already has everything needed - populated
+     * by the `computeColliderMovement` call above regardless of this method's own logic, so no extra
+     * sweep/query is needed to reach it.
+     */
+    private pushDynamicBodies;
+    /**
+     * Rapier's character controller doesn't expose a single "ground normal" directly - only a list of
+     * per-obstacle collisions (`computedCollision`) from the last `computeColliderMovement` call, each
+     * with its own contact normal. Best-effort approach: scan those collisions and return whichever
+     * normal points *most* nearly along `up` (i.e. the most floor-like of the bunch, however steep it
+     * actually is) - this deliberately does **not** discard a candidate merely for being steep (e.g.
+     * balanced on the flank of a sphere/cylinder, far past `maxSlopeClimbAngleRad`): that judgment
+     * belongs entirely to `CharacterController3dEntity.isWalkableGround` at the core level, which
+     * needs the *real* contact normal to make it, not a value already pre-filtered down here. An
+     * earlier version discarded any candidate with `dot(normal, up) <= 0.1` and fell back to the plain
+     * `up` vector when nothing cleared that bar - which silently reported perfectly-flat ground for a
+     * character resting against a normal steep enough to fail that same threshold, defeating
+     * `isWalkableGround` entirely (confirmed empirically: a character run-and-jumped onto the flank of
+     * a static sphere, landing on a contact whose true outward normal was ~70° off `up` - well past the
+     * default ~50° `maxSlopeClimbAngleRad` - permanently reported `groundNormal: {0,0,1}` instead, so
+     * the core entity kept treating it as resting on flat ground and it never slid off, visibly stuck
+     * balanced on a sliver of the sphere even with every input released).
+     *
+     * `numComputedCollisions()` itself is frequently `0` on a call that is still genuinely grounded -
+     * `computeColliderMovement` doesn't record an entry for a character caught by snap-to-ground alone
+     * (no obstacle actually blocked the *desired* movement that call), which in practice is most idle
+     * ticks: a character standing still (`desiredTranslation` exactly `{0,0,0}`, e.g. player released
+     * every key) has nothing for the sweep to hit, so it settles into being grounded via snap alone,
+     * over and over, tick after tick, without ever producing a fresh collision entry again. Guessing
+     * flat `up` on every such tick is exactly the bug above, just via a different, far more common
+     * path than "no collision was ever recorded" suggests - it's not a rare edge case, it's what happens
+     * the very first idle tick after any landing (including this one, right after the collision that
+     * *did* populate the true steep normal above). Fix: on a `0`-collision grounded call, reuse
+     * whichever normal this same field already held **before** this call (the character's own contact
+     * geometry hasn't changed just because this particular call didn't happen to re-sweep it) rather
+     * than guessing - `move()` only overwrites `this._groundNormal` with this method's return value
+     * *after* calling it, so reading the field here still sees the previous call's result. Only when
+     * there is no prior normal to reuse either (the very first grounded call ever, landing exactly via
+     * snap with nothing recorded yet) does this fall back to the plain `up` vector. Returns `null` if
+     * not grounded at all - `_groundNormal` naturally clears itself the moment the character goes
+     * airborne, so a later landing never reuses a stale value from a previous, unrelated surface.
+     */
+    private computeGroundNormal;
+    clone(): Rapier3dCharacterControllerComponent;
+    addToWorld(world: Rapier3dGgWorld): void;
+    removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
+    dispose(): void;
+}

package/dist/components/rapier-3d-character-controller.component.js

@@ -0,0 +1,398 @@
+import { BitMask, DebugBody3DSettings, Pnt3, Qtrn, } from '@gg-web-engine/core';
+import { Quaternion, RigidBodyDesc, Vector3, } from '@dimforge/rapier3d-compat';
+/**
+ * A capsule-shaped kinematic character controller backed by Rapier's own `KinematicCharacterController`
+ * (`world.createCharacterController`). `move()` is made fully synchronous (see
+ * `ICharacterController3dComponent`'s doc for why this matters) by never relying on
+ * `setNextKinematicTranslation` + a later `world.step()` to actually reposition the body - the plain
+ * (non-"next") `RigidBody.setTranslation`/`setRotation` is used instead, immediately followed by
+ * `World.propagateModifiedBodyPositionsToColliders` so the capsule's new position is visible to
+ * Rapier's collider state (and thus to the *next* `move()` call, or to any raycast) without needing a
+ * simulation step in between. `setNextKinematicTranslation`/`setNextKinematicRotation` are
+ * additionally set to the same target so that dynamic bodies pushed by the character still get a
+ * reasonable velocity estimate on whatever `world.step()` happens to run afterwards - this is a
+ * nice-to-have, not load-bearing for the synchronous contract.
+ *
+ * Note: a collider only enters Rapier's broad-phase as part of a `World.step()` - a level's static
+ * geometry (or this character itself) created and never stepped even once is invisible to `move()`'s
+ * sweep test, exactly as it would be to `world.raycast()`. This is a pre-existing engine property, not
+ * specific to this component; a normal per-frame game loop that calls `physicsWorld.simulate()`
+ * every tick already satisfies it after the first tick.
+ *
+ * Note: unlike `Rapier3dRigidBodyComponent`/`Rapier3dTriggerComponent`, this component's native body
+ * handle is *not* registered in `Rapier3dWorldComponent.handleIdEntityMap` - `world.raycast()` cannot
+ * currently resolve a hit against a character controller back to this component (it will simply be
+ * absent from `RaycastResult.hitBody`). Wiring that up would require widening the reverse-map's and
+ * `raycast()`'s return-type generics repo-wide for a corner case outside this interface's contract;
+ * left as a documented limitation rather than done speculatively.
+ */
+export class Rapier3dCharacterControllerComponent {
+    get up() {
+        return this._up;
+    }
+    set up(value) {
+        var _a;
+        this._up = Pnt3.norm(value);
+        (_a = this._nativeController) === null || _a === void 0 ? void 0 : _a.setUp(new Vector3(this._up.x, this._up.y, this._up.z));
+    }
+    get isGrounded() {
+        return this._isGrounded;
+    }
+    get groundNormal() {
+        return this._groundNormal;
+    }
+    get nativeBody() {
+        return this._nativeBody;
+    }
+    get nativeCollider() {
+        return this._nativeCollider;
+    }
+    get nativeController() {
+        return this._nativeController;
+    }
+    get position() {
+        return Pnt3.clone(this._nativeBody ? this._nativeBody.translation() : this._bodyDescr.translation);
+    }
+    set position(value) {
+        if (this._nativeBody) {
+            const v = new Vector3(value.x, value.y, value.z);
+            this._nativeBody.setTranslation(v, true);
+            this._nativeBody.setNextKinematicTranslation(v);
+            this.syncColliderTransform();
+        }
+        else {
+            this._bodyDescr.setTranslation(value.x, value.y, value.z);
+        }
+    }
+    get rotation() {
+        return Qtrn.clone(this._nativeBody ? this._nativeBody.rotation() : this._bodyDescr.rotation);
+    }
+    set rotation(value) {
+        if (this._nativeBody) {
+            const q = new Quaternion(value.x, value.y, value.z, value.w);
+            this._nativeBody.setRotation(q, true);
+            this._nativeBody.setNextKinematicRotation(q);
+            this.syncColliderTransform();
+        }
+        else {
+            this._bodyDescr.setRotation(new Quaternion(value.x, value.y, value.z, value.w));
+        }
+    }
+    get interactWithCollisionGroups() {
+        return BitMask.unpack(this.collisionGroups, 16);
+    }
+    set interactWithCollisionGroups(value) {
+        var _a;
+        let mask = value === 'all' ? BitMask.full(16) : BitMask.pack(value, 16);
+        mask = mask | (this.collisionGroups & (BitMask.full(16) << 16));
+        if (mask === this.collisionGroups) {
+            return;
+        }
+        this.collisionGroups = mask;
+        (_a = this._nativeCollider) === null || _a === void 0 ? void 0 : _a.setCollisionGroups(this.collisionGroups);
+    }
+    get ownCollisionGroups() {
+        return BitMask.unpack(this.collisionGroups >> 16, 16);
+    }
+    set ownCollisionGroups(value) {
+        var _a;
+        let mask = value === 'all' ? BitMask.full(16) : BitMask.pack(value, 16);
+        mask = (mask << 16) | (this.collisionGroups & BitMask.full(16));
+        if (mask === this.collisionGroups) {
+            return;
+        }
+        this.collisionGroups = mask;
+        (_a = this._nativeCollider) === null || _a === void 0 ? void 0 : _a.setCollisionGroups(this.collisionGroups);
+    }
+    constructor(world, options, _bodyDescr) {
+        this.world = world;
+        this.options = options;
+        this._bodyDescr = _bodyDescr;
+        this.entity = null;
+        this.name = '';
+        this._isGrounded = false;
+        this._groundNormal = null;
+        this._nativeBody = null;
+        this._nativeCollider = null;
+        this._nativeController = null;
+        this.collisionGroups = BitMask.full(32);
+        this.radius = options.radius;
+        this.centersDistance = options.centersDistance;
+        this._up = Pnt3.norm(options.up);
+        this.debugBodySettings = new DebugBody3DSettings({ type: 'RIGID_DYNAMIC', sleeping: () => false }, { shape: 'CAPSULE', radius: this.radius, centersDistance: this.centersDistance });
+        this.ownCollisionGroups = options.ownCollisionGroups;
+        this.interactWithCollisionGroups = options.interactWithCollisionGroups;
+    }
+    /**
+     * Makes any position/rotation change applied directly to `_nativeBody` (outside of `move()`, e.g.
+     * via the `position`/`rotation` setters) immediately visible to Rapier's collider state, without
+     * requiring a `world.step()` - see the class doc for why this matters. The pinned
+     * `@dimforge/rapier3d-compat` build only exposes `propagateModifiedBodyPositionsToColliders()` for
+     * this (no separate `QueryPipeline`/`updateSceneQueries` object to rebuild - the character
+     * controller queries `World`'s live `broadPhase`/`narrowPhase` directly), so that's the only call
+     * needed here.
+     */
+    syncColliderTransform() {
+        this.world.nativeWorld.propagateModifiedBodyPositionsToColliders();
+    }
+    move(desiredTranslation, dt) {
+        if (!this._nativeBody || !this._nativeCollider || !this._nativeController) {
+            // not yet added to the world - nothing to sweep against (matches
+            // `AmmoCharacterControllerComponent.move`'s no-op contract, see `ICharacterController3dComponent`)
+            return;
+        }
+        // make sure collider positions reflect any obstacle moved (by anything) since the last
+        // world.step()/propagate call, so the upcoming sweep test is accurate
+        this.syncColliderTransform();
+        // Rapier's own snap-to-ground, left enabled unconditionally, would otherwise undo a jump
+        // takeoff the very next tick: `computeColliderMovement` treats a character within
+        // `snapToGroundDistance` of the floor it just left as still grounded and pulls it right back
+        // down onto it, and a jump's own per-tick rise (`jumpSpeed * dt`) starts out far smaller than
+        // the default 0.3 snap distance - so every jump was silently cancelled before it ever left the
+        // ground. This is the exact same failure mode `AmmoCharacterControllerComponent`'s own
+        // hand-rolled mover hit and fixed (see that class's `move()` doc's `movingUp` guard); toggling
+        // snap-to-ground off for ticks that are actively rising, back on otherwise, mirrors it here.
+        //
+        // Autostep needs the identical guard, for a related but distinct reason: it only misbehaves
+        // while jumping *and* simultaneously blocked horizontally by something taller than
+        // `maxStepHeight` (e.g. running at a barrier and jumping right as you reach it, rather than
+        // jumping in open space) - confirmed empirically, a jump that looked perfect in the open turned
+        // into a small up-then-snap-back-down "flick" the instant the same jump was attempted pressed
+        // up against such an obstacle, the rise stopping right around `maxStepHeight` itself before
+        // reverting to standing height. Autostep's own "raise up to maxStepHeight, retry the blocked
+        // horizontal move, keep the raise only if that retry actually clears" evaluation runs as part of
+        // the very same `computeColliderMovement` call handling the jump's vertical component - when the
+        // retry still doesn't clear (barrier taller than the raise), whatever it does to "give back" the
+        // failed step attempt isn't scoped to just the horizontal axis, so it cancels the deliberate
+        // vertical rise sharing that same call too. There's no real reason to want auto-step-climbing
+        // active while already deliberately jumping, so disable it under the same condition.
+        const movingUp = Pnt3.dot(desiredTranslation, this._up) > 1e-9;
+        if (movingUp) {
+            this._nativeController.disableSnapToGround();
+            this._nativeController.disableAutostep();
+        }
+        else {
+            if (this.options.snapToGroundDistance > 0) {
+                this._nativeController.enableSnapToGround(this.options.snapToGroundDistance);
+            }
+            if (this.options.maxStepHeight > 0) {
+                this._nativeController.enableAutostep(this.options.maxStepHeight, this.options.minStepWidth, true);
+            }
+        }
+        const desired = new Vector3(desiredTranslation.x, desiredTranslation.y, desiredTranslation.z);
+        this._nativeController.computeColliderMovement(this._nativeCollider, desired);
+        const computed = this._nativeController.computedMovement();
+        const current = this._nativeBody.translation();
+        const next = new Vector3(current.x + computed.x, current.y + computed.y, current.z + computed.z);
+        this._nativeBody.setTranslation(next, true);
+        this._nativeBody.setNextKinematicTranslation(next);
+        this.syncColliderTransform();
+        this._isGrounded = this._nativeController.computedGrounded();
+        this._groundNormal = this.computeGroundNormal();
+        this.pushDynamicBodies(desiredTranslation, dt);
+    }
+    /**
+     * Shoves any dynamic body this tick's sweep bumped into - see `addToWorld`'s doc for why this is
+     * hand-rolled rather than Rapier's own `setApplyImpulsesToDynamicBodies`. Mirrors
+     * `AmmoCharacterControllerComponent.pushDynamicBody` exactly: models the contact as a simple
+     * inelastic collision against a virtual body of mass `options.pushMass` moving at `characterSpeed`
+     * (this tick's *horizontal* displacement - vertical/jump motion never pushes anything sideways -
+     * converted to a real m/s via `dt`, not a raw per-tick distance), driving the hit body's velocity
+     * along the push direction towards `characterSpeed * pushMass / (pushMass + bodyMass)` and only
+     * ever adding forward velocity, never removing any (so a body already outrunning the character in
+     * that direction is left alone). `computedCollision()` already has everything needed - populated
+     * by the `computeColliderMovement` call above regardless of this method's own logic, so no extra
+     * sweep/query is needed to reach it.
+     */
+    pushDynamicBodies(desiredTranslation, dt) {
+        var _a;
+        const pushMass = this.options.pushMass;
+        if (pushMass <= 0 || !this._nativeController) {
+            return;
+        }
+        const vertical = Pnt3.scalarMult(this._up, Pnt3.dot(desiredTranslation, this._up));
+        const horizontal = Pnt3.sub(desiredTranslation, vertical);
+        const horizLen = Pnt3.len(horizontal);
+        if (horizLen <= 1e-9) {
+            return;
+        }
+        // `dt` is required to recover a real m/s speed from `horizLen` (see
+        // `ICharacterController3dComponent.move()`'s doc). Falling back to the raw per-tick
+        // displacement as if it were already a speed would understate push force by roughly a factor of
+        // `dt` - silently wrong, not just imprecise - so skip the push for this tick instead when `dt`
+        // isn't available, same as `AmmoCharacterControllerComponent.pushDynamicBody`.
+        if (!dt || dt <= 1e-9) {
+            if (!Rapier3dCharacterControllerComponent.warnedMissingDtForPush) {
+                Rapier3dCharacterControllerComponent.warnedMissingDtForPush = true;
+                console.warn('[Rapier3dCharacterControllerComponent] move() was called without `dt` while `pushMass` > ' +
+                    '0 - skipping this dynamic-body push rather than approximating character speed from raw ' +
+                    'per-tick displacement (which would understate push force by roughly 1/dt). Pass the ' +
+                    'real tick delta (seconds) as the third argument to move() to enable pushing dynamic bodies.');
+            }
+            return;
+        }
+        const direction = Pnt3.scalarMult(horizontal, 1 / horizLen);
+        const characterSpeed = horizLen / dt;
+        const count = this._nativeController.numComputedCollisions();
+        for (let i = 0; i < count; i++) {
+            const collision = this._nativeController.computedCollision(i);
+            const body = (_a = collision === null || collision === void 0 ? void 0 : collision.collider) === null || _a === void 0 ? void 0 : _a.parent();
+            if (!body || !body.isDynamic()) {
+                continue;
+            }
+            const bodyMass = body.mass();
+            if (bodyMass <= 0) {
+                continue;
+            }
+            const pushSpeed = characterSpeed * (pushMass / (pushMass + bodyMass));
+            const v = body.linvel();
+            const currentAlong = v.x * direction.x + v.y * direction.y + v.z * direction.z;
+            if (pushSpeed <= currentAlong) {
+                continue;
+            }
+            const delta = pushSpeed - currentAlong;
+            body.setLinvel({ x: v.x + direction.x * delta, y: v.y + direction.y * delta, z: v.z + direction.z * delta }, true);
+        }
+    }
+    /**
+     * Rapier's character controller doesn't expose a single "ground normal" directly - only a list of
+     * per-obstacle collisions (`computedCollision`) from the last `computeColliderMovement` call, each
+     * with its own contact normal. Best-effort approach: scan those collisions and return whichever
+     * normal points *most* nearly along `up` (i.e. the most floor-like of the bunch, however steep it
+     * actually is) - this deliberately does **not** discard a candidate merely for being steep (e.g.
+     * balanced on the flank of a sphere/cylinder, far past `maxSlopeClimbAngleRad`): that judgment
+     * belongs entirely to `CharacterController3dEntity.isWalkableGround` at the core level, which
+     * needs the *real* contact normal to make it, not a value already pre-filtered down here. An
+     * earlier version discarded any candidate with `dot(normal, up) <= 0.1` and fell back to the plain
+     * `up` vector when nothing cleared that bar - which silently reported perfectly-flat ground for a
+     * character resting against a normal steep enough to fail that same threshold, defeating
+     * `isWalkableGround` entirely (confirmed empirically: a character run-and-jumped onto the flank of
+     * a static sphere, landing on a contact whose true outward normal was ~70° off `up` - well past the
+     * default ~50° `maxSlopeClimbAngleRad` - permanently reported `groundNormal: {0,0,1}` instead, so
+     * the core entity kept treating it as resting on flat ground and it never slid off, visibly stuck
+     * balanced on a sliver of the sphere even with every input released).
+     *
+     * `numComputedCollisions()` itself is frequently `0` on a call that is still genuinely grounded -
+     * `computeColliderMovement` doesn't record an entry for a character caught by snap-to-ground alone
+     * (no obstacle actually blocked the *desired* movement that call), which in practice is most idle
+     * ticks: a character standing still (`desiredTranslation` exactly `{0,0,0}`, e.g. player released
+     * every key) has nothing for the sweep to hit, so it settles into being grounded via snap alone,
+     * over and over, tick after tick, without ever producing a fresh collision entry again. Guessing
+     * flat `up` on every such tick is exactly the bug above, just via a different, far more common
+     * path than "no collision was ever recorded" suggests - it's not a rare edge case, it's what happens
+     * the very first idle tick after any landing (including this one, right after the collision that
+     * *did* populate the true steep normal above). Fix: on a `0`-collision grounded call, reuse
+     * whichever normal this same field already held **before** this call (the character's own contact
+     * geometry hasn't changed just because this particular call didn't happen to re-sweep it) rather
+     * than guessing - `move()` only overwrites `this._groundNormal` with this method's return value
+     * *after* calling it, so reading the field here still sees the previous call's result. Only when
+     * there is no prior normal to reuse either (the very first grounded call ever, landing exactly via
+     * snap with nothing recorded yet) does this fall back to the plain `up` vector. Returns `null` if
+     * not grounded at all - `_groundNormal` naturally clears itself the moment the character goes
+     * airborne, so a later landing never reuses a stale value from a previous, unrelated surface.
+     */
+    computeGroundNormal() {
+        var _a;
+        if (!this._isGrounded || !this._nativeController) {
+            return null;
+        }
+        const count = this._nativeController.numComputedCollisions();
+        let best = null;
+        let bestDot = -Infinity;
+        for (let i = 0; i < count; i++) {
+            const collision = this._nativeController.computedCollision(i);
+            if (!(collision === null || collision === void 0 ? void 0 : collision.normal1)) {
+                continue;
+            }
+            const normal = Pnt3.clone(collision.normal1);
+            const dot = Pnt3.dot(normal, this._up);
+            if (dot > bestDot) {
+                bestDot = dot;
+                best = normal;
+            }
+        }
+        return (_a = best !== null && best !== void 0 ? best : this._groundNormal) !== null && _a !== void 0 ? _a : Pnt3.clone(this._up);
+    }
+    clone() {
+        // read the CURRENT position/rotation, not `_bodyDescr`'s construction-time values - once
+        // `_nativeBody` exists, the `position`/`rotation` setters write straight to it and never touch
+        // `_bodyDescr` again (see those setters above), so `_bodyDescr` alone would be stale for any
+        // controller that has moved since being added to the world.
+        const pos = this.position;
+        const rot = this.rotation;
+        const bd = RigidBodyDesc.kinematicPositionBased();
+        bd.setTranslation(pos.x, pos.y, pos.z);
+        bd.setRotation(new Quaternion(rot.x, rot.y, rot.z, rot.w));
+        const comp = new Rapier3dCharacterControllerComponent(this.world, this.options, bd);
+        comp.collisionGroups = this.collisionGroups;
+        return comp;
+    }
+    addToWorld(world) {
+        if (world.physicsWorld != this.world) {
+            throw new Error('Rapier3D bodies cannot be shared between different worlds');
+        }
+        const nativeWorld = this.world.nativeWorld;
+        this._nativeBody = nativeWorld.createRigidBody(this._bodyDescr);
+        const colliderDescr = this.world.factory.createColliderDescr({
+            shape: 'CAPSULE',
+            radius: this.radius,
+            centersDistance: this.centersDistance,
+        })[0];
+        this._nativeCollider = nativeWorld.createCollider(colliderDescr, this._nativeBody);
+        this._nativeCollider.setCollisionGroups(this.collisionGroups);
+        this._nativeController = nativeWorld.createCharacterController(this.options.offset);
+        this._nativeController.setUp(new Vector3(this._up.x, this._up.y, this._up.z));
+        this._nativeController.setMaxSlopeClimbAngle(this.options.maxSlopeClimbAngleRad);
+        if (this.options.maxStepHeight > 0) {
+            this._nativeController.enableAutostep(this.options.maxStepHeight, this.options.minStepWidth, true);
+        }
+        if (this.options.snapToGroundDistance > 0) {
+            this._nativeController.enableSnapToGround(this.options.snapToGroundDistance);
+        }
+        // Rapier's own `KinematicCharacterController` has a built-in equivalent of `pushMass`
+        // (`setApplyImpulsesToDynamicBodies(true)` + `setCharacterMass(...)`) that looked like the
+        // obvious way to implement pushing here - no hand-rolled logic needed, unlike
+        // `AmmoCharacterControllerComponent` (whose ghost-based mover has no native equivalent at all).
+        // It was tried first, but is deliberately **not** used: confirmed empirically, enabling it on
+        // this kinematic-position-based character body doesn't just get the push physics wrong (mass
+        // ordering inverted - a *heavier* box ended up moving further than a lighter one at otherwise
+        // identical settings) but genuinely explodes - a pushed box's position jumped by 5+ meters in a
+        // single 16ms tick and kept climbing indefinitely tick after tick, not settling. Root cause not
+        // fully identified (plausibly `characterMass`'s override interacting badly with this body's own
+        // `mass()`, which a kinematic body reports as `0`, somewhere in Rapier's impulse resolution -
+        // not something this package's pinned `@dimforge/rapier3d-compat` build exposes enough to debug
+        // further from JS). `pushDynamicBodies` below is a hand-rolled equivalent instead, mirroring
+        // `AmmoCharacterControllerComponent.pushDynamicBody`'s own formula and contract exactly (down to
+        // the same `pushMass <= 0` "disable pushing" convention) - built on `computedCollision()`, which
+        // `computeColliderMovement` already populates every `move()` call regardless of this native
+        // feature being enabled, so no extra query is needed to reach it.
+        this.world.added$.next(this);
+    }
+    removeFromWorld(world, dispose) {
+        if (world.physicsWorld != this.world) {
+            throw new Error('Rapier3D bodies cannot be shared between different worlds');
+        }
+        if (this._nativeController) {
+            this.world.nativeWorld.removeCharacterController(this._nativeController);
+            this._nativeController = null;
+        }
+        if (this._nativeBody) {
+            if (this._nativeCollider) {
+                this.world.nativeWorld.removeCollider(this._nativeCollider, false);
+                this._nativeCollider = null;
+            }
+            this.world.nativeWorld.removeRigidBody(this._nativeBody);
+            this._nativeBody = null;
+        }
+        this.world.removed$.next(this);
+    }
+    dispose() {
+        if (this._nativeBody) {
+            this.removeFromWorld({ physicsWorld: this.world }, true);
+        }
+    }
+}
+// Module-wide (not per-instance) so a scene with several characters all being driven without
+// `dt` still only logs once, not once per character per tick - see `pushDynamicBodies`'s
+// missing-`dt` handling below.
+Rapier3dCharacterControllerComponent.warnedMissingDtForPush = false;

package/dist/components/rapier-3d-raycast-vehicle.component.d.ts

@@ -12,7 +12,7 @@ export declare class Rapier3dRaycastVehicleComponent extends Rapier3dRigidBodyCo
     constructor(world: Rapier3dWorldComponent, chassisBody: Rapier3dRigidBodyComponent);
     get wheelSpeed(): number;
     addToWorld(world: Rapier3dGgWorld): void;
-    removeFromWorld(world: Rapier3dGgWorld): void;
+    removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
     addWheel(options: WheelOptions, suspensionOptions: SuspensionOptions): void;
     setSteering(wheelIndex: number, steering: number): void;
     applyEngineForce(wheelIndex: number, force: number): void;

package/dist/components/rapier-3d-raycast-vehicle.component.js

@@ -26,14 +26,17 @@ export class Rapier3dRaycastVehicleComponent extends Rapier3dRigidBodyComponent
         }
         setInterval(() => this._nativeVehicle.updateVehicle(0.01), 10);
     }
-    removeFromWorld(world) {
+    removeFromWorld(world, dispose) {
         if (world.physicsWorld != this.world) {
             throw new Error('Rapier3D bodies cannot be shared between different worlds');
         }
         if (this.nativeVehicle) {
             world.physicsWorld.nativeWorld.removeVehicleController(this.nativeVehicle);
         }
-        super.removeFromWorld(world);
+        super.removeFromWorld(world, dispose);
+        if (dispose) {
+            this.dispose();
+        }
     }
     addWheel(options, suspensionOptions) {
         const descr = [

package/dist/components/rapier-3d-rigid-body.component.d.ts

@@ -37,7 +37,7 @@ export declare class Rapier3dRigidBodyComponent implements IRigidBody3dComponent
     set ownCollisionGroups(value: ReadonlyArray<CollisionGroup> | 'all');
     clone(): Rapier3dRigidBodyComponent;
     addToWorld(world: Rapier3dGgWorld): void;
-    removeFromWorld(world: Rapier3dGgWorld): void;
+    removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
     resetMotion(): void;
     dispose(): void;
 }

package/dist/components/rapier-3d-rigid-body.component.js

@@ -150,7 +150,7 @@ export class Rapier3dRigidBodyComponent {
         this.world.handleIdEntityMap.set(this._nativeBody.handle, this);
         this.world.added$.next(this);
     }
-    removeFromWorld(world) {
+    removeFromWorld(world, dispose) {
         if (world.physicsWorld != this.world) {
             throw new Error('Rapier3D bodies cannot be shared between different worlds');
         }
@@ -171,7 +171,7 @@ export class Rapier3dRigidBodyComponent {
     }
     dispose() {
         if (this.nativeBody) {
-            this.removeFromWorld({ physicsWorld: this.world });
+            this.removeFromWorld({ physicsWorld: this.world }, true);
         }
     }
 }

package/dist/components/rapier-3d-trigger.component.d.ts

@@ -17,7 +17,7 @@ export declare class Rapier3dTriggerComponent extends Rapier3dRigidBodyComponent
     protected readonly onLeft$: Subject<Rapier3dRigidBodyComponent>;
     constructor(world: Rapier3dWorldComponent, _colliderDescr: ColliderDesc[], shape: Shape3DDescriptor, _bodyDescr: RigidBodyDesc);
     addToWorld(world: Rapier3dGgWorld): void;
-    removeFromWorld(world: Rapier3dGgWorld): void;
+    removeFromWorld(world: Rapier3dGgWorld, dispose?: boolean): void;
     checkOverlaps(): void;
     clone(): Rapier3dTriggerComponent;
     dispose(): void;

package/dist/components/rapier-3d-trigger.component.js

@@ -29,12 +29,12 @@ export class Rapier3dTriggerComponent extends Rapier3dRigidBodyComponent {
         this.world.handleIdEntityMap.set(this._nativeBody.handle, this);
         this.world.added$.next(this);
     }
-    removeFromWorld(world) {
+    removeFromWorld(world, dispose) {
         for (const body of this.overlaps) {
             this.onLeft$.next(body);
         }
         this.overlaps.clear();
-        super.removeFromWorld(world);
+        super.removeFromWorld(world, dispose);
     }
     checkOverlaps() {
         this.world.eventQueue.drainCollisionEvents((h1, h2, started) => {

package/dist/components/rapier-3d-world.component.d.ts

@@ -1,18 +1,20 @@
 import { CollisionGroup, IPhysicsWorld3dComponent, Point3, RaycastOptions, RaycastResult } from '@gg-web-engine/core';
 import { EventQueue, World } from '@dimforge/rapier3d-compat';
 import { Rapier3dRigidBodyComponent } from './rapier-3d-rigid-body.component';
+import { Rapier3dCharacterControllerComponent } from './rapier-3d-character-controller.component';
 import { Rapier3dFactory } from '../rapier-3d-factory';
 import { Rapier3dLoader } from '../rapier-3d-loader';
 import { Rapier3dPhysicsTypeDocRepo } from '../types';
 import { Subject } from 'rxjs';
+type Rapier3dWorldChild = Rapier3dRigidBodyComponent | Rapier3dCharacterControllerComponent;
 export declare class Rapier3dWorldComponent implements IPhysicsWorld3dComponent<Rapier3dPhysicsTypeDocRepo> {
     private _factory;
     get factory(): Rapier3dFactory;
     private _loader;
     get loader(): Rapier3dLoader;
-    readonly added$: Subject<Rapier3dRigidBodyComponent>;
-    readonly removed$: Subject<Rapier3dRigidBodyComponent>;
-    readonly children: Rapier3dRigidBodyComponent[];
+    readonly added$: Subject<Rapier3dWorldChild>;
+    readonly removed$: Subject<Rapier3dWorldChild>;
+    readonly children: Rapier3dWorldChild[];
     private _gravity;
     get gravity(): Point3;
     set gravity(value: Point3);
@@ -31,3 +33,4 @@ export declare class Rapier3dWorldComponent implements IPhysicsWorld3dComponent<
     raycast(options: RaycastOptions<Point3>): RaycastResult<Point3, Rapier3dRigidBodyComponent>;
     dispose(): void;
 }
+export {};

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './components/rapier-3d-rigid-body.component';
 export * from './components/rapier-3d-trigger.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';