@quake2ts/shared 0.0.1

package/src/pmove/categorize.ts

@@ -0,0 +1,162 @@
+import { CONTENTS_NONE, type ContentsFlag } from '../bsp/contents.js';
+import { addVec3, clipVelocityVec3, type Vec3 } from '../math/vec3.js';
+import {
+  PmFlag,
+  type PmFlags,
+  PmType,
+  addPmFlag,
+  hasPmFlag,
+  removePmFlag,
+} from './constants.js';
+import { getWaterLevel } from './water.js';
+import type { PmovePointContentsFn, PmoveTraceFn, PmoveTraceResult } from './types.js';
+
+const GROUND_PROBE_DISTANCE = 0.25;
+const LADDER_BYPASS_VELOCITY = 180;
+const TRICK_VELOCITY_THRESHOLD = 100;
+const SLANTED_NORMAL_THRESHOLD = 0.7;
+const TRICK_NORMAL_THRESHOLD = 0.9;
+const TRICK_PM_TIME = 64;
+const LAND_PM_TIME = 128;
+const IMPACT_CLIP_OVERBOUNCE = 1.01;
+
+const WATERJUMP_CLEAR =
+  PmFlag.TimeWaterJump | PmFlag.TimeLand | PmFlag.TimeTeleport | PmFlag.TimeTrick;
+
+export interface CategorizePositionParams {
+  readonly pmType: PmType;
+  readonly pmFlags: PmFlags;
+  readonly pmTime: number;
+  readonly n64Physics: boolean;
+  readonly velocity: Vec3;
+  readonly startVelocity: Vec3;
+  readonly origin: Vec3;
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly viewheight: number;
+  readonly trace: PmoveTraceFn;
+  readonly pointContents: PmovePointContentsFn;
+}
+
+export interface CategorizePositionResult {
+  readonly pmFlags: PmFlags;
+  readonly pmTime: number;
+  readonly onGround: boolean;
+  readonly groundTrace?: PmoveTraceResult;
+  readonly groundContents: ContentsFlag;
+  readonly waterlevel: number;
+  readonly watertype: ContentsFlag;
+  readonly impactDelta?: number;
+}
+
+/**
+ * Pure mirror of PM_CatagorizePosition from `rerelease/p_move.cpp`: traces a quarter-unit
+ * below the player bounds to determine whether they stand on solid ground, updates timers
+ * and pmflags accordingly, records the latest ground plane data, and recalculates waterlevel
+ * by probing feet/waist/viewheight samples.
+ */
+export function categorizePosition(params: CategorizePositionParams): CategorizePositionResult {
+  const {
+    pmType,
+    n64Physics,
+    velocity,
+    startVelocity,
+    origin,
+    mins,
+    maxs,
+    viewheight,
+    trace,
+    pointContents,
+  } = params;
+
+  let pmFlags = params.pmFlags;
+  let pmTime = params.pmTime;
+  let impactDelta: number | undefined;
+  let onGround = hasPmFlag(pmFlags, PmFlag.OnGround);
+
+  let groundTrace: PmoveTraceResult | undefined;
+  let groundContents: ContentsFlag = CONTENTS_NONE;
+
+  const forceAirborne = velocity.z > LADDER_BYPASS_VELOCITY || pmType === PmType.Grapple;
+
+  if (forceAirborne) {
+    pmFlags = removePmFlag(pmFlags, PmFlag.OnGround);
+    onGround = false;
+  } else {
+    const end: Vec3 = { x: origin.x, y: origin.y, z: origin.z - GROUND_PROBE_DISTANCE };
+    const traceResult = trace(origin, end, mins, maxs);
+    groundTrace = traceResult;
+    groundContents = traceResult.contents ?? CONTENTS_NONE;
+
+    const planeNormal = traceResult.planeNormal;
+
+    let slantedGround =
+      traceResult.fraction < 1 && !!planeNormal && planeNormal.z < SLANTED_NORMAL_THRESHOLD;
+
+    if (slantedGround && planeNormal) {
+      const slantEnd = addVec3(origin, planeNormal);
+      const slantTrace = trace(origin, slantEnd, mins, maxs);
+      if (slantTrace.fraction < 1 && !slantTrace.startsolid) {
+        slantedGround = false;
+      }
+    }
+
+    if (
+      traceResult.fraction === 1 ||
+      !planeNormal ||
+      (slantedGround && !traceResult.startsolid)
+    ) {
+      pmFlags = removePmFlag(pmFlags, PmFlag.OnGround);
+      onGround = false;
+    } else {
+      onGround = true;
+
+      if (hasPmFlag(pmFlags, PmFlag.TimeWaterJump)) {
+        pmFlags &= ~WATERJUMP_CLEAR;
+        pmTime = 0;
+      }
+
+      const wasOnGround = hasPmFlag(pmFlags, PmFlag.OnGround);
+
+      if (!wasOnGround) {
+        if (
+          !n64Physics &&
+          velocity.z >= TRICK_VELOCITY_THRESHOLD &&
+          planeNormal.z >= TRICK_NORMAL_THRESHOLD &&
+          !hasPmFlag(pmFlags, PmFlag.Ducked)
+        ) {
+          pmFlags = addPmFlag(pmFlags, PmFlag.TimeTrick);
+          pmTime = TRICK_PM_TIME;
+        }
+
+        const clipped = clipVelocityVec3(velocity, planeNormal, IMPACT_CLIP_OVERBOUNCE);
+        impactDelta = startVelocity.z - clipped.z;
+      }
+
+      pmFlags = addPmFlag(pmFlags, PmFlag.OnGround);
+
+      if (!wasOnGround && (n64Physics || hasPmFlag(pmFlags, PmFlag.Ducked))) {
+        pmFlags = addPmFlag(pmFlags, PmFlag.TimeLand);
+        pmTime = LAND_PM_TIME;
+      }
+    }
+  }
+
+  const { waterlevel, watertype } = getWaterLevel({
+    origin,
+    mins,
+    viewheight,
+    pointContents,
+  });
+
+  return {
+    pmFlags,
+    pmTime,
+    onGround: hasPmFlag(pmFlags, PmFlag.OnGround),
+    groundTrace,
+    groundContents,
+    waterlevel,
+    watertype,
+    impactDelta,
+  };
+}

package/src/pmove/config.ts

@@ -0,0 +1,5 @@
+// Matching rerelease/bg_local.h:18-24
+export interface PmConfig {
+  airaccel: number;
+  n64_physics: boolean;
+}

package/src/pmove/constants.ts

@@ -0,0 +1,94 @@
+/**
+ * Mirrors the Quake II rerelease `water_level_t` enumeration from `game.h`
+ * (lines 443-449). These numeric values are relied upon throughout the
+ * movement code when checking how submerged a player is, so we keep the same
+ * ordering to make future porting work straightforward.
+ */
+export enum WaterLevel {
+  None = 0,
+  Feet = 1,
+  Waist = 2,
+  Under = 3,
+}
+
+/**
+ * Utility that matches the common rerelease checks that treat any level at or
+ * above the `WATER_WAIST` constant as "significantly submerged" for friction
+ * and current calculations.
+ */
+export function isAtLeastWaistDeep(level: WaterLevel): boolean {
+  return level >= WaterLevel.Waist;
+}
+
+/**
+ * Returns true when the player is considered underwater (the `WATER_UNDER`
+ * case in the rerelease). This mirrors the places in `p_move.cpp` that gate
+ * effects such as breath timers and screen warping.
+ */
+export function isUnderwater(level: WaterLevel): boolean {
+  return level === WaterLevel.Under;
+}
+
+/**
+ * Matches the Quake II rerelease `pmflags_t` bit layout from `game.h` so the
+ * shared helpers can manipulate the same flag words as the authoritative game
+ * and the client prediction layer.
+ */
+export const enum PmFlag {
+  Ducked = 1 << 0,
+  JumpHeld = 1 << 1,
+  OnGround = 1 << 2,
+  TimeWaterJump = 1 << 3,
+  TimeLand = 1 << 4,
+  TimeTeleport = 1 << 5,
+  NoPositionalPrediction = 1 << 6,
+  OnLadder = 1 << 7,
+  NoAngularPrediction = 1 << 8,
+  IgnorePlayerCollision = 1 << 9,
+  TimeTrick = 1 << 10,
+}
+
+export type PmFlags = number;
+
+export function hasPmFlag(flags: PmFlags, flag: PmFlag): boolean {
+  return (flags & flag) !== 0;
+}
+
+export function addPmFlag(flags: PmFlags, flag: PmFlag): PmFlags {
+  return flags | flag;
+}
+
+export function removePmFlag(flags: PmFlags, flag: PmFlag): PmFlags {
+  return flags & ~flag;
+}
+
+/**
+ * Player movement types mirrored from the rerelease `pmtype_t` enumeration.
+ * The exact numeric values matter when syncing pmove state across the network
+ * so we keep the same order as the C++ definition.
+ */
+export enum PmType {
+  Normal = 0,
+  Grapple = 1,
+  NoClip = 2,
+  Spectator = 3,
+  Dead = 4,
+  Gib = 5,
+  Freeze = 6,
+}
+
+/**
+ * Bitmask constants for the `buttons` field on the Quake II player command
+ * structure. These mirror the rerelease `BUTTON_*` definitions so logic such as
+ * jump/crouch checks can be shared between the server and client.
+ */
+export const enum PlayerButton {
+  None = 0,
+  Attack = 1 << 0,
+  Use = 1 << 1,
+  Holster = 1 << 2,
+  Jump = 1 << 3,
+  Crouch = 1 << 4,
+  Attack2 = 1 << 5,
+  Any = 1 << 7,
+}

package/src/pmove/currents.ts

@@ -0,0 +1,287 @@
+import type { ContentsFlag } from '../bsp/contents.js';
+import {
+  CONTENTS_CURRENT_0,
+  CONTENTS_CURRENT_180,
+  CONTENTS_CURRENT_270,
+  CONTENTS_CURRENT_90,
+  CONTENTS_CURRENT_DOWN,
+  CONTENTS_CURRENT_UP,
+  CONTENTS_LADDER,
+  MASK_CURRENT,
+} from '../bsp/contents.js';
+import { addVec3, crossVec3, normalizeVec3, scaleVec3, ZERO_VEC3, type Vec3 } from '../math/vec3.js';
+import { PlayerButton, WaterLevel, isAtLeastWaistDeep } from './constants.js';
+import type { PmoveCmd, PmoveTraceFn } from './types.js';
+
+export interface WaterCurrentParams {
+  readonly watertype: ContentsFlag;
+  readonly waterlevel: WaterLevel;
+  readonly onGround: boolean;
+  readonly waterSpeed: number;
+}
+
+export interface GroundCurrentParams {
+  readonly groundContents: ContentsFlag;
+  readonly scale?: number;
+}
+
+export interface AddCurrentsParams {
+  readonly wishVelocity: Vec3;
+  readonly onLadder: boolean;
+  readonly onGround: boolean;
+  readonly waterlevel: WaterLevel;
+  readonly watertype: ContentsFlag;
+  readonly groundContents: ContentsFlag;
+  readonly cmd: PmoveCmd;
+  readonly viewPitch: number;
+  readonly maxSpeed: number;
+  readonly ladderMod: number;
+  readonly waterSpeed: number;
+  readonly forward: Vec3;
+  readonly origin: Vec3;
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly trace?: PmoveTraceFn;
+}
+
+const DEFAULT_GROUND_CURRENT_SCALE = 100;
+const DEFAULT_FORWARD_LADDER_CLAMP = 200;
+const DEFAULT_SIDE_LADDER_CLAMP = 150;
+const LADDER_HORIZONTAL_CAP = 25;
+const LADDER_ASCEND_PITCH_THRESHOLD = 15;
+const LADDER_TRACE_DISTANCE = 1;
+const UP_VECTOR: Vec3 = { x: 0, y: 0, z: 1 };
+
+const DEFAULT_TRACE: PmoveTraceFn = (_, end) => ({
+  fraction: 1,
+  endpos: end,
+  allsolid: false,
+  startsolid: false,
+});
+
+/**
+ * Mirrors the rerelease pattern in `p_move.cpp` (lines 730-765) that turns the
+ * directional CONTENTS_CURRENT_* flags into a unit-ish direction vector.
+ */
+export function currentVectorFromContents(contents: ContentsFlag): Vec3 {
+  let x = 0;
+  let y = 0;
+  let z = 0;
+
+  if (contents & CONTENTS_CURRENT_0) {
+    x += 1;
+  }
+  if (contents & CONTENTS_CURRENT_90) {
+    y += 1;
+  }
+  if (contents & CONTENTS_CURRENT_180) {
+    x -= 1;
+  }
+  if (contents & CONTENTS_CURRENT_270) {
+    y -= 1;
+  }
+  if (contents & CONTENTS_CURRENT_UP) {
+    z += 1;
+  }
+  if (contents & CONTENTS_CURRENT_DOWN) {
+    z -= 1;
+  }
+
+  if (x === 0 && y === 0 && z === 0) {
+    return ZERO_VEC3;
+  }
+
+  return { x, y, z };
+}
+
+/**
+ * Computes the velocity contribution from water currents using the same rules
+ * as `PM_WaterMove`: the CONTENTS_CURRENT_* bits are turned into a direction
+ * vector, scaled by `pm_waterspeed`, and halved when the player only has their
+ * feet submerged while standing on solid ground.
+ */
+export function waterCurrentVelocity(params: WaterCurrentParams): Vec3 {
+  const { watertype, waterlevel, onGround, waterSpeed } = params;
+
+  if ((watertype & MASK_CURRENT) === 0) {
+    return ZERO_VEC3;
+  }
+
+  const direction = currentVectorFromContents(watertype);
+  if (direction === ZERO_VEC3) {
+    return ZERO_VEC3;
+  }
+
+  let scale = waterSpeed;
+  if (waterlevel === WaterLevel.Feet && onGround) {
+    scale *= 0.5;
+  }
+
+  return scaleVec3(direction, scale);
+}
+
+/**
+ * Computes the conveyor-style velocity that should be applied while touching a
+ * ground plane that carries CONTENTS_CURRENT_* bits. The rerelease multiplies
+ * the direction vector by 100 units per second, so we expose the same default
+ * while allowing callers to override the scalar for tests.
+ */
+export function groundCurrentVelocity(params: GroundCurrentParams): Vec3 {
+  const { groundContents, scale = DEFAULT_GROUND_CURRENT_SCALE } = params;
+
+  const direction = currentVectorFromContents(groundContents);
+  if (direction === ZERO_VEC3) {
+    return ZERO_VEC3;
+  }
+
+  return scaleVec3(direction, scale);
+}
+
+/**
+ * Pure mirror of PM_AddCurrents from rerelease `p_move.cpp`: handles ladder
+ * specific motion tweaks, water currents, and conveyor-style ground currents
+ * before pmove acceleration is applied.
+ */
+export function applyPmoveAddCurrents(params: AddCurrentsParams): Vec3 {
+  const {
+    wishVelocity,
+    onLadder,
+    onGround,
+    waterlevel,
+    watertype,
+    groundContents,
+    cmd,
+    viewPitch,
+    maxSpeed,
+    ladderMod,
+    waterSpeed,
+    forward,
+    origin,
+    mins,
+    maxs,
+    trace = DEFAULT_TRACE,
+  } = params;
+
+  let adjusted = wishVelocity;
+
+  if (onLadder) {
+    adjusted = applyLadderAdjustments({
+      wishVelocity: adjusted,
+      cmd,
+      waterlevel,
+      viewPitch,
+      maxSpeed,
+      ladderMod,
+      onGround,
+      forward,
+      origin,
+      mins,
+      maxs,
+      trace,
+    });
+  }
+
+  const waterVelocity = waterCurrentVelocity({ watertype, waterlevel, onGround, waterSpeed });
+  if (waterVelocity !== ZERO_VEC3) {
+    adjusted = addVec3(adjusted, waterVelocity);
+  }
+
+  if (onGround) {
+    const groundVelocity = groundCurrentVelocity({ groundContents });
+    if (groundVelocity !== ZERO_VEC3) {
+      adjusted = addVec3(adjusted, groundVelocity);
+    }
+  }
+
+  return adjusted;
+}
+
+interface LadderAdjustParams {
+  readonly wishVelocity: Vec3;
+  readonly cmd: PmoveCmd;
+  readonly waterlevel: WaterLevel;
+  readonly viewPitch: number;
+  readonly maxSpeed: number;
+  readonly ladderMod: number;
+  readonly onGround: boolean;
+  readonly forward: Vec3;
+  readonly origin: Vec3;
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly trace: PmoveTraceFn;
+}
+
+function applyLadderAdjustments(params: LadderAdjustParams): Vec3 {
+  const { wishVelocity, cmd, waterlevel, viewPitch, maxSpeed, ladderMod, onGround, forward, origin, mins, maxs, trace } = params;
+  const buttons = cmd.buttons ?? 0;
+  let adjusted = { ...wishVelocity };
+
+  if ((buttons & (PlayerButton.Jump | PlayerButton.Crouch)) !== 0) {
+    const ladderSpeed = isAtLeastWaistDeep(waterlevel) ? maxSpeed : DEFAULT_FORWARD_LADDER_CLAMP;
+    adjusted = {
+      ...adjusted,
+      z: buttons & PlayerButton.Jump ? ladderSpeed : -ladderSpeed,
+    };
+  } else if (cmd.forwardmove) {
+    const clamped = clamp(cmd.forwardmove, -DEFAULT_FORWARD_LADDER_CLAMP, DEFAULT_FORWARD_LADDER_CLAMP);
+    if (cmd.forwardmove > 0) {
+      const climb = viewPitch < LADDER_ASCEND_PITCH_THRESHOLD ? clamped : -clamped;
+      adjusted = { ...adjusted, z: climb };
+    } else {
+      if (!onGround) {
+        adjusted = { ...adjusted, x: 0, y: 0 };
+      }
+      adjusted = { ...adjusted, z: clamped };
+    }
+  } else {
+    adjusted = { ...adjusted, z: 0 };
+  }
+
+  if (!onGround) {
+    if (cmd.sidemove) {
+      let sideSpeed = clamp(cmd.sidemove, -DEFAULT_SIDE_LADDER_CLAMP, DEFAULT_SIDE_LADDER_CLAMP);
+      if (waterlevel < WaterLevel.Waist) {
+        sideSpeed *= ladderMod;
+      }
+
+      const flatForward = normalizeVec3({ x: forward.x, y: forward.y, z: 0 });
+      if (flatForward.x !== 0 || flatForward.y !== 0) {
+        const spot = addVec3(origin, scaleVec3(flatForward, LADDER_TRACE_DISTANCE));
+        const tr = trace(origin, spot, mins, maxs);
+        if (
+          tr.fraction !== 1 &&
+          !tr.allsolid &&
+          tr.contents !== undefined &&
+          (tr.contents & CONTENTS_LADDER) !== 0 &&
+          tr.planeNormal
+        ) {
+          const right = crossVec3(tr.planeNormal, UP_VECTOR);
+          adjusted = { ...adjusted, x: 0, y: 0 };
+          adjusted = addVec3(adjusted, scaleVec3(right, -sideSpeed));
+        }
+      }
+    } else {
+      adjusted = {
+        ...adjusted,
+        x: clampHorizontal(adjusted.x),
+        y: clampHorizontal(adjusted.y),
+      };
+    }
+  }
+
+  return adjusted;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function clampHorizontal(value: number): number {
+  if (value < -LADDER_HORIZONTAL_CAP) {
+    return -LADDER_HORIZONTAL_CAP;
+  }
+  if (value > LADDER_HORIZONTAL_CAP) {
+    return LADDER_HORIZONTAL_CAP;
+  }
+  return value;
+}

package/src/pmove/dimensions.ts

@@ -0,0 +1,40 @@
+import type { Vec3 } from '../math/vec3.js';
+import { PmFlag, type PmFlags, PmType } from './constants.js';
+
+export interface PlayerDimensions {
+  readonly mins: Vec3;
+  readonly maxs: Vec3;
+  readonly viewheight: number;
+}
+
+function createVec3(x: number, y: number, z: number): Vec3 {
+  return { x, y, z } satisfies Vec3;
+}
+
+/**
+ * Pure mirror of PM_SetDimensions from rerelease `p_move.cpp`.
+ * Computes the mins/maxs/viewheight triplet for a player based on
+ * their movement type and ducked flag without mutating inputs.
+ */
+export function computePlayerDimensions(pmType: PmType, pmFlags: PmFlags): PlayerDimensions {
+  const minsBase = createVec3(-16, -16, 0);
+  const maxsBase = createVec3(16, 16, 16);
+
+  if (pmType === PmType.Gib) {
+    return {
+      mins: minsBase,
+      maxs: maxsBase,
+      viewheight: 8,
+    } satisfies PlayerDimensions;
+  }
+
+  const ducked = pmType === PmType.Dead || (pmFlags & PmFlag.Ducked) !== 0;
+  const mins = createVec3(minsBase.x, minsBase.y, -24);
+  const maxs = createVec3(maxsBase.x, maxsBase.y, ducked ? 4 : 32);
+
+  return {
+    mins,
+    maxs,
+    viewheight: ducked ? -2 : 22,
+  } satisfies PlayerDimensions;
+}