ParlorNet
Turn-based game server for any computer, old or new
Clients | Protocols | Browsers | Telnet programs | Docs | Source

GameMaster (Mac, 1991-93): rulebooks and wire protocol

Status: research notes, 2026-11-21. Every fact carries a source tag like [S3] (list at the end). Anything not settled by a source is marked UNVERIFIED. Static analysis only: nothing was run and no connection was made.

Method: the GameMaster Developer's Kit (programming manual and the Pascal source of every User Kit rulebook) was found on the "Ian and Stuart's One" CD in a folder of Rhys Hollow's work, together with the later rulebooks Isolation (with source), Gravity Wars and Crystal Ball [S1][S9]. A second copy of the Dev Kit (Disc to the Future Part II, 1992) has byte-identical sources and manual [S10]. The GameMaster 1.0.0 application has no source; its 68k code keeps MacsBug routine names and was disassembled with Homebrew's capstone cstool [S4]. Offsets below such as CODE 3 0x2b06 are within a CODE resource after its 4-byte header. Files, URLs and sha256 are in a working folder outside the repository; the earlier copies are in the working folders for Dots and Boxes and Naval Combat.

Key findings in brief

  1. Thirteen rulebooks are known: the ten of the User Kit (December 1991), Isolation (February 1992), Gravity Wars (August-September 1992) and Crystal Ball (December 1993). An "Empire" rulebook was announced and never released (section 1).
  2. Three of them are ParlorNet games: Dots&Boxes, BattleShips (Naval Combat) and Othello (Reversi). Simple Talk is chat and Crystal Ball is an opponent-finding lobby; both are worth serving too.
  3. The rulebook layer is fully documented by source. A rulebook exchanges at most 250-character strings with its remote twin; Dots&Boxes sends M + one digit + six digits, BattleShips sends fleet strings, two-digit shots, Fire and Done, Othello sends two digits (section 3).
  4. The session layer is recovered from the binary. Messages are Pascal strings with a one-byte prefix, # for the rulebook and ~ for GameMaster's own control texts. A call is a TCP connection to port 918 carrying a fixed 786-byte call record. The callee answers with a text and a 10-byte address, and the caller then opens a second TCP connection to that address. It uploads the game state there and keeps that connection for play (section 2).
  5. Verdict: one ParlorNet server extension can be the remote GameMaster for Dots&Boxes, BattleShips and Othello, as the callee. The Mac user types the parlor's name or address in Connect; no DNS tricks are needed. It needs TCP port 918 published, a second published port for the game connection, and the parlor's public IPv4 address in its configuration. The ParlorNet types need small additions: a 13 by 11 Dots and Boxes board with a majority win, and a fixed six-shot salvo for Naval Combat (section 4). Rulebook code is never sent or accepted.

1. The rulebooks

RulebookAuthorDateID string (GMRZ)VersionGameParlorNet game
OthelloRhys HollowDec 1991Othello [RHS]0.2.0Othello on 8x8, local or remoteReversi
Connect 4Rhys HollowDec 1991Connect 4 [RHS]0.1.0Connect Fourno
BattleShipsRhys HollowDec 1991BattleShips [RHS]0.2.0Battleship with a 6-shot salvo, remote only, no savingNaval Combat
ChessQuinnDec 1991Eskimo Chess1.0.0Chessno
TicTacToeQuinnDec 1991Eskimo TicTacToe1.0.0noughts and crosses, the programmers' exampleno
DerfBallPeter N. LewisDec 1991Fred [PNL]1.0.0real-time sliding-pipe ball gameno
Dots&BoxesPeter N. LewisOct-Dec 1991Dots&Boxes [PNL]1.0.0Dots and Boxes, 13 by 11 boxesDots and Boxes
Global Thermonuclear WarPeter N. LewisDec 1991Global Thermonuclear War [PNL]1.0.0a joke after WarGamesno
Simple TalkPeter N. LewisDec 1991Simple Talk [PNL]1.0.0a copy of Unix talkchat
File TransferPeter N. LewisDec 1991File Transfer [PNL]1.0.0file transfer, remote onlyno
IsolationRhys Hollow24 Feb 1992 (Info-Mac 13 May 1992)Isolation [RHS]1.3.0 (connects to 1.2.0)move a piece, then destroy a square, on 6x8no
Gravity WarsRhys Hollow9 Aug-21 Sep 1992Gravity Wars [RHS]1.4.5port of the Amiga Gravity Wars: missiles by angle and speed among planetsno (see clients-cannonfire.md)
Crystal BallRhys Hollow16 Dec 1993PlayMe [RHS]1.0.0opponent finder: connects to a "Spirit World" serverlobby
EmpireMarcus Jagerannounced only ("If Jager ever finishes")----

Sources: the User Kit list and authors in the manual [S1] ?1.3 and ?7.1 and in Rulebooks.doc [S5]; the ID strings, versions and memory sizes decoded from each rulebook's GMRZ 128 resource with the layout of [S1] ?3.3 [S4]; Isolation [S6], Gravity Wars [S7], Crystal Ball [S8]; the folder summary lists the Dev Kit, the User Kit "with 10 or so rulebooks", Isolation, Gravity Wars and Crystal Ball, with the Spirit World site list SWsites.txt [S9]. The same files are on many 1992-96 CDs (BMUG, BBS in a Box, Info-Mac 1994-01, MacFormat, Ultra Mac Games) and on the UMich archive as gamemaster1.0.cpt.hqx, gmcrystalball.cpt.hqx and crystalball1.0.sit.hqx [S12][S15]. No other rulebook was found in those listings (UNVERIFIED absence; Wayback copies of redback.cs.uwa.edu.au's FTP were not checked).

A rulebook is a file of type GMRB, creator GMST, with an empty data fork. Its code is PROC 128, called as procedure Main(var gameevent: gameEventRecord) for every event GameMaster sends it; its header is GMRZ 128: name (Str63), author and copyright (Str127 each), ID string (Str63), four BCD versions (rulebook, oldest compatible rulebook, GameMaster written for, oldest GameMaster), two memory sizes and flags (disallow save, connect, restart, swap; no idle; no sleep-query) [S1] ?2, ?3.

2. The session layer (GameMaster 1.0.0)

From the application's code [S4] unless another source is given. GameMaster 1.0.0 announces itself as version 0x0100; the rulebooks ask for 0.2.0 to 1.0.0 [S4].

Transport

Messages on an open connection

SENDPORTSTRING (CODE 1 0x267c) sends a Pascal string: one length byte, then a prefix character, then the text. The prefix is ~ (0x7e) for GameMaster's own messages and # (0x23) for rulebook messages. GETPORTSTRING (CODE 1 0x2748) reads the length byte and then that many bytes, sets a flag when the first is ~, and passes on the rest [S4]. A rulebook message is therefore

len  '#'  text...        len = 1 + length(text); text at most 250 characters [S1] ?5.7

and arrives at the other side's rulebook as ge_MessageReceived with the same text [S1] ?5.4. Rulebook texts may contain any byte values (they are Pascal strings, not lines).

Control texts (~ prefix), all from the code [S4]:

TextSent byMeaning
Send Game Across Port :calleerulebook found and loaded; followed at once by a 10-byte address (below)
Send Code Please / Dont Send Codecalleecallee lacks the rulebook (or has an older one) and the user accepted / refused to learn it
Go away, I'm oldcalleethe caller needs a newer GameMaster than the callee's
Not Enough Memcalleeno memory for the game; connection closed
Just a moment, I'll seecalleethe game has arrived; the callee's user is being asked "Anyone for <game>?" (Play / No)
Play it Sam / sorry, not interestedcalleethe user's answer
Request to swap / Swap / Dont Swapeitherswap sides, and the answers
Request to restart / Restart / Dont Restarteitherrestart, and the answers
Beep Beep Beep Beep Beepeitherdisconnect (sent before closing)

A call, step by step

  1. Call record. The caller connects to port 918 and, once connected, asks its rulebook to flatten the game (ge_Flatten) and sends one 786-byte (0x312) record (DOWINDOW, CODE 3 0x33a4-0x3478):
OffsetSizeField
0x0004size of the game state that will follow (GetHandleSize of the game handle)
0x00464Str63 copied from a GameMaster global that no code in 1.0.0 writes, so empty in practice; the callee drops the call unless it equals its own copy (DODAEMON, CODE 3 0x2622). Purpose UNVERIFIED
0x0442caller's GameMaster version (0x0100)
0x0462required GameMaster version (from the rulebook's GMRZ); the callee answers Go away, I'm old if it is higher than its own
0x0482rulebook version
0x04a2oldest compatible rulebook version
0x04c64rulebook ID string (Str63), e.g. Dots&Boxes [PNL]
0x08c64a second Str63 from the rulebook record, probably the rulebook's name (UNVERIFIED)
0x0cc256the caller's own address as text (GETMYADDRESS)
0x1cc326the caller's connection record (kind byte, then address data; contents beyond the kind UNVERIFIED)

The callee (DODAEMON state 1, CODE 3 0x25f4) reads exactly 786 bytes, checks the two fields above, then looks the rulebook up by ID string and version.

  1. Answer. If the callee has a compatible rulebook it loads it, opens a second, passive TCP connection on a free local port (NEWPASSPORT and OPENPASSIVESPECIAL, CODE 3 0x221c, CODE 2 0x3a2e) and sends ~Send Game Across Port : followed by a raw 10-byte address on the first connection:
   byte 0     1 = TCP (2 = ADSP)
   byte 1     0
   bytes 2-5  the callee's IPv4 address (as MacTCP reports it)
   bytes 6-9  the local port, as a 32-bit big-endian number

Otherwise it offers to learn the rulebook (~Send Code Please, after which the caller sends a 68-byte header and the rulebook file in 8000-byte pieces, CODE 3 0x2c92-0x2dc6) or refuses (~Dont Send Code).

  1. Game upload. The caller reads the 10 bytes, closes the port-918 connection, connects to the given address and port, sends the flattened game state there in 8000-byte pieces with no further header, and from then on uses that connection for the game ($bc of the game record is set to it, CODE 3 0x3370). It sends ge_ConnectionMade to its own rulebook at once.
  2. Callee start. The callee receives exactly the announced number of bytes on the second connection, makes the game window, sends its rulebook ge_OldGame with the received state, then ge_Swap (so the two sides play different players), then ge_ConnectionMade [S1] ?6.7 [S4] (CODE 3 0x2920-0x2b1a). It sends ~Just a moment, I'll see, closes the port-918 connection and asks its user; the answer goes out as ~Play it Sam or ~sorry, not interested (HANDLEMYALERT).
  3. Play. Rulebook messages travel as # strings on the second connection until one side sends ~Beep Beep Beep Beep Beep and closes, or the connection drops (the rulebook gets ge_ConnectionLost).

So the caller always uploads its current game, which may be a saved game in progress, and the callee plays the other side of it.

Crystal Ball and the Spirit World

Crystal Ball is a rulebook that, connected to a "Spirit World" server, lists the people at that server with their name, address and preferred rulebook; the user then connects a game to an address from the list by hand [S8]. A Spirit World was run at redback.cs.uwa.edu.au (a saved connected game, "Redback Spirit World", ships with the rulebook) and Rhys Hollow kept a list of sites in SWsites.txt [S8][S9]. Since Crystal Ball connects through GameMaster, a Spirit World is something that speaks the session layer above as the callee. From the rulebook's code [S4-CB]:

No Spirit World server program was found.

3. The rulebook messages

All from the rulebook sources [S3] (Pascal, read for facts only), with the record sizes checked against the 68k code [S4].

Dots&Boxes (Peter Lewis)

BattleShips (Rhys Hollow)

Othello (Rhys Hollow)

Others

Connect 4, Chess, TicTacToe, Isolation and Gravity Wars follow the same pattern (strings built by the rulebook). Gravity Wars sends aim, planets, explosion, abort and restart messages (SENDAIM, SENDPLANETS, SENDEXPLOSION, SENDABORT, SENDRESTART) and both machines fly the missile [S7][S4]; it is not ParlorNet's Cannon Fire (planets and gravity instead of a terrain).

4. Feasibility: one GameMaster server extension

Yes, as the callee, for Dots and Boxes, Naval Combat and Reversi. The extension:

  1. Listens on TCP 918, reads the 786-byte call record, checks the required GameMaster version and the ID string and version against the rulebooks it supports (Dots&Boxes [PNL] 1.0.0, BattleShips [RHS] 0.2.0, Othello [RHS] 0.2.0; Simple Talk and Crystal Ball optionally). For anything else it answers ~Dont Send Code (the Mac shows "Game refused"). It never asks for or accepts rulebook code.
  2. Answers ~Send Game Across Port : with the parlor's public IPv4 address and a second published port, accepts the caller's second connection there, and reads the announced number of bytes of game state.
  3. Seats the caller at a ParlorNet table of that game. The caller's identity is only the name in its uploaded state and its address. On a parlor that needs passwords, the account would have to be matched another way (for example a Simple Talk exchange first, or a name-only parlor), to be decided.
  4. Plays the other side: sends ~Just a moment, I'll see, then ~Play it Sam once a ParlorNet opponent is seated (or ~sorry, not interested). It translates # messages into moves and ParlorNet moves into # messages, answers ~Request to restart and ~Request to swap (or refuses them), and sends ~Beep Beep Beep Beep Beep when the table ends.

Rules to settle in the ParlorNet types:

Reachability: MacTCP users type the parlor's host name or address; GameMaster resolves it with the ordinary DNR. Port 918 is fixed in the client (a privileged port on the host; the container maps it). Macs on AppleTalk only would need an AppleTalk bridge that registers NBP type GameMaster and forwards ADSP to TCP; that is separate work and not needed for MacTCP users. ParlorNet never needs to call out to a Mac.

Confidence: high on the rulebook layer (source), medium-high on the session layer (68k code read by hand). The cheapest confirmation is two GameMaster copies under an emulator with a logging relay on port 918 and on the second port; both copies of the application have identical resources [S4][S10], so the binary is a known-good copy.

5. Unverified items

  1. The purpose of the call record's field at 0x004 and the exact contents of 0x08c and 0x1cc.
  2. How the ADSP path carries the 10-byte address (kind 2) and whether NBP object names are the owner names.
  3. Dots&Boxes record offsets other than 0x1f4/0x1f6 and the total size.
  4. Crystal Ball's record offsets for name and rulebook, and the field order of the 192-byte entries.
  5. Whether any rulebook other than the thirteen above was published, and whether GameMaster 2 (announced in the Gravity Wars notes as "3 or 4 months off", September 1992) was released [S7].

Sources

This doc on GitHub


 These pages cover every ParlorNet server. | Source code | ParlorNet is free software.