Private Matches, Join Codes, and Game Modes

Game Modes Are Yours to Invent

A game mode is any string your game sends with a join call: 1V1, RANKED, BLITZ, TICTACTOE, DRAFT_SEASON3. The server never interprets the string, it simply groups players who sent the same one. That single rule turns the mode field into a general matchmaking tool, because anything you encode into the string becomes a matchmaking criterion.

Want ranked and casual pools? Two mode strings. Separate queues per game in a multi-game arcade? One mode string per game. A special weekend event? Invent EVENT_JULY and retire it Monday. Since the same server happily runs every mode at once, one install serves your whole catalog, and adding a new game or queue never touches server code.

Queueing for Several Modes at Once

A player can join with several modes at once by joining them with an ampersand, like "1V1&2V2", which means "I will take whichever fills first." Players match when they share at least one mode. This is the tool for keeping wait times short in a young player base: let casual players also accept ranked matches, or let a quick-match button queue for every active mode at once. The first compatible group wins, and everyone learns the agreed mode from the matched object, so your client always knows which rules to load.

Party Size Is Part of the Match

The numPlayers field says how many players this match should have, from 2 up to the configured maximum of 10. Players who want a duel never collide with players who want a 4 player free-for-all, because party size is part of the compatibility check, same mode and same size. The moment enough compatible players are waiting, the match forms, and everyone receives the full player list at once.

Slots are assigned in a predictable order: players who were waiting keep their queue order, and the player whose join completed the match takes the last slot. The matched object tells each client its own yourPlayerNum, and the common convention of slot 0 moving first gives every turn-based game a ready-made turn order.

Private Lobbies and Join Codes

Playing with friends skips the queue entirely. One player joins with private: "1" and gets back a short join code, six characters, easy to read out loud over voice chat or paste into a group text:

{"status": "waiting", "numPlayers": 4, "joinCode": "K7PMQ4", "playersWaiting": 1}

Friends join by sending that code in the joinCode field, and the match starts the moment the lobby reaches the size its creator chose. The creator's settings win, the host decides the mode and the player count, and friends only need the code. There are no accounts on the server and nothing for players to sign up for, the code is the whole invitation.

Generated codes avoid look-alike characters so they survive being read aloud. Your game can also supply its own code with private: "1" plus a joinCode of your choosing, which is how you control the format, brand the codes, or mint them from your own systems.

Carrying Loadouts Into the Match

Every join call can carry a username and three opaque info strings, playerInfo, talentInfo, and charInfo, and every player receives everyone's values in the matched object. This is how decks, characters, skins, and ranks travel into a match without a separate exchange step: pack whatever your game needs into those strings, JSON included, and each client renders the opponents from day one data. The timeLimit field works the same way at the match level, one string the host sets and every client reads.

Lifetimes and the Self-Cleaning Queue

A waiting entry lives for queueSeconds, 120 by default, so a lobby that never fills or a player who closed the tab disappears on schedule. A live match stays alive as long as actions keep flowing and expires after matchSeconds of silence, 3600 by default. Both timers are config settings, so a party game with long setup phases or a fast arcade queue can each tune their own rhythm. The practical effect is a server with nothing to babysit: the admin area shows what is live right now, and everything stale removes itself.