@quake2ts/shared 0.0.1

package/src/pmove/snap.ts

@@ -0,0 +1,89 @@
+import type { Vec3 } from '../math/vec3.js';
+import { fixStuckObjectGeneric } from './stuck.js';
+import type { PmoveTraceFn } from './types.js';
+
+const SNAP_OFFSETS = [0, -1, 1] as const;
+
+export interface GoodPositionParams {
+  readonly origin: Vec3;
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly trace: PmoveTraceFn;
+}
+
+export function goodPosition(params: GoodPositionParams): boolean {
+  const { origin, mins, maxs, trace } = params;
+  const result = trace(origin, origin, mins, maxs);
+  return result.allsolid ? false : true;
+}
+
+export type SnapResolution = 'unchanged' | 'fixed' | 'reverted';
+
+export interface SnapPositionParams extends GoodPositionParams {
+  readonly velocity: Vec3;
+  readonly previousOrigin: Vec3;
+}
+
+export interface SnapPositionResult {
+  readonly origin: Vec3;
+  readonly velocity: Vec3;
+  readonly resolution: SnapResolution;
+}
+
+/**
+ * Pure translation of PM_SnapPosition from rerelease `p_move.cpp`.
+ * Attempts to keep the caller's origin in a valid location by first
+ * checking the current origin against collision traces, then falling
+ * back to the shared `fixStuckObjectGeneric` helper before finally
+ * reverting to the provided previous origin when no fix is possible.
+ */
+export function snapPosition(params: SnapPositionParams): SnapPositionResult {
+  const { origin, velocity, mins, maxs, previousOrigin, trace } = params;
+
+  if (goodPosition({ origin, mins, maxs, trace })) {
+    return { origin: { ...origin }, velocity: { ...velocity }, resolution: 'unchanged' };
+  }
+
+  const fix = fixStuckObjectGeneric({
+    origin,
+    mins,
+    maxs,
+    trace: (start, localMins, localMaxs, end) => trace(start, end, localMins, localMaxs),
+  });
+
+  if (fix.result === 'fixed' || fix.result === 'good-position') {
+    return { origin: fix.origin, velocity: { ...velocity }, resolution: 'fixed' };
+  }
+
+  return { origin: { ...previousOrigin }, velocity: { ...velocity }, resolution: 'reverted' };
+}
+
+export interface InitialSnapPositionParams extends GoodPositionParams {}
+
+export interface InitialSnapPositionResult {
+  readonly origin: Vec3;
+  readonly snapped: boolean;
+}
+
+/**
+ * Pure translation of PM_InitialSnapPosition from rerelease `p_move.cpp`.
+ * Tries a 3x3x3 grid of +/-1 unit offsets around the base origin to find
+ * a valid collision-free spot, mirroring the search order of the C++ code.
+ */
+export function initialSnapPosition(params: InitialSnapPositionParams): InitialSnapPositionResult {
+  const { origin, mins, maxs, trace } = params;
+
+  for (const oz of SNAP_OFFSETS) {
+    for (const oy of SNAP_OFFSETS) {
+      for (const ox of SNAP_OFFSETS) {
+        const candidate = { x: origin.x + ox, y: origin.y + oy, z: origin.z + oz } satisfies Vec3;
+        if (goodPosition({ origin: candidate, mins, maxs, trace })) {
+          const snapped = ox !== 0 || oy !== 0 || oz !== 0;
+          return { origin: candidate, snapped };
+        }
+      }
+    }
+  }
+
+  return { origin: { ...origin }, snapped: false };
+}

package/src/pmove/special.ts

@@ -0,0 +1,207 @@
+import { CONTENTS_LADDER, CONTENTS_NONE, CONTENTS_NO_WATERJUMP } from '../bsp/contents.js';
+import { addVec3, lengthSquaredVec3, normalizeVec3, scaleVec3, type Vec3 } from '../math/vec3.js';
+import { PlayerButton, PmFlag, type PmFlags, addPmFlag, removePmFlag, WaterLevel } from './constants.js';
+import { stepSlideMove } from './slide.js';
+import type { PmoveCmd, PmovePointContentsFn, PmoveTraceFn } from './types.js';
+import { getWaterLevel } from './water.js';
+
+const LADDER_TRACE_DISTANCE = 1;
+const WATERJUMP_FORWARD_CHECK = 40;
+const WATERJUMP_FORWARD_SPEED = 50;
+const WATERJUMP_UPWARD_SPEED = 350;
+const WATERJUMP_PM_TIME = 2048;
+const WATERJUMP_SIM_STEP = 0.1;
+const WATERJUMP_BASE_GRAVITY = 800;
+const WATERJUMP_MAX_STEPS = 50;
+const GROUND_NORMAL_THRESHOLD = 0.7;
+const WATERJUMP_STEP_TOLERANCE = 18;
+const DEFAULT_OVERBOUNCE = 1.01;
+const WATERJUMP_DOWN_PROBE = 2;
+
+export interface SpecialMovementParams {
+  readonly pmFlags: PmFlags;
+  readonly pmTime: number;
+  readonly waterlevel: WaterLevel;
+  readonly watertype: number;
+  readonly gravity: number;
+  readonly cmd: PmoveCmd;
+  readonly forward: Vec3;
+  readonly origin: Vec3;
+  readonly velocity: Vec3;
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly viewheight: number;
+  readonly trace: PmoveTraceFn;
+  readonly pointContents: PmovePointContentsFn;
+  readonly onGround: boolean;
+  readonly overbounce?: number;
+  readonly stepSize?: number;
+  readonly maxBumps?: number;
+  readonly maxClipPlanes?: number;
+}
+
+export interface SpecialMovementResult {
+  readonly pmFlags: PmFlags;
+  readonly pmTime: number;
+  readonly velocity: Vec3;
+  readonly performedWaterJump: boolean;
+}
+
+/**
+ * Mirrors the ladder detection and water-jump probing logic from
+ * `PM_CheckSpecialMovement` in `rerelease/p_move.cpp`. The helper clears and
+ * re-adds the ladder flag based on nearby CONTENTS_LADDER brushes, then
+ * simulates a potential water jump by firing the same 40-unit probe and
+ * step-slide loop the C++ uses before committing to the upward velocity.
+ */
+export function checkSpecialMovement(params: SpecialMovementParams): SpecialMovementResult {
+  const {
+    pmFlags: initialFlags,
+    pmTime: initialPmTime,
+    waterlevel,
+    watertype,
+    gravity,
+    cmd,
+    forward,
+    origin,
+    velocity: initialVelocity,
+    mins,
+    maxs,
+    viewheight,
+    trace,
+    pointContents,
+    onGround,
+    overbounce = DEFAULT_OVERBOUNCE,
+    stepSize = WATERJUMP_STEP_TOLERANCE,
+    maxBumps,
+    maxClipPlanes,
+  } = params;
+
+  if (initialPmTime > 0) {
+    return { pmFlags: initialFlags, pmTime: initialPmTime, velocity: initialVelocity, performedWaterJump: false };
+  }
+
+  let pmFlags = removePmFlag(initialFlags, PmFlag.OnLadder);
+  let pmTime = initialPmTime;
+  let velocity = initialVelocity;
+
+  const flatforward = normalizeVec3({ x: forward.x, y: forward.y, z: 0 });
+  const hasForward = lengthSquaredVec3(flatforward) > 0;
+
+  if (waterlevel < WaterLevel.Waist && hasForward) {
+    const ladderEnd = addVec3(origin, scaleVec3(flatforward, LADDER_TRACE_DISTANCE));
+    const ladderTrace = trace(origin, ladderEnd, mins, maxs);
+    const contents = ladderTrace.contents ?? CONTENTS_NONE;
+
+    if (ladderTrace.fraction < 1 && (contents & CONTENTS_LADDER) !== 0) {
+      pmFlags = addPmFlag(pmFlags, PmFlag.OnLadder);
+    }
+  }
+
+  if (gravity === 0) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  if (((cmd.buttons ?? 0) & PlayerButton.Jump) === 0 && cmd.forwardmove <= 0) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  if (waterlevel !== WaterLevel.Waist) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  if ((watertype & CONTENTS_NO_WATERJUMP) !== 0) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  if (!hasForward) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  const forwardCheckEnd = addVec3(origin, scaleVec3(flatforward, WATERJUMP_FORWARD_CHECK));
+  const forwardTrace = trace(origin, forwardCheckEnd, mins, maxs);
+
+  if (
+    forwardTrace.fraction === 1 ||
+    !forwardTrace.planeNormal ||
+    forwardTrace.planeNormal.z >= GROUND_NORMAL_THRESHOLD
+  ) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  let simVelocity: Vec3 = {
+    x: flatforward.x * WATERJUMP_FORWARD_SPEED,
+    y: flatforward.y * WATERJUMP_FORWARD_SPEED,
+    z: WATERJUMP_UPWARD_SPEED,
+  };
+
+  let simOrigin = origin;
+  let hasTime = true;
+  const stepCount = computeWaterJumpSteps(gravity);
+
+  for (let i = 0; i < stepCount; i++) {
+    simVelocity = { x: simVelocity.x, y: simVelocity.y, z: simVelocity.z - gravity * WATERJUMP_SIM_STEP };
+    if (simVelocity.z < 0) {
+      hasTime = false;
+    }
+
+    const move = stepSlideMove({
+      origin: simOrigin,
+      velocity: simVelocity,
+      frametime: WATERJUMP_SIM_STEP,
+      trace,
+      mins,
+      maxs,
+      overbounce,
+      stepSize,
+      maxBumps,
+      maxClipPlanes,
+      hasTime,
+    });
+    simOrigin = move.origin;
+    simVelocity = move.velocity;
+  }
+
+  const downEnd = addVec3(simOrigin, { x: 0, y: 0, z: -WATERJUMP_DOWN_PROBE });
+  const downTrace = trace(simOrigin, downEnd, mins, maxs);
+
+  if (
+    downTrace.fraction === 1 ||
+    !downTrace.planeNormal ||
+    downTrace.planeNormal.z < GROUND_NORMAL_THRESHOLD ||
+    downTrace.endpos.z < origin.z
+  ) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  if (onGround && Math.abs(origin.z - downTrace.endpos.z) <= stepSize) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  const landingWater = getWaterLevel({ origin: downTrace.endpos, mins, viewheight, pointContents });
+  if (landingWater.waterlevel >= WaterLevel.Waist) {
+    return { pmFlags, pmTime, velocity, performedWaterJump: false };
+  }
+
+  pmFlags = addPmFlag(pmFlags, PmFlag.TimeWaterJump);
+  pmTime = WATERJUMP_PM_TIME;
+  velocity = {
+    x: flatforward.x * WATERJUMP_FORWARD_SPEED,
+    y: flatforward.y * WATERJUMP_FORWARD_SPEED,
+    z: WATERJUMP_UPWARD_SPEED,
+  } satisfies Vec3;
+
+  return { pmFlags, pmTime, velocity, performedWaterJump: true };
+}
+
+function computeWaterJumpSteps(gravity: number): number {
+  if (gravity === 0) {
+    return 0;
+  }
+
+  const scaled = Math.floor(10 * (WATERJUMP_BASE_GRAVITY / gravity));
+  if (scaled <= 0) {
+    return 0;
+  }
+  return Math.min(WATERJUMP_MAX_STEPS, scaled);
+}

package/src/pmove/stuck.ts

@@ -0,0 +1,258 @@
+import {
+  addVec3,
+  lengthSquaredVec3,
+  scaleVec3,
+  subtractVec3,
+  type Vec3,
+} from '../math/vec3.js';
+import type { PmoveTraceResult } from './types.js';
+
+const AXES = ['x', 'y', 'z'] as const;
+type Axis = (typeof AXES)[number];
+
+type AxisTuple = readonly [number, number, number];
+type SideBoundCode = -1 | 0 | 1;
+
+interface SideCheck {
+  readonly normal: AxisTuple;
+  readonly mins: readonly [SideBoundCode, SideBoundCode, SideBoundCode];
+  readonly maxs: readonly [SideBoundCode, SideBoundCode, SideBoundCode];
+}
+
+const SIDE_CHECKS: readonly SideCheck[] = [
+  { normal: [0, 0, 1], mins: [-1, -1, 0], maxs: [1, 1, 0] },
+  { normal: [0, 0, -1], mins: [-1, -1, 0], maxs: [1, 1, 0] },
+  { normal: [1, 0, 0], mins: [0, -1, -1], maxs: [0, 1, 1] },
+  { normal: [-1, 0, 0], mins: [0, -1, -1], maxs: [0, 1, 1] },
+  { normal: [0, 1, 0], mins: [-1, 0, -1], maxs: [1, 0, 1] },
+  { normal: [0, -1, 0], mins: [-1, 0, -1], maxs: [1, 0, 1] },
+];
+
+export interface FixStuckParams {
+  readonly origin: Vec3;
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly trace: FixStuckTraceFn;
+}
+
+export type FixStuckResult = 'good-position' | 'fixed' | 'no-good-position';
+
+export interface FixStuckOutcome {
+  readonly result: FixStuckResult;
+  readonly origin: Vec3;
+}
+
+export type FixStuckTraceFn = (
+  start: Vec3,
+  mins: Vec3,
+  maxs: Vec3,
+  end: Vec3,
+) => PmoveTraceResult;
+
+interface CandidatePosition {
+  readonly distance: number;
+  readonly origin: Vec3;
+}
+
+const ZERO_VEC: Vec3 = { x: 0, y: 0, z: 0 };
+
+type MutableVec3 = { x: number; y: number; z: number };
+
+function cloneMutable(vec: Vec3): MutableVec3 {
+  return { x: vec.x, y: vec.y, z: vec.z };
+}
+
+function tupleToVec3(tuple: AxisTuple): Vec3 {
+  return { x: tuple[0], y: tuple[1], z: tuple[2] };
+}
+
+function adjustAxis(vec: MutableVec3, axis: Axis, delta: number): void {
+  if (delta === 0) return;
+  switch (axis) {
+    case 'x':
+      vec.x += delta;
+      break;
+    case 'y':
+      vec.y += delta;
+      break;
+    case 'z':
+      vec.z += delta;
+      break;
+  }
+}
+
+function setAxis(vec: MutableVec3, axis: Axis, value: number): void {
+  switch (axis) {
+    case 'x':
+      vec.x = value;
+      break;
+    case 'y':
+      vec.y = value;
+      break;
+    case 'z':
+      vec.z = value;
+      break;
+  }
+}
+
+function axisValue(vec: Vec3, axis: Axis): number {
+  switch (axis) {
+    case 'x':
+      return vec.x;
+    case 'y':
+      return vec.y;
+    case 'z':
+    default:
+      return vec.z;
+  }
+}
+
+function boundValue(code: SideBoundCode, axis: Axis, mins: Vec3, maxs: Vec3): number {
+  if (code === -1) {
+    return axisValue(mins, axis);
+  }
+  if (code === 1) {
+    return axisValue(maxs, axis);
+  }
+  return 0;
+}
+
+function applySideOffset(base: Vec3, side: SideCheck, mins: Vec3, maxs: Vec3): MutableVec3 {
+  const result = cloneMutable(base);
+  for (let i = 0; i < AXES.length; i++) {
+    const axis = AXES[i];
+    const normal = side.normal[i];
+    if (normal < 0) {
+      adjustAxis(result, axis, axisValue(mins, axis));
+    } else if (normal > 0) {
+      adjustAxis(result, axis, axisValue(maxs, axis));
+    }
+  }
+  return result;
+}
+
+function buildSideBounds(side: SideCheck, mins: Vec3, maxs: Vec3): { mins: MutableVec3; maxs: MutableVec3 } {
+  const localMins = cloneMutable(ZERO_VEC);
+  const localMaxs = cloneMutable(ZERO_VEC);
+  for (let i = 0; i < AXES.length; i++) {
+    const axis = AXES[i];
+    setAxis(localMins, axis, boundValue(side.mins[i], axis, mins, maxs));
+    setAxis(localMaxs, axis, boundValue(side.maxs[i], axis, mins, maxs));
+  }
+  return { mins: localMins, maxs: localMaxs };
+}
+
+function addEpsilon(
+  source: MutableVec3,
+  axis: Axis | undefined,
+  direction: number,
+): MutableVec3 {
+  if (!axis || direction === 0) {
+    return source;
+  }
+  const clone = cloneMutable(source);
+  adjustAxis(clone, axis, direction);
+  return clone;
+}
+
+function addEpsilonImmutable(vec: Vec3, axis: Axis | undefined, direction: number): Vec3 {
+  if (!axis || direction === 0) {
+    return vec;
+  }
+  switch (axis) {
+    case 'x':
+      return { ...vec, x: vec.x + direction };
+    case 'y':
+      return { ...vec, y: vec.y + direction };
+    case 'z':
+    default:
+      return { ...vec, z: vec.z + direction };
+  }
+}
+
+/**
+ * TypeScript port of G_FixStuckObject_Generic from rerelease p_move.cpp. Attempts to
+ * nudge a stuck bounding box out of solid space by probing the faces of the box and
+ * moving towards the opposite side, keeping the smallest successful displacement.
+ */
+export function fixStuckObjectGeneric(params: FixStuckParams): FixStuckOutcome {
+  const { origin, mins, maxs, trace } = params;
+
+  const initial = trace(origin, mins, maxs, origin);
+  if (!initial.startsolid) {
+    return { result: 'good-position', origin: { ...origin } };
+  }
+
+  const candidates: CandidatePosition[] = [];
+
+  for (let i = 0; i < SIDE_CHECKS.length; i++) {
+    const side = SIDE_CHECKS[i];
+    const { mins: localMins, maxs: localMaxs } = buildSideBounds(side, mins, maxs);
+
+    let start = applySideOffset(origin, side, mins, maxs);
+    let tr = trace(start, localMins, localMaxs, start);
+
+    let epsilonAxis: Axis | undefined;
+    let epsilonDir = 0;
+
+    if (tr.startsolid) {
+      for (let axisIndex = 0; axisIndex < AXES.length; axisIndex++) {
+        if (side.normal[axisIndex] !== 0) {
+          continue;
+        }
+        const axis = AXES[axisIndex];
+        let epsilonStart = cloneMutable(start);
+        adjustAxis(epsilonStart, axis, 1);
+        tr = trace(epsilonStart, localMins, localMaxs, epsilonStart);
+        if (!tr.startsolid) {
+          start = epsilonStart;
+          epsilonAxis = axis;
+          epsilonDir = 1;
+          break;
+        }
+        epsilonStart = cloneMutable(start);
+        adjustAxis(epsilonStart, axis, -1);
+        tr = trace(epsilonStart, localMins, localMaxs, epsilonStart);
+        if (!tr.startsolid) {
+          start = epsilonStart;
+          epsilonAxis = axis;
+          epsilonDir = -1;
+          break;
+        }
+      }
+    }
+
+    if (tr.startsolid) {
+      continue;
+    }
+
+    const otherSide = SIDE_CHECKS[i ^ 1];
+    let oppositeStart = applySideOffset(origin, otherSide, mins, maxs);
+    oppositeStart = addEpsilon(oppositeStart, epsilonAxis, epsilonDir);
+
+    tr = trace(start, localMins, localMaxs, oppositeStart);
+    if (tr.startsolid) {
+      continue;
+    }
+
+    const normal = tupleToVec3(side.normal);
+    const end = addVec3(tr.endpos ?? oppositeStart, scaleVec3(normal, 0.125));
+    const delta = subtractVec3(end, oppositeStart);
+    let newOrigin = addVec3(origin, delta);
+    newOrigin = addEpsilonImmutable(newOrigin, epsilonAxis, epsilonDir);
+
+    const validation = trace(newOrigin, mins, maxs, newOrigin);
+    if (validation.startsolid) {
+      continue;
+    }
+
+    candidates.push({ origin: newOrigin, distance: lengthSquaredVec3(delta) });
+  }
+
+  if (candidates.length === 0) {
+    return { result: 'no-good-position', origin: { ...origin } };
+  }
+
+  candidates.sort((a, b) => a.distance - b.distance);
+  return { result: 'fixed', origin: { ...candidates[0].origin } };
+}

package/src/pmove/types.ts

@@ -0,0 +1,82 @@
+import type { ContentsFlag } from '../bsp/contents.js';
+import type { Vec3 } from '../math/vec3.js';
+import type { PmFlags, PmType, WaterLevel, PlayerButton } from './constants.js';
+
+export interface PmoveFrictionParams {
+  readonly velocity: Vec3;
+  readonly frametime: number;
+  readonly onGround: boolean;
+  readonly groundIsSlick: boolean;
+  readonly onLadder: boolean;
+  readonly waterlevel: number;
+  readonly pmFriction: number;
+  readonly pmStopSpeed: number;
+  readonly pmWaterFriction: number;
+}
+
+export interface PmoveAccelerateParams {
+  readonly velocity: Vec3;
+  readonly wishdir: Vec3;
+  readonly wishspeed: number;
+  readonly accel: number;
+  readonly frametime: number;
+}
+
+export interface PmoveCmd {
+  readonly forwardmove: number;
+  readonly sidemove: number;
+  readonly upmove: number;
+  readonly buttons: PlayerButton;
+  readonly impulse?: number;
+  readonly lightlevel?: number;
+  readonly angles: Vec3;
+}
+
+export interface PmoveWishResult {
+  readonly wishdir: Vec3;
+  readonly wishspeed: number;
+}
+
+export interface PmoveWishParams {
+  readonly forward: Vec3;
+  readonly right: Vec3;
+  readonly cmd: PmoveCmd;
+  readonly maxSpeed: number;
+}
+
+export interface PmoveTraceResult {
+  readonly fraction: number;
+  readonly endpos: Vec3;
+  readonly planeNormal?: Vec3;
+  readonly allsolid: boolean;
+  readonly startsolid: boolean;
+  readonly contents?: ContentsFlag;
+  readonly surfaceFlags?: number;
+}
+
+export type PmoveTraceFn = (start: Vec3, end: Vec3, mins?: Vec3, maxs?: Vec3) => PmoveTraceResult;
+
+export type PmovePointContentsFn = (point: Vec3) => ContentsFlag;
+
+// Missing exports added for runPmove
+export interface PmoveState {
+  pmType: PmType;
+  pmFlags: PmFlags;
+  origin: Vec3;
+  velocity: Vec3;
+  angles: Vec3;
+  viewAngles: Vec3;
+  viewHeight: number;
+  waterlevel: WaterLevel;
+  watertype: number;
+  cmd: PmoveCmd;
+  delta_angles: Vec3;
+  gravity: number;
+  mins: Vec3;
+  maxs: Vec3;
+}
+
+export interface PmoveImports {
+  trace: PmoveTraceFn;
+  pointcontents: PmovePointContentsFn;
+}

package/src/pmove/view.ts

@@ -0,0 +1,57 @@
+import type { Vec3 } from '../math/vec3.js';
+import { angleVectors, type AngleVectorsResult } from '../math/angles.js';
+import { PmFlag, type PmFlags } from './constants.js';
+
+export interface ClampViewAnglesParams {
+  readonly pmFlags: PmFlags;
+  readonly cmdAngles: Vec3;
+  readonly deltaAngles: Vec3;
+}
+
+export interface ClampViewAnglesResult extends AngleVectorsResult {
+  readonly viewangles: Vec3;
+}
+
+function addAngles(cmdAngles: Vec3, deltaAngles: Vec3): Vec3 {
+  return {
+    x: cmdAngles.x + deltaAngles.x,
+    y: cmdAngles.y + deltaAngles.y,
+    z: cmdAngles.z + deltaAngles.z,
+  } satisfies Vec3;
+}
+
+function clampPitch(pitch: number): number {
+  if (pitch > 89 && pitch < 180) {
+    return 89;
+  }
+  if (pitch < 271 && pitch >= 180) {
+    return 271;
+  }
+  return pitch;
+}
+
+/**
+ * Pure translation of `PM_ClampAngles` from `rerelease/p_move.cpp`. The helper
+ * fuses the latest command angles with the stored delta, applies the teleport
+ * pitch/roll reset, enforces the ±90° pitch window, and returns the resulting
+ * axis vectors that the C version stored in `pml.forward/right/up`.
+ */
+export function clampViewAngles(params: ClampViewAnglesParams): ClampViewAnglesResult {
+  const { pmFlags, cmdAngles, deltaAngles } = params;
+
+  let viewangles: Vec3;
+
+  if ((pmFlags & PmFlag.TimeTeleport) !== 0) {
+    viewangles = {
+      x: 0,
+      y: cmdAngles.y + deltaAngles.y,
+      z: 0,
+    } satisfies Vec3;
+  } else {
+    viewangles = addAngles(cmdAngles, deltaAngles);
+    viewangles = { ...viewangles, x: clampPitch(viewangles.x) };
+  }
+
+  const vectors = angleVectors(viewangles);
+  return { viewangles, ...vectors };
+}