Getting started
This page takes you from an account to a first BASIC program talking to the
hub. You need a commodoreonline.com account, and a Commodore with a network
device (see which devices work). A PC with a plain
TCP client, such as nc or PuTTY in raw mode, is handy for trying things
first.
1. Get a play token
Every program logs in to the hub with a play token. Get one on the My Games page in your account.
| Point | What |
|---|---|
| What it looks like | 8 letters and digits, such as K7Q2M9XP. There is no 0, O, 1 or I, so it can't be misread |
| How many | Up to 20, each with a label. Take one per machine or program if you like |
| What it can do | Log in to the hub as you, and nothing else. It can't sign in to the website, change your account or your games |
| Revoking | Revoke a token on My Games. Any session using it is disconnected at once |
Keep tokens off disks. A program asks for the token when it starts and keeps it in memory. Don't save it in a file, a saved game, or a program listing. Disks get shared, and anyone with your token can play as you (your handle, your chat, your turn-based matches and saved data) until you revoke it.
Your handle is the name other players see: 1-12 characters, A-Z,
0-9 and -, unique. A few that could pass for the system are reserved
(HUB, ADMIN, SYSOP, SYSTEM, DOT and the like). A new account gets
one made from its username. You can change it on My Games. Behind the handle is a permanent player id, which
never changes.
2. Register a game
Choose Register a game on My Games. Anyone can register a game and use it at once; there is no approval step.
| Field | What to choose |
|---|---|
| Id | 1-8 characters, A-Z and 0-9, such as TICTAC. Programs log in with it. It can't be changed. An incompatible new version is a new game (TICTAC2) |
| Name, description | Shown on the game's page |
| Notices | Optional: your terms, privacy notice or disclaimers, shown on the game's page under "Notices", apart from the description. Plain text; addresses on commodoreonline.com become links |
| Kind | live, turns (turn-based) or world |
| Server mode | relay (no game server), observe (a server sees all traffic) or authority (player messages go only to the server). A world needs authority. See game servers |
| Fewest and most players | Per match. For a world, the most per world |
| Turn limit | Turn-based games: how long a player may take before they forfeit, from a minute to a year, or none |
| Instances, arrivals | Worlds only: see worlds |
| Leaderboards | Up to 8. Each has an id of 1-8 characters, a label, an order (high or low wins), what it keeps (best, latest or total) and who may submit (players, or the server only). Live and turn-based games also get an automatic WINS board |
| Visibility | Who can play it (below) |
Visibility:
| Setting | Who can play | Where it shows |
|---|---|---|
private (the default) |
You and the players on your tester list | Only on your and your testers' My Games pages |
link |
Anyone who knows its id | Its own page, for anyone who has the address. Not in the games directory |
public |
Everyone | The games directory, with its leaderboards and results |
Add testers by handle on the game's settings page, at any stage. When a game
goes public you can clear its leaderboards, so test scores don't linger. To
anyone who isn't allowed to play a private game, the hub answers as if it
didn't exist (ERR,21).
Images. The game's settings page takes up to 8 images, shown on its page under the description: screenshots, a printable map, a reference card. PNG, JPEG, GIF or WebP, up to 8 MB and 16 million pixels each, with an optional caption. The site stores each one again as a PNG or a JPEG, at most 4,096 pixels on its longer side; a small one, such as a Commodore's screen, is shown scaled up with sharp pixels. Drag them, or use the arrows, to set the order. The site's moderators may hide or remove an image that breaks its guidelines; you see it on the settings page as under review.
Instructions. Under the description, the settings page has a box for how to play: the controls, the rules, tips. Up to 10,000 characters of plain text, shown in a fixed-width font as you typed it, so you can line up keys and what they do with spaces. A blank line starts a new paragraph. The game's page shows them in an "Instructions" section that stays closed until a player opens it, with a copy to print. They are checked when you change them; if they are held for the moderators, the settings page says so, and the rest of the game's page is unaffected.
Disks. The settings page can offer up to 4 disks from your library in My Disks, each under a label of your choice. The game's page lists their directories, and players add them to their own disks or download them. To publish a new version, use Replace image on the disk in My Disks: the game keeps offering the same disk, players who added it see Update my copy on the game's page, and they get a message saying there's a new version. Don't delete the disk and attach a new one: the game would offer a different disk, and the copies players made couldn't be updated. Every new image reaches players, saves from a Flyer included. Try a revision on a disk the game doesn't offer, or in a private test game, first.
The site can delist or suspend a game that breaks its guidelines. If that happens, the reason shows on your game's page.
For a first test, register a live game in relay mode with fewest
players 1. Then a quick match forms as soon as you ask for one, and you can
try everything alone.
3. Try it from a PC
The protocol is text, so you can log in by hand. Connect to
play.commodoreonline.com port 6502 with a raw TCP client and type, with
your game's id and your token:
HELLO,1,MYGAME,K7Q2M9XP,A
The hub answers with your handle:
OK,BRANDON
A says you are an ASCII client, so the hub sends no padding. Now try:
| You type | The hub answers |
|---|---|
WHO |
USER,BRANDON,LOBBY for each player in the lobby, then LIST,WHO |
SAY,HELLO |
Nothing to you. Others in the lobby get SAID,BRANDON,"HELLO" |
MATCH |
WAIT, then START,<match>,1,1,1 and SEAT,1,BRANDON once the match forms |
READY |
GO when every player is ready |
ALL,HI |
Nothing to you. Every other seat gets FROM,1,HI |
END,1 |
OVER,1,"BRANDON WINS", and you are back in the lobby |
BYE |
The hub closes the connection |
The protocol reference has every verb.
4. The development hub
The development hub is the hub on your own computer, for trying a game with several players, and with a game server, without the website. Download it for your system from Downloads, unzip it, and run it from a terminal:
gamehub -dev
It keeps everything in memory and forgets it when it stops (Ctrl+C). It:
- listens for Commodores on port 6502, and for game servers on
localhost:6503; - takes any game id, as a live game for 2 to 8 players;
- takes any token as your handle: log in with
ALICEand you areALICE; - takes any server key.
Try it from a PC first, as in section 3, with localhost in place of
play.commodoreonline.com and any name as the token. VICE on the same
computer reaches it at 127.0.0.1. A real Commodore reaches it at the
computer's address on your network, if the firewall lets port 6502 in.
To give a game other settings, register it with -game when you start the
hub. The form is ID:MIN:MAX[:KIND[:MODE]], or
ID:MIN:MAX:WORLD[:INSTANCE[:PRESENCE]] for a world, and -game can be
given more than once:
| Example | The game |
|---|---|
-game TICTAC:2:2 |
A live game for exactly two |
-game CHESS:2:2:TURNS |
A turn-based game |
-game GUESS:1:4:LIVE:AUTHORITY |
A live game for 1-4, run by a game server (mode OBSERVE or AUTHORITY) |
-game MILL:2:4:WORLD:PARTY:SERVER |
A world with an instance for each party (SHARED, PARTY or BOTH), where the server tells arrivals (HUB or SERVER) |
A game server connects to localhost:6503 with its SDK's insecure setting
(the hub makes its own certificate) and any key. Game
servers has the details, and the zip's
README.txt lists every setting.
When the game works, register it on My Games, and try it on the real hub while it is still private.
5. A first BASIC program, on a Flyer
A Flyer's tcp: channel needs no library. This program logs in, asks for a
quick match when you press M, sends each letter you type to the other
players, and prints every line the hub sends. Press Q to log out. It uses only
the BASIC every Commodore has, with no PEEK, POKE or SYS.
The listing is in lowercase, as petcat writes it. On a Commodore in its
normal uppercase mode, type it as you see it: the letters show in uppercase and
send the same bytes as uppercase ASCII. Change mygame to your game's id.
10 rem hello hub: a first program for the game hub, on a flyer's tcp:
20 h$="play.commodoreonline.com":p$="6502":g$="mygame"
30 input "play token";t$
40 open 15,7,15:open 2,7,2,"tcp:"+h$+","+p$
50 input#15,e,em$,x,y:if e then print "no hub:";e;em$:goto 900
60 print#2,"hello,1,";g$;",";t$;",u"
70 pt=ti
100 rem poll the hub four times a second; look at the keyboard
110 if ti-pt>=15 then pt=ti:gosub 1000
120 get k$:if k$="" then 110
130 if k$="q" then print#2,"bye":goto 900
140 if gs=0 then 170
150 if k$>="a" and k$<="z" then print#2,"all,key,";k$
160 goto 110
170 if k$="m" then print#2,"match"
180 goto 110
900 close 2:close 15:end
1000 rem n-a: says how many bytes wait. read a line only at 3 or more
1010 print#15,"n-a:2":input#15,e,em$,n,x:if n<3 then return
1020 input#2,v$,a$,b$,c$,d$,e$:print v$;" ";a$;" ";b$;" ";c$
1030 if v$="start" then print#2,"ready"
1040 if v$="go" then gs=1
1050 if v$="over" then gs=0
1060 goto 1010
How it works:
- Line 20 holds the settings: the hub's address and port, and the game's id.
- Line 60 logs in with flag
U: PETSCII in the uppercase character set. With no digit in the flags, the hub pads every line it sends to exactly 6 fields, soGOarrives asGO,,,,,. OneINPUT#with six variables then always reads exactly one line (line 1020). - Line 1010 asks the Flyer how many bytes are waiting (
N-A:2on the command channel; the reply is00,AVAIL,<bytes>,00). AnINPUT#on an emptytcp:channel would return a stale byte, and anINPUT#on a line whose end hasn't arrived could hang, so the program reads only when at least 3 bytes wait. - Line 110 polls four times a second. Each poll costs about 68 ms on a C64's serial bus (less on a PET's IEEE-488 bus), so polling in every pass of the loop would take most of the machine's time.
- Line 1060 polls again after each line, because
STARTand itsSEATlines arrive together. - Line 1030 answers
STARTwithREADY: the program has nothing to load. - Free text, such as chat, arrives in quotes:
SAID,BOB,"HI, ALL".INPUT#drops the quotes and keeps the comma, soB$isHI, ALL.
6. The same program with playlib
playlib is a small machine-language library for every supported device. It buffers whole lines, so a read costs a few milliseconds instead of a 68 ms poll, and it keeps an idle connection alive. Put the playlib file for your device on the disk beside the program.
10 if pl=0 then pl=1:load"playlib-flyer",8,1
20 h$="play.commodoreonline.com":hp=6502:g$="mygame"
30 so=49182:rd=49185:sn=49188:tg=49200:tp=49203:pe=49216:cl=49155
40 sys tg,t$:if t$="" then input "play token";t$:sys tp,t$
50 sys so,h$,hp:if peek(pe) then print "no hub:";peek(pe):end
60 sys sn,"hello",1,g$,t$,"u0"
100 sys rd,v$,a$,b$,c$,d$,e$:if v$<>"" then gosub 1000
110 get k$:if k$="" then 100
120 if k$="q" then sys sn,"bye":sys cl:end
130 if gs=0 then 160
140 if k$>="a" and k$<="z" then sys sn,"all","key",k$
150 goto 100
160 if k$="m" then sys sn,"match"
170 goto 100
1000 print v$;" ";a$;" ";b$;" ";c$
1010 if v$="start" then sys sn,"ready"
1020 if v$="go" then gs=1
1030 if v$="over" then gs=0
1040 return
- Line 10 loads playlib to
$C000. ALOADin a program runs the program again from the top, keeping its variables, soPLstops it loading twice. For a modem, loadplaylib-rs232(user port) orplaylib-swift(SwiftLink) instead; nothing else changes. - Line 20 holds the settings: the hub's address and port, and the game's id.
- Line 40 takes the token from playlib's session, if an earlier program left one in memory, and otherwise asks for it and keeps it there.
- Line 50 connects. On a Flyer playlib opens
tcp:; on a modem it dialsATDTplay.commodoreonline.com:6502. - Line 60 logs in with flags
U0: field count 0 asks the hub not to pad, since playlib splits lines itself and gives""for missing fields. - Line 100 returns at once, with
V$empty when nothing has come. It polls the device by itself when a poll is due, so the loop can call it as often as it likes.
Downloads
playlib, the ready-made lobby, the text client, the example games, the SDKs for game servers and the development hub are on the downloads page.
Next
- The Commodore protocol: every verb, reply and rule.
- playlib: the library in full, from BASIC, machine language and cc65.
- Game servers: when a game needs rules on the server.
