Server
A PokeLoom game that plays online talks to a server its creator runs. The server is part of the engine: a Rust program built from the same crates as the game, loading the same pack, so it applies the game’s own rules rather than a copy of them. This page is what exists, how it works, and what the plans add. The shapes of play (shared field, together, persistent world) are on Multiplayer overview.
Link battle
Section titled “Link battle”The first milestone is a battle between two players, because a battle risks no saves and proves the link end to end.
How a link battle stays honest
Section titled “How a link battle stays honest”Both players run the battle themselves, in lockstep: each machine holds the whole battle and steps it with both players’ choices. Nobody sends the result; both compute it.
- Seat order. Both machines run the battle in the same seat order. The second player looks at a mirrored copy, made fresh after each request and never played, so both see their own side first and speed ties and random targets draw the same on both.
- Commit and reveal. Each player first sends a hash of their choice, then the choice itself once both hashes are in. A player cannot wait to see the other’s move and then pick an answer. The random seed is made the same way from both players’ shares, so neither chooses it. A reveal that does not match its commit loses.
- Digests. After every request, each side compares a short hash of the whole battle state with the other’s. A difference is caught at the request where it happened.
- Rules. The battle is the engine’s own, checked against Pokémon Showdown. The link’s format was checked with team preview on and gimmick choices sent: thousands of random battles matched Showdown with no mismatch. Team preview is ported from Showdown.
The server
Section titled “The server”ploom-server serves one game:
ploom-server [--game ID] [--pack HASH] [--bind ADDR] [--name NAME] [--timer SECONDS] [--discovery ADDR]- It checks each player’s hello: the protocol version, the game and the pack’s hash. A battle needs both sides on the same data, so a different pack is refused.
- Players meet in a room by a six-letter code, or ask to be paired with whoever asks next.
- It relays the battle’s messages; it does not run the battle.
- A timer runs on each choice: a player who does not choose in time loses, and so does one who leaves.
- It answers LAN discovery over UDP, so players on one network find a host.
- It listens on the local machine only unless told to listen on a network.
The server is a library with a thin program around it, so a desktop game can embed it
and host from its own program: the desktop program’s --host runs the server
inside the game and links to it, and another player joins with --link. A script
starts the battle with netbattle.
What has been run
Section titled “What has been run”| Link | State |
|---|---|
| Two desktops through the server | runs; every request’s digests equal |
| Desktop and melonDS through the server | the DS joins melonDS’s access point and reaches the server; hello, pairing, teams and the seed cross; the battle stalls after the first choice, cause not found |
| Two DS by local wireless | not tried: two melonDS windows need their network dialogs, which cannot be driven headless |
| Encryption | none yet: the link is plain TCP |
On the DS, a game built without online play has no network code in its ROM. A build with it adds about 65 KB, the DS’s wireless network stack included.
Design
Section titled “Design”Everything below is planned (plan 33, which revises plan 22). The aim set by the owner: PokeLoom’s online play must not be behind what Pokémon Essentials and its community kits offer, in any way.
Principles
Section titled “Principles”- One program a creator ships.
ploom build serverwrites one executable per operating system with the game’s pack beside it. No database server, no scripting runtime to install. - Offline games link nothing. A game with online play off has no network code.
- The server runs the game’s own rules. It links the battle, data, systems, world and game crates and loads the same pack, so validation, battles and, in a shared world, the whole game are computed by the code the players run.
- The server owns anything of value. Every client is treated as hostile: bounds on every message, rate limits, validation, and the server’s own simulation where value is made.
- Nothing executable crosses the wire. Messages are plain fields checked on decode. Gifts, event packs and visiting trainers are signed by the creator’s key and checked before use.
Transport and security
Section titled “Transport and security”| Link | For |
|---|---|
| TCP with the Noise protocol | every game client, desktop and DS: the DS has TCP and no TLS, so one transport serves both |
| UDP | LAN discovery and LAN play on desktop |
| DS local wireless | DS-to-DS rooms nearby, the host DS running a small room host |
| HTTPS | public files: the gift feed, rankings, replays, the status page, the staff console |
Every frame is authenticated and encrypted with keys the game ships; replayed frames fail.
Accounts and storage
Section titled “Accounts and storage”- Accounts are a key pair made on first connection, kept in the game’s save folder but not in the save file, so a copied save does not copy the account. A creator may add a name and password so an account moves between machines, and a printed recovery code works without email.
- Storage is one embedded database file beside the server. Every transfer of value (a trade, a deposit, a prize) is one transaction: a disconnect leaves both sides as they were or both changed. Back-ups by command and on a schedule.
- Hosting. A dedicated server per game, run by its creator, on Linux, Windows or macOS; or a desktop game hosting a room from its own menu. PokeLoom’s owner hosts nothing by default.
Features, by milestone
Section titled “Features, by milestone”| Milestone | What it adds |
|---|---|
| O3 | Trades with legality checks, a fingerprint per creature, a trade journal, server escrow; offline wonder trade |
| O4 | Encryption, key accounts, recovery codes, optional passwords, minimum moderation |
| O5 | The vault, a ledger of currencies, creature IDs; signed gifts by feed and by password; cloud saves; ploom build server |
| O6 | Presence on maps, phrase chat, friends, rooms by code, online areas, region-map markers; ploom new --online |
| O7 | Server-run battles, ranked play, random battles, matchmaking, replays, leaderboards, spectating |
| O8 | The global trade station, online wonder trade, server gifts, a creator’s own web endpoints |
| O9 to O12 | Multi and free-for-all battles, shared flags and variables, co-op against the game’s trainers and facilities, visitors and record mixing, co-op bosses |
| O13 to O15 | The market, groups and staff tools in full, events and tournaments |
| O16 to O18 | The persistent shared world, run and mirrored by the server; shards and instances; anti-cheat statistics |
| O20 to O24 | Co-op (Co-op); O20, players on one machine, is built |
A creator turns features on in game.toml. Planned (plan 33), the shape of it:
[online]enabled = trueserver = "play.example.org:7400"accounts = "key" # "key" | "key+password" | "key+password+email"local_link = true # DS local wireless and LAN roomshost_from_game = true # desktop "Host a room"
[online.features]battle = { formats = ["singles", "doubles"], ranked = true }trade = truegifts = { passwords = true }Scripts reach online features through command rows (online, connect, netopen,
nettrade, gift, shared variables) and hooks (on connect, on gift), each
answer entering the input log so a replay stays exact. A script declares which flags
and variables are shared, and with whom, rather than calling a command to share them.
Honesty checks
Section titled “Honesty checks”| Check | Catches |
|---|---|
| A legality check of every creature against the pack’s data: stats from level, moves from learnsets, ability, held item, the game’s own bans | made or impossible creatures |
| A fingerprint of each creature’s fixed identity | the same creature deposited twice from copied saves |
| A server ID and history for every creature in the vault | duplication; where a creature came from |
| A ledger of every change of currency | edited money |
| Server-run battles for ranked play and prizes | edited outcomes and hidden-information cheats |
| Step checks against the world’s collision and timing | speed and wall hacks |
| The server’s mirror of the shared world | anything the simulation decides |
| Rate limits and account age | dumping, farming, throwaway accounts |
Invariants
Section titled “Invariants”- Games that carry real Pokémon data go online only on a private server (decision 108, decision 154).
- A battle online is the same battle as offline: same engine, same data, the same Showdown conformance.
- What the server sends that changes the game is written into the input log at the tick it arrived, so an online session can be replayed and checked with no network.