@quake2ts/shared 0.0.1

package/src/pmove/pmove.ts

@@ -0,0 +1,446 @@
+import type { Vec3 } from '../math/vec3.js';
+import { addVec3, dotVec3, lengthVec3, normalizeVec3, scaleVec3 } from '../math/vec3.js';
+import { angleVectors } from '../math/angles.js';
+import type {
+  PmoveAccelerateParams,
+  PmoveCmd,
+  PmoveFrictionParams,
+  PmoveWishParams,
+  PmoveWishResult,
+  PmoveState,
+  PmoveImports,
+  PmoveTraceResult
+} from './types.js';
+import { PlayerButton, PmFlag, PmType, addPmFlag, removePmFlag } from './constants.js';
+import { checkJump } from './jump.js';
+import { applyPmoveAirMove, applyPmoveWaterMove, applyPmoveWalkMove } from './move.js';
+import { categorizePosition } from './categorize.js';
+import { checkDuckState, DuckTraceParams } from './duck.js';
+// import { updateViewOffsets } from './view.js';
+
+const FRAMETIME = 0.025; // Define FRAMETIME here or import if available in constants? Using local definition for now as per previous context.
+
+/**
+ * Pure version of PM_Friction from rerelease p_move.cpp.
+ * Handles ground and water friction and returns a new velocity.
+ */
+export function applyPmoveFriction(params: PmoveFrictionParams): Vec3 {
+  const {
+    velocity,
+    frametime,
+    onGround,
+    groundIsSlick,
+    onLadder,
+    waterlevel,
+    pmFriction,
+    pmStopSpeed,
+    pmWaterFriction,
+  } = params;
+
+  const speed = lengthVec3(velocity);
+
+  // Matches the "if (speed < 1)" early-out: clears X/Y but preserves Z.
+  if (speed < 1) {
+    return { x: 0, y: 0, z: velocity.z };
+  }
+
+  let drop = 0;
+
+  // Ground friction (or ladder)
+  if ((onGround && !groundIsSlick) || onLadder) {
+    const control = speed < pmStopSpeed ? pmStopSpeed : speed;
+    const friction = pmFriction;
+    drop += control * friction * frametime;
+  }
+
+  // Water friction (only when not on ladder)
+  if (waterlevel > 0 && !onLadder) {
+    drop += speed * pmWaterFriction * waterlevel * frametime;
+  }
+
+  let newspeed = speed - drop;
+  if (newspeed < 0) {
+    newspeed = 0;
+  }
+
+  if (newspeed === speed) {
+    return velocity;
+  }
+
+  const scale = newspeed / speed;
+  return scaleVec3(velocity, scale);
+}
+
+/**
+ * Pure version of PM_Accelerate from rerelease p_move.cpp.
+ * Returns a new velocity with wishdir/wishspeed acceleration applied.
+ */
+export function applyPmoveAccelerate(params: PmoveAccelerateParams): Vec3 {
+  const { velocity, wishdir, wishspeed, accel, frametime } = params;
+
+  const currentSpeed = dotVec3(velocity, wishdir);
+  const addSpeed = wishspeed - currentSpeed;
+
+  if (addSpeed <= 0) {
+    return velocity;
+  }
+
+  let accelSpeed = accel * frametime * wishspeed;
+  if (accelSpeed > addSpeed) {
+    accelSpeed = addSpeed;
+  }
+
+  return {
+    x: velocity.x + wishdir.x * accelSpeed,
+    y: velocity.y + wishdir.y * accelSpeed,
+    z: velocity.z + wishdir.z * accelSpeed,
+  };
+}
+
+/**
+ * Mirrors PM_AirAccelerate in rerelease `p_move.cpp` (lines ~612-636): wishspeed is clamped
+ * to 30 for the addspeed calculation but the acceleration magnitude still uses the full wishspeed.
+ */
+export function applyPmoveAirAccelerate(params: PmoveAccelerateParams): Vec3 {
+  const { velocity, wishdir, wishspeed, accel, frametime } = params;
+
+  const wishspd = Math.min(wishspeed, 30);
+  const currentSpeed = dotVec3(velocity, wishdir);
+  const addSpeed = wishspd - currentSpeed;
+
+  if (addSpeed <= 0) {
+    return velocity;
+  }
+
+  let accelSpeed = accel * wishspeed * frametime;
+  if (accelSpeed > addSpeed) {
+    accelSpeed = addSpeed;
+  }
+
+  return {
+    x: velocity.x + wishdir.x * accelSpeed,
+    y: velocity.y + wishdir.y * accelSpeed,
+    z: velocity.z + wishdir.z * accelSpeed,
+  };
+}
+
+/**
+ * Pure mirror of PM_CmdScale from rerelease `p_move.cpp`. Computes the scalar applied to
+ * the command directional inputs so that the resulting wish velocity caps at `maxSpeed`
+ * regardless of the directional mix.
+ */
+export function pmoveCmdScale(cmd: PmoveCmd, maxSpeed: number): number {
+  const forward = Math.abs(cmd.forwardmove);
+  const side = Math.abs(cmd.sidemove);
+  const up = Math.abs(cmd.upmove);
+
+  const max = Math.max(forward, side, up);
+  if (max === 0) {
+    return 0;
+  }
+
+  const total = Math.sqrt(cmd.forwardmove * cmd.forwardmove + cmd.sidemove * cmd.sidemove + cmd.upmove * cmd.upmove);
+  return (maxSpeed * max) / (127 * total);
+}
+
+/**
+ * Computes wishdir/wishspeed for ground/air movement as done in PM_AirMove and
+ * PM_GroundMove. Z is forced to zero and wishspeed is clamped to maxSpeed, matching
+ * the rerelease p_move.cpp helpers before they call PM_Accelerate/PM_AirAccelerate.
+ */
+export function buildAirGroundWish(params: PmoveWishParams): PmoveWishResult {
+  const { forward, right, cmd, maxSpeed } = params;
+
+  let wishvel = {
+    x: forward.x * cmd.forwardmove + right.x * cmd.sidemove,
+    y: forward.y * cmd.forwardmove + right.y * cmd.sidemove,
+    z: 0,
+  } satisfies Vec3;
+
+  let wishspeed = lengthVec3(wishvel);
+  if (wishspeed > maxSpeed) {
+    const scale = maxSpeed / wishspeed;
+    wishvel = scaleVec3(wishvel, scale);
+    wishspeed = maxSpeed;
+  }
+
+  return {
+    wishdir: wishspeed === 0 ? wishvel : normalizeVec3(wishvel),
+    wishspeed,
+  };
+}
+
+/**
+ * Computes the wishdir/wishspeed mix for water movement, matching PM_WaterMove in
+ * rerelease p_move.cpp: includes the upward bias when no strong upmove is requested,
+ * clamps wishspeed to maxSpeed, and halves the returned wishspeed before acceleration.
+ */
+export function buildWaterWish(params: PmoveWishParams): PmoveWishResult {
+  const { forward, right, cmd, maxSpeed } = params;
+
+  // Use full 3D components for water movement
+  let wishvel = {
+    x: forward.x * cmd.forwardmove + right.x * cmd.sidemove,
+    y: forward.y * cmd.forwardmove + right.y * cmd.sidemove,
+    z: forward.z * cmd.forwardmove + right.z * cmd.sidemove,
+  } satisfies Vec3;
+
+  if (cmd.upmove > 10) {
+    wishvel = addVec3(wishvel, { x: 0, y: 0, z: cmd.upmove });
+  } else if (cmd.upmove < -10) {
+    wishvel = addVec3(wishvel, { x: 0, y: 0, z: cmd.upmove });
+  } else if (Math.abs(cmd.forwardmove) < 10 && Math.abs(cmd.sidemove) < 10) {
+    // Standard drift down when no vertical input AND no significant horizontal input
+    // Matches Quake 2 rerelease behavior (sinking slowly)
+    wishvel = addVec3(wishvel, { x: 0, y: 0, z: -60 });
+  } else {
+    // When moving horizontally but not vertically, drift slightly up
+    // This matches the "else { wishvel[2] += 10 }" logic in PM_WaterMove
+    wishvel = addVec3(wishvel, { x: 0, y: 0, z: 10 });
+  }
+
+  let wishspeed = lengthVec3(wishvel);
+  if (wishspeed > maxSpeed) {
+    const scale = maxSpeed / wishspeed;
+    wishvel = scaleVec3(wishvel, scale);
+    wishspeed = maxSpeed;
+  }
+
+  wishspeed *= 0.5;
+
+  return {
+    wishdir: wishspeed === 0 ? wishvel : normalizeVec3(wishvel),
+    wishspeed,
+  };
+}
+
+/**
+ * Runs the full player movement simulation for a single frame.
+ */
+export function runPmove(state: PmoveState, imports: PmoveImports): PmoveState {
+  if (state.pmType === PmType.Dead) {
+    return state;
+  }
+
+  let nextState = { ...state };
+
+  // Categorize Position
+  const catResult = categorizePosition({
+    pmType: nextState.pmType,
+    pmFlags: nextState.pmFlags,
+    pmTime: 0,
+    n64Physics: false,
+    velocity: nextState.velocity,
+    startVelocity: nextState.velocity,
+    origin: nextState.origin,
+    mins: nextState.mins,
+    maxs: nextState.maxs,
+    viewheight: nextState.viewHeight,
+    trace: imports.trace,
+    pointContents: imports.pointcontents
+  });
+
+  // Merge result back to state
+  nextState.pmFlags = catResult.pmFlags;
+  nextState.waterlevel = catResult.waterlevel;
+  nextState.watertype = catResult.watertype;
+
+  // Check Ducking (Before Jump)
+  const duckResult = checkDuckState({
+    pmType: nextState.pmType,
+    pmFlags: nextState.pmFlags,
+    buttons: nextState.cmd.buttons,
+    waterlevel: nextState.waterlevel,
+    hasGroundEntity: (nextState.pmFlags & PmFlag.OnGround) !== 0,
+    onLadder: false,
+    n64Physics: false,
+    origin: nextState.origin,
+    mins: nextState.mins,
+    maxs: nextState.maxs,
+    trace: (params: DuckTraceParams): PmoveTraceResult => {
+      // Adapter from DuckTraceFn (obj) to PmoveTraceFn (args)
+      return imports.trace(params.start, params.end, params.mins, params.maxs);
+    }
+  });
+
+  nextState.pmFlags = duckResult.pmFlags;
+  nextState.mins = duckResult.mins;
+  nextState.maxs = duckResult.maxs;
+  nextState.viewHeight = duckResult.viewheight;
+
+  // Check Jump
+  const jumpResult = checkJump({
+    pmFlags: nextState.pmFlags,
+    pmType: nextState.pmType,
+    buttons: nextState.cmd.buttons,
+    waterlevel: nextState.waterlevel,
+    onGround: (nextState.pmFlags & PmFlag.OnGround) !== 0,
+    velocity: nextState.velocity,
+    origin: nextState.origin
+  });
+
+  nextState.pmFlags = jumpResult.pmFlags;
+  nextState.velocity = jumpResult.velocity;
+  nextState.origin = jumpResult.origin;
+
+  if (jumpResult.onGround !== ((nextState.pmFlags & PmFlag.OnGround) !== 0)) {
+     if (jumpResult.onGround) {
+       nextState.pmFlags = addPmFlag(nextState.pmFlags, PmFlag.OnGround);
+     } else {
+       nextState.pmFlags = removePmFlag(nextState.pmFlags, PmFlag.OnGround);
+     }
+  }
+
+  // Frictional movement
+  const onGround = (nextState.pmFlags & PmFlag.OnGround) !== 0;
+
+  // Apply friction
+  const velocityBeforeFriction = nextState.velocity;
+  nextState.velocity = applyPmoveFriction({
+      velocity: nextState.velocity,
+      frametime: FRAMETIME,
+      onGround,
+      groundIsSlick: false,
+      onLadder: false, // Defaulting to false for now as ladder logic is complex
+      waterlevel: nextState.waterlevel,
+      pmFriction: 6, // Default
+      pmStopSpeed: 100, // Default
+      pmWaterFriction: 1 // Default
+  });
+
+  // Calculate view vectors from angles
+  const { forward, right } = angleVectors(nextState.viewAngles);
+
+  if (nextState.pmType === PmType.NoClip) {
+    // PM_NoclipMove
+    // Simplified noclip
+    const wishvel = {
+         x: forward.x * nextState.cmd.forwardmove + right.x * nextState.cmd.sidemove,
+         y: forward.y * nextState.cmd.forwardmove + right.y * nextState.cmd.sidemove,
+         z: nextState.cmd.upmove
+    };
+    const scale = FRAMETIME; // Just move by velocity
+    // Actually we need to apply velocity based on input
+    // But sticking to just what's needed for jumping/movement:
+    nextState.velocity = wishvel; // Simple override for noclip
+    nextState.origin = {
+        x: nextState.origin.x + wishvel.x * scale,
+        y: nextState.origin.y + wishvel.y * scale,
+        z: nextState.origin.z + wishvel.z * scale
+    };
+
+  } else if (nextState.waterlevel >= 2) {
+    const outcome = applyPmoveWaterMove({
+        origin: nextState.origin,
+        velocity: nextState.velocity,
+        frametime: FRAMETIME,
+        mins: nextState.mins,
+        maxs: nextState.maxs,
+        trace: imports.trace,
+        cmd: nextState.cmd,
+        forward,
+        right,
+        pmFlags: nextState.pmFlags,
+        onGround,
+        pmMaxSpeed: 300,
+        pmDuckSpeed: 100,
+        pmWaterAccelerate: 4,
+        pmWaterSpeed: 400,
+        onLadder: false,
+        watertype: nextState.watertype,
+        groundContents: 0, // Should be passed in?
+        waterlevel: nextState.waterlevel,
+        viewPitch: nextState.viewAngles.x,
+        ladderMod: 1,
+        stepSize: 18 // Added stepSize for consistency, though water move might not use it heavily
+    });
+    nextState.origin = outcome.origin;
+    nextState.velocity = outcome.velocity;
+
+  } else if ((nextState.pmFlags & PmFlag.OnGround) === 0) {
+     const outcome = applyPmoveAirMove({
+        origin: nextState.origin,
+        velocity: nextState.velocity,
+        frametime: FRAMETIME,
+        mins: nextState.mins,
+        maxs: nextState.maxs,
+        trace: imports.trace,
+        cmd: nextState.cmd,
+        forward,
+        right,
+        pmFlags: nextState.pmFlags,
+        onGround,
+        gravity: nextState.gravity,
+        pmType: nextState.pmType,
+        pmAccelerate: 10,
+        pmAirAccelerate: 1,
+        pmMaxSpeed: 300,
+        pmDuckSpeed: 100,
+        onLadder: false,
+        waterlevel: nextState.waterlevel,
+        watertype: nextState.watertype,
+        groundContents: 0,
+        viewPitch: nextState.viewAngles.x,
+        ladderMod: 1,
+        pmWaterSpeed: 400,
+        stepSize: 18 // Added stepSize
+    });
+    nextState.origin = outcome.origin;
+    nextState.velocity = outcome.velocity;
+
+  } else {
+     const outcome = applyPmoveWalkMove({
+        origin: nextState.origin,
+        velocity: nextState.velocity,
+        frametime: FRAMETIME,
+        mins: nextState.mins,
+        maxs: nextState.maxs,
+        trace: imports.trace,
+        cmd: nextState.cmd,
+        forward,
+        right,
+        pmFlags: nextState.pmFlags,
+        onGround,
+        gravity: nextState.gravity,
+        pmType: nextState.pmType,
+        pmAccelerate: 10,
+        pmMaxSpeed: 300,
+        pmDuckSpeed: 100,
+        onLadder: false,
+        waterlevel: nextState.waterlevel,
+        watertype: nextState.watertype,
+        groundContents: 0,
+        viewPitch: nextState.viewAngles.x,
+        ladderMod: 1,
+        pmWaterSpeed: 400,
+        stepSize: 18 // Added stepSize
+    });
+    nextState.origin = outcome.origin;
+    nextState.velocity = outcome.velocity;
+  }
+
+  // Categorize Position again at end of frame
+  const catResultEnd = categorizePosition({
+    pmType: nextState.pmType,
+    pmFlags: nextState.pmFlags,
+    pmTime: 0,
+    n64Physics: false,
+    velocity: nextState.velocity,
+    startVelocity: nextState.velocity,
+    origin: nextState.origin,
+    mins: nextState.mins,
+    maxs: nextState.maxs,
+    viewheight: nextState.viewHeight,
+    trace: imports.trace,
+    pointContents: imports.pointcontents
+  });
+
+  nextState.pmFlags = catResultEnd.pmFlags;
+  nextState.waterlevel = catResultEnd.waterlevel;
+  nextState.watertype = catResultEnd.watertype;
+
+  // Update view offsets (bobbing, etc)
+  // nextState = updateViewOffsets(nextState);
+
+  return nextState;
+}

package/src/pmove/slide.ts

@@ -0,0 +1,267 @@
+import { addVec3, ZERO_VEC3, clipVelocityVec3, crossVec3, dotVec3, scaleVec3, type Vec3 } from '../math/vec3.js';
+import type { PmoveTraceFn } from './types.js';
+
+const DEFAULT_MAX_CLIP_PLANES = 5;
+const DEFAULT_MAX_BUMPS = 4;
+const DEFAULT_STEP_SIZE = 18;
+const MIN_STEP_NORMAL = 0.7;
+
+export const SLIDEMOVE_BLOCKED_FLOOR = 1;
+export const SLIDEMOVE_BLOCKED_WALL = 2;
+
+export interface SlideMoveResult {
+  readonly velocity: Vec3;
+  readonly planes: readonly Vec3[];
+  readonly stopped: boolean;
+}
+
+export interface SlideMoveParams {
+  readonly origin: Vec3;
+  readonly velocity: Vec3;
+  readonly frametime: number;
+  readonly overbounce: number;
+  readonly trace: PmoveTraceFn;
+  readonly maxBumps?: number;
+  readonly maxClipPlanes?: number;
+  readonly mins?: Vec3;
+  readonly maxs?: Vec3;
+  /**
+   * Mirrors the pm->s.pm_time check in PM_StepSlideMove_Generic: if true, the
+   * returned velocity is reset to the primal velocity after collision
+   * resolution so time-based effects (like knockbacks) don't dampen.
+   */
+  readonly hasTime?: boolean;
+}
+
+export interface SlideMoveOutcome extends SlideMoveResult {
+  readonly origin: Vec3;
+  readonly blocked: number;
+}
+
+export interface StepSlideMoveParams extends SlideMoveParams {
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly stepSize?: number;
+}
+
+export interface StepSlideMoveOutcome extends SlideMoveOutcome {
+  readonly stepped: boolean;
+  readonly stepHeight: number;
+  readonly stepNormal?: Vec3;
+}
+
+/**
+ * Resolves a sequence of collision planes against a primal velocity using the same
+ * plane iteration logic seen in PM_StepSlideMove_Generic (rerelease p_move.cpp).
+ * The incoming planes should be ordered as they were encountered during traces;
+ * the function will accumulate them, clip the velocity to be parallel to all planes,
+ * and return zero velocity when three planes form an unresolvable corner or when
+ * the adjusted velocity would oppose the primal direction.
+ */
+export function resolveSlideMove(
+  initialVelocity: Vec3,
+  planesEncountered: readonly Vec3[],
+  overbounce: number,
+  maxClipPlanes = DEFAULT_MAX_CLIP_PLANES,
+  primalVelocity: Vec3 = initialVelocity,
+): SlideMoveResult {
+  if (planesEncountered.length === 0) {
+    return { velocity: initialVelocity, planes: [], stopped: false };
+  }
+
+  const planes: Vec3[] = [];
+  let velocity: Vec3 = initialVelocity;
+
+  for (const plane of planesEncountered) {
+    if (planes.length >= maxClipPlanes) {
+      return { velocity: ZERO_VEC3, planes, stopped: true };
+    }
+
+    // Skip near-duplicate planes to mirror the epsilon guard in PM_StepSlideMove_Generic.
+    const duplicate = planes.find((existing) => dotVec3(existing, plane) > 0.99);
+    if (duplicate) {
+      continue;
+    }
+
+    planes.push(plane);
+
+    let clipped: Vec3 | undefined;
+    let i = 0;
+    for (; i < planes.length; i++) {
+      const candidate = clipVelocityVec3(velocity, planes[i], overbounce);
+
+      let j = 0;
+      for (; j < planes.length; j++) {
+        if (j === i) continue;
+        if (dotVec3(candidate, planes[j]) < 0) break;
+      }
+
+      if (j === planes.length) {
+        clipped = candidate;
+        break;
+      }
+    }
+
+    if (clipped) {
+      velocity = clipped;
+    } else {
+      if (planes.length !== 2) {
+        return { velocity: ZERO_VEC3, planes, stopped: true };
+      }
+
+      const dir = crossVec3(planes[0], planes[1]);
+      const d = dotVec3(dir, velocity);
+      velocity = scaleVec3(dir, d);
+    }
+
+    // If velocity reversed relative to the primal direction, stop to avoid oscillations.
+    if (dotVec3(velocity, primalVelocity) <= 0) {
+      return { velocity: ZERO_VEC3, planes, stopped: true };
+    }
+  }
+
+  const stopped = velocity.x === 0 && velocity.y === 0 && velocity.z === 0;
+  return { velocity, planes, stopped };
+}
+
+/**
+ * Pure mirror of PM_SlideMoveGeneric from rerelease `p_move.cpp` (minus gravity/step handling).
+ * Uses a caller-provided trace to collect collision planes, accumulates them through
+ * `resolveSlideMove`, and returns the resulting origin/velocity/blocking state.
+ */
+export function slideMove(params: SlideMoveParams): SlideMoveOutcome {
+  const {
+    origin: initialOrigin,
+    velocity: initialVelocity,
+    frametime,
+    overbounce,
+    trace,
+    maxBumps = DEFAULT_MAX_BUMPS,
+    maxClipPlanes = DEFAULT_MAX_CLIP_PLANES,
+    mins,
+    maxs,
+    hasTime = false,
+  } = params;
+
+  let origin = initialOrigin;
+  let velocity = initialVelocity;
+  const planes: Vec3[] = [];
+  const primalVelocity = initialVelocity;
+  let timeLeft = frametime;
+  let blocked = 0;
+
+  for (let bump = 0; bump < maxBumps; bump++) {
+    if (velocity.x === 0 && velocity.y === 0 && velocity.z === 0) {
+      break;
+    }
+
+    const end = addVec3(origin, scaleVec3(velocity, timeLeft));
+    const tr = trace(origin, end, mins, maxs);
+
+    if (tr.allsolid) {
+      const velocity = hasTime ? primalVelocity : ZERO_VEC3;
+      return { origin: tr.endpos, velocity, planes, stopped: true, blocked };
+    }
+
+    if (tr.startsolid) {
+      const velocity = hasTime ? primalVelocity : ZERO_VEC3;
+      return { origin: tr.endpos, velocity, planes, stopped: true, blocked };
+    }
+
+    if (tr.fraction > 0) {
+      origin = tr.endpos;
+    }
+
+    if (tr.fraction === 1) {
+      break;
+    }
+
+    if (!tr.planeNormal) {
+      const velocity = hasTime ? primalVelocity : ZERO_VEC3;
+      return { origin, velocity, planes, stopped: true, blocked };
+    }
+
+    if (tr.planeNormal.z > 0.7) {
+      blocked |= SLIDEMOVE_BLOCKED_FLOOR;
+    }
+    if (tr.planeNormal.z === 0) {
+      blocked |= SLIDEMOVE_BLOCKED_WALL;
+    }
+
+    planes.push(tr.planeNormal);
+    timeLeft -= timeLeft * tr.fraction;
+
+    const resolved = resolveSlideMove(velocity, planes, overbounce, maxClipPlanes, primalVelocity);
+    velocity = resolved.velocity;
+    planes.splice(0, planes.length, ...resolved.planes);
+
+    if (primalVelocity.z > 0 && velocity.z < 0) {
+      velocity = { ...velocity, z: 0 };
+    }
+
+    if (resolved.stopped) {
+      const velocityOut = hasTime ? primalVelocity : velocity;
+      return { origin, velocity: velocityOut, planes, stopped: true, blocked };
+    }
+  }
+
+  const velocityOut = hasTime ? primalVelocity : velocity;
+  return { origin, velocity: velocityOut, planes, stopped: velocityOut.x === 0 && velocityOut.y === 0 && velocityOut.z === 0, blocked };
+}
+
+/**
+ * Mirrors PM_StepSlideMove (rerelease p_move.cpp) in a pure form: attempts a
+ * regular slide move, then retries from a stepped-up position when the first
+ * attempt was blocked. The function compares planar distance traveled and the
+ * steepness of the landing plane to decide whether to keep the step.
+ */
+export function stepSlideMove(params: StepSlideMoveParams): StepSlideMoveOutcome {
+  const { mins, maxs, stepSize = DEFAULT_STEP_SIZE, ...rest } = params;
+
+  const startOrigin = params.origin;
+  const startVelocity = params.velocity;
+
+  const downResult = slideMove({ ...rest, mins, maxs });
+
+  const upTarget = addVec3(startOrigin, { x: 0, y: 0, z: stepSize });
+  const upTrace = rest.trace(startOrigin, upTarget, mins, maxs);
+  if (upTrace.allsolid) {
+    return { ...downResult, stepped: false, stepHeight: 0 };
+  }
+
+  const actualStep = upTrace.endpos.z - startOrigin.z;
+  const steppedResult = slideMove({ ...rest, origin: upTrace.endpos, velocity: startVelocity, mins, maxs });
+
+  const pushDownTarget = addVec3(steppedResult.origin, { x: 0, y: 0, z: -actualStep });
+  const downTrace = rest.trace(steppedResult.origin, pushDownTarget, mins, maxs);
+
+  let steppedOrigin = steppedResult.origin;
+  let stepNormal = downTrace.planeNormal;
+
+  if (!downTrace.allsolid) {
+    steppedOrigin = downTrace.endpos;
+  }
+
+  const planarDistanceSquared = (a: Vec3, b: Vec3) => (a.x - b.x) ** 2 + (a.y - b.y) ** 2;
+  const downDist = planarDistanceSquared(downResult.origin, startOrigin);
+  const upDist = planarDistanceSquared(steppedOrigin, startOrigin);
+
+  if (downDist > upDist || (stepNormal && stepNormal.z < MIN_STEP_NORMAL)) {
+    return { ...downResult, stepped: false, stepHeight: 0 };
+  }
+
+  const steppedVelocity = { ...steppedResult.velocity, z: downResult.velocity.z };
+  const steppedBlocked = steppedResult.blocked;
+  const stopped = steppedVelocity.x === 0 && steppedVelocity.y === 0 && steppedVelocity.z === 0;
+
+  return {
+    origin: steppedOrigin,
+    velocity: steppedVelocity,
+    planes: steppedResult.planes,
+    blocked: steppedBlocked,
+    stopped,
+    stepped: true,
+    stepHeight: actualStep,
+    stepNormal,
+  };
+}