// Barcode Game Service // Purpose: Coordinates global barcode games, voting, player attribution, and // persistent scan counters for the scanner station. // Scope: Keeps game orchestration server-side while the scanner and driver pages // remain thin IO surfaces that subscribe to state and send votes/scans. const io = require('../../globals/io'); const logger = require('../../globals/logger').child('barcodeGameService'); const { loadConfig, registerConfigurationHandler } = require('../../configuration'); const { subscribe } = require('../eventBus'); const { sendSystemMessage } = require('../chatService'); const { getActiveDrivers } = require('../turnService'); const { getIdentitySummary } = require('../verificationService'); const { getFeatureState, listFeatureStates, updateFeatureState } = require('../identityService'); const { getRegistrySnapshot } = require('../barcodeScannerService'); const { loadStore, withGameStore } = require('./store'); const scanQuest = require('./games/scanQuest'); const scansPerSecond = require('./games/scansPerSecond'); const mostItems = require('./games/mostItems'); const GAME_SOCKET_ROOM = 'barcode-game'; const RECENT_EVENT_LIMIT = 20; const ROVER_ATTRIBUTION_WINDOW_MS = 60 * 1000; const GAME_TICK_MS = 5 * 1000; const VOTING_WINDOW_MS = 10 * 1000; const JOIN_WINDOW_MS = 30 * 1000; const STARTING_WINDOW_MS = 5 * 1000; const RESULTS_WINDOW_MS = 45 * 1000; const GAME_DEFINITIONS = [scanQuest, scansPerSecond, mostItems]; const GAMES_BY_ID = Object.fromEntries(GAME_DEFINITIONS.map((game) => [game.id, game])); let enabled; let botName; let botProfileImageUrl; function applyBarcodeGameConfig(barcodeGamesConfig = {}) { enabled = Boolean(barcodeGamesConfig.enabled); botName = String(barcodeGamesConfig.botName || 'Barcode Games').trim() || 'Barcode Games'; botProfileImageUrl = String(barcodeGamesConfig.profileImageUrl || '').trim() || null; } applyBarcodeGameConfig(loadConfig().barcodeGames || {}); function sendBarcodeGameChat(text) { const message = String(text || '').trim(); if (!message) return null; // Barcode game lifecycle messages use the same internal chat path as the // Overseer bot. Keeping this as a local helper makes the transition code // explicit while preserving the chat service's normal bot/profile handling. return sendSystemMessage(message, { nickname: botName, bot: true, profileImage: botProfileImageUrl, }); } function formatList(items = [], limit = 5) { // Chat messages should stay readable in the normal feed. This helper keeps // every lifecycle message to a short list while still making it obvious when // more players or stats existed than could fit comfortably in one message. const values = items .map((item) => String(item || '').trim()) .filter(Boolean); if (!values.length) return ''; const visible = values.slice(0, limit); const extraCount = values.length - visible.length; if (extraCount === 1) { // A single hidden item reads badly as "and 1 more" in chat, especially for // result summaries where the omitted item is usually just one normal stat. // Including it is still short and avoids making the bot sound confused. return values.slice(0, limit + 1).join(', '); } const suffix = extraCount > 1 ? `, plus ${extraCount} more` : ''; return `${visible.join(', ')}${suffix}`; } function getParticipantName(participant = {}) { return participant.nickname || participant.roverId || participant.participantKey || ''; } function formatParticipantSummary(participants = []) { const names = formatList(participants.map(getParticipantName)); return names || 'no counted rovers yet'; } function formatVoteSummary(votes = {}, selectedGameId = null) { const counts = countVotes(votes); const selectedVotes = selectedGameId ? counts[selectedGameId] || 0 : 0; const totalVotes = Object.values(counts).reduce((sum, count) => sum + count, 0); // The selected vote count matters more than a full per-game breakdown in // chat. The detailed vote buttons still show every game, while the bot gives // enough context to explain why this specific game moved to joining. if (!totalVotes) return 'No votes were counted'; if (selectedVotes === totalVotes) { return `${selectedVotes} ${selectedVotes === 1 ? 'vote' : 'votes'}`; } return `${selectedVotes} of ${totalVotes} ${totalVotes === 1 ? 'vote' : 'votes'}`; } function normalizeAwardSummaries(awards = []) { const totalsByPlayer = {}; awards.forEach((award) => { const playerKey = award?.playerKey; const points = Number.isFinite(award?.points) ? Math.max(0, Math.floor(award.points)) : 0; // applyPointAwards uses this same identity-only rule. Repeating it here // prevents the bot from claiming that a rover-only participant earned // leaderboard points when the persistent ledger intentionally ignored it. if (!playerKey || !String(playerKey).startsWith('identity:') || !points) return; const previous = totalsByPlayer[playerKey] || {}; totalsByPlayer[playerKey] = { playerKey, nickname: award.nickname || previous.nickname || award.roverId || 'unknown player', roverId: award.roverId || previous.roverId || null, points: (Number.isFinite(previous.points) ? previous.points : 0) + points, }; }); return Object.values(totalsByPlayer).sort((a, b) => (b.points || 0) - (a.points || 0)); } function formatAwardSummary(awards = []) { const summaries = normalizeAwardSummaries(awards); if (!summaries.length) return ''; // Award packets are the most authoritative source for point changes because // they are what the shared ledger actually applies. The formatter groups // multiple awards per player so chat does not spam one line per scan. return formatList( summaries.map((award) => `${award.nickname || award.roverId} scored ${award.points} ${award.points === 1 ? 'point' : 'points'}`), 5, ); } function formatPublicScoreSummary(publicState = {}) { const scoreEntries = Array.isArray(publicState?.scores) ? publicState.scores : Array.isArray(publicState?.finalResult?.participants) ? publicState.finalResult.participants : []; const summaries = scoreEntries .map((entry) => { // Public game state is less authoritative than award packets, but it is // still valuable for games that award throughout the round. The formatter // accepts both point-shaped and scan-count-shaped entries so game modules // can expose natural result data without chat-specific contracts. const points = Number.isFinite(entry?.points) ? Math.max(0, Math.floor(entry.points)) : null; const scanCount = Number.isFinite(entry?.scanCount) ? Math.max(0, Math.floor(entry.scanCount)) : null; const name = entry?.nickname || entry?.roverId || entry?.playerKey || ''; if (!name) return null; if (points !== null && points > 0) { return `${name} scored ${points} ${points === 1 ? 'point' : 'points'}`; } if (scanCount !== null && scanCount > 0) { return `${name} made ${scanCount} ${scanCount === 1 ? 'scan' : 'scans'}`; } return null; }) .filter(Boolean); // Some games, like scan quest, award during the round instead of returning a // final award packet. Their public state still carries round scores, so this // gives the bot a useful end summary without making each game hand-write chat. return formatList(summaries, 5); } function formatResultSummary(display = {}) { const primary = String(display?.primary || '').trim(); const usefulStats = Array.isArray(display?.stats) ? display.stats .map((stat) => { const label = String(stat?.label || '').trim(); const value = String(stat?.value ?? '').trim(); if (!label || !value) return ''; return `${label}: ${value}`; }) .filter(Boolean) : []; // Result summaries are already compact because games normally publish one // primary line and a few stats. Joining them all avoids vague bot messages // like "and 1 more" while still leaving the heavier participant lists to the // bounded formatList helper above. return [primary, ...usefulStats].filter(Boolean).join('. '); } function sendGameStartChat(definition, participants = []) { const title = definition?.title || 'Barcode game'; const participantSummary = formatParticipantSummary(participants); sendBarcodeGameChat(`${title} has started with ${participantSummary}.`); } function sendGameEndChat(definition, { display = null, publicState = null, awards = [], participants = [] } = {}) { const title = definition?.title || 'Barcode game'; const awardSummary = formatAwardSummary(awards) || formatPublicScoreSummary(publicState); const resultSummary = formatResultSummary(display || publicState?.display || {}); const participantSummary = formatParticipantSummary(participants); const details = [ resultSummary, awardSummary || `Played by ${participantSummary}`, ].filter(Boolean); // End messages intentionally combine game-provided results with shared ledger // awards. That keeps the bot useful for both end-scored games and games that // score during play while still avoiding game-specific chat code. sendBarcodeGameChat(`${title} ended. ${details.join(' ') || 'Results are now showing.'}`); } function getGameDefinition(gameId) { return GAMES_BY_ID[String(gameId || '')] || null; } function normalizeRgbChannel(value) { if (!Number.isFinite(value)) return null; return Math.max(0, Math.min(255, Math.round(value))); } function getGameThemeColor(definition) { const raw = definition?.themeColor; const r = normalizeRgbChannel(raw?.r); const g = normalizeRgbChannel(raw?.g); const b = normalizeRgbChannel(raw?.b); // Games own their visual identity, but the socket payload should always be a // small safe RGB object. Invalid or missing values fall back to neutral text // colors in the browser instead of leaking arbitrary styling data into React. if (r === null || g === null || b === null) return null; return { r, g, b }; } function getKnownObjects() { try { const snapshot = getRegistrySnapshot(); const codes = snapshot?.registry?.codes || {}; return Object.entries(codes) .filter(([, entry]) => entry?.type === 'object') .map(([code, entry]) => ({ code, entityId: entry.entityId, label: entry.label, })); } catch (err) { logger.warn('Failed to read barcode registry for game object list', { error: err.message }); return []; } } function normalizePlayerKey(identity = {}, socketId = '', roverId = '') { if (identity.userId) return `identity:${identity.userId}`; if (socketId) return `socket:${socketId}`; if (roverId) return `rover:${roverId}`; return null; } function normalizeIdentityPlayerKey(identity = {}) { // Permanent scoring is identity-only. Socket and rover IDs are useful runtime // evidence, but they are unstable and should not create leaderboard entries. return identity.userId ? `identity:${identity.userId}` : null; } function resolveRoverParticipant(roverId) { const normalizedRoverId = String(roverId || '').trim(); if (!normalizedRoverId) return null; const activeDrivers = getActiveDrivers(); const socketId = activeDrivers?.[normalizedRoverId] || null; const socket = socketId ? io.sockets.sockets.get(socketId) : null; const identity = socket ? getIdentitySummary(socket) : {}; const playerKey = normalizeIdentityPlayerKey(identity); return { // participantKey is the runtime round key. It can fall back to the rover ID // so the UI can show that a physical rover joined even if the driver has no // verified identity yet. playerKey stays identity-only because persistent // scoring should not create separate leaderboard rows for sockets or rovers. participantKey: playerKey || `rover:${normalizedRoverId}`, playerKey, roverId: normalizedRoverId, socketId, userId: identity.userId || null, cookieUserId: identity.cookieUserId || null, nickname: identity.nickname || normalizedRoverId, }; } function pruneRecentRoverSightings(draft, now) { const sightings = draft.recentRoverSightings || {}; Object.entries(sightings).forEach(([roverId, sighting]) => { if (!Number.isFinite(sighting?.scannedAt) || now - sighting.scannedAt > ROVER_ATTRIBUTION_WINDOW_MS) { delete sightings[roverId]; } }); draft.recentRoverSightings = sightings; } function recordRoverSighting(draft, scan, now) { if (!scan?.known || scan.type !== 'rover' || !scan.entityId) return null; const participant = resolveRoverParticipant(scan.entityId); if (!participant?.participantKey) return null; draft.recentRoverSightings = { ...(draft.recentRoverSightings || {}), [participant.roverId]: { ...participant, scannedAt: now, }, }; return participant; } function recordRoundParticipant(draft, participant, now) { if (!participant?.participantKey) return null; const previous = draft.roundParticipants?.[participant.participantKey] || {}; draft.roundParticipants = { ...(draft.roundParticipants || {}), [participant.participantKey]: { participantKey: participant.participantKey, playerKey: participant.playerKey || previous.playerKey || null, roverId: participant.roverId || previous.roverId || null, socketId: participant.socketId || previous.socketId || null, userId: participant.userId || previous.userId || null, cookieUserId: participant.cookieUserId || previous.cookieUserId || null, nickname: participant.nickname || previous.nickname || participant.roverId || 'unknown player', joinedAt: Number.isFinite(previous.joinedAt) ? previous.joinedAt : now, lastSeenAt: now, scanCount: (Number.isFinite(previous.scanCount) ? previous.scanCount : 0) + 1, }, }; return draft.roundParticipants[participant.participantKey]; } function getRoundParticipants(draft) { return Object.values(draft.roundParticipants || {}) .filter((participant) => participant?.participantKey) .sort((a, b) => (a.joinedAt || 0) - (b.joinedAt || 0)) .map((participant) => ({ participantKey: participant.participantKey, playerKey: participant.playerKey || null, roverId: participant.roverId || null, socketId: participant.socketId || null, userId: participant.userId || null, cookieUserId: participant.cookieUserId || null, nickname: participant.nickname || participant.roverId || 'unknown player', joinedAt: Number.isFinite(participant.joinedAt) ? participant.joinedAt : null, lastSeenAt: Number.isFinite(participant.lastSeenAt) ? participant.lastSeenAt : null, scanCount: Number.isFinite(participant.scanCount) ? participant.scanCount : 0, })); } function getProximityParticipants(draft, now) { pruneRecentRoverSightings(draft, now); return Object.values(draft.recentRoverSightings || {}) .filter((sighting) => sighting?.participantKey && now - sighting.scannedAt <= ROVER_ATTRIBUTION_WINDOW_MS) .map((sighting) => ({ participantKey: sighting.participantKey, playerKey: sighting.playerKey, roverId: sighting.roverId, socketId: sighting.socketId || null, userId: sighting.userId || null, cookieUserId: sighting.cookieUserId || null, nickname: sighting.nickname || sighting.roverId, scannedAt: sighting.scannedAt, })); } function incrementCounter(bucket, key, scan, now) { if (!key) return; const previous = bucket[key] || {}; bucket[key] = { code: scan.code || previous.code || null, entityId: scan.entityId || previous.entityId || key, label: scan.label || previous.label || key, type: scan.type || previous.type || null, count: (Number.isFinite(previous.count) ? previous.count : 0) + 1, lastScannedAt: now, }; } function updateGlobalCounters(draft, scan, now) { if (!scan?.known) return; const counters = draft.globalCounters || {}; counters.codes = counters.codes || {}; counters.objects = counters.objects || {}; counters.rovers = counters.rovers || {}; // Global counters intentionally ignore unknown scans. They are meant to be a // useful room/object popularity board, while game-specific rules can still // choose to count unknown codes when that makes sense. incrementCounter(counters.codes, scan.code, scan, now); if (scan.type === 'object') { incrementCounter(counters.objects, scan.entityId, scan, now); } else if (scan.type === 'rover') { incrementCounter(counters.rovers, scan.entityId, scan, now); } draft.globalCounters = counters; } function addRecentEvent(draft, event) { draft.recentEvents = [ { ...event, at: Date.now(), }, ...(Array.isArray(draft.recentEvents) ? draft.recentEvents : []), ].slice(0, RECENT_EVENT_LIMIT); } function recordPlayerParticipation(draft, gameId, participants, now) { if (!gameId || !Array.isArray(participants) || !participants.length) return; draft.players = draft.players || {}; participants.forEach((participant) => { if (!participant?.playerKey || !String(participant.playerKey).startsWith('identity:')) return; const previous = draft.players[participant.playerKey] || {}; const previousGames = previous.games || {}; const previousGame = previousGames[gameId] || {}; draft.players[participant.playerKey] = { playerKey: participant.playerKey, userId: participant.userId || previous.userId || null, cookieUserId: participant.cookieUserId || previous.cookieUserId || null, nickname: participant.nickname || previous.nickname || null, lastRoverId: participant.roverId || previous.lastRoverId || null, totalPoints: Number.isFinite(previous.totalPoints) ? previous.totalPoints : 0, lastSeenAt: now, games: { ...previousGames, [gameId]: { gameId, scanCount: (Number.isFinite(previousGame.scanCount) ? previousGame.scanCount : 0) + 1, lastPlayedAt: now, }, }, }; }); } function userIdFromPlayerKey(playerKey) { const value = String(playerKey || '').trim(); return value.startsWith('identity:usr_') ? value.slice('identity:'.length) : null; } function applyPointAwards(draft, gameId, awards = [], now) { if (!gameId || !Array.isArray(awards) || !awards.length) return; draft.players = draft.players || {}; awards.forEach((award) => { const playerKey = award?.playerKey; const points = Number.isFinite(award?.points) ? Math.max(0, Math.floor(award.points)) : 0; if (!playerKey || !String(playerKey).startsWith('identity:') || !points) return; const previous = draft.players[playerKey] || {}; const previousGames = previous.games || {}; const previousGame = previousGames[gameId] || {}; // Global points are applied only here so individual game files cannot drift // into different player-ledger formats. A game simply returns awards, and // the shared service records identity, total points, and per-game totals in // one persistent place. draft.players[playerKey] = { playerKey, userId: award.userId || previous.userId || userIdFromPlayerKey(playerKey), cookieUserId: award.cookieUserId || previous.cookieUserId || null, nickname: award.nickname || previous.nickname || null, lastRoverId: award.roverId || previous.lastRoverId || null, totalPoints: (Number.isFinite(previous.totalPoints) ? previous.totalPoints : 0) + points, lastSeenAt: now, games: { ...previousGames, [gameId]: { ...previousGame, gameId, points: (Number.isFinite(previousGame.points) ? previousGame.points : 0) + points, awards: (Number.isFinite(previousGame.awards) ? previousGame.awards : 0) + 1, lastAwardAt: now, lastReason: award.reason || null, }, }, }; const userId = draft.players[playerKey].userId; if (userId) { /* The game store still owns current game state, but long-lived per-person scoring is mirrored into identityService so future features can read one canonical user object instead of scraping barcode-games.json. */ updateFeatureState(userId, 'barcodeGames', (current) => { const currentGames = current?.games || {}; const currentGame = currentGames[gameId] || {}; return { ...(current || {}), playerKeys: Array.from(new Set([...(current?.playerKeys || []), playerKey])), nickname: draft.players[playerKey].nickname || current?.nickname || null, lastRoverId: draft.players[playerKey].lastRoverId || current?.lastRoverId || null, totalPoints: (Number.isFinite(current?.totalPoints) ? current.totalPoints : 0) + points, lastSeenAt: now, games: { ...currentGames, [gameId]: { ...currentGame, gameId, points: (Number.isFinite(currentGame.points) ? currentGame.points : 0) + points, awards: (Number.isFinite(currentGame.awards) ? currentGame.awards : 0) + 1, lastAwardAt: now, lastReason: award.reason || null, }, }, }; }, {}); } addRecentEvent(draft, { kind: 'pointsAwarded', gameId, playerKey, nickname: award.nickname || previous.nickname || null, points, reason: award.reason || null, }); }); } function ensureGameState(draft, gameId) { const definition = getGameDefinition(gameId); if (!definition) return null; draft.games = draft.games || {}; draft.games[gameId] = definition.normalizeState ? definition.normalizeState(draft.games[gameId]) : draft.games[gameId] || definition.createInitialState(); return draft.games[gameId]; } function buildGameContext(draft, extras = {}) { return { now: extras.now || Date.now(), objects: getKnownObjects(), participants: extras.participants || getRoundParticipants(draft), }; } function startGame(draft, gameId, now) { const definition = getGameDefinition(gameId); if (!definition) return false; const currentState = ensureGameState(draft, gameId); const nextState = definition.start ? definition.start(currentState, buildGameContext(draft, { now })) : definition.activate ? definition.activate(currentState, buildGameContext(draft, { now })) : currentState; draft.games[gameId] = nextState; draft.phase = 'running'; draft.runningGameId = gameId; draft.selectedGameId = gameId; draft.activeGameId = gameId; draft.voteEndsAt = null; draft.joinEndsAt = null; draft.startsAt = null; draft.resultsUntil = null; draft.resultGameId = null; draft.resultDisplay = null; addRecentEvent(draft, { kind: 'gameStarted', gameId, title: definition.title, }); sendGameStartChat(definition, getRoundParticipants(draft)); return true; } function normalizeGameResult(result, fallbackState) { if (!result || typeof result !== 'object' || Array.isArray(result)) { return { state: fallbackState, awards: [] }; } if (Object.prototype.hasOwnProperty.call(result, 'state')) { return { state: result.state, awards: Array.isArray(result.awards) ? result.awards : [], done: Boolean(result.done), display: result.display && typeof result.display === 'object' ? result.display : null, }; } return { state: result, awards: [], done: false, display: null }; } function countVotes(votes = {}) { const counts = {}; Object.values(votes || {}).forEach((vote) => { if (!getGameDefinition(vote?.gameId)) return; counts[vote.gameId] = (counts[vote.gameId] || 0) + 1; }); return counts; } function chooseVoteWinner(draft) { const counts = countVotes(draft.votes); const entries = Object.entries(counts).sort((a, b) => b[1] - a[1]); if (!entries.length) return null; const [topGameId, topCount] = entries[0]; const selectedCount = draft.selectedGameId ? counts[draft.selectedGameId] || 0 : 0; // Ties keep the currently selected pending game so a single equalizing vote // does not make the room display flicker during the voting window. if (draft.selectedGameId && selectedCount === topCount) return draft.selectedGameId; return topGameId; } function getVoterKey(socket) { const identity = getIdentitySummary(socket); return normalizePlayerKey(identity, socket?.id || '', '') || `socket:${socket?.id || 'unknown'}`; } function setVote(socket, gameId) { const definition = getGameDefinition(gameId); if (!definition) { return { error: 'unknown barcode game' }; } const now = Date.now(); const voterKey = getVoterKey(socket); const identity = getIdentitySummary(socket); const current = loadStore(); if (current.phase === 'joining' || current.phase === 'starting' || current.phase === 'running') { return { error: 'a barcode game is already starting or running' }; } withGameStore((draft) => { draft.votes = draft.votes || {}; draft.votes[voterKey] = { gameId: definition.id, voterKey, socketId: socket.id, nickname: identity.nickname || null, votedAt: now, }; const winner = chooseVoteWinner(draft) || definition.id; draft.selectedGameId = winner; if (draft.phase === 'idle' || draft.phase === 'results') { draft.phase = 'voting'; draft.voteEndsAt = now + VOTING_WINDOW_MS; draft.joinEndsAt = null; draft.startsAt = null; draft.runningGameId = null; draft.activeGameId = null; draft.resultsUntil = null; draft.resultDisplay = null; draft.roundParticipants = {}; sendBarcodeGameChat(`Voting has started. Current pick: ${definition.title}. Vote in the Activities tab.`); } else if (draft.phase === 'voting') { draft.voteEndsAt = Math.max(draft.voteEndsAt || 0, now + VOTING_WINDOW_MS); } }); broadcastState(); return { success: true, state: buildStatePayload(socket) }; } function settleActiveGameIfNeeded() { const store = loadStore(); const now = Date.now(); const phase = store.phase || 'idle'; if (phase === 'voting' && store.voteEndsAt && now >= store.voteEndsAt) { const winner = chooseVoteWinner(store) || store.selectedGameId; const winnerDefinition = getGameDefinition(winner); if (!winnerDefinition) return false; withGameStore((draft) => { draft.selectedGameId = winner; draft.phase = 'joining'; draft.joinEndsAt = now + JOIN_WINDOW_MS; draft.startsAt = null; draft.voteEndsAt = null; draft.roundParticipants = {}; addRecentEvent(draft, { kind: 'gameJoining', gameId: winner, title: winnerDefinition.title, }); sendBarcodeGameChat(`Voting ended. ${winnerDefinition.title} was selected with ${formatVoteSummary(draft.votes, winner)}. Scan a rover to join.`); }); return true; } if (phase === 'joining' && store.joinEndsAt && now >= store.joinEndsAt) { withGameStore((draft) => { // Joining exists so a real rover has to physically opt into a round. If // nobody scans a rover in time, the selected game is discarded and the // system returns to idle instead of starting an empty round that cannot // award points to anyone. draft.phase = 'idle'; draft.selectedGameId = null; draft.runningGameId = null; draft.activeGameId = null; draft.voteEndsAt = null; draft.joinEndsAt = null; draft.startsAt = null; draft.resultsUntil = null; draft.resultGameId = null; draft.resultDisplay = null; draft.votes = {}; draft.roundParticipants = {}; sendBarcodeGameChat('No rover joined in time. The selected barcode game was cancelled.'); }); return true; } if (phase === 'starting' && store.startsAt && now >= store.startsAt) { const gameId = store.selectedGameId; if (!getGameDefinition(gameId)) return false; withGameStore((draft) => { startGame(draft, gameId, now); }); return true; } if (phase === 'results' && store.resultsUntil && now >= store.resultsUntil) { withGameStore((draft) => { draft.phase = 'idle'; draft.selectedGameId = null; draft.runningGameId = null; draft.activeGameId = null; draft.voteEndsAt = null; draft.joinEndsAt = null; draft.startsAt = null; draft.resultsUntil = null; draft.resultGameId = null; draft.resultDisplay = null; draft.votes = {}; draft.roundParticipants = {}; }); return true; } const activeGameId = store.phase === 'running' ? store.runningGameId : null; const definition = getGameDefinition(activeGameId); const currentState = activeGameId ? store.games?.[activeGameId] : null; if (!definition?.tick || !currentState) return false; const normalizedState = ensureReadonlyGameState(store, activeGameId); const gameResult = definition.tick(normalizedState, buildGameContext(store, { now })); const { state: nextState, awards, done, display } = normalizeGameResult(gameResult, normalizedState); if (JSON.stringify(nextState) === JSON.stringify(normalizedState) && !done) return false; withGameStore((draft) => { draft.games[activeGameId] = nextState; applyPointAwards(draft, activeGameId, awards, now); if (done) { const publicState = definition.getPublicState ? definition.getPublicState(nextState, buildGameContext(draft, { now })) : null; const participants = getRoundParticipants(draft); draft.phase = 'results'; draft.resultGameId = activeGameId; draft.resultDisplay = display || publicState?.display || null; draft.resultsUntil = now + RESULTS_WINDOW_MS; draft.runningGameId = null; draft.activeGameId = null; draft.startsAt = null; draft.voteEndsAt = null; draft.joinEndsAt = null; draft.votes = {}; sendGameEndChat(definition, { display: draft.resultDisplay, publicState, awards, participants, }); } }); return true; } function handleScan(scan) { if (!enabled) return; const now = Number.isFinite(scan?.scannedAt) ? scan.scannedAt : Date.now(); withGameStore((draft) => { updateGlobalCounters(draft, scan, now); const scannedRoverParticipant = recordRoverSighting(draft, scan, now); if (draft.phase === 'joining' && scannedRoverParticipant) { const selectedDefinition = getGameDefinition(draft.selectedGameId); const joinedParticipant = recordRoundParticipant(draft, scannedRoverParticipant, now); if (selectedDefinition && joinedParticipant) { // The first rover scan is the physical confirmation that a real player // is at the scanner and wants this voted game to start. The short // starting phase gives the room and chat display a predictable countdown // before game rules begin consuming object scans. draft.phase = 'starting'; draft.startsAt = now + STARTING_WINDOW_MS; draft.joinEndsAt = null; addRecentEvent(draft, { kind: 'gameStarting', gameId: selectedDefinition.id, title: selectedDefinition.title, participant: joinedParticipant.nickname, }); } } else if ((draft.phase === 'starting' || draft.phase === 'running') && scannedRoverParticipant) { // Rovers scanned during the countdown or action are counted as active participants too. // This supports the physical reality of the station: a rover may be seen // just before or during useful object scans, and that should be enough to // associate the driver with the current round. recordRoundParticipant(draft, scannedRoverParticipant, now); } const proximityParticipants = getProximityParticipants(draft, now); const participants = getRoundParticipants(draft); const activeGameId = draft.phase === 'running' ? draft.runningGameId : null; const definition = getGameDefinition(activeGameId); if (definition) { const currentState = ensureGameState(draft, activeGameId); const gameResult = definition.handleScan ? definition.handleScan(currentState, scan, buildGameContext(draft, { now, participants })) : currentState; const { state: nextState, awards, done, display } = normalizeGameResult(gameResult, currentState); draft.games[activeGameId] = nextState; recordPlayerParticipation(draft, activeGameId, participants, now); applyPointAwards(draft, activeGameId, awards, now); if (done) { const publicState = definition.getPublicState ? definition.getPublicState(nextState, buildGameContext(draft, { now })) : null; const finalParticipants = getRoundParticipants(draft); draft.phase = 'results'; draft.resultGameId = activeGameId; draft.resultDisplay = display || publicState?.display || null; draft.resultsUntil = now + RESULTS_WINDOW_MS; draft.runningGameId = null; draft.activeGameId = null; draft.startsAt = null; draft.voteEndsAt = null; draft.joinEndsAt = null; draft.votes = {}; sendGameEndChat(definition, { display: draft.resultDisplay, publicState, awards, participants: finalParticipants, }); } } addRecentEvent(draft, { kind: 'scan', code: scan?.code || '', label: scan?.label || scan?.code || 'unknown', known: Boolean(scan?.known), type: scan?.type || null, participants: (participants.length ? participants : proximityParticipants) .map((participant) => participant.nickname || participant.roverId) .filter(Boolean), }); }); broadcastState(); } function topCounters(bucket = {}, limit = 5) { return Object.values(bucket || {}) .sort((a, b) => (b.count || 0) - (a.count || 0)) .slice(0, limit); } function getPlayerForSocket(store, socket) { if (!socket) return null; const identity = getIdentitySummary(socket); const playerKey = normalizeIdentityPlayerKey(identity); const featurePlayer = identity.userId ? getFeatureState(identity.userId, 'barcodeGames', null) : null; const player = playerKey ? store.players?.[playerKey] || null : null; if (!player && !featurePlayer) { return { playerKey, nickname: identity.nickname || null, totalPoints: 0, rank: null, games: {}, }; } const rankedPlayers = listBarcodePlayers(store.players) .sort((a, b) => (b.totalPoints || 0) - (a.totalPoints || 0)); const effectivePlayer = { ...(player || {}), ...(featurePlayer || {}), playerKey: player?.playerKey || playerKey || featurePlayer?.playerKeys?.[0], nickname: player?.nickname || featurePlayer?.nickname || identity.nickname || null, totalPoints: Math.max(Number(player?.totalPoints || 0), Number(featurePlayer?.totalPoints || 0)), games: { ...(featurePlayer?.games || {}), ...(player?.games || {}), }, }; const rank = rankedPlayers.findIndex((entry) => entry.playerKey === effectivePlayer.playerKey) + 1; return { playerKey: effectivePlayer.playerKey, nickname: effectivePlayer.nickname, totalPoints: effectivePlayer.totalPoints || 0, rank: rank > 0 ? rank : null, games: effectivePlayer.games || {}, }; } function buildStatePayload(socket = null) { settleActiveGameIfNeeded(); const store = loadStore(); const now = Date.now(); const voteCounts = countVotes(store.votes); const selectedDefinition = getGameDefinition(store.selectedGameId); const runningDefinition = getGameDefinition(store.runningGameId); const participants = getRoundParticipants(store); const context = buildGameContext(store, { now, participants }); const runningGame = runningDefinition ? runningDefinition.getPublicState(ensureReadonlyGameState(store, runningDefinition.id), context) : null; const activeGame = buildLifecycleGameState(store, { now, selectedDefinition, runningDefinition, runningGame, voteCounts, }); const leaderboard = topPlayers(store.players); return { phase: store.phase, selectedGameId: store.selectedGameId, runningGameId: store.runningGameId, activeGameId: store.runningGameId, participants, games: GAME_DEFINITIONS.map((game) => ({ id: game.id, title: game.title, description: game.description, themeColor: getGameThemeColor(game), voteCount: voteCounts[game.id] || 0, active: game.id === store.runningGameId, selected: game.id === store.selectedGameId, actionLabel: store.phase === 'idle' || store.phase === 'results' ? 'Vote' : game.id === store.selectedGameId ? 'Selected' : 'Vote', })), activeGame, leaderboard, ownPlayer: getPlayerForSocket(store, socket), counters: { objects: topCounters(store.globalCounters?.objects), rovers: topCounters(store.globalCounters?.rovers), codes: topCounters(store.globalCounters?.codes), }, recentEvents: Array.isArray(store.recentEvents) ? store.recentEvents.slice(0, 8) : [], }; } function buildLifecycleGameState(store, { now, selectedDefinition, runningDefinition, runningGame, voteCounts }) { const participants = getRoundParticipants(store); if (store.phase === 'running' && runningGame) { return { ...runningGame, themeColor: getGameThemeColor(runningDefinition), participants, }; } if (store.phase === 'results') { const resultDefinition = getGameDefinition(store.resultGameId); return { id: store.resultGameId, title: resultDefinition?.title || 'Results', themeColor: getGameThemeColor(resultDefinition), status: 'results', participants, display: { title: 'Results', primary: store.resultDisplay?.primary || 'Round complete', secondary: store.resultDisplay?.secondary || 'Vote to start another game', timer: store.resultsUntil ? { label: 'Results clear in', endsAt: store.resultsUntil } : null, stats: store.resultDisplay?.stats || [], sections: store.resultDisplay?.sections || [], results: store.resultDisplay?.results || [], }, }; } if (store.phase === 'starting') { return { id: store.selectedGameId, title: selectedDefinition?.title || 'Starting', themeColor: getGameThemeColor(selectedDefinition), status: 'starting', participants, display: { title: selectedDefinition?.title || 'Starting', primary: selectedDefinition ? `${selectedDefinition.title} starts soon` : 'Game starts soon', secondary: 'Get ready', timer: store.startsAt ? { label: 'Starts in', endsAt: store.startsAt } : null, stats: [], sections: [ { title: 'Players', // Joining and starting are shared lifecycle states, so they expose // their own display sections here instead of asking each game to // explain the same startup flow. items: participants.length ? participants.map((participant) => getParticipantName(participant)).filter(Boolean) : ['waiting for counted rovers'], }, ], results: [], }, }; } if (store.phase === 'joining') { const selectedTitle = selectedDefinition?.title || 'the selected game'; return { id: store.selectedGameId, title: selectedDefinition?.title || 'Join game', themeColor: getGameThemeColor(selectedDefinition), status: 'joining', participants, display: { title: selectedDefinition?.title || 'Join game', primary: 'Scan your rover to start', secondary: `${selectedTitle} needs at least one rover`, timer: store.joinEndsAt ? { label: 'Join by', endsAt: store.joinEndsAt } : null, stats: [], sections: [ { title: 'How to join', items: ['scan your rover barcode at the station'], }, ], results: [], }, }; } if (store.phase === 'voting') { const selectedTitle = selectedDefinition?.title || 'a barcode game'; return { id: store.selectedGameId, title: 'Voting', themeColor: getGameThemeColor(selectedDefinition), status: 'voting', participants, display: { title: 'Voting', primary: `Voting for ${selectedTitle}`, secondary: 'Most votes starts the next game', timer: store.voteEndsAt ? { label: 'Voting ends in', endsAt: store.voteEndsAt } : null, stats: GAME_DEFINITIONS.map((game) => ({ label: game.title, value: voteCounts[game.id] || 0, })), sections: [], results: [], }, }; } return { id: null, title: 'Barcode games', themeColor: null, status: 'idle', participants, display: { title: 'Barcode games', primary: 'Choose a game', secondary: 'Vote to start the next round', timer: null, stats: [], sections: [], results: [], }, }; } function listBarcodePlayers(players = {}) { const byKey = new Map(); Object.values(players || {}) .filter((player) => String(player?.playerKey || '').startsWith('identity:') && Number.isFinite(player?.totalPoints) && player.totalPoints > 0) .forEach((player) => byKey.set(player.playerKey, player)); listFeatureStates('barcodeGames').forEach(({ userId, state }) => { const playerKey = `identity:${userId}`; const previous = byKey.get(playerKey) || {}; byKey.set(playerKey, { ...previous, ...state, playerKey, userId, totalPoints: Math.max(Number(previous.totalPoints || 0), Number(state?.totalPoints || 0)), nickname: previous.nickname || state?.nickname || null, lastRoverId: previous.lastRoverId || state?.lastRoverId || null, }); }); return Array.from(byKey.values()).filter((player) => Number.isFinite(player?.totalPoints) && player.totalPoints > 0); } function topPlayers(players = {}, limit = 6) { return listBarcodePlayers(players) .sort((a, b) => (b.totalPoints || 0) - (a.totalPoints || 0)) .slice(0, limit) .map((player) => ({ playerKey: player.playerKey, nickname: player.nickname || player.lastRoverId || 'unknown player', totalPoints: player.totalPoints || 0, lastRoverId: player.lastRoverId || null, })); } function ensureReadonlyGameState(store, gameId) { const definition = getGameDefinition(gameId); if (!definition) return null; return definition.normalizeState ? definition.normalizeState(store.games?.[gameId]) : store.games?.[gameId] || null; } function broadcastState() { const room = io.sockets.adapter.rooms.get(GAME_SOCKET_ROOM); if (!room) return; room.forEach((socketId) => { const socket = io.sockets.sockets.get(socketId); if (socket) { socket.emit('barcodeGame:state', buildStatePayload(socket)); } }); } io.on('connection', (socket) => { socket.on('barcodeGame:subscribe', (_payload = {}, cb = () => {}) => { if (!enabled) return cb({ error: 'barcode games disabled' }); socket.join(GAME_SOCKET_ROOM); const state = buildStatePayload(socket); socket.emit('barcodeGame:state', state); cb({ success: true, state }); }); socket.on('barcodeGame:vote', ({ gameId } = {}, cb = () => {}) => { if (!enabled) return cb({ error: 'barcode games disabled' }); try { cb(setVote(socket, gameId)); } catch (err) { logger.warn('Barcode game vote failed', { error: err.message, gameId }); cb({ error: err.message || 'barcode game vote failed' }); } }); }); subscribe('barcode.scanned', (event) => { try { handleScan(event.payload); } catch (err) { // Scanner input should never be able to take down the server. Game failures // are logged and skipped so the scanner page can keep resolving barcodes. logger.warn('Barcode game scan handling failed', { error: err.message }); } }); if (!enabled) { logger.info('Barcode games disabled by config'); } registerConfigurationHandler('barcodeGames', (barcodeGamesConfig = {}) => { applyBarcodeGameConfig(barcodeGamesConfig); broadcastState(); }); module.exports = { buildStatePayload, handleScan, setVote, }; setInterval(() => { if (enabled && settleActiveGameIfNeeded()) { broadcastState(); } }, GAME_TICK_MS).unref?.();