The wire

The game speaks to Retro Play on TCP port 6670 at retroplay.network: ASCII, one line a command, every answer in order on the same connection, nothing over 255 bytes including the newline in either direction. It was designed for a 65C02 behind a sixteen-byte UART FIFO, so nothing in it needs a buffer bigger than a line.

The library, or the bytes

On a supported floor — Commander X16, MEGA65, Neo6502, Agon, SDL for a desktop build, and the rest as they land — link C* (cstar-api) and speak through cpm.h: cpm_open, cpm_login, cpm_here, cpm_score, cpm_top, cpm_rank, cpm_now, cpm_award, cpm_awards, cpm_x, polled once a frame, nothing blocking. C* knows the link (its CLM speaks the serial card or the socket), the protocol, the MAC and the platform token. An assembly API for CPM is in progress (cstar-api #34, the 65C02 first) for a game that has no C.

Or speak the bytes yourself. They are these.

Login

> HELLO 1 TETRIBLOX V1.0.0-RELEASE X16
< CHALLENGE 3f9a1c0e77b2d410
> AUTH ANDY 8c2e1f9a44b0c7d3
< OK AUTH ANDY

HELLO <proto> <game> <build> [<platform>] — proto is 1; the game's id; the build's version stamp (up to 24); the platform token (X16, MEGA65, NEO6502, AGON, SDL…), which C* supplies and which the site turns into "Commander X16". The reply is a 16-hex-digit nonce.

AUTH <user> <reply> — the gamertag and H(K, S ‖ nonce), where:

• H(K, m) is SipHash-2-4 keyed with the 16-byte program key K, the 8-byte result in the reference implementation's byte order, sent as 16 hex digits. Reference: K = 00 01 … 0f, message 00 01 … 0e, H = e545be4961ca29a1.
• S = H(K, PIN) over the PIN's six ASCII digits — the secret. The player sets a six-digit PIN for your game on their account page; your game asks for it once, derives S, keeps S on the card and forgets the PIN. Neither side ever stores a PIN.

ERR 403 at AUTH is a wrong reply, a PIN not set for this game, or a game not approved yet — the text says which.

Presence, scores, boards

> HERE PLAYING MARATHON
< OK HERE
> SCORE MARATHON 48200 61 6 610 AMC 5d71a3e0c9b84f12
< OK SCORE
< POSTED MARATHON 3 1
> TOP MARATHON 5
< ROW 1 ZED 91000 120 12 1400
< ROW 2 KAY 60100 80 8 900
< ROW 3 ANDY 48200 61 6 610
< END TOP MARATHON 137
> RANK MARATHON 50000
< OK RANK MARATHON 3
> NOW
< NOW 4 ZED KAY ANDY

• HERE <state> [<detail>] on change: MENU, PLAYING <mode>, VERSUS are Tetriblox's; HIDDEN keeps the player off the live page.
• SCORE <mode> <score> <lines> <level> <seconds> <initials> <mac> — the MAC is H(K, S ‖ nonce ‖ fields), fields being the ASCII between the verb and the MAC exactly as sent: MARATHON 48200 61 6 610 AMC. POSTED follows OK SCORE with the world rank and 1 if it beat the player's best. One best row an account a mode.
• TOP <mode> [<n>] [FRIENDS] — 1 to 10 rows; FRIENDS ranks the player among the people they follow. RANK <mode> <score> says where a score would land without posting.
• NOW — how many are on this game and up to five names.

Awards and the daily

> AWARD MARATHON_MAN 2b7e151628aed2a6
< OK AWARD MARATHON_MAN 100 130
> AWARDS
< AWARDS 00000203 130
> X DAILY
< DAILY 20260919 3141592653

AWARD <key> <mac> — the MAC over the key alone, H(K, S ‖ nonce ‖ key); the same award again is the same answer, so post what was earned offline without keeping count. AWARDS is the mask of held awards (bit n is award n in your declared order) and the player's points. AWARDLIST names them for a client that did not bake them in. X <text> is a line for your own game service, or for Retro Play's own answer to X DAILY when you have none (chapter 4).

Keeping the link

A link silent for three minutes is closed; PING gets PONG. QUIT gets BYE. SELECT <game> points the reads (TOP, RANK, AWARDS, NOW) at another game — the client uses it; SCORE, AWARD, X and presence stay the HELLO game's, so nothing can be forged through it.

The protocol reference — every verb, every reply, every error code, including the client's own verbs (GAMES, GAME, WHO, FRIEND, FRIENDS, MSG, INBOX, MAIL, LIBRARY, FILES, FILE) — is docs/protocol.md in retroplay-manager.

← Registering a game Awards and the daily →