@loonylabs/create-game 0.1.0

package/template/apps/server/src/areaManager.ts

@@ -0,0 +1,346 @@
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseAsciiGrid, createBiomeBlendFn, getTerrainHeight, getZoneCoords, ZONE_SIZE, mulberry32 } from '@loonylabs/gamedev-core';
+import type { RoomDef, Dungeon, PlacedRoom, GridData, TileInfo, BiomeDef } from '@loonylabs/gamedev-core';
+import { PLAYER_SPEED } from '../../game-data/src/world/movement.js';
+import type { GameEnemyDef as EnemyDef } from '../../game-data/src/combat/enemy-def.js';
+import { GameSession, type PlayerState } from '@loonylabs/gamedev-server';
+import type { Server } from 'socket.io';
+import { VoxelChunkCache } from './voxelChunkCache.js';
+import {
+  parseOverworldLayout,
+  getTileAt,
+  getBiomeTerrainOptions,
+  getStructureFlatZones,
+  TILE_SIZE,
+  BIOME_MOB_MAPPING,
+  type OverworldLayout,
+  type ParsedTile,
+} from '../../game-data/src/world/overworld-layout.js';
+import { BIOME_TERRAIN_OPTIONS } from '../../game-data/src/voxel/biome-terrain.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_DIR = resolve(__dirname, '../../game-data/src');
+
+/** Build a Dungeon from a single room definition — no generator randomness. */
+function buildSingleRoomDungeon(roomDef: RoomDef, seed = 0): Dungeon {
+  const grid = parseAsciiGrid(roomDef.ascii);
+
+  // Find spawn position
+  let spawnPosition = { x: 2, y: 5 }; // fallback
+  outer:
+  for (const row of grid.cells) {
+    for (const cell of row) {
+      if (cell.type === 'spawn') {
+        spawnPosition = { x: cell.x + 0.5, y: cell.y + 0.5 };
+        break outer;
+      }
+    }
+  }
+
+  const placedRoom: PlacedRoom = {
+    def: roomDef,
+    grid,
+    worldOffset: { x: 0, y: 0 },
+    doors: [],
+    isReachable: true,
+  };
+
+  return { seed, rooms: [placedRoom], spawnPosition };
+}
+
+export interface AreaSession {
+  session: GameSession;
+  areaType: 'room' | 'overworld' | 'dungeon' | 'voxel';
+  biomeId?: string;
+  /** Voxel chunk cache for voxel areas. */
+  chunkCache?: VoxelChunkCache;
+}
+
+/** Returns the tile type for a world position in the overworld layout. */
+export function getOverworldTileType(
+  layout: OverworldLayout,
+  worldX: number,
+  worldZ: number,
+): ParsedTile | undefined {
+  const col = Math.floor(worldX / TILE_SIZE);
+  const row = Math.floor(worldZ / TILE_SIZE);
+  return getTileAt(layout, col, row);
+}
+
+export class AreaManager {
+  private areas = new Map<string, AreaSession>();
+  private playerArea = new Map<string, string>(); // socketId -> areaId
+  private enemyDefs: EnemyDef[];
+  private biomes: Record<string, BiomeDef>;
+  private rooms: RoomDef[];
+  readonly layout: OverworldLayout;
+
+  /** World position of the dungeon entrance tile center (for return transitions). */
+  private dungeonEntrancePos: { x: number; z: number };
+
+  constructor(rooms: RoomDef[], seed: number) {
+    this.rooms = rooms;
+
+    // Load config
+    this.enemyDefs = JSON.parse(
+      readFileSync(resolve(CONFIG_DIR, 'enemies/enemy-defs.json'), 'utf-8')
+    );
+    this.biomes = JSON.parse(
+      readFileSync(resolve(CONFIG_DIR, 'world/biomes.json'), 'utf-8')
+    );
+
+    // --- Voxel Overworld ---
+    this.layout = parseOverworldLayout();
+
+    // Build TileInfo grid for biome blending
+    const tileInfoGrid: TileInfo[][] = this.layout.tiles.map(row =>
+      row.map(tile => ({
+        terrainOptions: getBiomeTerrainOptions(tile.def.biomeId),
+      })),
+    );
+    const flatZones = getStructureFlatZones(this.layout);
+    const blendFn = createBiomeBlendFn(tileInfoGrid, TILE_SIZE, TILE_SIZE, flatZones);
+    const overworldCache = new VoxelChunkCache(seed, undefined, blendFn);
+
+    const overworldSession = new GameSession('overworld', [], seed, undefined, undefined, {
+      playerSpeed: PLAYER_SPEED,
+      skipWalkCheck: true,
+    });
+
+    // Find basecamp center for spawn position
+    const basecampTiles = this._findTilesOfType('B');
+    const bcCenterCol = basecampTiles.length > 0
+      ? basecampTiles.reduce((s, t) => s + t.col, 0) / basecampTiles.length
+      : 1;
+    const bcCenterRow = basecampTiles.length > 0
+      ? basecampTiles.reduce((s, t) => s + t.row, 0) / basecampTiles.length
+      : 1;
+    const spawnX = (bcCenterCol + 0.5) * TILE_SIZE;
+    const spawnZ = (bcCenterRow + 0.5) * TILE_SIZE;
+    overworldSession.state.dungeon.spawnPosition = { x: spawnX, y: spawnZ };
+
+    this.areas.set('overworld', {
+      session: overworldSession,
+      areaType: 'voxel',
+      chunkCache: overworldCache,
+    });
+
+    this._spawnOverworldEnemies(overworldSession, seed);
+
+    // Find dungeon entrance position
+    const dungeonTiles = this._findTilesOfType('D');
+    if (dungeonTiles.length > 0) {
+      this.dungeonEntrancePos = {
+        x: (dungeonTiles[0].col + 0.5) * TILE_SIZE,
+        z: (dungeonTiles[0].row + 0.5) * TILE_SIZE,
+      };
+    } else {
+      this.dungeonEntrancePos = { x: spawnX, z: spawnZ };
+    }
+
+    // --- Dungeon ---
+    const dungeonSession = new GameSession('dungeon', rooms, seed, undefined, undefined, { playerSpeed: PLAYER_SPEED });
+    this.spawnInitialDungeonEnemies(dungeonSession);
+    this.areas.set('dungeon', { session: dungeonSession, areaType: 'dungeon' });
+  }
+
+  private _findTilesOfType(type: string): ParsedTile[] {
+    const result: ParsedTile[] = [];
+    for (const row of this.layout.tiles) {
+      for (const tile of row) {
+        if (tile.def.type === type) result.push(tile);
+      }
+    }
+    return result;
+  }
+
+  private _spawnOverworldEnemies(session: GameSession, seed: number): void {
+    const rng = mulberry32(seed);
+
+    for (const row of this.layout.tiles) {
+      for (const tile of row) {
+        if (!tile.def.spawnsMobs) continue;
+
+        const mobBiomeId = BIOME_MOB_MAPPING[tile.def.biomeId];
+        if (!mobBiomeId) continue;
+
+        const biome = this.biomes[mobBiomeId];
+        if (!biome?.mobs || biome.mobs.length === 0) continue;
+
+        // Spawn 3 enemies per wilderness tile
+        const enemiesPerTile = 3;
+        for (let i = 0; i < enemiesPerTile; i++) {
+          const mobId = biome.mobs[Math.floor(rng() * biome.mobs.length)];
+          const enemyDef = this.enemyDefs.find(d => d.id === mobId);
+          if (!enemyDef) continue;
+
+          // Random position within tile
+          const wx = (tile.col + 0.1 + rng() * 0.8) * TILE_SIZE;
+          const wz = (tile.row + 0.1 + rng() * 0.8) * TILE_SIZE;
+
+          // Second waypoint nearby
+          const wp2x = wx + (rng() * 6 - 3);
+          const wp2z = wz + (rng() * 6 - 3);
+
+          session.spawnEnemy({
+            enemyDefId: enemyDef.id,
+            x: wx,
+            y: wz, // Note: y = world Z in 2D convention
+            hp: enemyDef.hp,
+            maxHp: enemyDef.maxHp,
+            alive: true,
+            aiState: 'patrol',
+            waypoints: [{ x: wx, y: wz }, { x: wp2x, y: wp2z }],
+            waypointIndex: 0,
+            path: [],
+            attackCooldown: 0,
+          });
+        }
+      }
+    }
+  }
+
+  spawnInitialDungeonEnemies(session: GameSession): void {
+    const spawn = session.state.dungeon.spawnPosition;
+    const wp1 = { x: spawn.x + 1, y: spawn.y };
+    const wp2 = { x: spawn.x + 1, y: spawn.y + 1 };
+
+    if (session.isWalkable(Math.round(wp1.x), Math.round(wp1.y))) {
+      session.spawnEnemy({
+        enemyDefId: 'grunt',
+        x: wp1.x,
+        y: wp1.y,
+        hp: 50,
+        maxHp: 50,
+        alive: true,
+        aiState: 'patrol',
+        waypoints: [wp1, wp2],
+        waypointIndex: 0,
+        path: [],
+        attackCooldown: 0,
+      });
+    }
+  }
+
+  getAreaSession(areaId: string): AreaSession | undefined {
+    return this.areas.get(areaId);
+  }
+
+  getSession(areaId: string): GameSession | undefined {
+    return this.areas.get(areaId)?.session;
+  }
+
+  getPlayerArea(socketId: string): string {
+    return this.playerArea.get(socketId) ?? 'overworld';
+  }
+
+  addPlayerToArea(socketId: string, playerId: string, areaId: string): PlayerState {
+    const session = this.getSession(areaId);
+    if (!session) throw new Error(`Unknown area: ${areaId}`);
+    this.playerArea.set(socketId, areaId);
+    return session.addPlayer(socketId, playerId);
+  }
+
+  removePlayerFromArea(socketId: string): void {
+    const areaId = this.playerArea.get(socketId);
+    if (areaId) {
+      this.getSession(areaId)?.removePlayer(socketId);
+    }
+    this.playerArea.delete(socketId);
+  }
+
+  /** Get the dungeon entrance world position (for return transitions). */
+  getDungeonEntrancePos(): { x: number; z: number } {
+    return this.dungeonEntrancePos;
+  }
+
+  /**
+   * Move a player from their current area to a new area.
+   * Emits AREA_CHANGE to the player's socket.
+   */
+  movePlayer(
+    io: Server,
+    socketId: string,
+    toAreaId: string,
+    spawnX: number,
+    spawnY: number,
+  ): void {
+    const fromAreaId = this.playerArea.get(socketId);
+    if (!fromAreaId) return;
+
+    const fromSession = this.getSession(fromAreaId);
+    const player = fromSession?.state.players.get(socketId);
+    const playerId = player?.playerId ?? socketId;
+    const inventory = player?.inventory ?? [];
+    const equipped = player?.equipped ?? {};
+    const hp = player?.hp ?? 100;
+
+    // Remove from old area
+    fromSession?.removePlayer(socketId);
+    this.playerArea.delete(socketId);
+
+    // Add to new area
+    const toAreaSession = this.getAreaSession(toAreaId);
+    if (!toAreaSession) {
+      console.error(`[AreaManager] Unknown target area: ${toAreaId}`);
+      return;
+    }
+
+    // Reset dungeon if it was cleared (fresh run on re-entry)
+    if (toAreaId === 'dungeon' && toAreaSession.session.clearedAt) {
+      toAreaSession.session.regenerateDungeon(this.rooms);
+      this.spawnInitialDungeonEnemies(toAreaSession.session);
+      console.log(`[area] Dungeon reset for re-entry`);
+    }
+
+    // spawnX/Y of -1 means "use the area's natural spawn position"
+    const effectiveSpawnX = spawnX < 0 ? toAreaSession.session.state.dungeon.spawnPosition.x : spawnX;
+    const effectiveSpawnY = spawnY < 0 ? toAreaSession.session.state.dungeon.spawnPosition.y : spawnY;
+
+    const newPlayer = toAreaSession.session.addPlayer(socketId, playerId);
+    newPlayer.x = effectiveSpawnX;
+    newPlayer.y = effectiveSpawnY;
+    newPlayer.inventory = inventory;
+    newPlayer.equipped = equipped;
+    newPlayer.hp = hp;
+
+    // Explicitly update zone after setting new coordinates
+    const newZone = getZoneCoords(effectiveSpawnX, effectiveSpawnY, ZONE_SIZE);
+
+    // Move in spatial hash
+    toAreaSession.session.spatialHash.move(newPlayer.entityId, newPlayer.currentZone.tx, newPlayer.currentZone.ty, newZone.tx, newZone.ty);
+    newPlayer.currentZone = newZone;
+
+    this.playerArea.set(socketId, toAreaId);
+
+    // Build AREA_CHANGE payload
+    const payload: Record<string, unknown> = {
+      type: 'AREA_CHANGE',
+      targetArea: toAreaId,
+      spawnX: effectiveSpawnX,
+      spawnY: effectiveSpawnY,
+      localEntityId: newPlayer.entityId,
+      seed: toAreaSession.session.state.dungeon.seed,
+    };
+
+    if (toAreaSession.areaType === 'room' || toAreaSession.areaType === 'dungeon') {
+      payload.dungeon = toAreaSession.session.state.dungeon;
+    }
+    if (toAreaSession.biomeId) {
+      payload.biomeId = toAreaSession.biomeId;
+    }
+    if (toAreaSession.areaType === 'voxel') {
+      payload.voxelConfig = {
+        terrainOptions: null, // client will use its own biome blend
+        tileLayout: true,     // signal to client that this is a tile-based voxel area
+      };
+    }
+
+    const sock = io.sockets.sockets.get(socketId);
+    sock?.emit('message', payload);
+
+    console.log(`[area] ${playerId} moved from ${fromAreaId} to ${toAreaId} at (${effectiveSpawnX}, ${effectiveSpawnY})`);
+  }
+}

package/template/apps/server/src/db/client.ts

@@ -0,0 +1,45 @@
+import { createDb } from '@loonylabs/gamedev-server';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as schema from './schema.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = resolve(__dirname, '../../data');
+
+const CREATE_TABLES_SQL = `
+  CREATE TABLE IF NOT EXISTS players (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    hp INTEGER NOT NULL DEFAULT 100,
+    x REAL NOT NULL DEFAULT 0,
+    y REAL NOT NULL DEFAULT 0
+  );
+  CREATE TABLE IF NOT EXISTS items (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    rarity TEXT NOT NULL,
+    stat_bonus_json TEXT NOT NULL
+  );
+  CREATE TABLE IF NOT EXISTS inventories (
+    player_id TEXT NOT NULL,
+    item_id TEXT NOT NULL,
+    slot INTEGER NOT NULL,
+    PRIMARY KEY (player_id, slot)
+  );
+  CREATE TABLE IF NOT EXISTS equipped (
+    player_id TEXT NOT NULL,
+    slot_id TEXT NOT NULL,
+    item_id TEXT NOT NULL,
+    PRIMARY KEY (player_id, slot_id)
+  );
+`;
+
+export const db = createDb(resolve(DATA_DIR, 'game.db'), schema, CREATE_TABLES_SQL);
+
+export type Db = typeof db;
+
+export type PlayerRow = typeof schema.players.$inferSelect;
+export type ItemRow = typeof schema.items.$inferSelect;
+export type InventoryRow = typeof schema.inventories.$inferSelect;
+
+export { schema };

package/template/apps/server/src/db/schema.ts

@@ -0,0 +1,40 @@
+import { sqliteTable, text, integer, real } from 'drizzle-orm/sqlite-core';
+
+export const players = sqliteTable('players', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  hp: integer('hp').notNull().default(100),
+  x: real('x').notNull().default(0),
+  y: real('y').notNull().default(0),
+});
+
+export const items = sqliteTable('items', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  rarity: text('rarity').notNull(),
+  statBonusJson: text('stat_bonus_json').notNull(),
+});
+
+export const inventories = sqliteTable('inventories', {
+  playerId: text('player_id').notNull(),
+  itemId: text('item_id').notNull(),
+  slot: integer('slot').notNull(),
+});
+
+export const equipped = sqliteTable('equipped', {
+  playerId: text('player_id').notNull(),
+  slotId: text('slot_id').notNull(),
+  itemId: text('item_id').notNull(),
+});
+
+export const voxelDeltas = sqliteTable('voxel_deltas', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  cx: integer('cx').notNull(),
+  cz: integer('cz').notNull(),
+  lx: integer('lx').notNull(),
+  ly: integer('ly').notNull(),
+  lz: integer('lz').notNull(),
+  density: real('density').notNull(),
+  material: integer('material').notNull(),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull(),
+});

package/template/apps/server/src/gameLoop.ts

@@ -0,0 +1,267 @@
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Server } from 'socket.io';
+import type { GameSession } from '@loonylabs/gamedev-server';
+import { createTickLoop } from '@loonylabs/gamedev-server';
+import type { AreaManager, AreaSession } from './areaManager.js';
+import { getOverworldTileType } from './areaManager.js';
+import { updateEnemyAI } from './systems/enemyAI.js';
+import { updateItemPickup } from './systems/itemPickup.js';
+import { isDungeonCleared, getTerrainHeight, updatePhysicsBody, updateJumpState, snapToGround, consumeJumpBuffer } from '@loonylabs/gamedev-core';
+import { createVoxelPlayerPhysics, type VoxelPhysicsMap, voxelPhysicsRegistry } from './voxelPlayerState.js';
+import type { VoxelChunkCache } from './voxelChunkCache.js';
+import { SANDBOX_PHYSICS_CONFIG } from '../../game-data/src/voxel/sandbox-terrain-config.js';
+import { DUNGEON_PHYSICS_CONFIG } from '../../game-data/src/physics/dungeon-physics-config.js';
+import { GAME_JUMP_CONFIG } from '../../game-data/src/physics/jump-config.js';
+import { TILE_SIZE } from '../../game-data/src/world/overworld-layout.js';
+import { getDungeonGroundY } from './systems/dungeonPhysics.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const TICK_RATE = 20; // Hz
+
+// Area manifest — defines transition targets per area
+interface TransitionDef {
+  cellType?: string;
+  tileType?: string;
+  targetArea: string;
+  spawnX: number;
+  spawnY: number;
+  minX?: number;
+  maxX?: number;
+  minY?: number;
+  maxY?: number;
+}
+
+interface AreaDef {
+  id: string;
+  transitions: TransitionDef[];
+}
+
+interface AreaManifest {
+  areas: AreaDef[];
+}
+
+const manifest: AreaManifest = JSON.parse(
+  readFileSync(resolve(__dirname, '../../game-data/src/areas/area-manifest.json'), 'utf-8')
+);
+
+const transitionsByArea = new Map<string, TransitionDef[]>(
+  manifest.areas.map(a => [a.id, a.transitions])
+);
+
+export function startGameLoop(
+  io: Server,
+  session: GameSession,
+  areaManager: AreaManager,
+  areaId: string,
+  areaSession?: AreaSession,
+): () => void {
+  let tick = 0;
+
+  // Per-player transition cooldown (socketId -> timestamp) — prevents double-fire
+  const transitionCooldown = new Map<string, number>();
+
+  // Physics state — runs for voxel AND dungeon areas
+  const isVoxelArea = areaSession?.areaType === 'voxel';
+  const isDungeonArea = areaSession?.areaType === 'dungeon';
+  const runPhysics = isVoxelArea || isDungeonArea;
+  const chunkCache = areaSession?.chunkCache;
+  const physicsMap: VoxelPhysicsMap = new Map();
+  if (runPhysics) {
+    voxelPhysicsRegistry.set(areaId, physicsMap);
+  }
+
+  return createTickLoop(TICK_RATE, (dt) => {
+    tick++;
+    const now = Date.now();
+
+    session.updateMovement(dt);
+    updateEnemyAI(session, dt);
+    updateItemPickup(session);
+
+    // Physics tick — runs for voxel and dungeon areas
+    if (runPhysics) {
+      const getGroundY = isVoxelArea && chunkCache
+        ? (x: number, z: number) => getTerrainHeight(chunkCache.getChunkFn, x, z)
+        : (x: number, z: number) => getDungeonGroundY(session, x, z);
+
+      const physicsConfig = isVoxelArea ? SANDBOX_PHYSICS_CONFIG : DUNGEON_PHYSICS_CONFIG;
+
+      for (const player of session.state.players.values()) {
+        // Ensure physics state exists
+        if (!physicsMap.has(player.socketId)) {
+          const spawnHeight = getGroundY(player.x, player.y) ?? 32;
+          physicsMap.set(player.socketId, createVoxelPlayerPhysics(player.x, spawnHeight, player.y));
+        }
+
+        const physics = physicsMap.get(player.socketId)!;
+
+        // Sync horizontal position from PLAYER_MOVE_DIRECT
+        // player.x = world X, player.y = world Z (2D legacy mapping)
+        physics.body.x = player.x;
+        physics.body.z = player.y;
+
+        // Update jump timers
+        updateJumpState(physics.jumpState, physics.body, dt);
+
+        // Apply gravity + ground check
+        updatePhysicsBody(physics.body, dt, getGroundY, physicsConfig);
+
+        // Auto-jump if buffered and just landed
+        consumeJumpBuffer(physics.body, physics.jumpState, GAME_JUMP_CONFIG);
+
+        // Snap grounded entities to terrain after horizontal movement
+        if (physics.body.isGrounded) {
+          snapToGround(physics.body, getGroundY, physicsConfig);
+        }
+      }
+
+      // Clean up physics for disconnected players
+      for (const socketId of physicsMap.keys()) {
+        if (!session.state.players.has(socketId)) {
+          physicsMap.delete(socketId);
+        }
+      }
+    }
+
+    // Detect transitions
+    const transitions = transitionsByArea.get(areaId) ?? [];
+    if (transitions.length > 0) {
+      for (const player of session.state.players.values()) {
+        const lastTransition = transitionCooldown.get(player.socketId) ?? 0;
+        if (now - lastTransition < 1000) continue; // 1s cooldown
+
+        let matched = false;
+
+        // Tile-based transition (for voxel overworld)
+        // Only trigger near tile center (within 4 units) — not the whole 32×32 tile
+        if (isVoxelArea) {
+          const tile = getOverworldTileType(areaManager.layout, player.x, player.y);
+          if (tile) {
+            const tr = transitions.find(t => t.tileType && t.tileType === tile.def.type);
+            if (tr) {
+              const tileCenterX = (tile.col + 0.5) * TILE_SIZE;
+              const tileCenterZ = (tile.row + 0.5) * TILE_SIZE;
+              const dx = player.x - tileCenterX;
+              const dz = player.y - tileCenterZ;
+              const distToCenter = Math.sqrt(dx * dx + dz * dz);
+              if (distToCenter <= 4) {
+                transitionCooldown.set(player.socketId, now);
+                areaManager.movePlayer(io, player.socketId, tr.targetArea, tr.spawnX, tr.spawnY);
+                matched = true;
+              }
+            }
+          }
+        }
+
+        if (matched) break;
+
+        // Cell-based transition (for dungeons with stamped cells)
+        const cx = Math.round(player.x);
+        const cy = Math.round(player.y);
+        const cell = session.getCell(cx, cy);
+        if (cell?.type === 'transition') {
+          const tr = transitions.find(t => {
+            if (t.cellType !== 'transition' && t.cellType !== undefined) return false;
+            if (t.minX !== undefined && player.x < t.minX) return false;
+            if (t.maxX !== undefined && player.x > t.maxX) return false;
+            if (t.minY !== undefined && player.y < t.minY) return false;
+            if (t.maxY !== undefined && player.y > t.maxY) return false;
+            return true;
+          });
+          if (tr) {
+            transitionCooldown.set(player.socketId, now);
+            // When returning to overworld from dungeon, spawn near dungeon entrance
+            let sx = tr.spawnX;
+            let sy = tr.spawnY;
+            if (tr.targetArea === 'overworld' && sx < 0) {
+              const entrance = areaManager.getDungeonEntrancePos();
+              // Offset slightly so player doesn't immediately re-trigger D tile
+              sx = entrance.x - TILE_SIZE * 0.5;
+              sy = entrance.z;
+            }
+            areaManager.movePlayer(io, player.socketId, tr.targetArea, sx, sy);
+            break;
+          }
+        }
+      }
+    }
+
+    // Dungeon clearance check
+    if (areaId === 'dungeon' && session.state.enemies.length > 0 && !session.clearedAt) {
+      if (isDungeonCleared(session.state)) {
+        session.clearedAt = Date.now();
+        for (const player of session.state.players.values()) {
+          io.sockets.sockets.get(player.socketId)?.emit('message', {
+            type: 'DUNGEON_CLEAR',
+            countdownSeconds: 10,
+          });
+        }
+
+        let remaining = 10;
+        const countdown = setInterval(() => {
+          remaining--;
+          for (const player of session.state.players.values()) {
+            io.sockets.sockets.get(player.socketId)?.emit('message', {
+              type: 'COUNTDOWN_TICK',
+              secondsRemaining: remaining,
+            });
+          }
+          if (remaining <= 0) {
+            clearInterval(countdown);
+            const playerIds = [...session.state.players.keys()];
+            // Return to overworld basecamp
+            for (const socketId of playerIds) {
+              areaManager.movePlayer(io, socketId, 'overworld', -1, -1);
+            }
+          }
+        }, 1000);
+      }
+    }
+
+    let entities = session.getEntitySnapshots();
+
+    // For areas with physics, override positions with PhysicsBody data
+    if (runPhysics) {
+      const getGroundYForSync = isVoxelArea && chunkCache
+        ? (x: number, z: number) => getTerrainHeight(chunkCache.getChunkFn, x, z) ?? 0
+        : null;
+
+      entities = entities.map(e => {
+        // Players: use physics body Y
+        for (const [socketId, physics] of physicsMap) {
+          const p = session.state.players.get(socketId);
+          if (p && p.entityId === e.entityId) {
+            return { ...e, x: physics.body.x, y: physics.body.z, z: physics.body.z, worldY: physics.body.y };
+          }
+        }
+        // Non-player entities in voxel areas: compute terrain height
+        if (getGroundYForSync && e.type !== 'player') {
+          return { ...e, worldY: getGroundYForSync(e.x, e.y) };
+        }
+        return e;
+      });
+    }
+
+    // Emit to players in this session
+    for (const player of session.state.players.values()) {
+      const sock = io.sockets.sockets.get(player.socketId);
+      sock?.emit('message', { type: 'ENTITY_SYNC', entities, tick });
+    }
+
+    // Per-socket INPUT_ACK so each WASD client can reconcile predictions
+    for (const player of session.state.players.values()) {
+      if (player.lastProcessedInputId >= 0) {
+        const sock = io.sockets.sockets.get(player.socketId);
+        sock?.emit('message', {
+          type: 'INPUT_ACK',
+          lastProcessedInputId: player.lastProcessedInputId,
+          x: player.x,
+          y: player.y,
+        });
+      }
+    }
+  });
+}

package/template/apps/server/src/gameState.ts

@@ -0,0 +1,3 @@
+// Re-export from framework package for backwards compatibility
+export { GameSession, SpatialHash, moveAlongPath } from '@loonylabs/gamedev-server';
+export type { PlayerState, EnemyState, WorldItem, SpawnableEnemyDef, GameSessionOptions } from '@loonylabs/gamedev-server';