@jaysonder/tts-server 1.0.0

package/src/game/game.gateway.ts

@@ -0,0 +1,363 @@
+import {
+  WebSocketGateway,
+  WebSocketServer,
+  SubscribeMessage,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  MessageBody,
+  ConnectedSocket,
+} from '@nestjs/websockets';
+import { BadRequestException } from '@nestjs/common';
+import { Server, Socket } from 'socket.io';
+import { Logger } from '@nestjs/common';
+import { ZodSchema } from 'zod';
+import { GameEngineService, AUTO_ADVANCE_DELAY } from './services/game-engine.service.js';
+import { RoomManagerService } from './services/room-manager.service.js';
+import {
+  CreateRoomSchema,
+  JoinRoomSchema,
+  SubmitAnswerSchema,
+  type CreateRoomDto,
+  type JoinRoomDto,
+  type SubmitAnswerDto,
+} from './dto/game.dto.js';
+import { openaiRateLimiter, roomCreationRateLimiter, roomJoinRateLimiter, answerSubmissionRateLimiter } from '../common/utils/rate-limiter.js';
+import type { GameSettings } from '../common/types/index.js';
+
+function parseDto<T>(schema: ZodSchema<T>, data: unknown): T {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const messages = result.error.issues.map((e) => e.message);
+    throw new BadRequestException(messages.join(', '));
+  }
+  return result.data;
+}
+
+@WebSocketGateway({
+  cors: {
+    origin: process.env.CLIENT_URL,
+    methods: ['GET', 'POST'],
+    credentials: true,
+  },
+  pingTimeout: 20000,
+  pingInterval: 25000,
+})
+export class GameGateway implements OnGatewayConnection, OnGatewayDisconnect {
+  @WebSocketServer()
+  server: Server;
+
+  private readonly logger = new Logger(GameGateway.name);
+  private socketRoomMap = new Map<string, { roomCode: string | null; playerId: string | null }>();
+
+  constructor(
+    private readonly gameEngine: GameEngineService,
+    private readonly roomManager: RoomManagerService,
+  ) {}
+
+  handleConnection(client: Socket): void {
+    this.logger.log(`Client connected: ${client.id}`);
+    this.socketRoomMap.set(client.id, { roomCode: null, playerId: null });
+  }
+
+  handleDisconnect(client: Socket): void {
+    const socketData = this.socketRoomMap.get(client.id);
+    this.logger.log(`Client disconnected: ${client.id}`);
+
+    if (socketData?.roomCode && socketData?.playerId) {
+      const roomBefore = this.roomManager.getRoom(socketData.roomCode);
+      const playersBefore = roomBefore?.game.players.length ?? 0;
+
+      this.roomManager.removePlayer(socketData.roomCode, socketData.playerId);
+
+      const room = this.roomManager.getRoom(socketData.roomCode);
+      if (room) {
+        this.logger.log(`Player removed from room`, {
+          roomCode: socketData.roomCode,
+          playerId: socketData.playerId,
+          remainingPlayers: room.game.players.length,
+        });
+        this.server.to(socketData.roomCode).emit('player-left', {
+          playerId: socketData.playerId,
+          players: room.game.players,
+        });
+      } else {
+        this.logger.log(`Room deleted (last player left)`, { roomCode: socketData.roomCode, playersBefore });
+      }
+    }
+
+    this.socketRoomMap.delete(client.id);
+  }
+
+  @SubscribeMessage('create-room')
+  handleCreateRoom(
+    @MessageBody() rawData: unknown,
+    @ConnectedSocket() client: Socket,
+  ): { success: boolean; error?: string; roomCode?: string; player?: unknown; game?: unknown } {
+    if (!roomCreationRateLimiter.check(client.id)) {
+      this.logger.warn(`create-room rate limited: ${client.id}`);
+      return { success: false, error: 'Too many room creation attempts. Please try again later.' };
+    }
+
+    let data: CreateRoomDto;
+    try {
+      data = parseDto(CreateRoomSchema, rawData);
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Validation failed' };
+    }
+
+    this.logger.log(`create-room event`, { playerName: data.playerName, settings: data.settings });
+
+    try {
+      const settings: GameSettings = {
+        topic: data.settings.topic,
+        length: data.settings.length,
+        customLength: data.settings.customLength,
+        rounds: data.settings.rounds,
+        roundTimeLimit: data.settings.roundTimeLimit,
+      };
+
+      const room = this.roomManager.createRoom(data.playerName, settings);
+      this.socketRoomMap.set(client.id, { roomCode: room.code, playerId: room.game.players[0].id });
+      void client.join(room.code);
+
+      this.logger.log(`Room created`, { roomCode: room.code, playerId: room.game.players[0].id });
+
+      return {
+        success: true,
+        roomCode: room.code,
+        player: room.game.players[0],
+        game: room.game,
+      };
+    } catch (error) {
+      this.logger.error(`create-room failed`, { error: error instanceof Error ? error.message : String(error) });
+      return { success: false, error: error instanceof Error ? error.message : 'Failed to create room' };
+    }
+  }
+
+  @SubscribeMessage('join-room')
+  handleJoinRoom(
+    @MessageBody() rawData: unknown,
+    @ConnectedSocket() client: Socket,
+  ): { success: boolean; error?: string; roomCode?: string; player?: unknown; game?: unknown } {
+    if (!roomJoinRateLimiter.check(client.id)) {
+      this.logger.warn(`join-room rate limited: ${client.id}`);
+      return { success: false, error: 'Too many join attempts. Please try again later.' };
+    }
+
+    let data: JoinRoomDto;
+    try {
+      data = parseDto(JoinRoomSchema, rawData);
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Validation failed' };
+    }
+
+    this.logger.log(`join-room event`, { roomCode: data.roomCode, playerName: data.playerName });
+
+    try {
+      const result = this.roomManager.joinRoom(data.roomCode, data.playerName);
+
+      if (!result) {
+        this.logger.warn(`join-room failed - room not found or full`, { roomCode: data.roomCode });
+        return { success: false, error: 'Room not found or full' };
+      }
+
+      this.socketRoomMap.set(client.id, { roomCode: result.room.code, playerId: result.player.id });
+      void client.join(result.room.code);
+
+      this.logger.log(`Player joined room`, {
+        roomCode: result.room.code,
+        playerId: result.player.id,
+        playerName: data.playerName,
+      });
+
+      this.server.to(result.room.code).emit('player-joined', {
+        player: result.player,
+        players: result.room.game.players,
+        game: result.room.game,
+      });
+
+      return {
+        success: true,
+        roomCode: result.room.code,
+        player: result.player,
+        game: result.room.game,
+      };
+    } catch (error) {
+      this.logger.error(`join-room failed`, { error: error instanceof Error ? error.message : String(error) });
+      return { success: false, error: error instanceof Error ? error.message : 'Failed to join room' };
+    }
+  }
+
+  @SubscribeMessage('start-game')
+  async handleStartGame(@ConnectedSocket() client: Socket): Promise<{ success: boolean; error?: string }> {
+    const socketData = this.socketRoomMap.get(client.id);
+
+    if (!openaiRateLimiter.check(client.id)) {
+      this.logger.warn(`start-game rate limited: ${client.id}`);
+      return { success: false, error: 'Too many game starts. Please wait before trying again.' };
+    }
+
+    this.logger.log(`start-game event`, { roomCode: socketData?.roomCode, playerId: socketData?.playerId });
+
+    if (!socketData?.roomCode) {
+      return { success: false, error: 'Not in a room' };
+    }
+
+    const room = this.roomManager.getRoom(socketData.roomCode);
+    if (!room || room.hostId !== socketData.playerId) {
+      this.logger.warn(`start-game failed - not host or room not found`, {
+        roomCode: socketData.roomCode,
+        playerId: socketData.playerId,
+      });
+      return { success: false, error: 'Only host can start game' };
+    }
+
+    const roomCode = socketData.roomCode;
+
+    try {
+      const success = await this.gameEngine.startGame(roomCode, this.server);
+
+      if (success) {
+        this.logger.log(`Game started`, { roomCode, rounds: room.game.twisters.length });
+        this.server.to(roomCode).emit('game-started', {
+          game: room.game,
+          currentTwister: room.game.twisters[0],
+          roundStartTime: room.game.currentTwisterStartTime,
+          roundTimeLimit: room.game.roundTimeLimit,
+        });
+        return { success: true };
+      } else {
+        return { success: false, error: 'Failed to start game' };
+      }
+    } catch (error) {
+      this.logger.error(`start-game error`, { error: error instanceof Error ? error.message : String(error) });
+      return { success: false, error: error instanceof Error ? error.message : 'Failed to start game' };
+    }
+  }
+
+  @SubscribeMessage('submit-answer')
+  handleSubmitAnswer(
+    @MessageBody() rawData: unknown,
+    @ConnectedSocket() client: Socket,
+  ): { success: boolean; error?: string; similarity?: number } {
+    const socketData = this.socketRoomMap.get(client.id);
+
+    if (!answerSubmissionRateLimiter.check(client.id)) {
+      this.logger.warn(`submit-answer rate limited: ${client.id}`);
+      return { success: false, error: 'Too many submissions. Please slow down.' };
+    }
+
+    let data: SubmitAnswerDto;
+    try {
+      data = parseDto(SubmitAnswerSchema, rawData);
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Validation failed' };
+    }
+
+    this.logger.debug(`submit-answer event`, {
+      roomCode: socketData?.roomCode,
+      playerId: socketData?.playerId,
+      transcript: data.transcript.substring(0, 50),
+    });
+
+    if (!socketData?.roomCode || !socketData?.playerId) {
+      return { success: false, error: 'Not in a room' };
+    }
+
+    const result = this.gameEngine.submitAnswer(
+      socketData.roomCode,
+      socketData.playerId,
+      data.transcript,
+      data.timestamp,
+    );
+
+    if (!result) {
+      this.logger.warn(`submit-answer failed - cannot submit`, {
+        roomCode: socketData.roomCode,
+        playerId: socketData.playerId,
+      });
+      return { success: false, error: 'Cannot submit answer' };
+    }
+
+    this.logger.log(`Answer submitted`, {
+      roomCode: socketData.roomCode,
+      playerId: socketData.playerId,
+      similarity: result.similarity,
+      isComplete: result.isComplete,
+    });
+
+    this.server.to(socketData.roomCode).emit('player-submitted', {
+      playerId: socketData.playerId,
+      similarity: result.similarity,
+    });
+
+    if (result.isComplete) {
+      const roomCode = socketData.roomCode;
+      this.logger.log(`All players submitted, advancing round`, { roomCode });
+      setTimeout(() => {
+        this.gameEngine.advanceRound(roomCode, this.server);
+      }, AUTO_ADVANCE_DELAY);
+    }
+
+    return { success: true, similarity: result.similarity };
+  }
+
+  @SubscribeMessage('pause-game')
+  handlePauseGame(@ConnectedSocket() client: Socket): { success: boolean; error?: string } {
+    const socketData = this.socketRoomMap.get(client.id);
+
+    this.logger.log(`pause-game event`, { roomCode: socketData?.roomCode, playerId: socketData?.playerId });
+
+    if (!socketData?.roomCode || !socketData?.playerId) {
+      return { success: false, error: 'Not in a room' };
+    }
+
+    try {
+      const success = this.gameEngine.pauseGame(socketData.roomCode, socketData.playerId, this.server);
+      this.logger.log(`pause-game result`, { roomCode: socketData.roomCode, success });
+      return { success };
+    } catch (error) {
+      this.logger.error(`pause-game error`, { error: error instanceof Error ? error.message : String(error) });
+      return { success: false, error: 'Failed to pause game' };
+    }
+  }
+
+  @SubscribeMessage('resume-game')
+  handleResumeGame(@ConnectedSocket() client: Socket): { success: boolean; error?: string } {
+    const socketData = this.socketRoomMap.get(client.id);
+
+    this.logger.log(`resume-game event`, { roomCode: socketData?.roomCode });
+
+    if (!socketData?.roomCode) {
+      return { success: false, error: 'Not in a room' };
+    }
+
+    try {
+      const success = this.gameEngine.resumeGame(socketData.roomCode, this.server);
+      this.logger.log(`resume-game result`, { roomCode: socketData.roomCode, success });
+      return { success };
+    } catch (error) {
+      this.logger.error(`resume-game error`, { error: error instanceof Error ? error.message : String(error) });
+      return { success: false, error: 'Failed to resume game' };
+    }
+  }
+
+  @SubscribeMessage('get-room-state')
+  handleGetRoomState(@ConnectedSocket() client: Socket): { success: boolean; error?: string; game?: unknown; playerId?: string | null } {
+    const socketData = this.socketRoomMap.get(client.id);
+
+    this.logger.debug(`get-room-state event`, { roomCode: socketData?.roomCode });
+
+    if (!socketData?.roomCode) {
+      return { success: false, error: 'Not in a room' };
+    }
+
+    const room = this.roomManager.getRoom(socketData.roomCode);
+    if (!room) {
+      this.logger.warn(`get-room-state failed - room not found`, { roomCode: socketData.roomCode });
+      return { success: false, error: 'Room not found' };
+    }
+
+    return { success: true, game: room.game, playerId: socketData.playerId };
+  }
+}

package/src/game/game.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { GameGateway } from './game.gateway.js';
+import { GameController } from './game.controller.js';
+import { GameEngineService, RoomManagerService, TwisterGeneratorService } from './services/index.js';
+
+@Module({
+  controllers: [GameController],
+  providers: [GameGateway, GameEngineService, RoomManagerService, TwisterGeneratorService],
+  exports: [GameEngineService, RoomManagerService, TwisterGeneratorService],
+})
+export class GameModule {}

package/src/game/services/game-engine.service.ts

@@ -0,0 +1,281 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Server } from 'socket.io';
+import { TranscriptSchema } from '@nemsae/tts-validation';
+import type { ZodIssue } from 'zod';
+import type { Room, RoundResult, Player } from '../../common/types/index.js';
+import { RoomManagerService } from './room-manager.service.js';
+import { TwisterGeneratorService } from './twister-generator.service.js';
+import { scoreTwister } from './scoring.service.js';
+
+export const AUTO_ADVANCE_DELAY = 2000;
+
+@Injectable()
+export class GameEngineService {
+  private readonly logger = new Logger(GameEngineService.name);
+  private roundTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(
+    private readonly roomManager: RoomManagerService,
+    private readonly twisterGenerator: TwisterGeneratorService,
+  ) {}
+
+  async startGame(roomCode: string, io: Server): Promise<boolean> {
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room || room.game.status !== 'lobby') {
+      this.logger.warn(`startGame failed - invalid state, roomCode: ${roomCode}, status: ${room?.game.status}`);
+      return false;
+    }
+
+    this.logger.log(`Starting game, roomCode: ${roomCode}, topic: ${room.game.settings.topic}, rounds: ${room.game.settings.rounds}`);
+
+    const twisters = await this.twisterGenerator.generateTwisters(
+      room.game.settings.topic,
+      room.game.settings.length,
+      room.game.settings.customLength,
+      room.game.settings.rounds,
+    );
+
+    room.game.twisters = twisters;
+    room.game.currentRound = 0;
+    room.game.status = 'playing';
+    room.game.startedAt = Date.now();
+    room.game.currentTwisterStartTime = Date.now();
+    room.game.roundTimeLimit = room.game.settings.roundTimeLimit ?? null;
+
+    if (room.game.roundTimeLimit !== null) {
+      this.startRoundTimer(roomCode, io);
+    }
+
+    this.logger.log(`Game started successfully, roomCode: ${roomCode}, twistersGenerated: ${twisters.length}`);
+
+    return true;
+  }
+
+  submitAnswer(
+    roomCode: string,
+    playerId: string,
+    transcript: string,
+    _clientTimestamp: number,
+  ): { similarity: number; isComplete: boolean } | null {
+    const transcriptResult = TranscriptSchema.safeParse(transcript);
+    if (!transcriptResult.success) {
+      this.logger.warn(`submitAnswer failed - invalid transcript, roomCode: ${roomCode}, playerId: ${playerId}, error: ${transcriptResult.error.issues.map((e: ZodIssue) => e.message).join(', ')}`);
+      return null;
+    }
+    const sanitizedTranscript = transcriptResult.data;
+
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room || room.game.status !== 'playing') {
+      this.logger.warn(`submitAnswer failed - game not in playing state, roomCode: ${roomCode}, status: ${room?.game.status}`);
+      return null;
+    }
+    if (room.game.pausedAt !== null) {
+      this.logger.warn(`submitAnswer failed - game paused, roomCode: ${roomCode}`);
+      return null;
+    }
+
+    const currentTwister = room.game.twisters[room.game.currentRound];
+    if (!currentTwister) {
+      this.logger.warn(`submitAnswer failed - no current twister, roomCode: ${roomCode}, round: ${room.game.currentRound}`);
+      return null;
+    }
+
+    const roundElapsed = Date.now() - (room.game.currentTwisterStartTime || 0);
+    if (room.game.roundTimeLimit !== null && roundElapsed > room.game.roundTimeLimit) {
+      this.logger.warn(`submitAnswer failed - round time exceeded, roomCode: ${roomCode}, roundElapsed: ${roundElapsed}, limit: ${room.game.roundTimeLimit}`);
+      return null;
+    }
+
+    const { similarity } = scoreTwister(sanitizedTranscript, currentTwister.text);
+
+    this.logger.debug(`Answer scored, roomCode: ${roomCode}, playerId: ${playerId}, similarity: ${similarity}`);
+
+    const result: RoundResult = {
+      playerId,
+      twisterId: currentTwister.id,
+      similarity,
+      completedAt: Date.now(),
+    };
+    room.game.roundResults.push(result);
+
+    const player = room.game.players.find((p: Player) => p.id === playerId);
+    if (player) {
+      player.currentScore = similarity;
+    }
+
+    const submittedPlayerIds = new Set(
+      room.game.roundResults.filter((r: RoundResult) => r.twisterId === currentTwister.id).map((r: RoundResult) => r.playerId),
+    );
+
+    const allPlayersSubmitted = room.game.players.every((p: Player) => submittedPlayerIds.has(p.id));
+
+    this.logger.log(`Answer submitted, roomCode: ${roomCode}, playerId: ${playerId}, playerName: ${player?.name}, similarity: ${similarity}, allSubmitted: ${allPlayersSubmitted}`);
+
+    return { similarity, isComplete: allPlayersSubmitted };
+  }
+
+  advanceRound(roomCode: string, io: Server): boolean {
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room) {
+      this.logger.warn(`advanceRound failed - room not found, roomCode: ${roomCode}`);
+      return false;
+    }
+
+    room.game.currentRound++;
+
+    if (room.game.currentRound >= room.game.twisters.length) {
+      this.logger.log(`Game over - all rounds completed, roomCode: ${roomCode}, totalRounds: ${room.game.twisters.length}`);
+      room.game.status = 'game-over';
+      this.clearRoundTimer(roomCode);
+      this.endGame(roomCode, io);
+      return false;
+    }
+
+    room.game.currentTwisterStartTime = Date.now();
+    const currentTwister = room.game.twisters[room.game.currentRound];
+
+    this.logger.log(`Round advanced, roomCode: ${roomCode}, round: ${room.game.currentRound}, twisterId: ${currentTwister?.id}`);
+
+    io.to(roomCode).emit('round-advanced', {
+      currentRound: room.game.currentRound,
+      currentTwister,
+      roundStartTime: room.game.currentTwisterStartTime,
+      roundTimeLimit: room.game.roundTimeLimit,
+    });
+
+    if (room.game.roundTimeLimit !== null) {
+      this.startRoundTimer(roomCode, io);
+    }
+
+    return true;
+  }
+
+  pauseGame(roomCode: string, playerId: string, io: Server): boolean {
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room || room.game.status !== 'playing') {
+      this.logger.warn(`pauseGame failed - invalid state, roomCode: ${roomCode}, status: ${room?.game.status}`);
+      return false;
+    }
+    if (room.game.pausedAt !== null) {
+      this.logger.warn(`pauseGame failed - already paused, roomCode: ${roomCode}`);
+      return false;
+    }
+
+    this.clearRoundTimer(roomCode);
+
+    room.game.pausedAt = Date.now();
+    room.game.status = 'paused';
+
+    this.logger.log(`Game paused, roomCode: ${roomCode}, playerId: ${playerId}, pausedAt: ${room.game.pausedAt}`);
+
+    io.to(roomCode).emit('game-paused', {
+      pausedAt: room.game.pausedAt,
+      pausedBy: playerId,
+    });
+
+    return true;
+  }
+
+  resumeGame(roomCode: string, io: Server): boolean {
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room || room.game.status !== 'paused') {
+      this.logger.warn(`resumeGame failed - invalid state, roomCode: ${roomCode}, status: ${room?.game.status}`);
+      return false;
+    }
+    if (room.game.pausedAt === null) {
+      this.logger.warn(`resumeGame failed - not paused, roomCode: ${roomCode}`);
+      return false;
+    }
+
+    const pauseDuration = Date.now() - room.game.pausedAt;
+    room.game.totalPausedTime += pauseDuration;
+    room.game.status = 'playing';
+    room.game.pausedAt = null;
+
+    if (room.game.currentTwisterStartTime !== null) {
+      room.game.currentTwisterStartTime += pauseDuration;
+    }
+
+    this.logger.log(`Game resumed, roomCode: ${roomCode}, pauseDuration: ${pauseDuration}, totalPausedTime: ${room.game.totalPausedTime}`);
+
+    io.to(roomCode).emit('game-resumed', {
+      resumedAt: Date.now(),
+      totalPausedTime: room.game.totalPausedTime,
+      roundStartTime: room.game.currentTwisterStartTime,
+      roundTimeLimit: room.game.roundTimeLimit,
+    });
+
+    if (room.game.roundTimeLimit !== null) {
+      this.startRoundTimer(roomCode, io);
+    }
+
+    return true;
+  }
+
+  endGame(roomCode: string, io: Server): void {
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room) {
+      this.logger.warn(`endGame failed - room not found, roomCode: ${roomCode}`);
+      return;
+    }
+
+    room.game.status = 'game-over';
+    this.clearRoundTimer(roomCode);
+
+    const leaderboard = this.calculateLeaderboard(room);
+
+    this.logger.log(`Game ended, roomCode: ${roomCode}, leaderboard: ${JSON.stringify(leaderboard.map((e: { player: Player; accuracy: number; time: number }) => ({ name: e.player.name, accuracy: e.accuracy })))}`);
+
+    io.to(roomCode).emit('game-ended', { leaderboard });
+  }
+
+  private calculateLeaderboard(room: Room) {
+    return room.game.players
+      .map((player: Player) => {
+        const playerResults = room.game.roundResults.filter((r: RoundResult) => r.playerId === player.id);
+        const totalSimilarity = playerResults.reduce((sum: number, r: RoundResult) => sum + r.similarity, 0);
+        const accuracy = playerResults.length > 0 ? Math.round(totalSimilarity / playerResults.length) : 0;
+
+        const totalTime = room.game.startedAt ? Date.now() - room.game.startedAt - room.game.totalPausedTime : 0;
+
+        return { player, accuracy, time: totalTime };
+      })
+      .sort((a: { accuracy: number; time: number }, b: { accuracy: number; time: number }) => b.accuracy - a.accuracy || a.time - b.time);
+  }
+
+  private startRoundTimer(roomCode: string, io: Server): void {
+    this.clearRoundTimer(roomCode);
+
+    const room = this.roomManager.getRoom(roomCode);
+    if (!room || room.game.roundTimeLimit === null) return;
+
+    const elapsed = Date.now() - (room.game.currentTwisterStartTime || Date.now());
+    const remaining = Math.max(0, room.game.roundTimeLimit - elapsed);
+
+    this.logger.debug(`Starting round timer, roomCode: ${roomCode}, remaining: ${remaining}, totalDuration: ${room.game.roundTimeLimit}`);
+
+    const timer = setTimeout(() => {
+      this.logger.log(`Round timer expired, roomCode: ${roomCode}`);
+
+      io.to(roomCode).emit('round-time-expired', {
+        round: room.game.currentRound,
+      });
+
+      setTimeout(() => {
+        this.logger.log(`Auto-advancing after round time expired, roomCode: ${roomCode}`);
+        this.advanceRound(roomCode, io);
+      }, AUTO_ADVANCE_DELAY);
+    }, remaining);
+
+    this.roundTimers.set(roomCode, timer);
+  }
+
+  private clearRoundTimer(roomCode: string): void {
+    const timer = this.roundTimers.get(roomCode);
+    if (timer) {
+      clearTimeout(timer);
+      this.roundTimers.delete(roomCode);
+      this.logger.debug(`Round timer cleared, roomCode: ${roomCode}`);
+    }
+  }
+}

package/src/game/services/index.ts

@@ -0,0 +1,4 @@
+export * from './scoring.service.js';
+export * from './twister-generator.service.js';
+export * from './room-manager.service.js';
+export * from './game-engine.service.js';