@loonylabs/create-game 0.1.0

package/template/apps/server/src/tests/shooter-enemy-ai.test.ts

@@ -0,0 +1,328 @@
+import { describe, test, expect } from 'vitest';
+import {
+  createShooterEnemy,
+  updateShooterEnemyAI,
+  damageEnemy,
+  type AIUpdateContext,
+  type ShooterEnemy,
+} from '../../../experiences/shooter/ai/aiStateMachine.js';
+import { hasLineOfSight, distance3D } from '../../../experiences/shooter/ai/lineOfSight.js';
+import { getWaveDefinition, WAVE_DEFINITIONS } from '../../../experiences/shooter/data/wave-definitions.js';
+import { ENEMY_CONFIGS } from '../../../experiences/shooter/data/enemy-types.js';
+import { generateArena, getArenaObstacles } from '../../../experiences/shooter/arena/arenaGenerator.js';
+import { createPhysicsBody } from '../../../../packages/core/src/physics/gravity.js';
+
+// ---------------------------------------------------------------------------
+// Test Helpers
+// ---------------------------------------------------------------------------
+
+function createTestArena() {
+  return generateArena(42);
+}
+
+function createTestContext(
+  playerX: number = 10,
+  playerZ: number = 0,
+  playerHp: number = 100,
+): AIUpdateContext {
+  const arena = createTestArena();
+  const players = new Map([
+    ['p1', {
+      socketId: 'p1',
+      body: createPhysicsBody(playerX, 0, playerZ),
+      hp: playerHp,
+    }],
+  ]);
+  return {
+    players,
+    obstacles: getArenaObstacles(arena),
+    arena,
+    enemyShots: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Enemy Creation
+// ---------------------------------------------------------------------------
+
+describe('createShooterEnemy', () => {
+  test('creates enemy with correct type and health', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    expect(enemy.entityId).toBe(1);
+    expect(enemy.enemyType).toBe('rusher');
+    expect(enemy.health).toBe(ENEMY_CONFIGS.rusher.health);
+    expect(enemy.maxHealth).toBe(ENEMY_CONFIGS.rusher.health);
+    expect(enemy.alive).toBe(true);
+    expect(enemy.aiState).toBe('idle');
+  });
+
+  test('creates different types with different configs', () => {
+    const rusher = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    const sniper = createShooterEnemy(2, 'sniper', { x: 0, y: 0, z: 0 }, 42);
+    expect(rusher.health).not.toBe(sniper.health);
+    expect(rusher.config.attackRange).toBeLessThan(sniper.config.attackRange);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AI State Machine
+// ---------------------------------------------------------------------------
+
+describe('ShooterEnemyAI', () => {
+  test('idle enemy detects nearby player', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    const ctx = createTestContext(10, 0); // Player at 10 units away
+
+    // Run enough ticks to detect
+    for (let i = 0; i < 5; i++) {
+      updateShooterEnemyAI(enemy, 0.05, ctx);
+    }
+    expect(enemy.aiState).not.toBe('idle');
+  });
+
+  test('idle enemy does not detect distant player', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: -15, y: 0, z: -15 }, 42);
+    // Player far away (distance ~35, beyond rusher detection of 15)
+    const ctx = createTestContext(15, 15);
+    updateShooterEnemyAI(enemy, 0.05, ctx);
+    expect(enemy.aiState).toBe('idle');
+  });
+
+  test('enemy transitions from detect to chase after reaction time', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.aiState = 'detect';
+    enemy.targetPlayerId = 'p1';
+    enemy.stateTimer = 0;
+
+    const ctx = createTestContext(10, 0);
+
+    // Tick past reaction time
+    for (let i = 0; i < 20; i++) {
+      updateShooterEnemyAI(enemy, 0.05, ctx);
+    }
+    expect(['chase', 'attack']).toContain(enemy.aiState);
+  });
+
+  test('rusher chases toward player', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.aiState = 'chase';
+    enemy.targetPlayerId = 'p1';
+
+    const ctx = createTestContext(10, 0);
+
+    // Run several ticks
+    for (let i = 0; i < 10; i++) {
+      updateShooterEnemyAI(enemy, 0.05, ctx);
+    }
+    // Should have moved toward player (positive X)
+    expect(enemy.body.x).toBeGreaterThan(0);
+  });
+
+  test('enemy switches to attack when in range with LoS', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.aiState = 'chase';
+    enemy.targetPlayerId = 'p1';
+
+    // Player very close (within attack range of 6)
+    const ctx = createTestContext(3, 0);
+
+    updateShooterEnemyAI(enemy, 0.05, ctx);
+    expect(enemy.aiState).toBe('attack');
+  });
+
+  test('patrol retreats at low HP', () => {
+    const enemy = createShooterEnemy(1, 'patrol', { x: 0, y: 0, z: 0 }, 42);
+    enemy.aiState = 'attack';
+    enemy.targetPlayerId = 'p1';
+    enemy.health = 5; // Very low, below 20% threshold
+
+    const ctx = createTestContext(5, 0);
+    updateShooterEnemyAI(enemy, 0.05, ctx);
+    expect(enemy.aiState).toBe('retreat');
+  });
+
+  test('rusher never retreats', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.aiState = 'attack';
+    enemy.targetPlayerId = 'p1';
+    enemy.health = 1;
+
+    const ctx = createTestContext(3, 0);
+    updateShooterEnemyAI(enemy, 0.05, ctx);
+    expect(enemy.aiState).not.toBe('retreat');
+  });
+
+  test('enemy shoots when attacking and generates shot intent', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.aiState = 'attack';
+    enemy.targetPlayerId = 'p1';
+
+    // Player close with clear LoS (no obstacles between them)
+    const arena = generateArena(42);
+    const players = new Map([
+      ['p1', { socketId: 'p1', body: createPhysicsBody(3, 0, 0), hp: 100 }],
+    ]);
+    // Use empty obstacles so LoS is guaranteed
+    const ctx: AIUpdateContext = { players, obstacles: [], arena, enemyShots: [] };
+
+    // Collect all shots over multiple ticks
+    const allShots: typeof ctx.enemyShots = [];
+    for (let i = 0; i < 40; i++) {
+      ctx.enemyShots = [];
+      updateShooterEnemyAI(enemy, 0.05, ctx);
+      allShots.push(...ctx.enemyShots);
+    }
+    // Should have produced at least one shot
+    expect(allShots.length).toBeGreaterThan(0);
+  });
+
+  test('dead enemy is not updated', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.alive = false;
+    const initialState = enemy.aiState;
+
+    const ctx = createTestContext(3, 0);
+    updateShooterEnemyAI(enemy, 0.05, ctx);
+    expect(enemy.aiState).toBe(initialState);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Damage
+// ---------------------------------------------------------------------------
+
+describe('damageEnemy', () => {
+  test('reduces health', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    const killed = damageEnemy(enemy, 10);
+    expect(killed).toBe(false);
+    expect(enemy.health).toBe(20); // 30 - 10
+    expect(enemy.alive).toBe(true);
+  });
+
+  test('kills when health reaches 0', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    const killed = damageEnemy(enemy, 30);
+    expect(killed).toBe(true);
+    expect(enemy.health).toBe(0);
+    expect(enemy.alive).toBe(false);
+  });
+
+  test('overkill sets health to 0', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    damageEnemy(enemy, 100);
+    expect(enemy.health).toBe(0);
+    expect(enemy.alive).toBe(false);
+  });
+
+  test('cannot damage dead enemy', () => {
+    const enemy = createShooterEnemy(1, 'rusher', { x: 0, y: 0, z: 0 }, 42);
+    enemy.alive = false;
+    const killed = damageEnemy(enemy, 10);
+    expect(killed).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Line of Sight
+// ---------------------------------------------------------------------------
+
+describe('lineOfSight', () => {
+  test('clear LoS between two points', () => {
+    const result = hasLineOfSight(
+      { x: 0, y: 1, z: 0 },
+      { x: 10, y: 1, z: 0 },
+      [],
+    );
+    expect(result).toBe(true);
+  });
+
+  test('blocked by obstacle', () => {
+    const wall = { min: { x: 5, y: 0, z: -1 }, max: { x: 6, y: 3, z: 1 } };
+    const result = hasLineOfSight(
+      { x: 0, y: 1, z: 0 },
+      { x: 10, y: 1, z: 0 },
+      [wall],
+    );
+    expect(result).toBe(false);
+  });
+
+  test('LoS around obstacle', () => {
+    const wall = { min: { x: 5, y: 0, z: -1 }, max: { x: 6, y: 3, z: 1 } };
+    // Aim around the wall (Z offset)
+    const result = hasLineOfSight(
+      { x: 0, y: 1, z: 5 },
+      { x: 10, y: 1, z: 5 },
+      [wall],
+    );
+    expect(result).toBe(true);
+  });
+});
+
+describe('distance3D', () => {
+  test('calculates correct distance', () => {
+    expect(distance3D({ x: 0, y: 0, z: 0 }, { x: 3, y: 4, z: 0 })).toBeCloseTo(5);
+  });
+
+  test('zero distance for same point', () => {
+    expect(distance3D({ x: 5, y: 5, z: 5 }, { x: 5, y: 5, z: 5 })).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Wave Definitions
+// ---------------------------------------------------------------------------
+
+describe('WaveDefinitions', () => {
+  test('wave 0 has 3 rushers', () => {
+    const wave = getWaveDefinition(0);
+    expect(wave.enemies).toEqual([{ type: 'rusher', count: 3 }]);
+  });
+
+  test('wave 1 has patrols and rushers', () => {
+    const wave = getWaveDefinition(1);
+    const total = wave.enemies.reduce((sum, e) => sum + e.count, 0);
+    expect(total).toBe(3);
+  });
+
+  test('wave 2 has all types', () => {
+    const wave = getWaveDefinition(2);
+    const types = wave.enemies.map(e => e.type);
+    expect(types).toContain('sniper');
+    expect(types).toContain('patrol');
+    expect(types).toContain('rusher');
+  });
+
+  test('waves beyond defined ones scale up', () => {
+    const lastDefined = getWaveDefinition(WAVE_DEFINITIONS.length - 1);
+    const beyond = getWaveDefinition(WAVE_DEFINITIONS.length + 2);
+    const lastTotal = lastDefined.enemies.reduce((s, e) => s + e.count, 0);
+    const beyondTotal = beyond.enemies.reduce((s, e) => s + e.count, 0);
+    expect(beyondTotal).toBeGreaterThan(lastTotal);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Enemy Type Configs
+// ---------------------------------------------------------------------------
+
+describe('EnemyTypeConfigs', () => {
+  test('rusher has high speed, low HP', () => {
+    expect(ENEMY_CONFIGS.rusher.health).toBeLessThan(ENEMY_CONFIGS.patrol.health);
+    expect(ENEMY_CONFIGS.rusher.characterConfig.walkSpeed).toBeGreaterThan(ENEMY_CONFIGS.patrol.characterConfig.walkSpeed);
+  });
+
+  test('sniper has long range, low fire rate', () => {
+    expect(ENEMY_CONFIGS.sniper.attackRange).toBeGreaterThan(ENEMY_CONFIGS.rusher.attackRange);
+    expect(ENEMY_CONFIGS.sniper.weaponConfig.fireRate).toBeLessThan(ENEMY_CONFIGS.rusher.weaponConfig.fireRate);
+  });
+
+  test('all configs have unique detection radii', () => {
+    const radii = [
+      ENEMY_CONFIGS.rusher.detectionRadius,
+      ENEMY_CONFIGS.patrol.detectionRadius,
+      ENEMY_CONFIGS.sniper.detectionRadius,
+    ];
+    expect(new Set(radii).size).toBe(3);
+  });
+});

package/template/apps/server/src/tests/shooter-experience.test.ts

@@ -0,0 +1,281 @@
+import { describe, test, expect } from 'vitest';
+import { ShooterExperience, createShooterSession, addShooterPlayer, removeShooterPlayer } from '../../../experiences/shooter/index.js';
+import { generateArena, getArenaGroundHeight, getArenaObstacles } from '../../../experiences/shooter/arena/arenaGenerator.js';
+import { DEFAULT_ARENA_CONFIG } from '../../../experiences/shooter/arena/arenaTypes.js';
+import { createWeaponState, processShoot, startReload, updateWeaponState, DEFAULT_WEAPON_CONFIG } from '../../../experiences/shooter/data/weapon-config.js';
+import { hitscanRaycast } from '../../../experiences/shooter/arena/hitscan.js';
+
+// ---------------------------------------------------------------------------
+// ShooterExperience
+// ---------------------------------------------------------------------------
+
+describe('ShooterExperience', () => {
+  test('implements ExperienceDefinition', () => {
+    const exp = new ShooterExperience();
+    expect(exp.id).toBe('shooter');
+    expect(exp.name).toBeDefined();
+    expect(exp.description).toBeDefined();
+    expect(exp.defaultCameraMode).toBe('third-person');
+  });
+
+  test('createSystems returns non-empty list', () => {
+    const exp = new ShooterExperience();
+    const systems = exp.createSystems();
+    expect(systems.length).toBe(5);
+    expect(systems.map(s => s.id)).toEqual([
+      'shooter-wave-spawner', 'shooter-enemy-ai', 'shooter-physics', 'shooter-weapon', 'shooter-entity-sync',
+    ]);
+  });
+
+  test('systems have unique ids', () => {
+    const exp = new ShooterExperience();
+    const ids = exp.createSystems().map(s => s.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Arena Generation
+// ---------------------------------------------------------------------------
+
+describe('ArenaGenerator', () => {
+  test('generates arena with correct dimensions', () => {
+    const arena = generateArena(42, DEFAULT_ARENA_CONFIG);
+    expect(arena.width).toBe(DEFAULT_ARENA_CONFIG.width);
+    expect(arena.depth).toBe(DEFAULT_ARENA_CONFIG.depth);
+  });
+
+  test('generates 4 outer walls', () => {
+    const arena = generateArena(42);
+    expect(arena.walls).toHaveLength(4);
+  });
+
+  test('generates spawn points in corners', () => {
+    const arena = generateArena(42);
+    expect(arena.spawnPoints.length).toBeGreaterThanOrEqual(4);
+  });
+
+  test('generates cover blocks', () => {
+    const arena = generateArena(42);
+    expect(arena.covers.length).toBeGreaterThan(0);
+    expect(arena.covers.length).toBeLessThanOrEqual(DEFAULT_ARENA_CONFIG.coverCount);
+  });
+
+  test('same seed produces same arena', () => {
+    const a1 = generateArena(42);
+    const a2 = generateArena(42);
+    expect(a1.covers.length).toBe(a2.covers.length);
+    expect(a1.covers.map(c => c.position)).toEqual(a2.covers.map(c => c.position));
+    expect(a1.spawnPoints).toEqual(a2.spawnPoints);
+  });
+
+  test('different seeds produce different arenas', () => {
+    const a1 = generateArena(42);
+    const a2 = generateArena(999);
+    // Cover positions should differ (extremely unlikely to be identical)
+    const pos1 = a1.covers.map(c => `${c.position.x.toFixed(2)},${c.position.z.toFixed(2)}`).join('|');
+    const pos2 = a2.covers.map(c => `${c.position.x.toFixed(2)},${c.position.z.toFixed(2)}`).join('|');
+    expect(pos1).not.toBe(pos2);
+  });
+
+  test('ground height returns 0 inside arena', () => {
+    const arena = generateArena(42);
+    expect(getArenaGroundHeight(arena, 0, 0)).toBe(0);
+    expect(getArenaGroundHeight(arena, 5, -5)).toBe(0);
+  });
+
+  test('ground height returns null outside arena', () => {
+    const arena = generateArena(42);
+    expect(getArenaGroundHeight(arena, 100, 100)).toBeNull();
+    expect(getArenaGroundHeight(arena, -100, -100)).toBeNull();
+  });
+
+  test('getArenaObstacles includes walls and covers', () => {
+    const arena = generateArena(42);
+    const obstacles = getArenaObstacles(arena);
+    expect(obstacles.length).toBe(arena.walls.length + arena.covers.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Shooter Session
+// ---------------------------------------------------------------------------
+
+describe('ShooterSession', () => {
+  test('createShooterSession creates session with arena', () => {
+    const session = createShooterSession(42);
+    expect(session.arena).toBeDefined();
+    expect(session.players.size).toBe(0);
+    expect(session.nextEntityId).toBe(1);
+  });
+
+  test('addShooterPlayer adds player at spawn point', () => {
+    const session = createShooterSession(42);
+    const player = addShooterPlayer(session, 'sock1', 'p1');
+    expect(player.entityId).toBe(1);
+    expect(player.hp).toBe(100);
+    expect(player.weapon.currentAmmo).toBe(DEFAULT_WEAPON_CONFIG.maxAmmo);
+    expect(session.players.size).toBe(1);
+  });
+
+  test('removeShooterPlayer removes player', () => {
+    const session = createShooterSession(42);
+    addShooterPlayer(session, 'sock1', 'p1');
+    removeShooterPlayer(session, 'sock1');
+    expect(session.players.size).toBe(0);
+  });
+
+  test('multiple players get different spawn points', () => {
+    const session = createShooterSession(42);
+    const p1 = addShooterPlayer(session, 's1', 'p1');
+    const p2 = addShooterPlayer(session, 's2', 'p2');
+    expect(p1.body.x !== p2.body.x || p1.body.z !== p2.body.z).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Weapon System
+// ---------------------------------------------------------------------------
+
+describe('WeaponSystem', () => {
+  test('shooting decreases ammo', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    processShoot(state, DEFAULT_WEAPON_CONFIG);
+    expect(state.currentAmmo).toBe(DEFAULT_WEAPON_CONFIG.maxAmmo - 1);
+  });
+
+  test('cannot shoot during reload', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    state.isReloading = true;
+    const result = processShoot(state, DEFAULT_WEAPON_CONFIG);
+    expect(result).toBe(false);
+    expect(state.currentAmmo).toBe(DEFAULT_WEAPON_CONFIG.maxAmmo);
+  });
+
+  test('cannot shoot during cooldown', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    processShoot(state, DEFAULT_WEAPON_CONFIG); // First shot
+    const result = processShoot(state, DEFAULT_WEAPON_CONFIG); // Immediately after
+    expect(result).toBe(false);
+  });
+
+  test('cannot shoot with no ammo', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    state.currentAmmo = 0;
+    const result = processShoot(state, DEFAULT_WEAPON_CONFIG);
+    expect(result).toBe(false);
+  });
+
+  test('reload restores ammo after timer', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    state.currentAmmo = 0;
+    startReload(state, DEFAULT_WEAPON_CONFIG);
+    expect(state.isReloading).toBe(true);
+    // Simulate time passing
+    for (let i = 0; i < 100; i++) updateWeaponState(state, 0.05, DEFAULT_WEAPON_CONFIG);
+    expect(state.currentAmmo).toBe(DEFAULT_WEAPON_CONFIG.maxAmmo);
+    expect(state.isReloading).toBe(false);
+  });
+
+  test('fire cooldown expires over time', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    processShoot(state, DEFAULT_WEAPON_CONFIG);
+    expect(state.fireCooldown).toBeGreaterThan(0);
+    // Tick past cooldown
+    for (let i = 0; i < 20; i++) updateWeaponState(state, 0.05, DEFAULT_WEAPON_CONFIG);
+    expect(state.fireCooldown).toBe(0);
+    // Should be able to shoot again
+    const result = processShoot(state, DEFAULT_WEAPON_CONFIG);
+    expect(result).toBe(true);
+  });
+
+  test('cannot reload when already full', () => {
+    const state = createWeaponState(DEFAULT_WEAPON_CONFIG);
+    startReload(state, DEFAULT_WEAPON_CONFIG);
+    expect(state.isReloading).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Hitscan Raycast
+// ---------------------------------------------------------------------------
+
+describe('hitscanRaycast', () => {
+  test('hits wall in front of player', () => {
+    const obstacles = [{ min: { x: 5, y: 0, z: -1 }, max: { x: 6, y: 3, z: 1 } }];
+    const result = hitscanRaycast(
+      { x: 0, y: 1, z: 0 },
+      { x: 1, y: 0, z: 0 },
+      100,
+      obstacles,
+      [],
+    );
+    expect(result).not.toBeNull();
+    expect(result!.hitPoint.x).toBeCloseTo(5);
+    expect(result!.entityId).toBeNull();
+  });
+
+  test('misses when aiming away', () => {
+    const obstacles = [{ min: { x: 5, y: 0, z: -1 }, max: { x: 6, y: 3, z: 1 } }];
+    const result = hitscanRaycast(
+      { x: 0, y: 1, z: 0 },
+      { x: -1, y: 0, z: 0 },
+      100,
+      obstacles,
+      [],
+    );
+    expect(result).toBeNull();
+  });
+
+  test('hits entity sphere', () => {
+    const entities = [{ entityId: 42, position: { x: 10, y: 1, z: 0 }, radius: 0.5 }];
+    const result = hitscanRaycast(
+      { x: 0, y: 1, z: 0 },
+      { x: 1, y: 0, z: 0 },
+      100,
+      [],
+      entities,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.entityId).toBe(42);
+    expect(result!.distance).toBeCloseTo(9.5, 1);
+  });
+
+  test('returns closest hit (wall before entity)', () => {
+    const obstacles = [{ min: { x: 5, y: 0, z: -1 }, max: { x: 6, y: 3, z: 1 } }];
+    const entities = [{ entityId: 42, position: { x: 10, y: 1, z: 0 }, radius: 0.5 }];
+    const result = hitscanRaycast(
+      { x: 0, y: 1, z: 0 },
+      { x: 1, y: 0, z: 0 },
+      100,
+      obstacles,
+      entities,
+    );
+    expect(result).not.toBeNull();
+    expect(result!.entityId).toBeNull(); // Wall is closer
+    expect(result!.hitPoint.x).toBeCloseTo(5);
+  });
+
+  test('respects max distance', () => {
+    const obstacles = [{ min: { x: 50, y: 0, z: -1 }, max: { x: 51, y: 3, z: 1 } }];
+    const result = hitscanRaycast(
+      { x: 0, y: 1, z: 0 },
+      { x: 1, y: 0, z: 0 },
+      10, // Max distance is 10, wall is at 50
+      obstacles,
+      [],
+    );
+    expect(result).toBeNull();
+  });
+
+  test('returns null when nothing in range', () => {
+    const result = hitscanRaycast(
+      { x: 0, y: 1, z: 0 },
+      { x: 1, y: 0, z: 0 },
+      100,
+      [],
+      [],
+    );
+    expect(result).toBeNull();
+  });
+});

package/template/apps/server/src/tests/voxelChunkCache.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from 'vitest';
+import { VoxelChunkCache } from '../voxelChunkCache.js';
+import { VOXEL_CHUNK_X, VOXEL_CHUNK_Y, VOXEL_CHUNK_Z } from '@loonylabs/gamedev-core';
+
+describe('VoxelChunkCache', () => {
+  test('generates and caches chunks deterministically', () => {
+    const cache = new VoxelChunkCache(42, { baseHeight: 32 });
+    const c1 = cache.get(0, 0);
+    const c2 = cache.get(0, 0);
+    expect(c1).toBe(c2); // same reference = cached
+    expect(c1.density.length).toBe(VOXEL_CHUNK_X * VOXEL_CHUNK_Y * VOXEL_CHUNK_Z);
+  });
+
+  test('different chunk coords produce different chunks', () => {
+    const cache = new VoxelChunkCache(42, { baseHeight: 32 });
+    const c1 = cache.get(0, 0);
+    const c2 = cache.get(1, 0);
+    expect(c1).not.toBe(c2);
+    expect(c1.cx).toBe(0);
+    expect(c2.cx).toBe(1);
+  });
+
+  test('getChunkFn returns chunks compatible with getTerrainHeight', () => {
+    const cache = new VoxelChunkCache(42, { baseHeight: 32 });
+    const chunk = cache.getChunkFn(0, 0);
+    expect(chunk).not.toBeNull();
+    expect(chunk!.density.length).toBe(VOXEL_CHUNK_X * VOXEL_CHUNK_Y * VOXEL_CHUNK_Z);
+  });
+});