A guided tour of the game hub
This page is for anyone who would like to write a game that Commodore owners can play together over the internet. It explains how the whole system fits together, slowly and from the beginning, with small examples along the way.
You don't need any networking background. If you have written a program in BASIC, or a little Python, you know enough to follow everything here. Take it a section at a time, and try the examples if you can.
The other pages in this section are the reference: every command, every field, every limit. You won't need them to understand the ideas. Come back to them when you are writing your game and need an exact detail.
Contents
- The pieces
- Lines of text
- Logging in, and the lobby
- Three kinds of game
- A live match, with no server at all
- When you want a game server
- Your first game server
- Turn-based games
- Worlds
- The Commodore side
- What the hub keeps for you
- From an idea to players
- Where to go next
- Words used on these pages
1. The pieces
Four things take part when people play a game through the hub.
Your Commodore. A C64, a VIC-20, a C128, a PET or another Commodore, with a network device: a Flyer, a WiFi modem, or another way of reaching the internet. It runs your game: a BASIC program, a machine-language program, or one of the ready-made programs described later. (The hub works with any of them. The ready-made programs run on the C64 and the PET; section 10 says which devices.)
The hub. A program that runs all the time on commodoreonline.com's
server, at play.commodoreonline.com. It works rather like the sysop of an
old bulletin board. It knows who is logged in, lets them chat, introduces
players who want a game, passes their messages to each other, and keeps the
scores. The hub serves every game at once.
The website. commodoreonline.com is where members get the play token their Commodore logs in with, where you register your game, and where everyone sees leaderboards and results.
Your game server. This one is optional. It is a program you write yourself, which runs on a PC (yours, or one you rent) and connects to the hub. It knows your game's rules. Many games don't need one at all.
flowchart LR
A["Alice's C64"] -- "text lines" --> H(("The hub<br>play.commodoreonline.com"))
B["Bob's C128"] -- "text lines" --> H
S["Your game server<br>(optional, on a PC)"] -- "JSON lines" --> H
W["The website"] --- H
The most important idea on this page is this: the hub knows nothing about your game. To the hub, a move in tic-tac-toe is just a line of text to pass along. It doesn't know what a board, a card or a room is. That is how one hub can run every game, and it is why your game can be anything you like.
2. Lines of text
Your Commodore and the hub talk in lines of text, much as a terminal
talks to a bulletin board. Each line starts with a word in capitals, the verb, which
says what the line is for. Then come the fields, separated by commas.
Each line ends with a carriage return, just as PRINT# sends one.
Here is the first line every program sends, to log in:
HELLO,1,TICTAC,K7Q2M9XP,U
| Part | Meaning |
|---|---|
HELLO |
The verb: "I'd like to log in" |
1 |
The version of the protocol. Always 1 for now |
TICTAC |
Which game this is: the game's id, chosen when it was registered |
K7Q2M9XP |
The player's play token, which says who they are |
U |
Flags. U means "I'm a Commodore in its normal uppercase mode" |
The hub answers with a line of its own:
OK,ALICE
That means "welcome, you are logged in, and your name here is ALICE".
This is why BASIC can play: PRINT# sends a line, and INPUT# reads one,
splitting it at the commas into separate variables. A program can read every
line the hub sends with one statement:
input#2,v$,a$,b$,c$,d$,e$
After reading OK,ALICE, V$ holds OK and A$ holds ALICE.
How to read the examples on this page. They show the lines exactly as
they went to and from a real hub. A > is a line a player's program sent,
and a < is a line the hub sent back:
ALICE > HELLO,1,TICTAC,ALICE,A
ALICE < OK,ALICE
Two small differences from what a Commodore sees:
- The examples log in with flag
A(plain ASCII), as a PC does. So text appears in mixed case. - For a BASIC program, the hub adds empty fields to the end of each line, so
that
GOarrives asGO,,,,,. That way, anINPUT#with six variables always reads exactly one whole line. The examples leave the extra commas out so they are easier to read.
Free text, such as chat, always comes inside double quotes:
SAID,BOB,"HI, EVERYONE". INPUT# keeps commas inside quotes, so the
message arrives whole, in one variable.
You can try all of this from a PC, before you write a line of Commodore code. Connect to the hub with a plain text tool and type the lines yourself. Getting started shows how.
3. Logging in, and the lobby
Play tokens. A member gets play tokens on the My Games page of their
account. A token is eight letters and digits, such as K7Q2M9XP. It lets a
program log in to the hub as that member, and do nothing else. It can't sign
in to the website or change their account. A program asks for the token when
it starts, and keeps it in memory, never on disk, because disks get shared.
Handles. Every member has a handle, the name other players see, such
as ALICE. Members choose their own on My Games.
The lobby. After logging in, a player is in the game's lobby, a waiting room for everyone logged in to that game. Each game has its own lobby. Players in it can chat, see who is around, and find someone to play with.
Here Alice logs in, then Bob. Alice asks who is there and says hello:
ALICE > HELLO,1,TICTAC,ALICE,A
ALICE < OK,ALICE
BOB > HELLO,1,TICTAC,BOB,A
BOB < OK,BOB
ALICE < ARRIVE,BOB
ALICE > WHO
ALICE < USER,ALICE,LOBBY
ALICE < USER,BOB,LOBBY
ALICE < LIST,WHO
ALICE > SAY,ANYONE FOR A GAME?
BOB < SAID,ALICE,"ANYONE FOR A GAME?"
A few things to notice:
- The hub told Alice that Bob arrived (
ARRIVE). Nobody had to ask. WHOgets one line per player, thenLIST,WHOto say the list is finished. Every list from the hub ends that way, so a program knows when to stop reading.SAYis chat. The hub sends it to everyone else in the lobby asSAID, with the speaker's handle. The speaker doesn't get their own words back.
From the lobby, a player can start a match, step into a world, or log out
with BYE. When a match ends, they come back to the lobby:
flowchart LR
L["Log in<br>HELLO"] --> Lobby(("The lobby<br>chat, WHO"))
Lobby -- "MATCH, HOST, INVITE" --> M["A match"]
M -- "OVER" --> Lobby
Lobby -- "WORLD" --> W["A world"]
W -- "LEAVE" --> Lobby
Lobby -- "BYE" --> X["Logged out"]
4. Three kinds of game
When you register a game, you choose what kind it is.
Live. Everyone plays at the same time, connected together, from start to finish. Tic-tac-toe, a card game, a race, a shoot-out. The match starts with everyone, ends with a result, and the players go back to the lobby. You choose how many players a match takes: one or two, or a handful, or more.
Turn-based. The players take turns, and need not be connected at the same time. Alice makes her move on Monday evening and switches off. Bob logs in on Wednesday, sees her move, and makes his. The hub keeps the match and all its moves in between, for days or weeks if your game allows. Chess by mail, battleships, a strategy game.
World. A place that keeps going, which players wander into and out of whenever they like, alone or together. Your game server holds everything about the world: the rooms, the objects, the monsters, what each player is carrying. A text adventure for many players, a MUD, a dungeon, a town. Worlds always have a game server (section 6).
| If your game... | Choose |
|---|---|
| has a start and an end, with everyone playing at once | Live |
| is played a move at a time, and nobody should have to wait at the keyboard | Turn-based |
| has no end, and players come and go | World |
5. A live match, with no server at all
Let's watch Alice and Bob play a live game of tic-tac-toe. There is no game server here: the players' own computers run the game, and the hub just passes their moves along.
ALICE > MATCH
ALICE < WAIT
BOB > MATCH
BOB < WAIT
ALICE < START,1,1,2,1
ALICE < SEAT,1,ALICE
ALICE < SEAT,2,BOB
BOB < START,1,2,2,1
BOB < SEAT,1,ALICE
BOB < SEAT,2,BOB
ALICE > READY
BOB > READY
ALICE < GO
BOB < GO
ALICE > ALL,MARK,5
BOB < FROM,1,MARK,5
BOB > ALL,MARK,1
ALICE < FROM,2,MARK,1
... and so on, until Alice has three in a row ...
ALICE > END,1
BOB > END,1
ALICE < OVER,1,"ALICE WINS"
BOB < OVER,1,"ALICE WINS"
Step by step:
MATCHasks for a quick match. The hub answersWAIT("I'm finding you an opponent"). When Bob asks too, there are enough players.STARTsays a match has formed. Its fields are the match's number (1), your seat (Alice is seat 1, Bob seat 2), how many players there are (2), and which seat is the host (seat 1). ASEATline follows for each player, so every program knows who is who.READY. Before playing, a program may need a moment: to load a character set, draw the board, or load the game itself from disk. It sendsREADYwhen it is ready. When everyone is, the hub sendsGO.ALLsends a message to every other player. Alice sendsALL,MARK,5. Bob receivesFROM,1,MARK,5: "from seat 1,MARK,5".ENDreports who won: seat 1. When the players agree, the hub ends the match withOVER, records the result, and both players are back in the lobby.
MARK,5 means whatever your game says it means. Here it means "I put my
mark in square 5", but the hub never looks inside. You decide what your
messages look like. Keep them short, as they travel over slow modems too.
Seats are the players' numbers within a match: 1, 2, 3 and so on. Your program uses them to tell players apart. Seat 0 is special: it is the game server, if the game has one.
The same match as a picture, with time running downwards:
sequenceDiagram
participant A as Alice's C64
participant H as The hub
participant B as Bob's C128
A->>H: MATCH
B->>H: MATCH
H->>A: START, SEAT, SEAT
H->>B: START, SEAT, SEAT
A->>H: READY
B->>H: READY
H->>A: GO
H->>B: GO
A->>H: ALL,MARK,5
H->>B: FROM,1,MARK,5
B->>H: ALL,MARK,1
H->>A: FROM,2,MARK,1
A->>H: END,1
B->>H: END,1
H->>A: OVER,1,"ALICE WINS"
H->>B: OVER,1,"ALICE WINS"
Other ways to start a match. Quick match pairs up whoever is waiting. Players can also pick their opponents:
- Tables.
HOSTopens a table, others see it withTABLESand sit down withJOIN, and the host starts the game withBEGIN. - Invitations.
INVITE,BOBasks Bob directly, and he answers withACCEPTorDECLINE.
Every match then starts the same way, with START, SEAT, READY and GO.
Other messages. TELL,2,... sends to one seat only, rather than to
everyone. And if Bob's connection drops in the middle of a game, the others
get DROP,2. If Bob logs in again within 2 minutes, the hub puts him back in
his seat, and the others get BACK,2.
6. When you want a game server
The tic-tac-toe above trusts each player's program. Alice's computer decides whether her own move is allowed, and both computers report who won. Among friends that works well. But some games need someone in charge:
- A referee. Someone has to check that moves are allowed, or keep the official score.
- Secrets. In a card game, each player's hand must stay hidden from the others. If the cards were dealt on the players' own machines, a curious player could peek with a machine-language monitor.
- A world. Something has to keep the rooms, the objects and the monsters while players come and go, and remember it all when everyone has gone.
- Heavy lifting. A large map, a clever computer opponent, or a hundred players at once can be too much for an 8-bit computer, but easy for a PC.
That someone is your game server. Here is the key thing to understand about it:
A game server is just another client of the hub, with special powers. It connects to the hub much as a Commodore does, and the hub passes it messages just as it passes them to players. The differences:
- It logs in with the game's server key, a secret password for your game, rather than a play token.
- It is seat 0 in every match. A player sends to it with
TELL,0,..., and everything it sends arrives asFROM,0,.... - It serves all of your game's matches at once, with one connection. A hundred matches going on means one server, not a hundred.
- It can do things players can't. It can end a match and declare the winner, record scores, save data, give out achievements, and move players between places in a world.
Server modes. When you register a game, you choose how much the server is in charge:
| Mode | Like... | What happens to players' messages |
|---|---|---|
relay |
Players passing notes across a table | Straight to the other players. There is no server |
observe |
A referee who reads every note but doesn't stop them | To the other players, and the server gets a copy. The server decides the results |
authority |
Every note goes to the referee, who decides what each player sees | Only to the server. The server sends each player what they should know |
flowchart TB
subgraph relay ["relay: no server"]
direction LR
A1["Alice"] --> H1(("hub")) --> B1["Bob"]
end
subgraph observe ["observe: the server watches"]
direction LR
A2["Alice"] --> H2(("hub")) --> B2["Bob"]
H2 -. "a copy" .-> S2["server"]
end
subgraph authority ["authority: the server decides"]
direction LR
A3["Alice"] --> H3(("hub")) --> S3["server"]
S3 --> H3
H3 --> B3["Bob"]
end
relay ~~~ observe ~~~ authority
observe suits a game whose players' programs already run it, where
you'd like a fair score. authority suits games with secrets, and worlds
always use it.
The server connects to the hub, not the other way round. It reaches out
to play.commodoreonline.com, just as a web browser reaches out to a web
site. So it can run on your own PC at home, behind your router, with nothing
to set up.
7. Your first game server
Let's write a complete game server: Higher or Lower. The server thinks of a number from 1 to 100. The players guess, and the server tells each of them "too high" or "too low". The first to guess right wins.
It is written in Python, with the hub's Python SDK. The SDK (software development kit) is a small library that does the connecting, reconnecting and message formats for you. There are SDKs for Go and C++ as well, which work the same way. Python is a friendly place to start.
Events and calls
A game server is mostly a list of answers to the question "what should happen when...?"
- The hub tells your server what happens: a player joins, a player sends a message, a match ends. These are events.
- Your server answers by asking the hub to do things: send a message, end the match. These are calls.
For each kind of event, you write a small function called a handler, which the SDK calls when that event arrives. You only write the handlers your game needs. Higher or Lower needs four:
| Handler | Called when |
|---|---|
on_join |
A player is in a match. It tells you their seat and handle |
on_ready |
Every player has sent READY. Time to start |
on_msg |
A player sent the server a message (TELL,0,...) |
on_close |
The match is over. Time to tidy up |
It makes two calls:
| Call | What it does |
|---|---|
send_text |
Sends text to a player, or to everyone in the match |
end |
Ends the match, with the winner's seat |
The program
# hilo.py: a tiny game server for the game hub.
# The server thinks of a number; the players guess it.
import asyncio
import random
from retroswitch import gamehub
class HiLo(gamehub.Handlers):
def __init__(self):
self.secret = {} # each match's number, by match id
self.names = {} # each player's handle, by (match, seat)
def on_join(self, s, e):
# A player is in a match. Remember their handle.
self.names[(e.match, e.seat)] = e.handle
async def on_ready(self, s, e):
# Every player has loaded the game: think of a number.
self.secret[e.match] = random.randint(1, 100)
await s.send_text(e.match, gamehub.ALL,
"I'm thinking of a number from 1 to 100.")
async def on_msg(self, s, e):
# A player sent a guess, such as TELL,0,50
secret = self.secret.get(e.match)
if secret is None:
return
guess = int(e.line) if e.line.isdigit() else 0
if guess < secret:
await s.send_text(e.match, e.seat, f"{guess} is too low.")
elif guess > secret:
await s.send_text(e.match, e.seat, f"{guess} is too high.")
else:
name = self.names[(e.match, e.seat)]
await s.send_text(e.match, gamehub.ALL, f"{name} guessed it: {secret}!")
await s.end(e.match, e.seat)
def on_close(self, s, e):
# The match is over. Forget it.
self.secret.pop(e.match, None)
for key in [k for k in self.names if k[0] == e.match]:
del self.names[key]
config = gamehub.Config(addr="localhost:6503", game="HILO", key="dev", insecure=True)
asyncio.run(gamehub.run(config, HiLo()))
Some notes for reading it:
sande. Every handler gets two things.sis the server, which you use to make calls (s.send_text,s.end).eis the event, which holds its details:e.match(which match),e.seat(which player),e.line(what they sent),e.handle(their name).- One server, many matches. Several matches can run at once, so the program keeps each match's secret number in a dictionary, by match number.
asyncandawait. A call goes over the network to the hub, which takes a moment.awaitmeans "do this, and carry on when it's done". A handler that makes calls is writtenasync def. You don't need to know more than that to write a game.- Text.
send_textsends ordinary text. The hub converts it to each player's character set, and wraps it to fit their screen: 40 columns on a C64, 22 on a VIC-20, 80 on an 80-column PET or a C128 in 80 columns. You never count columns. - Turning wrapping off. For text you lay out yourself, such as a map or
a table, use
send_preinstead: the hub breaks lines only where you put newlines, and cuts any line too long for the screen. Andsendsends one line exactly as you give it, for a Commodore program of your own that reads it as data. - The last two lines connect to the hub and start the game. These settings are for the development hub on your own PC (section 12).
What the player sees
This game is registered as a live game in authority mode, for 1 to 4
players. A quick match therefore starts as soon as one player asks. Here is
Alice playing, as a real hub recorded it:
ALICE > HELLO,1,HILO,ALICE,A
ALICE < OK,ALICE
ALICE > MATCH
ALICE < WAIT
ALICE < START,2,1,1,1
ALICE < SEAT,1,ALICE
ALICE > READY
ALICE < GO
ALICE < FROM,0,"I'm thinking of a number from 1 to 100."
ALICE > TELL,0,50
ALICE < FROM,0,"50 is too low."
ALICE > TELL,0,75
ALICE < FROM,0,"75 is too high."
ALICE > TELL,0,62
ALICE < FROM,0,"62 is too low."
ALICE > TELL,0,68
ALICE < FROM,0,"68 is too low."
ALICE > TELL,0,71
ALICE < FROM,0,"ALICE guessed it: 71!"
ALICE < OVER,1,"ALICE WINS"
TELL,0,50 means "tell seat 0, the server: 50". Every answer comes back as
FROM,0, from the server. And because the game is in authority mode, a
guess goes only to the server. If Bob were playing too, he would never see
Alice's guesses, only her win.
Here is how the conversation flows between all three:
sequenceDiagram
participant A as Alice's C64
participant H as The hub
participant S as Your server
A->>H: MATCH
H->>A: START, SEAT
H->>S: open, join (a match, and Alice is in it)
A->>H: READY
H->>A: GO
H->>S: ready
S->>H: send_text "I'm thinking of a number..."
H->>A: FROM,0,"I'm thinking of a number..."
A->>H: TELL,0,50
H->>S: msg: seat 1 says "50"
S->>H: send_text "50 is too low."
H->>A: FROM,0,"50 is too low."
A->>H: TELL,0,71
H->>S: msg: seat 1 says "71"
S->>H: send_text "ALICE guessed it: 71!", then end (seat 1 wins)
H->>A: FROM,0,"ALICE guessed it: 71!"
H->>A: OVER,1,"ALICE WINS"
H->>S: close
What actually travels to the server
You never need to see this, because the SDK takes care of it. But it is
reassuring to know there is no magic. The server's side of the conversation
is lines too, in a format called JSON, which most programming languages read
easily. This is a different, even smaller game, recorded on a real hub. The
server's lines are marked SERVER, and they are interleaved with Alice's in
the order they happened:
SERVER > {"op":"hello","v":1,"game":"RAW","key":"dev"}
SERVER < {"ev":"welcome","game":"RAW","v":1}
ALICE > MATCH
ALICE < WAIT
ALICE < START,6,1,1,1
ALICE < SEAT,1,ALICE
SERVER < {"ev":"open","kind":"live","match":6,"playing":false,"seats":[{"handle":"ALICE","player":1,"seat":1}]}
SERVER < {"cols":40,"ev":"join","handle":"ALICE","match":6,"player":1,"seat":1}
ALICE > READY
ALICE < GO
SERVER < {"ev":"ready","match":6}
SERVER > {"op":"send","match":6,"to":"all","text":"Say something!"}
ALICE < FROM,0,"Say something!"
ALICE > TELL,0,HELLO SERVER
SERVER < {"ev":"msg","line":"HELLO SERVER","match":6,"seat":1,"to":0}
SERVER > {"op":"send","match":6,"to":1,"text":"You said HELLO SERVER."}
ALICE < FROM,0,"You said HELLO SERVER."
SERVER > {"op":"end","match":6,"result":1,"reason":"ALICE WINS","id":1}
SERVER < {"ev":"close","match":6,"reason":"ALICE WINS","result":1}
SERVER < {"ev":"reply","id":1,"ok":true}
ALICE < OVER,1,"ALICE WINS"
The "id":1 on the last op asks the hub to answer when it's done, which it
does with "reply".
Each event the SDK hands to a handler is one of those "ev" lines, and each
call sends one "op" line. Because it is all plain lines, a server can be
written in any language, with or without an SDK. The
game servers page describes every line.
If the server stops
Servers get restarted: for an update, or because the PC was switched off.
While yours is away, players who send it something get an error (ERR,51),
and a notice from the hub. The SDK keeps trying to reconnect by itself. When
it gets back, the hub tells it about every match and world still running,
with an on_open and an on_join for each player, so it can carry on.
8. Turn-based games
A turn-based game works much like a live one, with three differences:
- A move is sent with
TURN, and the hub stores it. - The hub keeps track of whose turn it is, and says so with
NEXT. - Players can leave and come back days later. The match waits for them.
Here Alice and Bob start a game of chess. Alice moves. Bob steps away from the match, then comes back to it later:
ALICE < GO
ALICE < NEXT,1
BOB < GO
BOB < NEXT,1
ALICE > TURN,E2E4
ALICE < NEXT,2
BOB < FROM,1,E2E4
BOB < NEXT,2
BOB > LEAVE
BOB < OK
... later ...
BOB > MINE
BOB < TURNS,1,ALICE,YOU
BOB < LIST,MINE
BOB > RESUME,1
BOB < START,1,2,2,1
BOB < SEAT,1,ALICE
BOB < SEAT,2,BOB
BOB < HIST,1
BOB < FROM,1,E2E4
BOB < NEXT,2
BOB > TURN,E7E5
BOB < NEXT,1
NEXT,1says it is seat 1's turn. A program shows "your move" when the seat is its own, and "waiting for Alice" when it isn't.MINElists the player's matches.TURNS,1,ALICE,YOUsays that in match 1, with Alice, it is your turn. The hub also sends these lines by itself when a player logs in, so nobody misses a turn.RESUME,1reopens the match.HIST,1says one stored move follows, and the program replays it to rebuild the board. ThenNEXTsays whose turn it is now.
sequenceDiagram
participant A as Alice's C64
participant H as The hub (stores the moves)
participant B as Bob's C128
A->>H: TURN,E2E4
H->>B: FROM,1,E2E4 and NEXT,2
Note over B: Bob switches off
Note over A,B: two days later
B->>H: HELLO, then RESUME,1
H->>B: START, SEAT, HIST,1, FROM,1,E2E4, NEXT,2
B->>H: TURN,E7E5
Note over A: Alice is told it's her turn when she next logs in
When you register a turn-based game, you set a turn limit: how long a player may take over a move before they forfeit. It can be anything from a minute to a year, or no limit at all.
A turn-based game can have a server too. It gets each move (on_turn), and
can check it, end the match, or decide whose turn is next.
9. Worlds
A world is a place that keeps going. Players drop in and out whenever they like. Your game server holds everything about it: the map, the objects, the monsters, the puzzles, and what each player has done. The hub looks after the people: who is logged in, where each of them is, and who can hear whom.
Places
A world is divided into places. A place is whatever your game wants it to be: a room in a cave, a square on a map, a level of a dungeon. The server moves players between places, and the hub uses them to decide who sees what:
- When a player moves into a place, the players already there are told
(
ENTER), and so are those left behind (EXIT). - Chat (
SAY) reaches only the players in the same place. WHOlists only the players in the same place.- The server can send a message to everyone in a place at once.
flowchart LR
subgraph MOUTH ["Place: MOUTH"]
C["Carol"]
end
subgraph GROTTO ["Place: GROTTO"]
A["Alice"]
B["Bob"]
end
MOUTH -- "IN" --> GROTTO
GROTTO -- "OUT" --> MOUTH
Here Alice and Bob can chat with each other, but Carol hears neither of them.
A small world
This server is a cave with two places. Players type IN, OUT or LOOK:
# cave.py: a tiny world for the game hub, with two rooms.
import asyncio
from retroswitch import gamehub
# Each room: its description, and where its exits lead.
ROOMS = {
"MOUTH": ("You stand at the mouth of a cave. A path leads in.",
{"IN": "GROTTO"}),
"GROTTO": ("A damp grotto. Water drips somewhere in the dark.",
{"OUT": "MOUTH"}),
}
class Cave(gamehub.Handlers):
def __init__(self):
self.where = {} # each player's room, by (match, seat)
async def on_join(self, s, e):
# A player has entered the world: start them at the cave's mouth.
await self.move(s, e.match, e.seat, "MOUTH")
async def on_msg(self, s, e):
# A player typed a command, such as IN or LOOK.
room = self.where.get((e.match, e.seat))
if room is None:
return
command = e.line.strip().upper()
description, exits = ROOMS[room]
if command == "LOOK":
await s.send_text(e.match, e.seat, description)
elif command in exits:
await self.move(s, e.match, e.seat, exits[command])
else:
await s.send_text(e.match, e.seat, "Try LOOK, IN or OUT.")
async def move(self, s, match, seat, room):
# Put the player in a room, and tell them what they see.
self.where[(match, seat)] = room
await s.place(match, seat, room)
description, exits = ROOMS[room]
await s.send_text(match, seat, description)
def on_leave(self, s, e):
# The player left the world.
self.where.pop((e.match, e.seat), None)
config = gamehub.Config(addr="localhost:6503", game="CAVE", key="dev", insecure=True)
asyncio.run(gamehub.run(config, Cave()))
The new call is s.place, which moves a player to a place. The hub does
the rest: it tells the right people who has arrived and who has gone.
A world is a world for the hub too, so "match" in this code means the world itself. Every player in it has a seat, just as in a match.
Alice enters first and goes in. Then Bob arrives:
ALICE > HELLO,1,CAVE,ALICE,A
ALICE < OK,ALICE
ALICE < START,4,1,0,0
ALICE > READY
ALICE < GO
ALICE < FROM,0,"You stand at the mouth of a cave. A"
ALICE < FROM,0,"path leads in."
ALICE > TELL,0,IN
ALICE < FROM,0,"A damp grotto. Water drips somewhere in"
ALICE < FROM,0,"the dark."
BOB > HELLO,1,CAVE,BOB,A
BOB < OK,BOB
BOB < START,4,2,0,0
BOB > READY
BOB < GO
BOB < FROM,0,"You stand at the mouth of a cave. A"
BOB < FROM,0,"path leads in."
BOB > TELL,0,IN
BOB < ENTER,1,ALICE
BOB < FROM,0,"A damp grotto. Water drips somewhere in"
BOB < FROM,0,"the dark."
ALICE < ENTER,2,BOB
BOB > SAY,HELLO?
ALICE < SAID,BOB,"HELLO?"
ALICE > TELL,0,OUT
ALICE < FROM,0,"You stand at the mouth of a cave. A"
ALICE < FROM,0,"path leads in."
BOB < EXIT,1
- Straight in. This world has no lobby: a player is in it as soon as they
log in (
START, thenREADYandGO). More about that below. - The wrapping. The server sent each description as one sentence. The hub broke it into lines that fit a 40-column screen, at the spaces between words.
ENTERandEXITcame from the hub, not the server. When Bob went in, he was told that Alice was already there, and she was told he'd arrived. When Alice went out, Bob saw her go.- Chat stays in the room. Bob's
HELLO?reached Alice because they were both in the grotto.
One world, or a world each
When you register a world, you choose its instances: how many copies of the world there are.
| Instances | What players get | Good for |
|---|---|---|
| Shared | One world, which everyone enters. Players log in and they are in it, as in the cave above | A town, a MUD, a big persistent dungeon |
| Party | A group forms in the lobby, as for a match, and gets its own copy of the world. The hub saves it, and the group can come back to it another day | A cooperative adventure for a few friends, where others mustn't wander in and spoil the puzzle |
| Both | The lobby first. WORLD enters the shared world, and a party forms with MATCH, HOST or INVITE |
A world with expeditions for small groups |
You also choose who announces arrivals, the presence setting. With
hub, the hub sends ENTER and EXIT, as in the cave. With server, your
server tells the story itself ("Bob climbs down the rope, dripping wet").
A world doesn't have to be text
Worlds suit text adventures very well, but nothing about them is limited to text. A world server can send binary frames, small packets of bytes, to a machine-language program that draws the screen. A roguelike, where each dungeon room is a place and the server sends "the orc moves to 12,7", is a world too. The protocol page describes frames.
10. The Commodore side
There are three ways to write the part that runs on the Commodore. Choose whichever suits your game and your experience.
The hub itself doesn't mind which Commodore a player has: a program says how wide its screen is when it logs in. The ready-made programs below run on these machines:
| Machine | Devices | Ready-made programs |
|---|---|---|
| C64, and a C128 in C64 mode | A Flyer, a WiFi modem on the user port, a SwiftLink | The text client, playlib, the lobby |
| PET with BASIC 4 and 32 KB, 40 or 80 columns | A Flyer | The text client, playlib |
| VIC-20, and any Commodore with a Flyer | A Flyer | None yet: a BASIC program talks to the hub directly, through the Flyer's tcp: channel (below) |
The ready-made text client: no Commodore code at all
For text worlds, and any game where the server does the talking, there is a ready-made text client. It shows what the server sends, carries chat, and sends each line the player types to the server. You write only the server.
- Typing
go northsendsTELL,0,GO NORTHto your server. - Typing a line that starts with a quote mark sends chat:
"hello all. - Typing a line that starts with
/sends a command to the hub:/who,/world,/match 2,/bye./helplists them.
A small file on the disk, WORLD, names your game, so the client goes
straight to it. Another, TITLE, holds a welcome shown before connecting.
The website can build the whole disk for a world game, ready to offer on the
game's page. See text worlds.
BASIC, with playlib
playlib is a small machine-language library that does the networking for
a BASIC program. It loads high in memory, out of BASIC's way: at $C000 on
the C64, and at $7000 on a PET. You call it with SYS. It works the same
on every device it supports: load a different build of it for a Flyer, a WiFi
modem on the user port or a SwiftLink, and nothing else in your program
changes. On a PET the SYS addresses are lower, so a game for both machines
keeps them in variables.
The heart of a BASIC game is a loop that checks for a line from the hub, checks the keyboard, and goes round again. With playlib, reading a line takes a few milliseconds, and gives empty strings when nothing has arrived:
100 sys rd,v$,a$,b$,c$,d$,e$:if v$<>"" then gosub 1000
110 get k$:if k$="" then 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
(The listing is in lowercase, as petcat writes it. On a Commodore in its
normal uppercase mode, the letters show as capitals.)
Getting started has the complete program, and explains every line.
There is also a ready-made lobby program. It handles chat, finding opponents and starting matches, then loads your game when a match begins, and goes back to the lobby when it ends. You write only the game itself.
A Flyer can also talk to the hub from BASIC without playlib, through its
tcp: channel. Getting started
has that version too.
Machine language and cc65
playlib has a jump table for machine-language programs, and works from cc65's C as well. Fast action games will want binary frames: compact messages of bytes rather than text. See playlib.
11. What the hub keeps for you
Besides passing messages, the hub keeps a few things, so your game doesn't need a server just to remember them.
Leaderboards. When you register a game, you can give it up to 8
leaderboards: high scores, fastest times, most gold. A program submits a
score with SCORE, and asks for the top of a board with TOP:
BOB > SCORE,HIGH,950
BOB < RANK,HIGH,1,BOB,950
ALICE > SCORE,HIGH,1200
ALICE < RANK,HIGH,1,ALICE,1200
ALICE > TOP,HIGH,3
ALICE < RANK,HIGH,1,ALICE,1200
ALICE < RANK,HIGH,2,BOB,950
ALICE < LIST,TOP
Each RANK line gives the board, the place, the handle and the score. Live
and turn-based games also get a WINS board automatically, from their
results. The boards show on the game's page on the website. If cheating would
matter, you can make a board one that only your server may submit to.
Saved data. Each player can keep a little data in each game, up to 64 KB
in all: a level reached, a character, settings. PUT saves a value, and
GET reads it back, from any machine:
ALICE > PUT,LEVEL,7
ALICE < OK
ALICE > GET,LEVEL
ALICE < VAL,LEVEL,7
A server can read and write the same values, and keep data of its own for the whole game.
Achievements and a page. A game server can award achievements ("First try!"), which show on the player's My Games page and on the game's page. It can also publish a page of text about the game, such as the state of the world or a hall of fame, which shows on the game's page.
12. From an idea to players
Here is the usual path from an idea to a game people play.
- Register your game on My Games. Choose its id carefully: 1-8 letters
and digits, such as
HILO, and it can never be changed. A new game starts private: only you, and the testers you name, can see it or play it. Anyone else who tries is told there is no such game. - Write it, and try it. The development hub is a copy of the hub that runs on your own PC. It needs no registration and no play tokens: log in with any name and that is your handle. It is on the downloads page, for Windows, macOS and Linux.
-
If it has a server, make a server key on your game's settings page. It is shown once, so copy it then. Keep it out of your program's source code: put it in a file or a setting, and change the two lines that connect:
import os config = gamehub.Config(addr="play.commodoreonline.com:6503", game="HILO", key=os.environ["HILO_KEY"])Your server can run on your own PC while you develop, or on any machine that stays switched on once people play.
- Invite testers. Add their handles on your game's settings page. They can play it straight away, and nobody else can.
- Open it up. Set the game to
link(anyone who knows its id can play, but it isn't listed) orpublic(it is listed in the games directory). You can clear the leaderboards first, so test scores don't linger.
Changing a game later. You can improve your game at any time. If a new
version can't play against the old one, register it as a new game with a new
id (HILO2), so players with the old disk aren't confused.
13. Where to go next
| When you want to... | Read |
|---|---|
| Get a play token, register a game, and type in a first BASIC program | Getting started |
| Look up a command, a reply, an error code or a limit | The Commodore protocol |
| Use playlib from BASIC, machine language or cc65 | playlib |
| Ship the ready-made text client with your world | Text worlds |
| Write a game server, in Python, Go or C++ | Game servers |
14. Words used on these pages
| Word | Meaning |
|---|---|
| Authority mode | Players' game messages go only to the game server, which decides what everyone sees |
| Call | Something a game server asks the hub to do: send a message, end a match |
| Event | Something the hub tells a game server: a player joined, a player sent a message |
| Field | One part of a line, between commas |
| Frame | A compact message of bytes, for machine-language games |
| Game id | A game's permanent name for the hub, such as TICTAC |
| Game server | Your own program, which connects to the hub and runs a game's rules |
| Handle | A player's name, as other players see it |
| Handler | A function in a game server that runs when an event arrives |
| Hub | The program at play.commodoreonline.com that every game goes through |
| Instance | A copy of a world: the shared one, or a party's own |
| Lobby | Each game's waiting room, for chat and finding a match |
| Match | One game being played, from START to OVER |
| Observe mode | Players' messages go to each other as usual, and the game server gets a copy |
| Party | A group of players with their own copy of a world |
| Place | A part of a world, such as a room. Players in the same place see and hear each other |
| Play token | The eight-character code a Commodore program logs in with |
| playlib | The machine-language library that does the networking for Commodore programs |
| Relay mode | No game server: the hub passes players' messages between them |
| SDK | A library for writing game servers. There are SDKs for Python, Go and C++ |
| Seat | A player's number in a match or world. Seat 0 is the game server |
| Server key | The secret password a game server logs in with |
| Verb | The first word of a line, which says what the line is for |
| World | A persistent game run by a game server, which players drop in and out of |
