Matchmaking — pair players up
Build the lobby that pairs two strangers into a game
⏱ Est. ~7 min
01 · Read
Matchmaking is what turns a single-player game into a multiplayer experience. The concept is simple: maintain a waiting list. When two players are waiting, pair them up, create a game room, and start the match.
The tricky part is the edge cases: what happens if a player disconnects while waiting? What if they disconnect mid-game? What if both players want to play again? A good matchmaking system handles all of these gracefully.
💡 Picture thisThink of a restaurant host managing a waitlist. When a table for two opens up, they seat the next two people on the list. If someone leaves the waitlist, they get removed. If someone leaves mid-meal, the host doesn't keep saving their spot.
Key points
- Matchmaking maintains a queue of waiting players
- When two players are in the queue, pair them into a room
- Each room has its own TicTacToeGame instance
- Disconnect handling is critical — both in the queue and mid-game
02 · Prompt template
Ask Claude to build the matchmaking module. Describe the data structures and pairing logic explicitly.
Help me build a matchmaking.js module for my tic-tac-toe game. Requirements: (1) Maintain a waiting queue (an array of sockets). (2) Export an addToQueue(socket, io) function: if someone is already waiting, pair the two — generate a unique room ID, create a new TicTacToeGame instance, randomly assign X and O, have both sockets join that room, and emit 'game-start' to both with their symbol and the room ID. If no one is waiting, add this socket to the queue and emit 'waiting' to it. (3) Export a removeFromQueue(socket) function that removes a disconnected socket from the waiting queue. (4) Use a Map to track active games (roomId -> { game, players }), and another Map to track which room each socket is in (socketId -> roomId). (5) Export a handleDisconnect(socket, io) function: if the socket is in the queue, remove it; if it's in an active game, emit 'opponent-left' to the opponent and clean up the room. Import the TicTacToeGame class from ./game.03 · Code example
Your matchmaking module uses three data structures. Understand what each stores and why it exists.
Three data structures
// Players waiting for a match
const waitingQueue = [];
// Active game rooms: roomId -> { game, players: { X: socket, O: socket } }
const activeGames = new Map();
// Which room each player is in: socket.id -> roomId
const playerRooms = new Map();
waitingQueue holds sockets that clicked 'Find Game' but haven't been paired yet. activeGames maps each room to its game state and player sockets — that's how the server knows which game a move belongs to. playerRooms is a reverse lookup — given a socket ID (from a disconnect event), find which room they're in so we can notify the opponent.
04 · Prompt template
Now wire matchmaking into your server. Ask Claude to update server.js to use the new module.
Update server.js to use the matchmaking module. In the 'connection' event, listen for 'find-game' from the client and call addToQueue. In the 'disconnect' event, call handleDisconnect. Also listen for 'make-move' — when a player submits a move, find their room from playerRooms, find the corresponding game from activeGames, call game.makeMove(index), and if it's valid, emit 'move-made' to the room with the move details. If the game ended, emit 'game-over' to the room with the result.
05 · Read
Stop and read what Claude produced. This is the most important habit you can build: don't just run it — read it first.
Trace through what happens when:
1. The first player connects and clicks Find Game 2. The second player does the same 3. They get paired into a room 4. The first player makes a move
Does the code match the plan from Lesson 2? Does the server validate moves before broadcasting? Does disconnect handling clean up correctly?
If anything doesn't match your plan, ask Claude to fix it. You're the architect — Claude is the builder.
Key points
- Read before you run — always
- Mentally trace through scenarios
- Compare the code against your plan
- If it doesn't match, ask Claude to fix it
06 · Quiz
A player disconnects while waiting in the matchmaking queue. What should happen?
- Nothing — they'll reconnect automatically
- They should be removed from the queue so they don't get paired with a new player who joins
- The server should crash and restart
- Their spot should be saved for 5 minutes
07 · Fill in the blank
When two players are in the queue, the matchmaking system creates a game _____ and assigns each player a symbol (X or O).
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.