01 Two ways to play together

The game knows three ways to play a grid, recorded in the mode field of each game: solo, shared and live. The last two look alike on screen, but not at all in the database.

Shared Live
Where you play on a single phone, side by side each on their own phone, wherever you are
When you invite once the grid is solved during the game
What your friend gets a copy of the solved game a seat in the common game
Score the one from the copied game the team's, the same for everyone
Real time none the others' moves arrive live

In both cases, each game keeps players_count, the number of people who played it (the "done by N"), and the same mode on all of the team's games.

02 The data model

It all fits in five PostgreSQL tables. Sharing and live use the same ones, but not the same links.

Guess game → row · col the cell station correct hint hint? points frozen author → player Game player · grid status · gave_up score restarts_count players_count done by N mode 1 · 2 · 3 shared_from → sharing team → live GridInvitation player game → sharing team → live status Team grid holder → the game players_count active TeamMember team → player game → joined_at left_at left? shared_from team team holder game
The five tables of multiplayer: sharing goes through shared_from, live through Team.
  • Game is one attempt by a player at a grid; their current game is the most recent one. It keeps its outcome (status, gave_up), its up-to-date score and its restarts, plus two fields for multiplayer: players_count, the "done by N", and mode (1 solo, 2 shared, 3 live), the same value on all of a team's games.
  • Guess is a move, always attached to a game. A right answer, an error and a hint are all Guess rows: correct says whether the station fits, hint whether it's a hint. points is frozen at the time of the move (rarity bonus included, −20 for an error or a hint), and the game's score is their sum, minus the restarts. author is only filled in if the move was played by someone other than the game's player: empty means it's them.
  • GridInvitation is an invitation to a friend, of one of two kinds: game for a share (the solved game to copy), team for live (the team to join). A database constraint requires exactly one of the two. status is pending, accepted or declined.
  • Team is a live team: its grid, holder, the game that carries the moves, and players_count, the number of members still there.
  • TeamMember is one stay of a player in a team, with the game they play in it, joined_at and left_at. A constraint only allows one ongoing stay per player and per team: coming back creates a new row.

Two links make all the difference. In sharing, Game.shared_from links each copy to the original game. In live, Game.team links the members' games to their team, and Team.holder designates the only one of them that carries the moves.

03 Sharing afterwards: a copy

You solved the grid with friends sitting next to you. You can then invite them, among the players you follow whose game on that grid isn't finished. Only your own solved game can be shared: not a copy you received, nor a game played live.

When a friend accepts, they receive an identical copy: same answers, same hints, same restarts, same score, same start and same end. The copy's shared_from field points to your game. Nothing is recounted: the copy adds no answer to the cell counters, and the rarity of each answer stays the one you got.

Game 101 · Alice status = won score = 640 players_count = 3 mode = shared shared_from = NULL 9 Guess, played here Game 205 · Bob status = won score = 640 players_count = 3 shared_from = 101 9 Guess, copied Game 206 · Chloé status = won score = 640 players_count = 3 shared_from = 101 9 Guess, copied shared_from GridInvitation game = 101 player = Bob accepted game = 101 player = Chloé accepted game = 101 player = David pending
A share: each friend who accepts receives their own copy, linked to the original by shared_from.

The copy becomes the friend's current game on the grid. If they had started on their own, that game stays, like a game from before a restart. Then players_count is updated on your game and on all its copies: with each new friend who accepts, everyone goes from "done by 2" to "done by 3".

04 Live: a single game for the whole team

In live, there's no copy during the game: the whole team writes into a single game, the one of whoever sent the invitations.

Team team key = HMAC(id) players_count = 2 lock for every move members TeamMember · one stay per row Alice current Bob current Chloé left at 12:10 holder Alice's game holder all the answers author = who played Bob's game pointer no answers written at the end Chloé's game no team her own copy of the answers played solo since
One team, a single written game: the holder's. The other members only have a pointer to it.
  • Team is the team's stable identity. Its row serves as a lock: every action (a move, a hint, a give-up, an arrival, a departure) starts with a SELECT … FOR UPDATE on it, so two moves of the team never run at the same time. players_count counts the active members.
  • The holder game (Team.holder) is the only one a move writes to: a Guess row, whose author field says who played it, and the score update.
  • The other members' pointer games have no answers: when the server loads a member's state, it follows the pointer to the holder. They're only written when the player arrives, then once at the end, in a single UPDATE: status, score, end time and team size.
  • TeamMember keeps one row per stay: Chloé, who left at 12:10, is still listed, with her departure time. Her game has lost its team and carries its own copy of the moves.

A move thus costs the same for two or for six: one insert and one update. And two teammates can never have different grids in the database.

05 Joining midway: merging

You can join a team when you've already started the grid on your own. Your progress is then merged with the team's, with a simple rule: we keep your right answers that the team is missing, and the worse of the two for errors and hints, never the sum.

Alice's team Bob, solo The team after Bob joins
Cells found 4 3, of which 1 already found by Alice 6
Errors 1 2 2
Hints 0 1, on a still-empty cell 1
Bob's game, solo Team's game (holder) ✓ A1 Odéon cell taken ✓ B2 Nation ✓ C1 Bastille ✗ error ✗ error already 1 ? hint C3 ✓ A1 Saint-Michel author = Alice ✓ A2 Opéra author = Alice ✓ A3 Cité author = Alice ✓ B1 Pigalle author = Alice ✗ error author = Alice ✓ B2 Nation author = Bob ✓ C1 Bastille author = Bob ✗ error author = Bob ? hint C3 author = Bob
The merge: four of Bob's moves are copied into the team's game, with him as author. His own game doesn't change.
  • One of Bob's right answers is copied if its cell and its station are still free in the team's game (a station can only be used once per grid). It keeps its points, earned when Bob played it, and Bob becomes its author.
  • For errors, we copy just enough for the team to have as many as Bob: here just one, which costs the team 20 points. Same for hints, only on a cell that's still empty.
  • Bob's game stays as it is, like a game from before a restart. Nothing is recounted in the cell statistics.

Why the worse and not the sum? Adding up the errors could make a team lose at the very moment someone joins it. Keeping only the team's would, conversely, let you wipe out your errors by joining friends.

06 How the points are split

Points aren't shared out among the members: they belong to the game, and each member has the team's full score.

  • An answer earns the same whoever plays it: 15 points, plus the rarity bonus of the station in its cell. These points are fixed at the time of the answer and never change, even when the answer is copied.
  • Penalties are shared: an error or a hint costs the whole team 20 points, and the 3 attempts and the 3 hints are the game's, not each person's. A restart, after a game lost on errors, sends the whole team off to new games, with the 50-point penalty for everyone.
  • The score follows the formula of a solo game: the sum of the answers' points, minus 50 per restart, brought back between 0 and 900.
  • Each cell keeps its author. That's what makes it possible to show who found what, and how many cells each member found, without ever splitting the score.

A shared game follows the same logic: the copy has the score of the original game, no more and no less.

On the daily leaderboard, each member appears with the team's score. The members of one team are grouped on a single row, under the nickname of whoever started the game, and each keeps their rank. On equal scores, a multiplayer game ranks after a perfect solo game (no errors or restarts) and before a solo game with errors. The team's size is displayed, but doesn't weight the score yet.

Your stats, for their part, only count the games that carry their own answers: a copy received from a friend or a live member's game doesn't go in. In live, only the person who holds the team's game therefore sees the grid there; for the other members, as for whoever receives a copy, it doesn't appear.

07 How a move reaches the others

A move isn't replayed on the others' side. Python applies it once, in the database, commits the transaction, then publishes a notice to Redis that the real-time server forwards to the whole team. This notice carries the state afterwards, a delta:

JSON
{
  "kind": "found",
  "code": "K7MP3QRS9TUV",
  "delta": {
    "score": 312, "errors": 1, "hints": 0, "found_count": 7, "restarts_count": 0,
    "can_hint": true, "is_over": false,
    "open_counts": [[4, 0, 12], [9, 3, 1], [6, 2, 5]],
    "cell": {"row": 0, "col": 1, "station": "…", "found_by": "K7MP3QRS9TUV"}
  }
}

Each teammate's page recalculates nothing, it copies these values over. But first, it compares the delta's counters with the ones it displays:

Verdict When What the page does
apply a single counter goes up, by one step (a cell found, an error or a hint) applies the delta: the cell lights up, the score scrolls
already seen no counter goes up nothing: it's its own move, a duplicate, or a reload that arrived earlier
gap a counter jumps by two, or the team restarted reloads the grid from the API

Applying the same delta twice changes nothing, since the counters are absolute values. And each move advances exactly one counter: a lost or out-of-order move shows up as a jump, and the page reloads. While your own request is in flight, the others' deltas wait in a queue, then are checked against the response. The end of a game always reloads: the end screen needs more than a delta.

08 When someone leaves

Leaving covers two very different things: leaving the page, and leaving the team.

Leaving the page

Closing the tab, switching to another app or losing the network changes nothing in the database: you stay a member, and the game goes on without you. Only your presence changes.

  1. The page closes its real-time connection as soon as it's hidden.
  2. The real-time server removes your presence from Redis and notifies your teammates, who see you leave. If you were pointing at a cell, it's erased on their side.
  3. If the server crashed without doing this cleanup, your presence expires on its own after a minute.

While you're away, the others' moves are written and published, but nobody sets them aside for you. When you come back, the page reconnects and reloads the grid, which contains every move played in the meantime; the new cells light up as for a live move. If the game ended without you, the result is already written in your game, and it counts for you like for the others.

Leaving the team

You can leave the team as long as the game is in progress, or lost on errors. Everything happens in one transaction, under the team's lock:

  • a member leaves: the team's answers are copied into their game, authors included, and it loses its team. They carry on solo exactly where the team was, cells, errors and hints included, with the same score. Their game keeps the size the team had, and stays marked as played with others;
  • whoever holds the team's game leaves: their game keeps its answers and stays theirs. The member who arrived first receives a copy of the answers, and their game becomes the team's new game. The team itself doesn't change;
  • in both cases, players_count goes down by one. If only one person remains, they play as solo and can invite again.
Before Team players = 3 Alice holder Bob pointer Chloé pointer holder After Alice leaves Team players = 2 Alice no team Bob holder · copy Chloé pointer holder
When whoever holds the team's game leaves, the holder passes to the member who arrived first. The team, its key and its invitations don't change.

Points aren't divided on leaving either: whoever leaves takes the team's full score at that moment, and what they play next only counts for their own game. Leaving a game lost on errors keeps its outcome: you can then restart it solo, with the restart penalty.

On the real-time side, the page of whoever leaves receives a new ticket with no team and reconnects: it no longer receives the team's moves. The others receive a left notice, reload the grid and in turn receive a ticket without the person who left.