| ParlorNet Turn-based game server for any computer, old or new | |
| Clients | Protocols | Browsers | Telnet programs | Docs | Source |
This note describes how an invitation travels between ParlorNet's frontends. It covers the core's model, what each protocol did before this work, and what it does now. The research for each protocol is in docs/research/ (ios-protocol.md, eclipse-ios-client.md, backgammon-network.md, the bg-client files and bg-client-outland.md).
An invitation belongs to an open table. It records who is invited, who invited them, the seat held for them if any, and when it was made. The full rules are in docs/protocol.md under "Invitations and private tables".
A player seated at an open table invites someone with INV table name [seat]. Anyone with an account can be invited. If the invited player is not online, the core still keeps the invitation and answers OK offline instead of OK, so the frontend can tell the inviter.
The invited player sees the invitation in IVL. Everyone at the table sees an INVITE event. The invited player accepts by sitting down with JON, which puts them in the held seat. They decline with UNV table theirname.
An invitation can end in several other ways. A seated player can withdraw it with UNV. It expires an hour after it was made, unless the inviter sends INV again to renew it. It ends when the inviter stands up from the open table, and when the game starts. If the table goes away altogether, the invitation simply disappears from IVL.
Each of these endings, except sitting down, produces an UNINVITE seat name why event. The last word says why: declined, withdrawn, expired, left or started. The inviter is seated at the table, so these events are how the inviter learns what happened. The invited player learns about new and vanished invitations from IVL, which every frontend checks every few seconds.
WHO lists the players who are online now, including the bot while it runs. Every frontend builds its own player list from it. Online means signed in and active recently, as docs/accounts.md explains under "Who is online".
The bot (docs/bot.md) is invited like anyone else. It sees the invitation in its own IVL and sits down within a few seconds.
IOS serves Reversi on port 6503, for Reversi The Eclipse and for terminals. IOS has no tables. One player challenges another by name with match, and the other answers with accept name or decline name. Eclipse takes the name from its player list, which is the reply to who. It shows an Accept dialog when it reads a line of the form <ios> MATCH ... FROM name ....
Before this work, who listed only the IOS players and the players seated at tables. The bot is never seated until it is invited, so it never appeared, and Eclipse users could not pick it. When an IOS player matched someone who was not on IOS, the adapter opened a table but did not invite anyone. That is why matching the bot did nothing. Offers between two IOS players were kept inside the adapter, so the web and telnet never saw them. An invitation made on the web never reached an IOS player.
Now who lists the players who are online, and the bot is among them. fi bot explains that it is the server's bot.
When a player types match X, in Eclipse's form or the terminal form, the adapter tries three things in order. If X has already invited this player, it accepts that invitation. If X is waiting alone at an open public Reversi table, it joins that table. Otherwise it makes a new table, seats the player in the colour they asked for, and invites X with the other seat held. The challenger's minutes become the time per turn. If no player has that name, the adapter says so and removes the table.
Every invitation to an IOS player now arrives as an <ios> MATCH line with FROM, followed by its second line and a sentence for people at a terminal. This works whether the invitation came from IOS, the web, telnet or the native protocol. Each session checks its invitations every three seconds. When one IOS player challenges another, the second session checks at once. An invitation to a game other than Reversi arrives as a line of text.
accept X sits down at X's table, and decline X declines the invitation. The challenger then sees "X declines the match." If the invitation runs out instead, the challenger sees "Your challenge to X has expired."
The FIBS adapter serves Backgammon on port 6505, for MacFIBS, FIBS/W, xfibs, xibc and CLIP clients. On FIBS, a player types invite name n to offer an n-point match. The other player sees "name wants to play a n point match with you." and then "Type 'join name' to accept." They accept with join name. FIBS has no command to decline. An invitation nobody answers simply stays until the inviter makes another.
Before this work, invite already made a private table and invited the other player to seat 1, and join already accepted an invitation. The who, rawwho and CLIP lists did not include the bot. An invitation made on the web or by telnet arrived as one long line. xfibs only recognises "Type 'join name'" at the start of a line, so it never offered to join. The inviter was never told when an invitation was declined or had expired.
Now the who lists show the players who are online. The bot always shows as ready, and whois bot explains how to play it. invite bot 1 starts a game against the bot.
An invitation from anywhere now arrives as FIBS's two lines. If the match was offered on FIBS, the line gives its length. Otherwise it says "a 1 point match", because a table made elsewhere plays a single game. An invitation to another game arrives as one line of text.
ParlorNet adds a decline name command, which help lists. When an invitation is declined, the inviter sees " X declines your invitation." When it expires, they see " Your invitation to X has expired."
The Outland adapter serves Backgammon on port 6506, for the Outland Gateway. In Outland, a player sends a challenge record to someone in the lobby list. The other player's client shows a dialog with Accept as White, Accept as Red and Decline, and sends back a response record.
Before this work, the lobby listed the Outland players and the players at Backgammon tables, but not the bot. A challenge to anyone who was neither an Outland player nor waiting alone at an open table was declined at once. Invitations made elsewhere never reached an Outland player.
Now the lobby lists the players who are online, and the bot is always available.
A challenge can go to someone who is not an Outland player and is not waiting at an open table, such as a web or telnet player or the bot. In that case the adapter makes a private table with the cube turned off. It seats the challenger at seat 0, which is Red, and invites the other player to seat 1. The client waits for the answer. The adapter reports the challenge as accepted when the game starts. It reports it as declined if the invitation is declined, withdrawn or expires.
An invitation to an Outland player from anywhere arrives as a challenge from the inviter, as long as the player is free in the lobby. If the inviter is not in the client's list yet, the adapter adds them first. When the player accepts, the adapter sits them in the held seat and shows the board in the colour they picked. When they decline, it declines the invitation. An invitation to another game arrives as a notice.
Before this work, telnet players could invite the bot with bot at a table or new ... bot in the menu. Nothing else worked. They never saw invitations sent to them, and they could neither decline one nor invite a person by name.
Now the menu lists the player's invitations. The plain menu shows them under "Invitations for you". The full-screen menu shows them at the top of Your tables and gives a notice when a new one arrives. Enter or join n accepts an invitation, and X or decline n declines it.
At a table, invite name invites a player and uninvite name withdraws the invitation. The table's log says how each invitation ended. who lists the players who are online.
Before this work, the lobby already listed "Invitations for you" with Join and Decline links. A table page could invite a player by name and offered "Invite the bot". The table log said "X is no longer invited" however the invitation ended.
Now the table log says how each invitation ended, and the lobby lists the players who are online. Nothing else changed.
INV, UNV and IVL work as before. UNINVITE now ends with its reason, and INV answers OK offline for a player who is not online. WHO lists the players online, and ACT reports a player's activity. docs/protocol.md and docs/pnp.md describe them. A client written before these changes sees an extra word after UNINVITE and after OK, and can ignore it.
There is no GGS adapter. The research in docs/research/ios-protocol.md outlines how GGS handles requests. A player sends ts ask (for example ts ask 8 <player>), and the other player sees a request line of the form /os: + .id rating player clock type R|U rating player [clock]. They answer with ts accept. ts open n sets how many requests a player accepts at once. The research records no command to decline.
A GGS adapter would map ts ask to NEW and INV, the request line to IVL, and ts accept to JON. If GGS has a way to decline, it would map to UNV. The request's .id would stand for the table.
Some behaviour could not be checked without the period clients themselves.
| These pages cover every ParlorNet server. | Source code | ParlorNet is free software. |