| ParlorNet Turn-based game server for any computer, old or new | |
| Clients | Protocols | Browsers | Telnet programs | Docs | Source |
Goal: any machine that can open a byte stream and parse a line can play. The protocol carries typed game state and moves; it has no generic board and no lowest-common-denominator display. Clients are written against game types (below). Terminals reach games through the telnet server extension, which knows each type and renders it for a character screen; it is a server extension (adapters.md), not part of the protocol.
A guide for people writing their own frontend, with sample sessions recorded from a real server for the protocol and for every game, is pnp.md.
On the public port (6501) the client speaks first. Its first bytes are a newline alone, which sets the connection's line ending:
| The client sends first | Line ending |
|---|---|
| CR, then LF within 250 ms | CR LF |
| CR, and no LF within 250 ms | CR |
| LF, then CR within 250 ms | LF CR |
| LF, and no CR within 250 ms | LF |
After the client's newline (public port), or straight after the TLS handshake (extension channel), the server sends one line: PARLOR/1 name AUTH=signin SIGNUP=signup [LABEL=label], where name is the server's short name, signin the sign-in method (none, password, totp, ...), signup the sign-up method (none, password, email, ...) and label, if the operator set one, the printable name of the credential, with _ for spaces (shortened, or left out, so the line fits 80 bytes). A client checks the first word and the version before anything else, and signs in as the server asks (docs/accounts.md): USER name to sign in, REG name to sign up (or HELO name for either), then answers each ASK with AUT.
A reply is any number of data lines (GAM, TAB, V, EVT ...) ending with exactly one line starting OK, ERR code text or, during sign-in, ASK field label [secret]. A client reads until it sees one of them. An ERR text may start with wait=N, the seconds to wait before trying again (for example after a wrong code).
| Request | Meaning |
|---|---|
| HELO name [code] | Sign in, or (a name not yet taken) sign up. The reply is INF lines and an ASK (answer with AUT), ERR, or OK (below). The optional second word is a shortcut for direct 8-bit clients under sign-in totp only: the current 6-digit code (anything else: ERR BADCODE, not counted). It is refused under password (the password is asked for) and ignored under none. Server extensions never send it. Wrong answers lock the name (ERR LOCKED wait=N ...). |
| USER name [code] | Sign in only: as HELO for a name that has an account (the same steps, lockouts and code shortcut); a name with no account is ERR NOPLAYER and nothing is made. Unknown names count against the client address as sign-ups do (20 in 10 minutes, then ERR BUSY wait=N). |
| REG name | Sign up only: the sign-up method's steps for a new name (under sign-up email it goes straight to the address, without HELO's yes/no question). A name that has an account is ERR NAMEINUSE; a reserved word (new, guest: some frontends take them at their login prompt) is ERR RESERVED, also on HELO. Under sign-up email, while as many sign-ups as the server allows are waiting for their code, a new one (by REG, or HELO for a free name) is refused at once with ERR BUSY wait=N Too many sign-ups in progress; try again in ..., and a sign-up whose name is held by another one waiting for its code is ERR NAMEINUSE that name was just taken at its address (docs/accounts.md, Sign-up limits). The bot's names (bot, bot1 to bot3, docs/bot.md) are ERR RESERVED on USER, HELO and REG for every connection but the bot's own. HELO keeps doing both, for clients written before these two. |
| AUT field value | The answer to an ASK during sign-in, sign-up, recovery or a password change (docs/accounts.md). Before an ASK the reply may carry INF text lines to show the player (info). ASK field label [secret] [yn] [cred]: secret means do not echo; yn means a yes/no question, answered y or n; cred means it asks for the account's credential (or a password being chosen), the only question a password the client already supplied may answer. |
|---|---|
| CAN kind[,kind...] | Before HELO: the sign-in step kinds this client can show, of text, secret, yn, info (all four if never sent). A step needing another kind is refused with ERR CANNOT. OK kinds. |
| OK after sign-in | Public port: OK -. Extension channel: OK sid, the session id: a handle for the server extension, never a credential, never shown to the player. |
| SRC address | Extension channel only, before HELO: the IPv4 or IPv6 address of the client this connection serves, for the per-address limits on sign-up and mail (docs/accounts.md). OK, ERR NOTFRONTEND (public port, where the connection's own address is used), ERR SYNTAX. |
| SES sid | Extension channel only: resume a session this server extension was issued. OK name, or ERR NOSESSION (unknown, expired, ended, another server extension's, or issued under a key the server extension no longer holds), ERR NOTFRONTEND (public port), ERR RATE (three failures on this connection). |
| OUT [all] | End this session (the connection is signed out and may sign in again), or with all every session of the player, live connections included. OK n, the number ended. A connection whose session was ended elsewhere gets ERR SIGNEDOUT once. |
| PWD | Sign-in password only (ERR NOAUTH otherwise): change the password. The server asks for the current one, a new one and the new one again (ASK/AUT), then OK; the player's other sessions end. |
| MOTD | The operator's message of the day: MOTD text lines (at most 73 characters of text each, so the line fits 80 bytes with its CR LF; a line that fits is sent as written, spaces and all, so an ASCII layout survives; a longer one is wrapped at spaces, and a longer word is cut; MOTD alone for a blank line), at most 20 of them, then OK. The marker {contribute} in the operator's text is replaced by the setting site.contribute_url (by default the project's home, https://github.com/eric-cgn/parlornet); where the operator cleared it, every line holding the marker is left out. Allowed before signing in. |
| GAM | List what this server hosts: GAM type/ver rules name minplayers maxplayers [flags], ending OK. Flags: staged (turns made of steps, needs UND/END), nomoves (no legal-move list; use CHK), drop (in a game of three or more, one player can leave and the others play on; see Turn timer). Allowed before signing in. |
| PRL | The protocols this server speaks now: DOC url (the documentation site, the setting site.docs_url; left out when the operator cleared it), then for each protocol PRO key port name and, when it has one, PRD key text, by port; then OK. The core's own PARLOR/1 on the public port is always there; every other protocol is there while the server extension that declared it is connected (Protocols, below). Allowed before signing in, on both listeners. |
| PRO key port name | Extension channel only: this connection serves the protocol key on the public port port, under name (below). OK, ERR SYNTAX, ERR LIMIT (more than 4 keys on one connection), ERR NOTFRONTEND (public port). Allowed before signing in. |
| PRD key text | Extension channel only: the one-line description of a protocol this connection declared. OK, ERR NOPROTO (not declared on this connection), ERR SYNTAX, ERR NOTFRONTEND. Allowed before signing in. |
| LST | List the tables that are open or playing (finished ones are not listed): TAB id type/ver rules filled/seats status names turn=secs [vis=private] [bot=seat,...], where names lists every seat in order, - for an empty one, turn is the table's time per turn, vis=private marks a private table, and bot= lists the seats held by bots (docs/bot.md); ending OK. Public tables are listed for everyone, private ones only for their creator and players seated or invited there. |
| NEW type rules [key=val...] | Create a table (one game instance, hosted and arbitrated by this server). OK tableid. The creator is not seated by it: they sit down with JON like anyone else. type may leave out its version (reversi is reversi/1). At most six options; a key is letters and digits, a key or a value at most 12 characters. The option turn= (like 5m, 1h, 1d; 1 minute to 30 days, default 1 day) sets the time each player has per turn, and vis=public or vis=private (default public) who may sit down; both are handled by the server, not the game. The option players=n sets the number of seats, from the game's minimum to its maximum (default: the minimum). |
| JON table [seat] | Sit at a table, in the first free seat or the one asked for (ERR TAKEN if it is not free or held for an invited player). An invited player gets the seat held for them, if any, and the invitation is used up. A private table without an invitation is ERR PRIVATE. OK seat |
| INV table name [seat] | Invite a player to an open table where you are seated, and optionally hold a free seat for them. Inviting the same player again replaces the invitation and starts its hour again. The reply is OK. If the player is not online now, the reply is OK offline, and the invitation is still kept for them. Errors are ERR NOTSEATED, CLOSED, NOPLAYER, STATE (already seated), TAKEN, LIMIT. |
| UNV table name | Withdraw an invitation (any player seated at the table), or decline your own. OK, or ERR NOINVITE. |
| IVL | Your invitations: IVT table type/ver rules from status [seat=n], where from is who invited you and seat the seat held for you; ending OK. |
| WHO | List the players who are online now. Each is a line PLR name idle=secs [bot], sorted by name, at most 200, and the reply ends with OK. A player is online when they are signed in and have been active in the last presence.idle seconds (default 1800). Signed in means a live connection on any frontend, or a web session that has not ended. idle is the number of seconds since the player's last activity. bot marks the bot, which is online while it is connected and always shows idle=0. Activity means requests that do something, such as NEW, JON, MOV, CHT and ACT. Requests that only look, such as LST, SIN, WAT, VUE and WHO, never count. docs/accounts.md gives the full list under "Who is online". |
| ACT | Tell the server that the player did something on this frontend that needs no other request, such as a command the frontend handles itself. It counts as activity. The reply is OK. |
| LVE table | Stand up from an open table, or stop watching. A running game is not affected: the player stays seated and can come back at any time. |
| RES table | Resign a running game: END resign seat. In a game flagged drop with more than two seats still playing, only this seat leaves (GONE seat resign) and the others play on; the seat can no longer move or resign there (ERR STATE). |
| SEE table | Watch a table (spectator view). A private table can be watched only by its creator and players seated or invited there (ERR PRIVATE). At most 20 watchers a table (ERR FULL). |
| VUE table [flags] | This player's view (see Views). Flag M adds the legal-move list, T the status text, G the table's static geometry. |
| MOV table token... | Play a move, or one step of a staged turn. OK, OK more (turn continues), OK done (turn complete, send END), or ERR ILLEGAL reason. |
| CHK table token... | Validate a move without playing it. OK [info] (for example a score) or ERR ILLEGAL reason. Every type answers it; for nomoves types it takes the place of the move list. |
| UND table | Undo the last step of a staged turn (ERR NOSTAGE for a type without staged turns). |
| END table | Commit a staged turn (ERR NOSTAGE likewise). |
| SIN table [n] | Events since sequence number n (polling); without n, the events this connection has not seen. |
| WAT table [n] [secs] | As SIN, but wait up to secs (default 20, at most 30) for something (optional; polling clients may ignore). |
| CHT table text | Table chat, by a seated player or a watcher: printable ASCII, at most 56 characters kept. OK; the line comes back as the event CHT. |
| PRF GET key, PRF SET key value, PRF DEL key, PRF LST | A little data kept for the signed-in player, such as a display setting (below). GET: PRF key value if the key is set, then OK. SET keeps a value, DEL removes a key (OK either way), LST lists every key as PRF key value lines, then OK. A key is 1 to 12 of [A-Za-z0-9_-], in any case (kept in lower case); a value is the rest of the line, 1 to 56 printable ASCII characters (spaces allowed inside). At most 16 keys and 1024 bytes of keys and values per namespace and player: over that, ERR LIMIT. ERR BADKEY, ERR BADVALUE, ERR SYNTAX; before signing in, ERR NOHELO. |
| BYE | Close. |
Each server extension may keep a little data with a player, such as the telnet extension's movement keys, so a setting follows the player to their next sign-in. The data is kept in namespaces:
Each server extension tells the core which protocol it serves, so the core can say what the server speaks now and a server's web pages list it without a table of their own (docs/design/protocol-declarations.md).
PRO IOS 6503 Internet Othello Server (IOS) OK PRD IOS Reversi for clients of the Internet Othello Server OK PRL DOC http://docs.parlornet.org/ PRO HTTP 6500 HTTP and HTML 3.2 PRD HTTP HTML 3.2 pages for any browser with tables and forms PRO PARLOR/1 6501 ParlorNet protocol (PARLOR/1) PRD PARLOR/1 ParlorNet's own protocol, for programs written for it PRO IOS 6503 Internet Othello Server (IOS) PRD IOS Reversi for clients of the Internet Othello Server OK
Events are numbered per table: EVT table seq kind ....
VUE returns V type/ver seq, then type-defined lines, then OK; before the game starts, V type/ver seq and S Waiting for players. Hidden information is removed per player by the server.
Every table has a time per turn, set by its creator (turn= on NEW). When it is a player's turn the clock starts; if it runs out, the game ends with END timeout seat and that player loses. In a game flagged drop (Rummy Tile Classic, Dots and Boxes, Cannon Fire) with more than two seats still playing, a resignation or a timeout takes only that seat out of the game (GONE seat resign, GONE seat timeout) and the others play on; once two seats are left, the next one ends the game as above. Disconnecting does nothing: a player who goes away keeps their seat and their clock keeps running. Only resigning (RES) or running out of time loses a game without finishing it.
A table is public or private, chosen by its creator (vis= on NEW). Anyone may sit at a public table; a private table's seats are only for its creator, players already seated and players invited there, and only they see it in LST or may watch it.
Any player seated at an open table, public or private, can invite another player by name (INV), optionally holding a seat for them; nobody else can sit in a held seat. The invitation shows in the invited player's IVL and as an INVITE event at the table.
An invitation stays pending until something ends it. If the player sits down with JON, they get the held seat and the table shows a JOIN event. Every other ending shows an UNINVITE event with a reason:
If the whole table goes away, its invitations disappear from IVL without an event. That happens when the last player stands up, when the operator ends the table, or when it stays open for six hours.
The inviter is seated at the table, so they see these events through SIN, WAT or a MOV reply. The invited player sees invitations come and go in IVL. An invitation to a player who is not online is kept the same way, and INV answers OK offline to say so. Each frontend shows invitations in its own protocol's form and maps its own accept and decline commands to JON and UNV, as docs/design/invites.md describes. The server keeps invitations, visibility and held seats in its database. Telling a player who is not connected that they have been invited is left to the notification layer (docs/architecture.md).
The server keeps players, tables, game state, events, invitations and the data kept with PRF in SQLite (--db), written as they change, so a restart loses nothing.
For types flagged staged, a turn is a series of steps. MOV applies one step tentatively (OK more while the turn is incomplete, OK done when it is complete), UND takes back the last step, END commits the turn. Validation happens as steps are made and again at END. A one-step game commits on its first MOV.
Every type/ver has a spec (docs/types/) that defines: its view lines, event kinds, move tokens, staged-turn pattern, worst-case view and typical event size, and a set of recorded games as conformance vectors. It must also have a reference 80x25 ASCII rendering in the telnet extension, so every game works on a character screen.
| These pages cover every ParlorNet server. | Source code | ParlorNet is free software. |