@woosh/meep-engine 3.1.0 → 3.3.0

package/src/engine/control/first-person/math/jumpDynamics.js

@@ -1,108 +1,108 @@
-import { assert } from "../../../../core/assert.js";
-
-/**
- * Jump power as physics, not a magic velocity.
- *
- * A jump is the legs doing WORK: a push-off force `F` (newtons) applied over a
- * leg-extension distance `d` (meters) while the body is still on the ground.
- * That work becomes the body's kinetic energy at the instant it leaves the
- * ground, which gravity then trades back for height:
- *
- *     F · d   =   ½ · m · v₀²          (leg work → launch kinetic energy)
- *     ½ · m · v₀²   =   m · g · h      (launch KE → potential energy at apex)
- *
- * Eliminating v₀ collapses the two into a single, mass-honest relationship
- * between the force the legs deliver and the apex the body reaches:
- *
- *     h   =   F · d / (m · g)
- *     F   =   m · g · h / d
- *     v₀  =   √(2 · F · d / m)   =   √(2 · g · h)
- *
- * Why express jump power as a FORCE (newtons) rather than a launch velocity?
- *   - It is a property of the CHARACTER (the legs), not of the jump. A fixed
- *     leg force makes a heavier body jump lower — `h ∝ 1/m` — for free, which a
- *     raw launch-velocity number cannot express (the same v₀ ignores mass).
- *   - It composes: momentum, fatigue, and surface bonuses all add/scale in the
- *     same physical currency (newtons) before a single conversion to velocity.
- *
- * `d` (the push-off distance) is the one extra parameter a newtons model needs:
- * force alone can't determine a launch without the distance (or time) it acts
- * over. It is a body constant — roughly the crouch-to-full-extension travel of
- * the legs (~0.4–0.5 m for a ~1.8 m human countermovement jump).
- *
- * All three functions are pure and frame-independent. The headline is
- * {@link jumpForceForHeight}: the newtons a designer needs to reach a desired
- * apex on a given character. {@link launchVelocityForForce} is the forward
- * conversion an ability applies at launch.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * The push-off force (newtons) the legs must deliver for the body to reach a
- * given apex height — i.e. newtons BACK-CALCULATED from the desired maximum
- * jump height on this character.
- *
- *     F = m · g · h / d
- *
- * Heavier body → more force for the same height; stronger gravity → more force;
- * a longer push-off distance → less force (the work is spread over more travel).
- *
- * @param {number} mass             body mass, kg (> 0)
- * @param {number} gravity          gravitational acceleration, m/s² (> 0)
- * @param {number} pushoffDistance  leg push-off distance, m (> 0)
- * @param {number} height           desired apex height above launch, m (>= 0)
- * @returns {number} push-off force in newtons
- */
-export function jumpForceForHeight(mass, gravity, pushoffDistance, height) {
-    assert.greaterThan(mass, 0, "mass");
-    assert.greaterThan(gravity, 0, "gravity");
-    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
-    assert.greaterThanOrEqual(height, 0, "height");
-
-    return (mass * gravity * height) / pushoffDistance;
-}
-
-/**
- * The apex height (meters) a given push-off force produces on this character —
- * the inverse of {@link jumpForceForHeight}.
- *
- *     h = F · d / (m · g)
- *
- * @param {number} force            push-off force, newtons (>= 0)
- * @param {number} mass             body mass, kg (> 0)
- * @param {number} gravity          gravitational acceleration, m/s² (> 0)
- * @param {number} pushoffDistance  leg push-off distance, m (> 0)
- * @returns {number} apex height above launch, meters
- */
-export function jumpHeightForForce(force, mass, gravity, pushoffDistance) {
-    assert.greaterThanOrEqual(force, 0, "force");
-    assert.greaterThan(mass, 0, "mass");
-    assert.greaterThan(gravity, 0, "gravity");
-    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
-
-    return (force * pushoffDistance) / (mass * gravity);
-}
-
-/**
- * The launch velocity (m/s) a given push-off force imparts to this character —
- * the forward conversion an ability applies at the instant of launch.
- *
- *     v₀ = √(2 · F · d / m)
- *
- * Note this is independent of gravity: gravity only governs the apex the launch
- * velocity then reaches, not the launch itself.
- *
- * @param {number} force            push-off force, newtons (>= 0)
- * @param {number} mass             body mass, kg (> 0)
- * @param {number} pushoffDistance  leg push-off distance, m (> 0)
- * @returns {number} launch velocity, m/s
- */
-export function launchVelocityForForce(force, mass, pushoffDistance) {
-    assert.greaterThanOrEqual(force, 0, "force");
-    assert.greaterThan(mass, 0, "mass");
-    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
-
-    return Math.sqrt((2 * force * pushoffDistance) / mass);
-}
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Jump power as physics, not a magic velocity.
+ *
+ * A jump is the legs doing WORK: a push-off force `F` (newtons) applied over a
+ * leg-extension distance `d` (meters) while the body is still on the ground.
+ * That work becomes the body's kinetic energy at the instant it leaves the
+ * ground, which gravity then trades back for height:
+ *
+ *     F · d   =   ½ · m · v₀²          (leg work → launch kinetic energy)
+ *     ½ · m · v₀²   =   m · g · h      (launch KE → potential energy at apex)
+ *
+ * Eliminating v₀ collapses the two into a single, mass-honest relationship
+ * between the force the legs deliver and the apex the body reaches:
+ *
+ *     h   =   F · d / (m · g)
+ *     F   =   m · g · h / d
+ *     v₀  =   √(2 · F · d / m)   =   √(2 · g · h)
+ *
+ * Why express jump power as a FORCE (newtons) rather than a launch velocity?
+ *   - It is a property of the CHARACTER (the legs), not of the jump. A fixed
+ *     leg force makes a heavier body jump lower — `h ∝ 1/m` — for free, which a
+ *     raw launch-velocity number cannot express (the same v₀ ignores mass).
+ *   - It composes: momentum, fatigue, and surface bonuses all add/scale in the
+ *     same physical currency (newtons) before a single conversion to velocity.
+ *
+ * `d` (the push-off distance) is the one extra parameter a newtons model needs:
+ * force alone can't determine a launch without the distance (or time) it acts
+ * over. It is a body constant — roughly the crouch-to-full-extension travel of
+ * the legs (~0.4–0.5 m for a ~1.8 m human countermovement jump).
+ *
+ * All three functions are pure and frame-independent. The headline is
+ * {@link jumpForceForHeight}: the newtons a designer needs to reach a desired
+ * apex on a given character. {@link launchVelocityForForce} is the forward
+ * conversion an ability applies at launch.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The push-off force (newtons) the legs must deliver for the body to reach a
+ * given apex height — i.e. newtons BACK-CALCULATED from the desired maximum
+ * jump height on this character.
+ *
+ *     F = m · g · h / d
+ *
+ * Heavier body → more force for the same height; stronger gravity → more force;
+ * a longer push-off distance → less force (the work is spread over more travel).
+ *
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} gravity          gravitational acceleration, m/s² (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @param {number} height           desired apex height above launch, m (>= 0)
+ * @returns {number} push-off force in newtons
+ */
+export function jumpForceForHeight(mass, gravity, pushoffDistance, height) {
+    assert.greaterThan(mass, 0, "mass");
+    assert.greaterThan(gravity, 0, "gravity");
+    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
+    assert.greaterThanOrEqual(height, 0, "height");
+
+    return (mass * gravity * height) / pushoffDistance;
+}
+
+/**
+ * The apex height (meters) a given push-off force produces on this character —
+ * the inverse of {@link jumpForceForHeight}.
+ *
+ *     h = F · d / (m · g)
+ *
+ * @param {number} force            push-off force, newtons (>= 0)
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} gravity          gravitational acceleration, m/s² (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @returns {number} apex height above launch, meters
+ */
+export function jumpHeightForForce(force, mass, gravity, pushoffDistance) {
+    assert.greaterThanOrEqual(force, 0, "force");
+    assert.greaterThan(mass, 0, "mass");
+    assert.greaterThan(gravity, 0, "gravity");
+    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
+
+    return (force * pushoffDistance) / (mass * gravity);
+}
+
+/**
+ * The launch velocity (m/s) a given push-off force imparts to this character —
+ * the forward conversion an ability applies at the instant of launch.
+ *
+ *     v₀ = √(2 · F · d / m)
+ *
+ * Note this is independent of gravity: gravity only governs the apex the launch
+ * velocity then reaches, not the launch itself.
+ *
+ * @param {number} force            push-off force, newtons (>= 0)
+ * @param {number} mass             body mass, kg (> 0)
+ * @param {number} pushoffDistance  leg push-off distance, m (> 0)
+ * @returns {number} launch velocity, m/s
+ */
+export function launchVelocityForForce(force, mass, pushoffDistance) {
+    assert.greaterThanOrEqual(force, 0, "force");
+    assert.greaterThan(mass, 0, "mass");
+    assert.greaterThan(pushoffDistance, 0, "pushoffDistance");
+
+    return Math.sqrt((2 * force * pushoffDistance) / mass);
+}

package/src/engine/control/first-person/math/stepTowards.js

@@ -1,20 +1,20 @@
-/**
- * Linearly step a scalar toward a target by at most `maxStep`. If the gap
- * is smaller than the step, snaps to target. Used for accel/decel on
- * horizontal velocity.
- *
- * @param {number} current
- * @param {number} target
- * @param {number} maxStep must be >= 0
- * @returns {number}
- */
-export function stepTowards(current, target, maxStep) {
-    const delta = target - current;
-    if (delta > maxStep) {
-        return current + maxStep;
-    }
-    if (delta < -maxStep) {
-        return current - maxStep;
-    }
-    return target;
-}
+/**
+ * Linearly step a scalar toward a target by at most `maxStep`. If the gap
+ * is smaller than the step, snaps to target. Used for accel/decel on
+ * horizontal velocity.
+ *
+ * @param {number} current
+ * @param {number} target
+ * @param {number} maxStep must be >= 0
+ * @returns {number}
+ */
+export function stepTowards(current, target, maxStep) {
+    const delta = target - current;
+    if (delta > maxStep) {
+        return current + maxStep;
+    }
+    if (delta < -maxStep) {
+        return current - maxStep;
+    }
+    return target;
+}

package/src/engine/control/first-person/pose/FirstPersonPose.js

@@ -1,137 +1,137 @@
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { FirstPersonPosture } from "./FirstPersonPosture.js";
-
-/**
- * Read-only outputs intended for a downstream skeleton system to consume.
- *
- * Surfaced as a separate struct (rather than reading {@link FirstPersonState}
- * directly) so that the skeleton-driving contract is stable even if
- * internal state representations change later. A future first-person arms
- * rig, third-person body rig, and network-replicated remote rig should all
- * be able to drive themselves from these channels alone.
- */
-
-/**
- * Vertical (kinetic) state — "what is the body doing in 3D space right now".
- * Independent of {@link FirstPersonLocomotionMode}; the player can be
- * Airborne while sprinting, Anticipating from a crouch, etc.
- * @readonly enum
- */
-export const FirstPersonActionState = {
-    Grounded: 0,
-    Anticipating: 1, // squashing down before jump impulse
-    Airborne: 2,
-    Landing: 3,
-};
-
-/**
- * Horizontal (intent-driven) locomotion mode. Drives the blend tree for the
- * skeletal rig's locomotion layer. Orthogonal to {@link FirstPersonActionState}
- * — a Sprint-mode player who jumps is `(Sprint, Airborne)` until they land.
- * @readonly enum
- */
-export const FirstPersonLocomotionMode = {
-    Idle: 0,
-    Walk: 1,
-    Sprint: 2,
-    Crouch: 3,
-};
-
-export class FirstPersonPose {
-    /**
-     * World-space body root.
-     * @type {Vector3}
-     */
-    rootPosition = new Vector3();
-
-    /**
-     * Body facing yaw (radians, around world up).
-     * @type {number}
-     */
-    rootYawRad = 0;
-
-    /**
-     * Head decoupled from body. For most first-person controllers
-     * headYawRad === rootYawRad; surfaced separately so future torso-twist
-     * rigs can lag the head.
-     * @type {number}
-     */
-    headYawRad = 0;
-
-    /**
-     * @type {number}
-     */
-    headPitchRad = 0;
-
-    /**
-     * Includes lean roll.
-     * @type {number}
-     */
-    headRollRad = 0;
-
-    /**
-     * Stride phase, [0..1). Same value the camera bob uses, so a feet rig
-     * driven by this will land its footfalls on the same frames the camera
-     * dips.
-     * @type {number}
-     */
-    locomotionPhase = 0;
-
-    /**
-     * m/s, horizontal speed. Drives a blend tree.
-     * @type {number}
-     */
-    locomotionSpeed = 0;
-
-    /**
-     * [-1..1] lateral component, for strafe-blend space.
-     * @type {number}
-     */
-    locomotionStrafe = 0;
-
-    /**
-     * Kinetic vertical state. See {@link FirstPersonActionState}.
-     * @type {number}
-     */
-    actionState = FirstPersonActionState.Grounded;
-
-    /**
-     * Horizontal locomotion intent mode. See {@link FirstPersonLocomotionMode}.
-     * @type {number}
-     */
-    locomotionMode = FirstPersonLocomotionMode.Idle;
-
-    /**
-     * [0..1] interpolation between standing and fully-crouched pose.
-     * Legacy field — pinned to (height − eyeHeight)/(height − crouchHeight),
-     * so a body in Prone reads ≥ 1.0 (saturated). Use {@link postureAmount}
-     * if the animator needs to distinguish Crouch / Prone / Hang.
-     * @type {number}
-     */
-    crouchAmount = 0;
-
-    /**
-     * Current body shape. Picks which animation track the rig should
-     * blend toward — Stand / Crouch / Prone / Hang. See
-     * {@link FirstPersonPosture}.
-     * @type {number}
-     */
-    posture = FirstPersonPosture.Stand;
-
-    /**
-     * [0..1] blend weight from Stand toward the current {@link posture}.
-     * 0 = fully standing (postures hold-frame is the standing rig);
-     * 1 = fully in the posture's target shape. Computed from eye-height
-     * relative to the posture's target height, so the value transitions
-     * smoothly with the same spring the camera uses.
-     * @type {number}
-     */
-    postureAmount = 0;
-
-    /**
-     * Same as headPitchRad, surfaced separately for IK consumers that only
-     * need the aim axis.
-     * @type {number}
-     */
-    aimPitch = 0;
-}
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { FirstPersonPosture } from "./FirstPersonPosture.js";
+
+/**
+ * Read-only outputs intended for a downstream skeleton system to consume.
+ *
+ * Surfaced as a separate struct (rather than reading {@link FirstPersonState}
+ * directly) so that the skeleton-driving contract is stable even if
+ * internal state representations change later. A future first-person arms
+ * rig, third-person body rig, and network-replicated remote rig should all
+ * be able to drive themselves from these channels alone.
+ */
+
+/**
+ * Vertical (kinetic) state — "what is the body doing in 3D space right now".
+ * Independent of {@link FirstPersonLocomotionMode}; the player can be
+ * Airborne while sprinting, Anticipating from a crouch, etc.
+ * @readonly enum
+ */
+export const FirstPersonActionState = {
+    Grounded: 0,
+    Anticipating: 1, // squashing down before jump impulse
+    Airborne: 2,
+    Landing: 3,
+};
+
+/**
+ * Horizontal (intent-driven) locomotion mode. Drives the blend tree for the
+ * skeletal rig's locomotion layer. Orthogonal to {@link FirstPersonActionState}
+ * — a Sprint-mode player who jumps is `(Sprint, Airborne)` until they land.
+ * @readonly enum
+ */
+export const FirstPersonLocomotionMode = {
+    Idle: 0,
+    Walk: 1,
+    Sprint: 2,
+    Crouch: 3,
+};
+
+export class FirstPersonPose {
+    /**
+     * World-space body root.
+     * @type {Vector3}
+     */
+    rootPosition = new Vector3();
+
+    /**
+     * Body facing yaw (radians, around world up).
+     * @type {number}
+     */
+    rootYawRad = 0;
+
+    /**
+     * Head decoupled from body. For most first-person controllers
+     * headYawRad === rootYawRad; surfaced separately so future torso-twist
+     * rigs can lag the head.
+     * @type {number}
+     */
+    headYawRad = 0;
+
+    /**
+     * @type {number}
+     */
+    headPitchRad = 0;
+
+    /**
+     * Includes lean roll.
+     * @type {number}
+     */
+    headRollRad = 0;
+
+    /**
+     * Stride phase, [0..1). Same value the camera bob uses, so a feet rig
+     * driven by this will land its footfalls on the same frames the camera
+     * dips.
+     * @type {number}
+     */
+    locomotionPhase = 0;
+
+    /**
+     * m/s, horizontal speed. Drives a blend tree.
+     * @type {number}
+     */
+    locomotionSpeed = 0;
+
+    /**
+     * [-1..1] lateral component, for strafe-blend space.
+     * @type {number}
+     */
+    locomotionStrafe = 0;
+
+    /**
+     * Kinetic vertical state. See {@link FirstPersonActionState}.
+     * @type {number}
+     */
+    actionState = FirstPersonActionState.Grounded;
+
+    /**
+     * Horizontal locomotion intent mode. See {@link FirstPersonLocomotionMode}.
+     * @type {number}
+     */
+    locomotionMode = FirstPersonLocomotionMode.Idle;
+
+    /**
+     * [0..1] interpolation between standing and fully-crouched pose.
+     * Legacy field — pinned to (height − eyeHeight)/(height − crouchHeight),
+     * so a body in Prone reads ≥ 1.0 (saturated). Use {@link postureAmount}
+     * if the animator needs to distinguish Crouch / Prone / Hang.
+     * @type {number}
+     */
+    crouchAmount = 0;
+
+    /**
+     * Current body shape. Picks which animation track the rig should
+     * blend toward — Stand / Crouch / Prone / Hang. See
+     * {@link FirstPersonPosture}.
+     * @type {number}
+     */
+    posture = FirstPersonPosture.Stand;
+
+    /**
+     * [0..1] blend weight from Stand toward the current {@link posture}.
+     * 0 = fully standing (postures hold-frame is the standing rig);
+     * 1 = fully in the posture's target shape. Computed from eye-height
+     * relative to the posture's target height, so the value transitions
+     * smoothly with the same spring the camera uses.
+     * @type {number}
+     */
+    postureAmount = 0;
+
+    /**
+     * Same as headPitchRad, surfaced separately for IK consumers that only
+     * need the aim axis.
+     * @type {number}
+     */
+    aimPitch = 0;
+}

package/src/engine/control/first-person/pose/FirstPersonPosture.js

@@ -1,27 +1,27 @@
-/**
- * Body posture — discrete shape the body holds. Drives eye height and
- * gait gating (stride / footstep / bob).
- *
- * The base controller computes posture from intent each tick (Stand vs.
- * Crouch). Abilities own the posture while they're active and can force
- * Prone (slide) or Hang (ledge-grab). When an ability releases, the
- * next base tick re-derives posture from intent.
- *
- * Why a single enum field rather than override sentinels: a uniform
- * channel that every consumer (eye-height spring, stride gate, future
- * skeleton animator) reads from one place. Adding a new posture means
- * adding one enum value + one mapping, not threading "is X overriding
- * Y" sentinels through L2.
- *
- * @readonly enum
- */
-export const FirstPersonPosture = {
-    /** Upright on both feet — the default. Strides normally. */
-    Stand: 0,
-    /** Knees bent, head dropped — feet still strike the ground. */
-    Crouch: 1,
-    /** Body horizontal — sliding or diving. No stride; eye near ground. */
-    Prone: 2,
-    /** Suspended from hands — hanging on a ledge. No stride. */
-    Hang: 3,
-};
+/**
+ * Body posture — discrete shape the body holds. Drives eye height and
+ * gait gating (stride / footstep / bob).
+ *
+ * The base controller computes posture from intent each tick (Stand vs.
+ * Crouch). Abilities own the posture while they're active and can force
+ * Prone (slide) or Hang (ledge-grab). When an ability releases, the
+ * next base tick re-derives posture from intent.
+ *
+ * Why a single enum field rather than override sentinels: a uniform
+ * channel that every consumer (eye-height spring, stride gate, future
+ * skeleton animator) reads from one place. Adding a new posture means
+ * adding one enum value + one mapping, not threading "is X overriding
+ * Y" sentinels through L2.
+ *
+ * @readonly enum
+ */
+export const FirstPersonPosture = {
+    /** Upright on both feet — the default. Strides normally. */
+    Stand: 0,
+    /** Knees bent, head dropped — feet still strike the ground. */
+    Crouch: 1,
+    /** Body horizontal — sliding or diving. No stride; eye near ground. */
+    Prone: 2,
+    /** Suspended from hands — hanging on a ledge. No stride. */
+    Hang: 3,
+};

package/src/engine/control/first-person/test/buildTestPlayer.js

@@ -1,36 +1,36 @@
-import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
-import { TransformedShape3D } from "../../../../core/geom/3d/shape/TransformedShape3D.js";
-import { BodyKind } from "../../../physics/ecs/BodyKind.js";
-import { Collider } from "../../../physics/ecs/Collider.js";
-import { RigidBody } from "../../../physics/ecs/RigidBody.js";
-
-/**
- * Spec-side helper: build the RigidBody + Collider pair the controller's
- * link() expects. Each test's makeWorld() can call this after
- * constructing the controller + transform, adding both components to
- * the entity builder before `.build(ecd)`.
- *
- * Capsule dimensions are loose — the prototype sizes them from
- * `cfg.body` but tests don't exercise the actual collision shape; what
- * matters for the controller's assert is that a RigidBody of the right
- * kind is present.
- *
- * @returns {{ rigidBody: RigidBody, collider: Collider }}
- */
-export function buildTestPlayerBody() {
-    const rigidBody = new RigidBody();
-    rigidBody.kind = BodyKind.KinematicPosition;
-    rigidBody.mass = 1;
-
-    const collider = new Collider();
-    // Capsule lives in [feet .. head] in world space — see the prototype's
-    // buildPlayerEntity for the rationale. Wrap the centred CapsuleShape3D
-    // in a TransformedShape3D with a +Y offset of half the body height
-    // (1.8 / 2 = 0.9), matching prototype geometry.
-    collider.shape = TransformedShape3D.from_translation(
-        CapsuleShape3D.from(0.34, 1.12),
-        [0, 0.9, 0],
-    );
-
-    return { rigidBody, collider };
-}
+import { CapsuleShape3D } from "../../../../core/geom/3d/shape/CapsuleShape3D.js";
+import { TransformedShape3D } from "../../../../core/geom/3d/shape/TransformedShape3D.js";
+import { BodyKind } from "../../../physics/ecs/BodyKind.js";
+import { Collider } from "../../../physics/ecs/Collider.js";
+import { RigidBody } from "../../../physics/ecs/RigidBody.js";
+
+/**
+ * Spec-side helper: build the RigidBody + Collider pair the controller's
+ * link() expects. Each test's makeWorld() can call this after
+ * constructing the controller + transform, adding both components to
+ * the entity builder before `.build(ecd)`.
+ *
+ * Capsule dimensions are loose — the prototype sizes them from
+ * `cfg.body` but tests don't exercise the actual collision shape; what
+ * matters for the controller's assert is that a RigidBody of the right
+ * kind is present.
+ *
+ * @returns {{ rigidBody: RigidBody, collider: Collider }}
+ */
+export function buildTestPlayerBody() {
+    const rigidBody = new RigidBody();
+    rigidBody.kind = BodyKind.KinematicPosition;
+    rigidBody.mass = 1;
+
+    const collider = new Collider();
+    // Capsule lives in [feet .. head] in world space — see the prototype's
+    // buildPlayerEntity for the rationale. Wrap the centred CapsuleShape3D
+    // in a TransformedShape3D with a +Y offset of half the body height
+    // (1.8 / 2 = 0.9), matching prototype geometry.
+    collider.shape = TransformedShape3D.from_translation(
+        CapsuleShape3D.from(0.34, 1.12),
+        [0, 0.9, 0],
+    );
+
+    return { rigidBody, collider };
+}