How the game talks to the platform¶
A Trackmania 2020 server does not call the backend directly. When you cross the finish line, the news travels as a message. The message goes onto a queue and waits there for the backend. That queue lives in Redis, the one road between the game servers and the platform.
The controller next to each server, kontrol, watches the game. When something happens, kontrol drops a message. The backend reads the message and writes it down. Neither side talks to the other directly.
What Redis is¶
Redis is a database that keeps its data in memory, so reading and writing take a fraction of a millisecond. Kacky runs one Redis for the live platform, on its own server next to the other shared services. The test platform has its own Redis, so a test never mixes with real finishes.
Kacky uses Redis for three jobs:
| Job | What it carries | If nobody is listening |
|---|---|---|
| Streams | Finishes, connects, map starts, check-ins: everything that must reach the backend | The message waits |
| Broadcasts | Live commands to every server at once, such as "start the map sync" | The message is gone |
| Shared memory | Small values that every server reads, such as the running map sync and the shared clock | The value stays as it is |
Most of this page is about streams, because that is where your times travel.
Streams: a log that keeps its order¶
A stream is a list of messages that only grows at the end. On arrival, every message gets an id, and the ids keep the order. Kacky has one stream per family of messages: player messages, server messages, map messages, and a few more for admin actions, leaderboards, and donations.
Reading a message does not remove it from the stream. So two readers can read the same stream, each at its own pace, and neither takes anything away from the other. Old messages are trimmed after a while, so a stream never fills the memory.
Readers and receipts¶
The backend reads each stream as a group. A group remembers which messages it handled. The backend takes a message, handles it, and then sends a receipt for it. A message without a receipt counts as not handled yet.
That receipt is what makes the system safe:
- If the backend stops in the middle of a message, no receipt goes out. When the backend comes back, it gets the same message again and handles it.
- If the backend is down for an hour, the messages of that hour wait in the stream. The group knows where it stopped, and the backend works through the backlog in order.
Some messages must reach every server, not one reader. A donation on Ko-fi is posted in the chat of every server. For those, every server reads the stream as its own group, so each server gets its own copy and sends its own receipts.
Messages have names¶
Every message has a short name that says what happened: a player connected, a player finished, a server checked in, a map started. Each kind of message has exactly one handler on the backend. A "player finished" message becomes a finish. A server's regular check-in proves that the server is still alive. (Finishes are not the same as records. See Records vs Finishes for why.)
Following a finish¶
sequenceDiagram
participant TM as Trackmania server
participant K as kontrol
participant R as Redis
participant API as Backend
participant C as Website / Discord bot
TM->>K: you crossed the line
K->>R: add a "finished" message to the player stream
R->>API: the backend reads it
API->>API: write the finish to the database
API->>R: receipt: handled
API-->>C: rankings on the website, live status in the admin panel
Questions and answers¶
Most messages flow one way, game to backend. A few need an answer: "give me the records of this map", "give me the leaderboard". A question carries a return address and a ticket number. The backend writes its answer to that address, with the same ticket number. So the answer reaches the exact server that asked, and the ticket tells the server which question it answers.
A server does not wait forever. If no answer comes in time, kontrol carries on with what it already knows, for example the records it loaded at the map start.
sequenceDiagram
participant K as kontrol on server 7
participant R as Redis
participant API as Backend
K->>R: question, ticket 42, reply to server 7
R->>API: the backend reads the question
API->>R: answer, ticket 42, to server 7
R->>K: server 7 gets its answer
Broadcasts and shared memory¶
Streams are for messages that must not get lost. Some messages only matter right now. When an admin starts the map sync, every server must hear it at once. A server that is offline does not need the old command later. Those go out as broadcasts: every server that listens at that moment gets the message, and nothing is stored.
What a server must still know after a restart goes into shared memory instead. The running map sync, the time every server agrees on, and the live player limit are small values in Redis. A server that comes back reads them and continues. Map sync shows how the servers use them.
Why a queue instead of a phone call¶
The game servers and the backend live on their own schedules. Servers restart, redeploy, and drop offline. The backend deploys whenever it deploys. A queue lets the two sides ignore each other's downtime. kontrol drops the message and moves on. After the backend comes back, it picks the message up.
No finish is ever lost¶
Your finish is not a fragile phone call. A phone call nobody picks up is gone for good. Your finish is a durable message. It sits on the stream, and only the backend's receipt marks it as handled.
- If the backend is down or mid-deploy when you cross the line, your finish waits in the stream. When the backend comes back, it works through the backlog and catches up. Nothing is dropped.
- If a finish ever does slip through, it is still recoverable. The controllers keep a log of every finish. An admin can find the finish and add it back by hand from the insert-finish tool in the admin panel.
That is the quiet advantage of an event-based system. Every event is a message you can re-read or replay, not a moment that is gone the instant it happens.
The catch: nothing forces the two sides to agree¶
A message is just text. The backend checks its shape, not its meaning. There is no shared safety net across the two codebases. One side writes fields by name, the other side reads fields by name, and nothing forces the names to match.
A renamed field fails silently
Rename a field on one side and forget the other, and nothing errors. The message still arrives and still looks valid. The value quietly goes missing. There is no crash, no log, and no red flag. The problem only turns up later as wrong numbers on the website. The two sides must change together, or not at all.
The bigger picture (who owns what, and how the pieces connect) is in the Architecture overview.