@quake2ts/shared 0.0.1

package/src/protocol/stats.ts

@@ -0,0 +1,161 @@
+import { setCompressedInteger, getCompressedInteger } from './bitpack.js';
+import { PowerupId } from '../items/powerups.js';
+
+// Matching rerelease/bg_local.h:196-262
+export enum PlayerStat {
+    STAT_HEALTH_ICON = 0,
+    STAT_HEALTH,
+    STAT_AMMO_ICON,
+    STAT_AMMO,
+    STAT_ARMOR_ICON,
+    STAT_ARMOR,
+    STAT_SELECTED_ICON,
+    STAT_PICKUP_ICON,
+    STAT_PICKUP_STRING,
+    STAT_TIMER_ICON,
+    STAT_TIMER,
+    STAT_HELPICON,
+    STAT_SELECTED_ITEM,
+    STAT_LAYOUTS,
+    STAT_FRAGS,
+    STAT_FLASHES,
+    STAT_CHASE,
+    STAT_SPECTATOR,
+
+    // CTF Stats (Rerelease/KEX)
+    STAT_CTF_TEAM1_PIC = 18,
+    STAT_CTF_TEAM1_CAPS = 19,
+    STAT_CTF_TEAM2_PIC = 20,
+    STAT_CTF_TEAM2_CAPS = 21,
+    STAT_CTF_FLAG_PIC = 22,
+    STAT_CTF_JOINED_TEAM1_PIC = 23,
+    STAT_CTF_JOINED_TEAM2_PIC = 24,
+    STAT_CTF_TEAM1_HEADER = 25,
+    STAT_CTF_TEAM2_HEADER = 26,
+    STAT_CTF_TECH = 27,
+    STAT_CTF_ID_VIEW = 28,
+    STAT_CTF_MATCH = 29,
+    STAT_CTF_ID_VIEW_COLOR = 30,
+    STAT_CTF_TEAMINFO = 31,
+
+    // Rerelease additions
+    STAT_WEAPONS_OWNED_1 = 32,
+    STAT_WEAPONS_OWNED_2 = 33,
+
+    // Ammo counts (start index)
+    STAT_AMMO_INFO_START = 34,
+    // Calculated below, but enum needs literal or constant if we want to use it as type.
+    // However, for TS Enum, we can just define start.
+
+    // Powerups start after Ammo.
+    // AMMO_MAX=12, 9 bits each -> 108 bits -> 7 int16s.
+    // 34 + 7 = 41.
+    STAT_POWERUP_INFO_START = 41,
+
+    // Keys and other KEX stats (Start after Powerups)
+    // POWERUP_MAX=23, 2 bits each -> 46 bits -> 3 int16s.
+    // 41 + 3 = 44.
+    STAT_KEY_A = 44,
+    STAT_KEY_B = 45,
+    STAT_KEY_C = 46,
+
+    STAT_ACTIVE_WHEEL_WEAPON = 47,
+    STAT_COOP_RESPAWN = 48,
+    STAT_LIVES = 49,
+    STAT_HIT_MARKER = 50,
+    STAT_SELECTED_ITEM_NAME = 51,
+    STAT_HEALTH_BARS = 52,
+    STAT_ACTIVE_WEAPON = 53,
+
+    STAT_LAST
+}
+
+// Constants for bit packing logic
+export const AMMO_MAX = 12;
+export const NUM_BITS_FOR_AMMO = 9;
+export const NUM_AMMO_STATS = Math.ceil((AMMO_MAX * NUM_BITS_FOR_AMMO) / 16); // 7
+
+export const POWERUP_MAX = 23; // Adjusted to include TechRegeneration (index 22)
+export const NUM_BITS_FOR_POWERUP = 2;
+export const NUM_POWERUP_STATS = Math.ceil((POWERUP_MAX * NUM_BITS_FOR_POWERUP) / 16); // 3
+
+// Powerup ID mapping from string to C++ integer index (powerup_t in bg_local.h)
+const POWERUP_STAT_MAP: Partial<Record<PowerupId, number>> = {
+  [PowerupId.PowerScreen]: 0,
+  [PowerupId.PowerShield]: 1,
+  // 2 is POWERUP_AM_BOMB (not in PowerupId?)
+  [PowerupId.QuadDamage]: 3,
+  [PowerupId.QuadFire]: 4,
+  [PowerupId.Invulnerability]: 5,
+  [PowerupId.Invisibility]: 6,
+  [PowerupId.Silencer]: 7,
+  [PowerupId.Rebreather]: 8,
+  [PowerupId.EnviroSuit]: 9,
+  [PowerupId.Bandolier]: 10, // Placeholder/Map mismatch handling?
+  [PowerupId.AmmoPack]: 10, // Original reused indices or had gaps?
+  [PowerupId.IRGoggles]: 11,
+  [PowerupId.DoubleDamage]: 12,
+  [PowerupId.SphereVengeance]: 13,
+  [PowerupId.SphereHunter]: 14,
+  [PowerupId.SphereDefender]: 15,
+  [PowerupId.Doppelganger]: 16,
+  [PowerupId.Flashlight]: 17,
+  [PowerupId.Compass]: 18,
+  [PowerupId.TechResistance]: 19,
+  [PowerupId.TechStrength]: 20,
+  [PowerupId.TechHaste]: 21,
+  [PowerupId.TechRegeneration]: 22,
+  // Add missing mappings to avoid runtime lookups failing for new types
+  [PowerupId.TagToken]: -1,
+};
+
+// 9 bits for ammo count
+export function G_SetAmmoStat(stats: number[], ammoId: number, count: number): void {
+  if (ammoId < 0 || ammoId >= AMMO_MAX) return;
+
+  // Clamp count to 9 bits (0-511)
+  let val = count;
+  if (val > 511) val = 511;
+  if (val < 0) val = 0;
+
+  setCompressedInteger(stats, PlayerStat.STAT_AMMO_INFO_START, ammoId, val, NUM_BITS_FOR_AMMO);
+}
+
+export function G_GetAmmoStat(stats: number[], ammoId: number): number {
+  if (ammoId < 0 || ammoId >= AMMO_MAX) return 0;
+  return getCompressedInteger(stats, PlayerStat.STAT_AMMO_INFO_START, ammoId, NUM_BITS_FOR_AMMO);
+}
+
+// 2 bits for powerup active/inactive state
+export function G_SetPowerupStat(stats: number[], powerupId: PowerupId | number, val: number): void {
+  let index: number | undefined;
+
+  if (typeof powerupId === 'number') {
+    index = powerupId;
+  } else {
+    index = POWERUP_STAT_MAP[powerupId];
+  }
+
+  if (index === undefined || index < 0 || index >= POWERUP_MAX) return;
+
+  // Clamp value to 2 bits (0-3)
+  let safeVal = val;
+  if (safeVal > 3) safeVal = 3;
+  if (safeVal < 0) safeVal = 0;
+
+  setCompressedInteger(stats, PlayerStat.STAT_POWERUP_INFO_START, index, safeVal, NUM_BITS_FOR_POWERUP);
+}
+
+export function G_GetPowerupStat(stats: number[], powerupId: PowerupId | number): number {
+  let index: number | undefined;
+
+  if (typeof powerupId === 'number') {
+    index = powerupId;
+  } else {
+    index = POWERUP_STAT_MAP[powerupId];
+  }
+
+  if (index === undefined || index < 0 || index >= POWERUP_MAX) return 0;
+
+  return getCompressedInteger(stats, PlayerStat.STAT_POWERUP_INFO_START, index, NUM_BITS_FOR_POWERUP);
+}

package/src/protocol/tempEntity.ts

@@ -0,0 +1,69 @@
+
+// Temp entity constants from Quake 2
+export enum TempEntity {
+  GUNSHOT = 0,
+  BLOOD = 1,
+  BLASTER = 2,
+  RAILTRAIL = 3,
+  SHOTGUN = 4,
+  EXPLOSION1 = 5,
+  EXPLOSION2 = 6,
+  ROCKET_EXPLOSION = 7,
+  GRENADE_EXPLOSION = 8,
+  SPARKS = 9,
+  SPLASH = 10,
+  BUBBLETRAIL = 11,
+  SCREEN_SPARKS = 12,
+  SHIELD_SPARKS = 13,
+  BULLET_SPARKS = 14,
+  LASER_SPARKS = 15,
+  PARASITE_ATTACK = 16,
+  ROCKET_EXPLOSION_WATER = 17,
+  GRENADE_EXPLOSION_WATER = 18,
+  MEDIC_CABLE_ATTACK = 19,
+  BFG_EXPLOSION = 20,
+  BFG_BIGEXPLOSION = 21,
+  BOSSTPORT = 22,
+  BFG_LASER = 23,
+  GRAPPLE_CABLE = 24,
+  WELDING_SPARKS = 25,
+  GREENBLOOD = 26,
+  BLUEHYPERBLASTER = 27,
+  PLASMA_EXPLOSION = 28,
+  TUNNEL_SPARKS = 29,
+  // ROGUE
+  BLASTER2 = 30,
+  RAILTRAIL2 = 31,
+  FLAME = 32,
+  LIGHTNING = 33,
+  DEBUGTRAIL = 34,
+  PLAIN_EXPLOSION = 35,
+  FLASHLIGHT = 36,
+  FORCEWALL = 37,
+  HEATBEAM = 38,
+  MONSTER_HEATBEAM = 39,
+  STEAM = 40,
+  BUBBLETRAIL2 = 41,
+  MOREBLOOD = 42,
+  HEATBEAM_SPARKS = 43,
+  HEATBEAM_STEAM = 44,
+  CHAINFIST_SMOKE = 45,
+  ELECTRIC_SPARKS = 46,
+  TRACKER_EXPLOSION = 47,
+  TELEPORT_EFFECT = 48,
+  DBALL_GOAL = 49,
+  WIDOWBEAMOUT = 50,
+  NUKEBLAST = 51,
+  WIDOWSPLASH = 52,
+  EXPLOSION1_BIG = 53,
+  EXPLOSION1_NP = 54,
+  FLECHETTE = 55,
+  BLUEHYPERBLASTER_KEX = 56,
+  BFG_ZAP = 57,
+  BERSERK_SLAM = 58,
+  GRAPPLE_CABLE_2 = 59,
+  POWER_SPLASH = 60,
+  LIGHTNING_BEAM = 61,
+  EXPLOSION1_NL = 62,
+  EXPLOSION2_NL = 63
+}

package/src/protocol/usercmd.ts

@@ -0,0 +1,63 @@
+import { angleMod } from '../math/angles.js';
+import type { Vec3 } from '../math/vec3.js';
+import { PlayerButton } from '../pmove/constants.js';
+
+export interface UserCommand {
+  readonly msec: number;
+  readonly buttons: PlayerButton;
+  readonly angles: Vec3;
+  readonly forwardmove: number;
+  readonly sidemove: number;
+  readonly upmove: number;
+  readonly serverFrame?: number;
+  readonly sequence: number;
+  readonly lightlevel: number;
+  readonly impulse: number;
+}
+
+export interface MouseDelta {
+  readonly deltaX: number;
+  readonly deltaY: number;
+}
+
+export interface MouseLookOptions {
+  readonly sensitivity: number;
+  readonly invertY: boolean;
+  readonly sensitivityX?: number;
+  readonly sensitivityY?: number;
+}
+
+export const DEFAULT_FORWARD_SPEED = 200;
+export const DEFAULT_SIDE_SPEED = 200;
+export const DEFAULT_UP_SPEED = 200;
+export const DEFAULT_YAW_SPEED = 140;
+export const DEFAULT_PITCH_SPEED = 150;
+export const DEFAULT_MOUSE_SENSITIVITY = 3;
+
+function clampPitch(pitch: number): number {
+  const normalized = angleMod(pitch);
+
+  if (normalized > 89 && normalized < 180) return 89;
+  if (normalized < 271 && normalized >= 180) return 271;
+
+  return normalized;
+}
+
+export function addViewAngles(current: Vec3, delta: Vec3): Vec3 {
+  return {
+    x: clampPitch(current.x + delta.x),
+    y: angleMod(current.y + delta.y),
+    z: angleMod(current.z + delta.z),
+  } satisfies Vec3;
+}
+
+export function mouseDeltaToViewDelta(delta: MouseDelta, options: MouseLookOptions): Vec3 {
+  const yawScale = options.sensitivityX ?? options.sensitivity;
+  const pitchScale = (options.sensitivityY ?? options.sensitivity) * (options.invertY ? -1 : 1);
+
+  return {
+    x: delta.deltaY * pitchScale,
+    y: delta.deltaX * yawScale,
+    z: 0,
+  } satisfies Vec3;
+}

package/src/protocol/writeUserCmd.ts

@@ -0,0 +1,30 @@
+import { BinaryWriter } from '../io/binaryWriter.js';
+import { UserCommand } from './usercmd.js';
+
+export function writeUserCommand(writer: BinaryWriter, cmd: UserCommand): void {
+  // msec (byte)
+  writer.writeByte(cmd.msec);
+
+  // buttons (byte)
+  writer.writeByte(cmd.buttons);
+
+  // angles (short * 3) - Scaled 360 -> 65536
+  writer.writeAngle16(cmd.angles.x);
+  writer.writeAngle16(cmd.angles.y);
+  writer.writeAngle16(cmd.angles.z);
+
+  // forwardmove (short)
+  writer.writeShort(cmd.forwardmove);
+
+  // sidemove (short)
+  writer.writeShort(cmd.sidemove);
+
+  // upmove (short)
+  writer.writeShort(cmd.upmove);
+
+  // impulse (byte)
+  writer.writeByte(cmd.impulse);
+
+  // lightlevel (byte)
+  writer.writeByte(0); // TODO: Lightlevel
+}

package/src/replay/index.ts

@@ -0,0 +1,2 @@
+export * from './schema.js';
+export * from './io.js';

package/src/replay/io.ts

@@ -0,0 +1,37 @@
+import { ReplaySession, ReplayFrame } from './schema.js';
+import { UserCommand } from '../protocol/usercmd.js';
+
+export function serializeReplay(session: ReplaySession): string {
+    return JSON.stringify(session, null, 2);
+}
+
+export function deserializeReplay(json: string): ReplaySession {
+    const session = JSON.parse(json);
+
+    // Validate structure lightly
+    if (!session.metadata || !Array.isArray(session.frames)) {
+        throw new Error('Invalid replay format: missing metadata or frames');
+    }
+
+    return session as ReplaySession;
+}
+
+export function createReplaySession(map: string, seed?: number): ReplaySession {
+    return {
+        metadata: {
+            map,
+            date: new Date().toISOString(),
+            version: '1.0',
+            seed
+        },
+        frames: []
+    };
+}
+
+export function addReplayFrame(session: ReplaySession, cmd: UserCommand, serverFrame: number, startTime: number) {
+    session.frames.push({
+        serverFrame,
+        cmd,
+        timestamp: Date.now() - startTime
+    });
+}

package/src/replay/schema.ts

@@ -0,0 +1,42 @@
+import { UserCommand } from '../protocol/usercmd.js';
+
+export interface ReplayFrame {
+    /**
+     * The server frame number this command was executed on.
+     */
+    serverFrame: number;
+
+    /**
+     * The command sent by the client.
+     */
+    cmd: UserCommand;
+
+    /**
+     * The timestamp (in ms) relative to start of recording.
+     */
+    timestamp: number;
+
+    /**
+     * The hash of the game state AFTER this frame was executed.
+     * Optional for backward compatibility or lightweight recording.
+     */
+    stateHash?: number;
+}
+
+export interface ReplaySession {
+    /**
+     * Metadata about the recording.
+     */
+    metadata: {
+        map: string;
+        date: string;
+        version: string;
+        seed?: number; // Random seed
+        gravity?: { x: number, y: number, z: number }; // Capture gravity
+    };
+
+    /**
+     * The sequence of inputs.
+     */
+    frames: ReplayFrame[];
+}

package/src/testing.ts

@@ -0,0 +1,200 @@
+import type { PmoveTraceFn, PmoveTraceResult } from './pmove/types.js';
+import type { Vec3 } from './math/vec3.js';
+import { CONTENTS_LADDER } from './bsp/contents.js';
+
+export const intersects = (end: Vec3, maxs: Vec3, mins: Vec3, boxMins: Vec3, boxMaxs: Vec3): boolean => {
+  return (
+    end.x + maxs.x > boxMins.x &&
+    end.x + mins.x < boxMaxs.x &&
+    end.y + maxs.y > boxMins.y &&
+    end.y + mins.y < boxMaxs.y &&
+    end.z + maxs.z > boxMins.z &&
+    end.z + mins.z < boxMaxs.z
+  );
+};
+
+export const stairTrace: PmoveTraceFn = (start: Vec3, end: Vec3, mins?: Vec3, maxs?: Vec3): PmoveTraceResult => {
+  // Default bbox if not provided
+  const useMins = mins ?? { x: -16, y: -16, z: -24 };
+  const useMaxs = maxs ?? { x: 16, y: 16, z: 32 };
+
+  // Step: x from 0 forward, z from 0 to 8
+  const STEP_HEIGHT = 8;
+  const STEP_X_START = 0;
+
+  const isHorizontal = Math.abs(end.z - start.z) < 1;
+  const isMovingDown = end.z < start.z;
+
+  // Check if trying to go below the floor
+  const endMinZ = end.z + useMins.z;
+  const startMinZ = start.z + useMins.z;
+  const endMaxX = end.x + useMaxs.x;
+
+  // If moving horizontally, check if we'd hit the vertical face of the step
+  // The step only blocks if the player's origin is below the step height
+  if (isHorizontal && end.z < STEP_HEIGHT && endMaxX > STEP_X_START) {
+    // Check if we're crossing into the step area
+    const startMaxX = start.x + useMaxs.x;
+    if (startMaxX <= STEP_X_START) {
+      // We're moving from before the step to past it, block
+      return {
+        allsolid: false,
+        startsolid: false,
+        fraction: 0,
+        endpos: start,
+        planeNormal: { x: -1, y: 0, z: 0 },
+        contents: 1,
+      };
+    }
+  }
+
+  // If moving down and over the step area, land on the step surface
+  if (isMovingDown && end.x >= STEP_X_START) {
+    // The step surface is at z=STEP_HEIGHT in world space
+    // The player's bbox bottom reaches this plane when origin.z + mins.z = STEP_HEIGHT
+    // So the player's origin should be at z = STEP_HEIGHT - mins.z
+    const landZ = STEP_HEIGHT - useMins.z;
+
+    // Check if we'd pass through the step surface
+    // We cross the plane if start is above it and end would be below it
+    if (startMinZ > STEP_HEIGHT && endMinZ < STEP_HEIGHT) {
+      // Calculate the fraction along the ray where we intersect the plane
+      // The bbox bottom is at: start.z + useMins.z + t * (end.z - start.z + 0) = STEP_HEIGHT
+      // Solving for t: t = (STEP_HEIGHT - (start.z + useMins.z)) / ((end.z + useMins.z) - (start.z + useMins.z))
+      const fraction = (STEP_HEIGHT - startMinZ) / (endMinZ - startMinZ);
+
+      // Clamp to valid range [0, 1]
+      const clampedFraction = Math.max(0, Math.min(1, fraction));
+
+      // Calculate the endpos along the ray at this fraction
+      const finalX = start.x + clampedFraction * (end.x - start.x);
+      const finalY = start.y + clampedFraction * (end.y - start.y);
+      const finalZ = start.z + clampedFraction * (end.z - start.z);
+
+      return {
+        allsolid: false,
+        startsolid: false,
+        fraction: clampedFraction,
+        endpos: { x: finalX, y: finalY, z: finalZ },
+        planeNormal: { x: 0, y: 0, z: 1 },
+        contents: 1,
+      };
+    }
+  }
+
+  // If moving down and would go below floor level, block at floor
+  if (isMovingDown && endMinZ < 0) {
+    // Floor is at z=0, so player origin should be at z = -mins.z when landing
+    const landZ = -useMins.z;
+
+    // Only apply if we're crossing the floor plane
+    if (startMinZ >= 0) {
+      // Calculate fraction where bbox bottom hits z=0
+      const fraction = (0 - startMinZ) / (endMinZ - startMinZ);
+      const clampedFraction = Math.max(0, Math.min(1, fraction));
+
+      const finalX = start.x + clampedFraction * (end.x - start.x);
+      const finalY = start.y + clampedFraction * (end.y - start.y);
+      const finalZ = start.z + clampedFraction * (end.z - start.z);
+
+      return {
+        allsolid: false,
+        startsolid: false,
+        fraction: clampedFraction,
+        endpos: { x: finalX, y: finalY, z: finalZ },
+        planeNormal: { x: 0, y: 0, z: 1 },
+        contents: 1,
+      };
+    }
+
+    // Already below floor, block immediately
+    return {
+      allsolid: false,
+      startsolid: false,
+      fraction: 0,
+      endpos: start,
+      planeNormal: { x: 0, y: 0, z: 1 },
+      contents: 1,
+    };
+  }
+
+  // Free movement
+  return {
+    allsolid: false,
+    startsolid: false,
+    fraction: 1.0,
+    endpos: end,
+    contents: 0,
+  };
+};
+
+export const ladderTrace: PmoveTraceFn = (start: Vec3, end: Vec3, mins?: Vec3, maxs?: Vec3): PmoveTraceResult => {
+  // Default bbox if not provided
+  const useMins = mins ?? { x: -16, y: -16, z: -24 };
+  const useMaxs = maxs ?? { x: 16, y: 16, z: 32 };
+
+  // Define the ladder volume (x=0 to x=8, y=-16 to y=16, z=0 to z=100)
+  const LADDER_X_MIN = 0;
+  const LADDER_X_MAX = 8;
+  const LADDER_Y_MIN = -16;
+  const LADDER_Y_MAX = 16;
+  const LADDER_Z_MIN = 0;
+  const LADDER_Z_MAX = 100;
+
+  // Check if end position is within the ladder volume
+  const endInLadder =
+    end.x + useMins.x < LADDER_X_MAX &&
+    end.x + useMaxs.x > LADDER_X_MIN &&
+    end.y + useMins.y < LADDER_Y_MAX &&
+    end.y + useMaxs.y > LADDER_Y_MIN &&
+    end.z + useMins.z < LADDER_Z_MAX &&
+    end.z + useMaxs.z > LADDER_Z_MIN;
+
+  // If moving into the ladder from outside (moving forward into it)
+  const movingIntoLadder = start.x < LADDER_X_MIN && end.x >= LADDER_X_MIN;
+
+  // If moving horizontally into the ladder front face, block with ladder surface
+  if (movingIntoLadder && Math.abs(end.z - start.z) < 0.1) {
+    return {
+      allsolid: false,
+      startsolid: false,
+      fraction: 0,
+      endpos: start,
+      planeNormal: { x: -1, y: 0, z: 0 },
+      contents: CONTENTS_LADDER,
+    };
+  }
+
+  // If we're in the ladder volume, return success but with CONTENTS_LADDER
+  // This allows the player to detect they're on a ladder without blocking movement
+  if (endInLadder) {
+    return {
+      allsolid: false,
+      startsolid: false,
+      fraction: 1.0,
+      endpos: end,
+      contents: CONTENTS_LADDER,
+    };
+  }
+
+  // Floor at z=0
+  if (end.z + useMins.z <= 0) {
+    return {
+      allsolid: false,
+      startsolid: false,
+      fraction: 0,
+      endpos: start,
+      planeNormal: { x: 0, y: 0, z: 1 },
+      contents: 1,
+    };
+  }
+
+  // No collision - free movement
+  return {
+    allsolid: false,
+    startsolid: false,
+    fraction: 1.0,
+    endpos: end,
+    contents: 0,
+  };
+};