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.
Gameis 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-datescoreand its restarts, plus two fields for multiplayer:players_count, the "done by N", andmode(1 solo, 2 shared, 3 live), the same value on all of a team's games.Guessis a move, always attached to a game. A right answer, an error and a hint are allGuessrows:correctsays whether the station fits,hintwhether it's a hint.pointsis 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.authoris only filled in if the move was played by someone other than the game's player: empty means it's them.GridInvitationis an invitation to a friend, of one of two kinds:gamefor a share (the solved game to copy),teamfor live (the team to join). A database constraint requires exactly one of the two.statusis pending, accepted or declined.Teamis a live team: its grid,holder, the game that carries the moves, andplayers_count, the number of members still there.TeamMemberis one stay of a player in a team, with the game they play in it,joined_atandleft_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.
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.
Teamis 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 aSELECT … FOR UPDATEon it, so two moves of the team never run at the same time.players_countcounts the active members.- The holder game (
Team.holder) is the only one a move writes to: aGuessrow, whoseauthorfield 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. TeamMemberkeeps 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 |
- 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:
{
"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.
- The page closes its real-time connection as soon as it's hidden.
- 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.
- 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_countgoes down by one. If only one person remains, they play as solo and can invite again.
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.