@quake2ts/test-utils 0.0.1

package/src/game/factories.ts

@@ -0,0 +1,204 @@
+import {
+  Entity,
+  MoveType,
+  Solid,
+  ServerFlags,
+  DeadFlag,
+  EntityFlags
+} from '@quake2ts/game';
+import type { PlayerState, EntityState } from '@quake2ts/shared';
+import type { GameStateSnapshot } from '@quake2ts/game';
+
+// -- Shared / Game State Factories --
+
+export const createPlayerStateFactory = (overrides?: Partial<PlayerState>): PlayerState => ({
+  pm_type: 0,
+  pm_time: 0,
+  pm_flags: 0,
+  origin: { x: 0, y: 0, z: 0 },
+  velocity: { x: 0, y: 0, z: 0 },
+  viewAngles: { x: 0, y: 0, z: 0 },
+  onGround: false,
+  waterLevel: 0,
+  watertype: 0,
+  mins: { x: 0, y: 0, z: 0 },
+  maxs: { x: 0, y: 0, z: 0 },
+  damageAlpha: 0,
+  damageIndicators: [],
+  blend: [0, 0, 0, 0],
+  stats: [],
+  kick_angles: { x: 0, y: 0, z: 0 },
+  kick_origin: { x: 0, y: 0, z: 0 },
+  gunoffset: { x: 0, y: 0, z: 0 },
+  gunangles: { x: 0, y: 0, z: 0 },
+  gunindex: 0,
+  gun_frame: 0,
+  rdflags: 0,
+  fov: 90,
+  renderfx: 0,
+  ...overrides,
+});
+
+export const createEntityStateFactory = (overrides?: Partial<EntityState>): EntityState => ({
+  number: 0,
+  origin: { x: 0, y: 0, z: 0 },
+  angles: { x: 0, y: 0, z: 0 },
+  oldOrigin: { x: 0, 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,
+  ...overrides,
+});
+
+export const createGameStateSnapshotFactory = (overrides?: Partial<GameStateSnapshot>): GameStateSnapshot => ({
+  gravity: { x: 0, y: 0, z: -800 },
+  origin: { x: 0, y: 0, z: 0 },
+  velocity: { x: 0, y: 0, z: 0 },
+  viewangles: { x: 0, y: 0, z: 0 },
+  level: { timeSeconds: 0, frameNumber: 0, previousTimeSeconds: 0, deltaSeconds: 0.1 },
+  entities: {
+    activeCount: 0,
+    worldClassname: 'worldspawn',
+  },
+  packetEntities: [],
+  pmFlags: 0,
+  pmType: 0,
+  waterlevel: 0,
+  watertype: 0,
+  deltaAngles: { x: 0, y: 0, z: 0 },
+  health: 100,
+  armor: 0,
+  ammo: 0,
+  blend: [0, 0, 0, 0],
+  damageAlpha: 0,
+  damageIndicators: [],
+  stats: [],
+  kick_angles: { x: 0, y: 0, z: 0 },
+  kick_origin: { x: 0, y: 0, z: 0 },
+  gunoffset: { x: 0, y: 0, z: 0 },
+  gunangles: { x: 0, y: 0, z: 0 },
+  gunindex: 0,
+  pm_time: 0,
+  gun_frame: 0,
+  rdflags: 0,
+  fov: 90,
+  renderfx: 0,
+  pm_flags: 0,
+  pm_type: 0,
+  ...overrides,
+});
+
+// -- Entity Factories --
+
+// Helper to remove internal fields that shouldn't be copied via Object.assign,
+// but PRESERVE the Entity prototype so getters/setters/methods work.
+function sanitizeEntity(ent: Entity): Partial<Entity> {
+  // We modify the instance in place (it's a factory-created one, so safe to mutate).
+  // We want to delete properties that would conflict with EntitySystem internals
+  // if this object is merged into another Entity via Object.assign.
+
+  // Actually, Object.assign(target, source) only copies enumerable own properties.
+  // If we delete them from 'ent', they won't be copied.
+  // BUT 'ent' must still be a valid Entity for tests that use the factory result directly.
+
+  // The issue in `dm-spawn.test.ts` was:
+  // Object.assign(player, createPlayerEntityFactory(...))
+  // 'player' is a REAL entity from the system.
+  // 'createPlayerEntityFactory' returns an Entity.
+  // 'Entity' class defines 'linkNext = null' etc as instance properties.
+  // So Object.assign copies 'linkNext: null'.
+
+  // We need to remove these properties from the returned object so Object.assign doesn't copy them.
+  // But we want to keep the prototype.
+
+  const safe = ent as any;
+  delete safe.index;
+  delete safe.inUse;
+  delete safe.freePending;
+  delete safe.linkPrevious;
+  delete safe.linkNext;
+  delete safe.linkcount;
+
+  return ent;
+}
+
+export function createEntityFactory(overrides: Partial<Entity> = {}): Partial<Entity> {
+  const ent = new Entity(1);
+  Object.assign(ent, {
+    classname: 'info_null',
+    health: 0,
+    max_health: 0,
+    takedamage: false,
+    deadflag: DeadFlag.Alive,
+    solid: Solid.Not,
+    movetype: MoveType.None,
+    flags: 0,
+    svflags: 0,
+    ...overrides
+  });
+  return sanitizeEntity(ent);
+}
+
+export function createPlayerEntityFactory(overrides: Partial<Entity> = {}): Partial<Entity> {
+  return createEntityFactory({
+    classname: 'player',
+    health: 100,
+    max_health: 100,
+    takedamage: true,
+    solid: Solid.BoundingBox,
+    movetype: MoveType.Walk,
+    svflags: ServerFlags.Player,
+    viewheight: 22,
+    ...overrides
+  });
+}
+
+export function createMonsterEntityFactory(classname: string, overrides: Partial<Entity> = {}): Partial<Entity> {
+  return createEntityFactory({
+    classname,
+    health: 100,
+    max_health: 100,
+    takedamage: true,
+    solid: Solid.BoundingBox,
+    movetype: MoveType.Step,
+    svflags: ServerFlags.Monster,
+    deadflag: DeadFlag.Alive,
+    ...overrides
+  });
+}
+
+export function createItemEntityFactory(classname: string, overrides: Partial<Entity> = {}): Partial<Entity> {
+  return createEntityFactory({
+    classname,
+    solid: Solid.Trigger,
+    movetype: MoveType.Toss,
+    ...overrides
+  });
+}
+
+export function createProjectileEntityFactory(classname: string, overrides: Partial<Entity> = {}): Partial<Entity> {
+  return createEntityFactory({
+    classname,
+    solid: Solid.Bsp,
+    movetype: MoveType.FlyMissile,
+    svflags: ServerFlags.Projectile,
+    ...overrides
+  });
+}
+
+export function createTriggerEntityFactory(classname: string, overrides: Partial<Entity> = {}): Partial<Entity> {
+  return createEntityFactory({
+    classname,
+    solid: Solid.Trigger,
+    movetype: MoveType.None,
+    ...overrides
+  });
+}

package/src/game/helpers/physics.ts

@@ -0,0 +1,171 @@
+import { Entity, MoveType, Solid, EntitySystem } from '@quake2ts/game';
+import { Vec3, copyVec3, TraceResult, addVec3, subtractVec3, scaleVec3, lengthVec3, normalizeVec3, dotVec3 } from '@quake2ts/shared';
+import { TestContext } from '../helpers.js';
+import { intersects, createTraceMock } from '../../shared/collision.js';
+
+/**
+ * Creates a physics test scenario with pre-configured geometry.
+ * NOTE: Since real BSP loading is complex, this often uses block entities
+ * or mocked trace functions unless a real BSP is loaded in the context.
+ */
+export interface PhysicsScenario {
+  ground: Entity;
+  walls: Entity[];
+  setup: (context: TestContext) => void;
+}
+
+export function createPhysicsTestScenario(
+  scenarioType: 'stairs' | 'ladder' | 'platform' | 'slope' | 'room',
+  context: TestContext
+): PhysicsScenario {
+  const walls: Entity[] = [];
+  const ground = context.entities.spawn();
+  ground.classname = 'func_wall';
+  ground.solid = Solid.Bsp;
+  ground.movetype = MoveType.Push;
+  ground.origin = { x: 0, y: 0, z: -10 };
+  ground.mins = { x: -1000, y: -1000, z: -10 };
+  ground.maxs = { x: 1000, y: 1000, z: 0 };
+  context.entities.linkentity(ground);
+
+  const setupStairs = () => {
+    // Create steps
+    for (let i = 0; i < 5; i++) {
+      const step = context.entities.spawn();
+      step.classname = 'func_wall';
+      step.solid = Solid.Bsp;
+      step.origin = { x: 100 + i * 32, y: 0, z: i * 16 };
+      step.mins = { x: 0, y: -64, z: 0 };
+      step.maxs = { x: 32, y: 64, z: 16 };
+      context.entities.linkentity(step);
+      walls.push(step);
+    }
+  };
+
+  const setupLadder = () => {
+    const ladder = context.entities.spawn();
+    ladder.classname = 'func_wall'; // Or func_ladder if available
+    ladder.solid = Solid.Bsp;
+    ladder.origin = { x: 100, y: 0, z: 0 };
+    ladder.mins = { x: 0, y: -32, z: 0 };
+    ladder.maxs = { x: 10, y: 32, z: 200 };
+    // surfaceFlags is a numeric property if we cast to any or define it, usually on entity state/brush
+    // But Entity class might not expose it directly unless it has collision fields
+    // Assuming Entity has it or we just ignore for mock tests
+    (ladder as any).surfaceFlags = 1; // SURF_LADDER
+    context.entities.linkentity(ladder);
+    walls.push(ladder);
+  };
+
+  const setupPlatform = () => {
+    const plat = context.entities.spawn();
+    plat.classname = 'func_plat';
+    plat.solid = Solid.Bsp;
+    plat.movetype = MoveType.Push;
+    plat.origin = { x: 0, y: 0, z: 0 }; // Starts low
+    plat.mins = { x: -64, y: -64, z: 0 };
+    plat.maxs = { x: 64, y: 64, z: 10 };
+    // Platform logic handles movement, but for physics collision it's just a solid box moving
+    context.entities.linkentity(plat);
+    walls.push(plat);
+  };
+
+  if (scenarioType === 'stairs') setupStairs();
+  else if (scenarioType === 'ladder') setupLadder();
+  else if (scenarioType === 'platform') setupPlatform();
+
+  return {
+    ground,
+    walls,
+    setup: (ctx) => {
+        // Additional setup if needed
+    }
+  };
+}
+
+
+/**
+ * Simulates a single physics step for an entity.
+ * Uses the game's runPmove logic or manually invokes similar steps.
+ * This is useful for testing specific movement mechanics in isolation.
+ */
+export function simulateMovement(entity: Entity, destination: Vec3, context: TestContext): TraceResult {
+    // Calculate velocity needed to reach destination in one frame (assuming 0.1s tick)
+    const dt = 0.1;
+    const delta = subtractVec3(destination, entity.origin);
+    const dist = lengthVec3(delta);
+
+    if (dist < 0.001) {
+        return createTraceMock({ fraction: 1.0, endpos: destination }) as unknown as TraceResult;
+    }
+
+    const dir = normalizeVec3(delta);
+    entity.velocity = scaleVec3(dir, dist / dt);
+
+    // Perform trace to check if movement is possible
+    const start = { ...entity.origin };
+    const end = destination;
+
+    // Check if context.entities.trace is a mocked function we can control or real one
+    // We assume the interface matches
+    const tr = context.entities.trace(start, entity.mins, entity.maxs, end, entity, (entity as any).clipmask || 0);
+
+    // Update origin if not stuck
+    if (!tr.startsolid && !tr.allsolid) {
+        // Trace result returns endpos which is where we stopped
+        if (tr.endpos) {
+             entity.origin = { ...tr.endpos };
+        } else {
+             // Fallback if trace result is simple
+             // In real engine trace always has endpos
+             entity.origin = { ...end }; // Should be tr.endpos really
+        }
+        context.entities.linkentity(entity);
+    }
+
+    // Return TraceResult, cast if needed as we don't import CollisionTraceResult specifically
+    return tr as unknown as TraceResult;
+}
+
+/**
+ * Simulates gravity application on an entity.
+ */
+export function simulateGravity(entity: Entity, deltaTime: number, context: TestContext): void {
+    const gravity = (context.game as any).cvars?.gravity?.value ?? 800; // MockGame might not have cvars yet
+    if (entity.groundentity || !entity.movetype) return;
+
+    // Simple Euler integration for gravity
+    entity.velocity = {
+        x: entity.velocity.x,
+        y: entity.velocity.y,
+        z: entity.velocity.z - gravity * deltaTime
+    };
+
+    // Check ground after applying gravity velocity
+    // Simple check: trace down
+    const start = { ...entity.origin };
+    const end = { x: start.x, y: start.y, z: start.z - 0.25 };
+
+    const tr = context.entities.trace(start, entity.mins, entity.maxs, end, entity, (entity as any).clipmask || 0);
+
+    if (tr.fraction < 1.0) {
+        entity.groundentity = tr.ent || context.entities.world;
+        entity.velocity = { ...entity.velocity, z: 0 };
+        // Snap to ground
+        if (tr.endpos) {
+             entity.origin = { ...entity.origin, z: tr.endpos.z };
+        }
+    } else {
+        entity.groundentity = null; // Assigning null instead of undefined
+    }
+}
+
+/**
+ * Simulates a jump action.
+ */
+export function simulateJump(entity: Entity, context: TestContext): void {
+    if (!entity.groundentity) return;
+
+    entity.groundentity = null;
+    entity.velocity = { ...entity.velocity, z: 270 }; // Standard jump velocity
+}

package/src/game/helpers/save.ts

@@ -0,0 +1,232 @@
+import { Entity, LevelState } from '@quake2ts/game';
+import type { GameSaveFile } from '@quake2ts/game';
+import { TestContext } from '../helpers.js';
+import { Vec3 } from '@quake2ts/shared';
+
+// If LevelFrameState is not exported from @quake2ts/game, we define a compatible interface here
+export interface LevelFrameState {
+    readonly frameNumber: number;
+    readonly timeSeconds: number;
+    readonly previousTimeSeconds: number;
+    readonly deltaSeconds: number;
+}
+
+/**
+ * Interface for a mock save game object.
+ */
+export interface MockSaveGame {
+    game: GameSaveFile;
+    entities: any[]; // Serialized entities
+    client: any; // Serialized client
+    level: LevelState;
+    timestamp: number;
+}
+
+/**
+ * Creates a mock SaveGame object.
+ *
+ * @param overrides - Optional overrides for save game properties.
+ * @returns A MockSaveGame object.
+ */
+export function createMockSaveGame(overrides?: Partial<MockSaveGame>): MockSaveGame {
+    const defaultLevelState: LevelFrameState = {
+        frameNumber: 100,
+        timeSeconds: 10.0,
+        previousTimeSeconds: 9.9,
+        deltaSeconds: 0.1
+    };
+
+    const defaultLevel: LevelState = {
+        next_auto_save: 0,
+        health_bar_entities: [null, null, null, null],
+        intermission_angle: { x: 0, y: 0, z: 0 },
+        intermission_origin: { x: 0, y: 0, z: 0 },
+        helpmessage1: "",
+        helpmessage2: "",
+        help1changed: 0,
+        help2changed: 0,
+        mapname: 'test_map'
+    };
+
+    const defaultGame: GameSaveFile = {
+        version: 2,
+        timestamp: Date.now(),
+        map: 'test_map',
+        difficulty: 1,
+        playtimeSeconds: 100,
+        level: defaultLevelState,
+        entities: {
+            timeSeconds: 10.0,
+            pool: { capacity: 1024, activeOrder: [], freeList: [], pendingFree: [] },
+            entities: [],
+            thinks: [],
+            awareness: {
+                frameNumber: 0,
+                sightEntityIndex: null,
+                sightEntityFrame: 0,
+                soundEntityIndex: null,
+                soundEntityFrame: 0,
+                sound2EntityIndex: null,
+                sound2EntityFrame: 0,
+                sightClientIndex: null
+            },
+            crossLevelFlags: 0,
+            crossUnitFlags: 0,
+            level: defaultLevel
+        },
+        rng: { mt: { index: 0, state: [] } },
+        gameState: {},
+        cvars: [],
+        configstrings: []
+    };
+
+    return {
+        game: overrides?.game ?? defaultGame,
+        entities: overrides?.entities ?? [],
+        client: overrides?.client ?? {},
+        level: overrides?.level ?? defaultLevel,
+        timestamp: overrides?.timestamp ?? Date.now()
+    };
+}
+
+/**
+ * Captures the current test context state as a save game snapshot.
+ * Note: This is a simplified snapshot for testing, not a full serialization.
+ *
+ * @param context - The test context to snapshot.
+ * @returns A MockSaveGame representing the current state.
+ */
+export function createSaveGameSnapshot(context: TestContext): MockSaveGame {
+    const entities: any[] = [];
+    context.entities.forEachEntity((ent: Entity) => {
+        if (!ent.inUse) return;
+        // Simple serialization of essential fields
+        entities.push({
+            classname: ent.classname,
+            origin: { ...ent.origin },
+            angles: { ...ent.angles },
+            health: ent.health,
+            spawnflags: ent.spawnflags,
+            targetname: ent.targetname
+        });
+    });
+
+    // We need to construct a LevelFrameState for the save file
+    const levelFrameState: LevelFrameState = {
+        frameNumber: (context.game as any).level?.frameNumber ?? 0,
+        timeSeconds: (context.game as any).level?.timeSeconds ?? (context.game as any).time ?? 0,
+        previousTimeSeconds: 0,
+        deltaSeconds: 0.1
+    };
+
+    const currentLevel = (context.entities as any).level || {};
+
+    return {
+        game: {
+            version: 2,
+            timestamp: Date.now(),
+            map: 'snapshot_map',
+            difficulty: 0,
+            playtimeSeconds: (context.game as any).time ?? 0,
+            level: levelFrameState,
+            entities: context.entities.createSnapshot(),
+            rng: { mt: { index: 0, state: [] } },
+            gameState: {},
+            cvars: [],
+            configstrings: []
+        },
+        entities,
+        client: {},
+        level: currentLevel as LevelState,
+        timestamp: Date.now()
+    };
+}
+
+/**
+ * Restores a test context from a save game snapshot.
+ *
+ * @param saveGame - The save game to restore.
+ * @param context - The test context to update.
+ */
+export function restoreSaveGameSnapshot(saveGame: MockSaveGame, context: TestContext): void {
+    // Clear existing entities (except world/clients if needed, but for test usually clear all)
+    // Assuming context.entities has a way to reset or we just free all
+    // context.entities.reset() // if available
+
+    // Re-spawn entities
+    saveGame.entities.forEach(entData => {
+        const ent = context.entities.spawn();
+        ent.classname = entData.classname;
+        ent.origin = { ...entData.origin };
+        ent.angles = { ...entData.angles };
+        ent.health = entData.health;
+        ent.spawnflags = entData.spawnflags;
+        ent.targetname = entData.targetname;
+        context.entities.linkentity(ent);
+    });
+
+    // Restore level state
+    if ((context.entities as any).level) {
+        Object.assign((context.entities as any).level, saveGame.level);
+    }
+}
+
+/**
+ * Result of comparing two save games.
+ */
+export interface SaveGameDiff {
+    entityCountDiff: number;
+    differentEntities: { index: number, field: string, expected: any, actual: any }[];
+    gameStateDiffs: string[];
+}
+
+/**
+ * Compares two save games and returns the differences.
+ * Useful for testing save/load determinism.
+ *
+ * @param a - First save game.
+ * @param b - Second save game.
+ * @returns A SaveGameDiff object.
+ */
+export function compareSaveGames(a: MockSaveGame, b: MockSaveGame): SaveGameDiff {
+    const diffs: SaveGameDiff = {
+        entityCountDiff: a.entities.length - b.entities.length,
+        differentEntities: [],
+        gameStateDiffs: []
+    };
+
+    // Compare game state
+    const aTime = a.game.level.timeSeconds;
+    const bTime = b.game.level.timeSeconds;
+    if (aTime !== bTime) diffs.gameStateDiffs.push(`time: ${aTime} vs ${bTime}`);
+
+    const aFrame = a.game.level.frameNumber;
+    const bFrame = b.game.level.frameNumber;
+    if (aFrame !== bFrame) diffs.gameStateDiffs.push(`framenum: ${aFrame} vs ${bFrame}`);
+
+    // Compare entities (naive index matching)
+    const count = Math.min(a.entities.length, b.entities.length);
+    for (let i = 0; i < count; i++) {
+        const entA = a.entities[i];
+        const entB = b.entities[i];
+
+        if (entA.classname !== entB.classname) {
+            diffs.differentEntities.push({ index: i, field: 'classname', expected: entA.classname, actual: entB.classname });
+        }
+        if (entA.health !== entB.health) {
+            diffs.differentEntities.push({ index: i, field: 'health', expected: entA.health, actual: entB.health });
+        }
+        // Vector checks
+        if (!vec3Equals(entA.origin, entB.origin)) {
+            diffs.differentEntities.push({ index: i, field: 'origin', expected: entA.origin, actual: entB.origin });
+        }
+    }
+
+    return diffs;
+}
+
+function vec3Equals(a: Vec3, b: Vec3, epsilon = 0.001): boolean {
+    return Math.abs(a.x - b.x) < epsilon &&
+           Math.abs(a.y - b.y) < epsilon &&
+           Math.abs(a.z - b.z) < epsilon;
+}