@quake2ts/test-utils 0.0.1

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@quake2ts/test-utils",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./src/engine/mocks/webgpu": {
+      "types": "./src/engine/mocks/webgpu.ts",
+      "import": "./src/engine/mocks/webgpu.ts",
+      "require": "./src/engine/mocks/webgpu.ts"
+    },
+    "./src/setup/webgpu": {
+      "types": "./src/setup/webgpu.ts",
+      "import": "./src/setup/webgpu.ts",
+      "require": "./src/setup/webgpu.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "gl-matrix": "^3.4.4",
+    "@quake2ts/game": "0.0.1",
+    "@quake2ts/server": "0.0.1",
+    "@quake2ts/engine": "^0.0.1",
+    "@quake2ts/shared": "0.0.1"
+  },
+  "peerDependencies": {
+    "@webgpu/types": "^0.1.68",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.57.0",
+    "pngjs": "^7.0.0",
+    "vitest": "^1.6.0",
+    "webgpu": "^0.3.8"
+  },
+  "peerDependenciesMeta": {
+    "@webgpu/types": {
+      "optional": true
+    },
+    "pixelmatch": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    },
+    "pngjs": {
+      "optional": true
+    },
+    "webgpu": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@napi-rs/canvas": "^0.1.84",
+    "@types/jsdom": "^27.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "@webgpu/types": "^0.1.68",
+    "fake-indexeddb": "^6.0.0",
+    "jsdom": "^27.3.0",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.57.0",
+    "pngjs": "^7.0.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0",
+    "webgpu": "^0.3.8"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest run --passWithNoTests",
+    "test:webgpu": "cross-env TEST_TYPE=webgpu vitest run"
+  }
+}

package/src/client/helpers/hud.ts

@@ -0,0 +1,114 @@
+import { vi } from 'vitest';
+import { PlayerState } from '@quake2ts/shared';
+import { PlayerClient, PowerupId, KeyId } from '@quake2ts/game';
+import { FrameRenderStats } from '@quake2ts/engine';
+
+// Since test-utils cannot import from client, we need to mock MessageSystem here or define an interface
+// The Draw_Hud function expects a MessageSystem which has drawCenterPrint and drawNotifications.
+// However, the signature in `hud.ts` uses the class.
+// For testing purposes, we might need a mock MessageSystem interface in test-utils or import it if possible.
+// But we can't import from client. So we will return a mock object that satisfies the interface.
+
+export interface HudState {
+    ps: PlayerState;
+    client: PlayerClient;
+    health: number;
+    armor: number;
+    ammo: number;
+    stats: number[]; // Game stats (health, armor, ammo indices)
+    pickupIcon?: string;
+    damageIndicators?: any[];
+    renderStats?: FrameRenderStats; // Optional render stats for verification
+    timeMs: number;
+    messages: any; // Using any for now to avoid circular dependency
+}
+
+export function createMockHudState(overrides?: Partial<HudState>): HudState {
+    const defaultPs = {
+        damageAlpha: 0,
+        damageIndicators: [],
+        origin: { x: 0, y: 0, z: 0 },
+        velocity: { x: 0, y: 0, z: 0 },
+        viewAngles: { x: 0, y: 0, z: 0 },
+        onGround: true,
+        waterLevel: 0,
+        mins: { x: 0, y: 0, z: 0 },
+        maxs: { x: 0, y: 0, z: 0 },
+        centerPrint: null,
+        notify: null
+    } as unknown as PlayerState;
+
+    const defaultClient = {
+        inventory: {
+            armor: { armorCount: 50, armorType: 'jacket' },
+            currentWeapon: 1, // Blaster usually
+            ammo: { counts: [] },
+            keys: new Set<KeyId>(),
+            powerups: new Map<PowerupId, number>()
+        }
+    } as unknown as PlayerClient;
+
+    // Use a numeric array for game stats (EntityState.stats)
+    // Indexes: 1=Health, 2=Ammo, 4=Armor (based on client/src/index.ts usage)
+    const defaultStats = new Array(32).fill(0);
+    defaultStats[1] = 100; // Health
+    defaultStats[2] = 25;  // Ammo
+    defaultStats[4] = 50;  // Armor
+
+    const defaultMessages = {
+        drawCenterPrint: vi.fn(),
+        drawNotifications: vi.fn(),
+        addCenterPrint: vi.fn(),
+        addNotification: vi.fn(),
+        clear: vi.fn()
+    };
+
+    return {
+        ps: overrides?.ps ?? defaultPs,
+        client: overrides?.client ?? defaultClient,
+        health: overrides?.health ?? 100,
+        armor: overrides?.armor ?? 50,
+        ammo: overrides?.ammo ?? 25,
+        stats: overrides?.stats ?? defaultStats,
+        pickupIcon: overrides?.pickupIcon,
+        damageIndicators: overrides?.damageIndicators,
+        renderStats: overrides?.renderStats,
+        timeMs: overrides?.timeMs ?? 1000,
+        messages: overrides?.messages ?? defaultMessages
+    };
+}
+
+export function createMockScoreboard(players: any[] = []): any {
+    return {
+        players: players,
+        draw: vi.fn()
+    };
+}
+
+export interface MockChatMessage {
+    text: string;
+    sender?: string;
+    timestamp?: number;
+}
+
+export function createMockChatMessage(text: string, sender?: string, timestamp: number = Date.now()): MockChatMessage {
+    return {
+        text,
+        sender,
+        timestamp
+    };
+}
+
+export interface MockNotification {
+    type: string;
+    message: string;
+    duration?: number;
+}
+
+export function createMockNotification(type: string, message: string, duration: number = 3000): MockNotification {
+    return {
+        type,
+        message,
+        duration
+    };
+}

package/src/client/helpers/prediction.ts

@@ -0,0 +1,136 @@
+import { EntityState } from '@quake2ts/shared';
+import { ClientState, createMockClientState } from '../mocks/state.js';
+import { UserCommand } from '@quake2ts/shared';
+
+// -- Interfaces --
+
+export interface PredictionScenario {
+  clientState: ClientState;
+  snapshots: EntityState[][];
+  lagMs: number;
+}
+
+export interface SmoothingAnalysis {
+  smooth: boolean;
+  maxError: number;
+  averageError: number;
+  jumps: number[];
+}
+
+// -- Helpers --
+
+export const createPredictionTestScenario = (lagMs: number = 100): PredictionScenario => {
+  // Create a base client state using the factory
+  const clientState = createMockClientState({
+    playerNum: 0,
+    serverTime: 1000,
+    getClientName: (num: number) => 'TestPlayer'
+  });
+
+  // Create some snapshot history
+  const snapshots: EntityState[][] = [];
+  for (let i = 0; i < 5; i++) {
+    const frameEntities: EntityState[] = [
+      {
+        number: 1,
+        origin: { x: i * 10, y: 0, z: 0 },
+        angles: { x: 0, y: 0, z: 0 },
+        oldOrigin: { x: (i - 1) * 10, y: 0, z: 0 },
+        modelIndex: 0,
+        modelIndex2: 0,
+        modelIndex3: 0,
+        modelIndex4: 0,
+        frame: 0,
+        skinNum: 0,
+        effects: 0,
+        renderfx: 0,
+        solid: 0,
+        sound: 0,
+        event: 0
+      }
+    ];
+    snapshots.push(frameEntities);
+  }
+
+  return {
+    clientState,
+    snapshots,
+    lagMs
+  };
+};
+
+export const simulateClientPrediction = (
+  state: ClientState,
+  input: UserCommand,
+  deltaTime: number
+): ClientState => {
+  // This is a stub for simulating prediction
+  // Real implementation would invoke PMove logic
+  // For testing helpers, we might just update time
+  return {
+    ...state,
+    serverTime: state.serverTime + deltaTime * 1000
+  };
+};
+
+export const createInterpolationTestData = (
+  startState: EntityState,
+  endState: EntityState,
+  steps: number = 10
+): EntityState[] => {
+  const result: EntityState[] = [];
+
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps;
+    const lerp = (a: number, b: number) => a + (b - a) * t;
+
+    result.push({
+      ...startState,
+      origin: {
+        x: lerp(startState.origin.x, endState.origin.x),
+        y: lerp(startState.origin.y, endState.origin.y),
+        z: lerp(startState.origin.z, endState.origin.z),
+      },
+      angles: {
+         x: lerp(startState.angles.x, endState.angles.x),
+         y: lerp(startState.angles.y, endState.angles.y),
+         z: lerp(startState.angles.z, endState.angles.z),
+      }
+    });
+  }
+
+  return result;
+};
+
+export const verifySmoothing = (states: EntityState[]): SmoothingAnalysis => {
+  let maxError = 0;
+  let totalError = 0;
+  const jumps: number[] = [];
+
+  for (let i = 1; i < states.length; i++) {
+    const prev = states[i-1].origin;
+    const curr = states[i].origin;
+
+    const dx = curr.x - prev.x;
+    const dy = curr.y - prev.y;
+    const dz = curr.z - prev.z;
+    const dist = Math.sqrt(dx*dx + dy*dy + dz*dz);
+
+    // Assume constant velocity, check for large deviations
+    // Ideally we'd compare against expected position
+    // Here we just track distance changes
+
+    if (dist > 50) { // arbitrary jump threshold
+        jumps.push(i);
+    }
+
+    totalError += dist; // This isn't really error without a reference, but serves as a metric
+  }
+
+  return {
+    smooth: jumps.length === 0,
+    maxError,
+    averageError: totalError / (states.length - 1 || 1),
+    jumps
+  };
+};

package/src/client/helpers/view.ts

@@ -0,0 +1,201 @@
+
+import { vec3 } from 'gl-matrix';
+import { Camera } from '@quake2ts/engine';
+import { Vec3 } from '@quake2ts/shared';
+
+// Define RefDef interface locally if it's not exported from shared/engine,
+// or import it if we find it.
+// Based on grep, RefDef seems elusive or I missed it.
+// Standard Quake 2 RefDef:
+export interface RefDef {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  fov_x: number;
+  fov_y: number;
+  vieworg: vec3;
+  viewangles: vec3;
+  time: number;
+  rdflags: number;
+  // ... other fields
+}
+
+export interface ViewState {
+  camera: Camera;
+  viewport: { x: number; y: number; width: number; height: number };
+  refdef: RefDef;
+}
+
+export interface ViewScenario {
+  viewState: ViewState;
+  cleanup: () => void;
+}
+
+export interface CameraInput {
+  forward?: number;
+  right?: number;
+  up?: number;
+  pitchDelta?: number;
+  yawDelta?: number;
+  rollDelta?: number;
+}
+
+export interface DemoCameraResult {
+  origin: Vec3;
+  angles: Vec3;
+  fov: number;
+}
+
+function toVec3(v: Vec3 | vec3 | { x: number, y: number, z: number } | number[]): vec3 {
+  if (v instanceof Float32Array && v.length === 3) {
+    return v as vec3;
+  }
+  if (Array.isArray(v) && v.length === 3) {
+      return vec3.fromValues(v[0], v[1], v[2]);
+  }
+  if (typeof v === 'object' && 'x' in v && 'y' in v && 'z' in v) {
+    return vec3.fromValues(v.x, v.y, v.z);
+  }
+  // Fallback or error? defaulting to 0,0,0
+  return vec3.create();
+}
+
+/**
+ * Creates a mock Camera instance with optional overrides.
+ * Accepts partial Camera properties, where position/angles can be Vec3 objects or arrays.
+ */
+export function createMockCamera(overrides: Partial<Omit<Camera, 'position' | 'angles'> & { position: any, angles: any }> = {}): Camera {
+  const camera = new Camera();
+
+  if (overrides.position) {
+    camera.position = toVec3(overrides.position);
+  }
+  if (overrides.angles) {
+    camera.angles = toVec3(overrides.angles);
+  }
+  if (overrides.fov !== undefined) {
+    camera.fov = overrides.fov;
+  }
+  // Apply other properties if exposed by Camera class setters
+
+  return camera;
+}
+
+/**
+ * Creates a mock Demo Camera state result (for getDemoCamera mock).
+ * This returns a structure using Vec3 interface compatible with angleVectors, unlike Camera class.
+ */
+export function createMockDemoCameraResult(overrides: Partial<DemoCameraResult> = {}): DemoCameraResult {
+    return {
+        origin: overrides.origin || { x: 0, y: 0, z: 0 },
+        angles: overrides.angles || { x: 0, y: 0, z: 0 },
+        fov: overrides.fov ?? 90
+    };
+}
+
+/**
+ * Creates a mock RefDef object.
+ */
+export function createMockRefDef(overrides: Partial<RefDef> = {}): RefDef {
+  return {
+    x: 0,
+    y: 0,
+    width: 320,
+    height: 240,
+    fov_x: 90,
+    fov_y: 90,
+    vieworg: vec3.create(),
+    viewangles: vec3.create(),
+    time: 0,
+    rdflags: 0,
+    ...overrides
+  };
+}
+
+/**
+ * Creates a mock ViewState object.
+ */
+export function createMockViewState(overrides: Partial<ViewState> = {}): ViewState {
+  return {
+    camera: overrides.camera || createMockCamera(),
+    viewport: overrides.viewport || { x: 0, y: 0, width: 800, height: 600 },
+    refdef: overrides.refdef || createMockRefDef(),
+    ...overrides
+  };
+}
+
+/**
+ * Creates a pre-configured view test scenario.
+ */
+export function createViewTestScenario(scenarioType: 'firstPerson' | 'thirdPerson' | 'spectator'): ViewScenario {
+  const camera = createMockCamera();
+  const refdef = createMockRefDef();
+
+  switch (scenarioType) {
+    case 'firstPerson':
+      camera.position = vec3.fromValues(100, 100, 50);
+      camera.angles = vec3.fromValues(0, 45, 0);
+      vec3.copy(refdef.vieworg, camera.position);
+      vec3.copy(refdef.viewangles, camera.angles);
+      break;
+    case 'thirdPerson':
+      camera.position = vec3.fromValues(100, 100, 100); // Higher/back
+      camera.angles = vec3.fromValues(30, 45, 0); // Looking down
+      // Refdef might differ from camera in 3rd person (refdef usually is player eye, camera is offset)
+      vec3.set(refdef.vieworg, 100, 100, 50); // Player origin
+      break;
+    case 'spectator':
+      camera.position = vec3.fromValues(0, 0, 100);
+      camera.angles = vec3.fromValues(90, 0, 0); // Top down
+      break;
+  }
+
+  return {
+    viewState: {
+      camera,
+      viewport: { x: 0, y: 0, width: 800, height: 600 },
+      refdef
+    },
+    cleanup: () => {
+      // Any cleanup if needed
+    }
+  };
+}
+
+/**
+ * Simulates camera movement based on input delta.
+ * This is a helper to verify camera logic, not a replacement for full physics.
+ */
+export function simulateCameraMovement(camera: Camera, input: CameraInput, deltaTime: number): Camera {
+  // Simple movement simulation
+  const speed = 100; // units per second
+
+  // Update angles
+  if (input.pitchDelta) camera.angles[0] += input.pitchDelta;
+  if (input.yawDelta) camera.angles[1] += input.yawDelta;
+  if (input.rollDelta) camera.angles[2] += input.rollDelta;
+
+  // Force update dirty flag in Camera
+  camera.angles = camera.angles;
+
+  // Calculate forward/right/up vectors based on new angles
+  // For simplicity, we can use simple trig or just assume standard axis aligned for basic tests
+  // But proper way is AngleVectors.
+  // Since we don't have AngleVectors imported here (it's in shared), we might skip complex relative movement
+  // or import it.
+
+  // Ideally: import { angleVectors } from '@quake2ts/shared/math/angles';
+  // But we want to avoid deep deps if possible.
+
+  // For now, let's just apply absolute movement if provided, or simplistic axis logic
+  if (input.forward || input.right || input.up) {
+      // simplistic impl
+      camera.position[0] += (input.forward || 0) * deltaTime;
+      camera.position[1] += (input.right || 0) * deltaTime;
+      camera.position[2] += (input.up || 0) * deltaTime;
+      camera.position = camera.position;
+  }
+
+  return camera;
+}

package/src/client/mocks/console.ts

@@ -0,0 +1,75 @@
+import { vi } from 'vitest';
+
+export interface MockConsole {
+  // Add Console interface methods here as needed, based on usage in engine/client
+  // Currently the Console interface is not strictly defined in shared types for test-utils
+  // but we mimic what is commonly used.
+  print: (text: string) => void;
+  error: (text: string) => void;
+  execute: (text: string) => void;
+  addCommand: (name: string, handler: (args: string[]) => void) => void;
+  getCvar: (name: string) => string | undefined;
+  setCvar: (name: string, value: string) => void;
+
+  // Test helpers
+  getHistory: () => string[];
+  clearHistory: () => void;
+  getErrors: () => string[];
+}
+
+export interface MockCommand {
+  name: string;
+  handler: (args: string[]) => void;
+}
+
+export interface CvarRegistry {
+  [key: string]: string;
+}
+
+export function createMockConsole(overrides?: Partial<MockConsole>): MockConsole {
+  const history: string[] = [];
+  const errors: string[] = [];
+  const commands: Record<string, (args: string[]) => void> = {};
+  const cvars: Record<string, string> = {};
+
+  return {
+    print: vi.fn((text: string) => {
+      history.push(text);
+    }),
+    error: vi.fn((text: string) => {
+      errors.push(text);
+    }),
+    execute: vi.fn((text: string) => {
+      const parts = text.trim().split(/\s+/);
+      const cmd = parts[0];
+      const args = parts.slice(1);
+      if (commands[cmd]) {
+        commands[cmd](args);
+      } else {
+        history.push(`Unknown command "${cmd}"`);
+      }
+    }),
+    addCommand: vi.fn((name: string, handler: (args: string[]) => void) => {
+      commands[name] = handler;
+    }),
+    getCvar: vi.fn((name: string) => cvars[name]),
+    setCvar: vi.fn((name: string, value: string) => {
+      cvars[name] = value;
+    }),
+    getHistory: () => history,
+    clearHistory: () => {
+      history.length = 0;
+      errors.length = 0;
+    },
+    getErrors: () => errors,
+    ...overrides
+  };
+}
+
+export function createMockCommand(name: string, handler: (args: string[]) => void): MockCommand {
+  return { name, handler };
+}
+
+export function createMockCvarRegistry(initialCvars?: Record<string, string>): CvarRegistry {
+  return { ...initialCvars };
+}

package/src/client/mocks/download.ts

@@ -0,0 +1,48 @@
+import { vi } from 'vitest';
+
+export interface DownloadManager {
+    download(url: string): Promise<ArrayBuffer>;
+    cancel(url: string): void;
+    getProgress(url: string): number;
+}
+
+export function createMockDownloadManager(overrides?: Partial<DownloadManager>): DownloadManager {
+    return {
+        download: vi.fn().mockResolvedValue(new ArrayBuffer(0)),
+        cancel: vi.fn(),
+        getProgress: vi.fn().mockReturnValue(0),
+        ...overrides
+    };
+}
+
+export interface PrecacheList {
+    models: string[];
+    sounds: string[];
+    images: string[];
+}
+
+export function createMockPrecacheList(
+    models: string[] = [],
+    sounds: string[] = [],
+    images: string[] = []
+): PrecacheList {
+    return {
+        models,
+        sounds,
+        images
+    };
+}
+
+export async function simulateDownload(
+    url: string,
+    progressCallback?: (percent: number) => void
+): Promise<ArrayBuffer> {
+    const steps = 10;
+    for (let i = 0; i <= steps; i++) {
+        if (progressCallback) {
+            progressCallback(i / steps);
+        }
+        await new Promise(resolve => setTimeout(resolve, 10));
+    }
+    return new ArrayBuffer(1024);
+}