Text worlds
A text world needs no game program on the Commodore. The text client is one program for every text world on the hub, on a C64 or a PET: it shows what the game server sends, other players' chat and arrivals, and sends what the player types. An author writes only the game server; players need nothing but the client's disk.
The client is machine language on playlib. One disk serves
every machine and device: a small BASIC boot program, TEXTCLIENT, sees
whether it runs on a C64 (or a C128 in C64 mode) or a PET with BASIC 4, finds
the device, loads the right playlib and runs the client for that machine. On
a C64 the device may be a Flyer, a modem on the user port or a SwiftLink; on
a PET, a Flyer. It is on the downloads page,
with playlib.
For players
LOAD"TEXTCLIENT",8
RUN
The client shows the disk's title, if it has one, finds the device and says
which (Device: a Flyer.), asks for the game's id (unless the disk names
it), then for your play token (unless this session has one), connects to
play.commodoreonline.com and logs in.
The play token is asked for once a session and kept in memory, never on
the disk. A program run after the client, or the client run again, finds it
there until the machine is switched off. A refused token (Error 20) is asked
for again.
The device. If something answers on unit 7, the boot program takes it for
a Flyer. Otherwise, on a C64, it asks once which modem you have (1 on the
user port, 2 a SwiftLink) and remembers the answer for the session; on a PET
it says NO FLYER ON UNIT 7. A PET needs 32 KB.
The screen
| Rows | What |
|---|---|
| 0-21 | What comes in, scrolling up. Long lines wrap at spaces |
| 22 | The status line: the game, your handle, the device, and LOBBY, WORLD or OFFLINE |
| 23-24 | What you type, after >: up to 72 characters |
On an 80-column PET, rows 0-22 scroll, row 23 is the status line and row 24 is the input line.
Incoming text never touches the input line, so a half-typed command survives a busy room. Each line you send is also shown in the scrolling area.
| Color | What |
|---|---|
| White | The game's text |
| Cyan | Chat, after the speaker's handle: BOB: Right, I'm going down. |
| Yellow | Arrivals and departures: BOB is here., BOB has gone. |
| Light green | The hub's replies: lists, parties, Ok. |
| Light red | Errors and notices: Error 12: ..., THE GAME SERVER IS AWAY |
| Light grey | What you typed |
| Grey | A line the client doesn't know, as it came |
A PET has no colors. There, every line that isn't the game's text starts with
its first word in reverse video: the speaker's handle in chat and arrivals, a
reversed > before what you typed.
A game server can't change colors or send reverse video, and everything it sends arrives as the game's voice, so it can't look like a player.
What you type
| Typed | Sent | For |
|---|---|---|
go north |
TELL,0,GO NORTH |
The game. Letters go in capitals, whichever case you typed. A quote mark becomes an apostrophe |
"hello all |
SAY,hello all |
Chat to everyone in the same place, as typed |
/who |
WHO |
The players in your place (in the lobby, everyone in the game) |
/match 2 |
MATCH,2 |
Form a party of two by quick match. Or /host 3, and the others /join <id>; or /invite bob, and Bob types /accept <id> |
/world |
WORLD |
Enter the game's shared world. A game with only a shared world puts you in at login |
/mine |
MINE |
Your saved parties: Party 12 of ALICE: /resume 12 |
/resume 12 |
RESUME,12 |
Go back into party 12 |
/decline 12 |
DECLINE,12 |
Leave party 12 for good |
/leave |
LEAVE |
Out of the world, to the lobby |
/bye |
BYE |
Log out |
/help, /help more |
(nothing) | A short help on the screen; then the party and lobby commands |
/sound |
(nothing) | Sounds off, or on again, until the machine is switched off (below, "A world's look and sound") |
Any line starting with / is sent as a hub verb in capitals, with commas for
spaces, so every verb in the protocol works. The
client answers START with READY by itself.
For authors: what the server should send
The client is generic: it shows whatever the server sends, so a text world is all server.
| Point | What to do |
|---|---|
| Registration | Kind world, which is always in authority mode. Instances: party (each group its own saved copy), shared (one world, entered at login) or both. Arrivals: server if the server narrates them, hub for the client's BOB is here. |
| Text | send with text (the SDKs' SendText). The hub converts it to the client's mixed case and wraps it to the client's width: 39 columns on a C64 or a 40-column PET, 79 on an 80-column PET. A newline starts a line; two newlines make a blank line, and so does a newline at the start, which sets a description apart. Keep paragraphs short: a C64 reads about 9 lines a second through a Flyer, 7 through a modem at 2400 baud, and about one at 300 baud |
| Preformatted text | wrap: false (SendPre), up to 39 characters a line (a map that suits every screen) |
| Payload lines | Avoid send with line: the client shows it as it is, quotes and commas included |
| Commands | They arrive as msg from the seat, to 0: the line as typed, in ASCII capitals (GO NORTH), or in the case typed with the setting "Commands: as typed" (below), at most 72 characters, with any " made '. In the terminal look a player can type up to 150 characters: a longer command arrives in pieces, each but the last ending in ~ (which a Commodore can't type), split where a space was. Join them with a space. Split commands into words, and be generous with synonyms |
| Chat | Players' SAY reaches the others in their place, and the server too (say), for a password spoken aloud. The client shows it in its own color; the server can't |
| Entering | In a world, join comes once the client has sent READY. Place the player (place) and describe where they are: the client shows nothing of its own then |
| Arrivals | With arrivals by the server, tell the others when someone comes and goes ("BOB goes down.", "ALICE arrives."), and list who is there in each description. With hub, the client shows ENTER and EXIT as sentences |
| Leaving | leave comes when a player goes back to the lobby or is gone for good. Tell those still there |
| The end | end on a party closes it for good and records the result. The players see Back in the lobby: <reason> |
| When the hub is busy | Its storage can be unreachable for a moment: saving, reading and ending then fail with busy. Check each one, and try again a few seconds later until it holds |
| Reconnects | When the connection to the hub drops, the SDK reconnects, and the hub sends open and join again for every party still running. Keep the state of a party you already know; read saved data only for one you don't |
| Screen widths | 40 columns, or 80 on an 80-column PET (join says cols 40 or 80). The hub does the wrapping, so a server that sends paragraphs needn't care |
What the client shows for each line
| Line from the hub | Shown |
|---|---|
FROM,0,"text" |
The text. FROM,0,"" is a blank line. A payload without quotes is shown as it is. A quote in your text arrives doubled ("", flag Q) and is shown as one, so 10 PRINT "HELLO" shows as written |
SAID,BOB,"hi" |
BOB: hi, in cyan |
ENTER,3,BOB, EXIT,3 |
BOB is here., BOB has gone. |
ARRIVE,BOB, DEPART,BOB |
BOB is in the lobby., BOB has left the lobby. |
USER,BOB,PLAY |
BOB (play) |
TURNS,12,ALICE,PARTY |
Party 12 of ALICE: /resume 12 |
TABLE,7,ALICE,2,4 |
Table 7 of ALICE, 2 of 4: /join 7 |
INVITED,7,ALICE |
ALICE invites you: /accept 7 |
JOINED, DECLINED, CLOSED |
BOB joins your table., BOB says no., Closed: <reason> |
WAIT |
Waiting for the others... |
START,12,..., SEAT,1,ALICE |
Entering world 12..., ALICE is in the party. |
OVER,0,"THE LEDGER IS FOUND" |
Back in the lobby: THE LEDGER IS FOUND |
NOTE,"...", ERR,12,"..." |
The notice; Error 12: ... |
OK,ALICE (to HELLO) |
Logged in as ALICE. Type /help for help. |
GO, LIST,... |
Nothing |
The client logs in with HELLO,1,<game>,<token>,MXQ0: mixed case, lines up
to 160 bytes, doubled quotes, no padding.
Shipping the client with your world
Put the client's disk together with two optional sequential files, so players go straight to your world.
WORLD, one line each, each ending in a CR:
| Line | What | If empty or missing |
|---|---|---|
| 1 | The game's id. With it the client doesn't ask | Asked for |
| 2 | The hub's host | play.commodoreonline.com |
| 3 | Its port | 6502 |
| 4 | The device: flyer, swift or rs232 (the first letter counts) |
The client finds it |
| 5 | A test script, for automated tests (the client's README) | No test mode |
| 6 | The client's settings, a letter each (below): such as t1sk |
The standard look, text at once, no sounds, commands in capitals |
MILL
play.commodoreonline.com
6502
TITLE: your welcome, shown in white before the client connects. Lines of
up to 79 characters, wrapped at spaces.
A world's look and sound
A world can ask the client to present it differently. Set them on your game's
disk settings page, beside the title; the site writes them into the standard
disk's WORLD, and the play page (Play in your browser on the game's
page) follows them too. With a disk of your own, write the sixth line of
WORLD yourself.
| Setting | Letter | What changes |
|---|---|---|
| Look: terminal | t |
Like a dumb terminal: no status line, none of the client's own lines (Logged in as ..., Device: ...), the token asked for as PLAY TOKEN:, and NO CARRIER when the connection drops. A black screen, your text in phosphor green, chat and the others in shades of their own. Up to 150 characters typed, on the bottom four rows. The boot program doesn't mention the game hub |
| Text speed: 1200 or 300 baud | 1 or 3 |
Your text, and the title, appear a character at a time: 120 a second, or 30. Text that has waited 2 seconds is shown at once, so a busy room never falls behind |
| Sounds | s |
On a C64: a relay's click for each character shown, a tick for each key, and a dial tone, touch tones, a ring and a modem's handshake while connecting. Players turn them off with /sound, and on the play page with a switch |
| Commands: as typed | k |
Commands keep the case they were typed in, instead of capitals. For chat worlds |
The letters go in any order, in either case: t1sk is all four. A player
who prefers the standard look can play the same world from any other disk,
or type the game's id at the client's own disk.
The example: the mill
The Go SDK's mill example is a whole cooperative text adventure for the
client, in about 480 lines of Go: a party of two to four finds a lever at the
sluice and a brake in the wheel pit, and must work them together to open the
loft. It is registered as a world with party instances and arrivals by the
server, and it saves each party's progress so that a party can go home and
resume later. See game servers.
