playlib: the library for the C64 and the PET
playlib connects a C64 or PET program to the hub. It turns the bytes a network device delivers into whole lines and frames, keeps them in a receive buffer, sends lines and frames, splits lines into fields, and keeps an idle connection alive. It also keeps a session in memory, so the player types the play token once, not once per program.
- BASIC calls it with
SYS, at fixed addresses. - Machine language calls the same jump table with registers.
- cc65 programs link it and call it from C.
This page describes interface version 4. playlib, the lobby and the examples are on the downloads page.
The builds
| File | For | Size |
|---|---|---|
playlib-flyer |
C64: a Flyer's tcp: channel, any firmware |
About 2.1 KB from $C000 |
playlib-rs232 |
C64: a Hayes modem on the user port, at 300, 1200 or 2400 baud | About 2.8 KB from $C000 |
playlib-swift |
C64: a Hayes modem on a SwiftLink | About 2.3 KB from $C000 |
playlib-pet |
A PET with BASIC 4 and 32 KB: a Flyer on the IEEE-488 bus | About 2.3 KB from $7000 (the PET) |
playlib-flyer.lib, -rs232.lib, -swift.lib |
cc65 programs on the C64: the same core and driver, linked into the program | About 1.5 KB of code and data with the Flyer driver, plus its buffers |
The C64's PRGs load at $C000. Their buffers and the session take
$CB00-$CDFF, outside the file. The user-port build also uses $CE00-$CEFF
for what it is sending.
Memory
| Range | What |
|---|---|
$C000-$C03F |
The jump table |
$C040-$C05F |
The variables |
$C060-$CAFF |
Code and data |
$CB00-$CBA1 |
MSG: the current line or frame |
$CBA2-$CC25 |
What is being sent |
$CC26-$CC63 |
The session |
$CC64-$CCFF |
Free |
$CD00-$CDFF |
The receive buffer |
$CE00-$CEFF |
User-port build only: what is being sent. Free otherwise |
$CF00-$CFFF |
Free |
playlib uses zero page $FB-$FE during its calls, and logical files 120 and
121.
From BASIC
Load the build for your device from the program, not in direct mode: a
LOAD ,8,1 in direct mode moves BASIC's variables to the end of the file.
10 if pl=0 then pl=1:load"playlib-flyer",8,1
20 so=49182:rd=49185:sn=49188:pe=49216:tg=49200:tp=49203
30 sys tg,t$:if t$="" then input "play token";t$:sys tp,t$
35 h$="play.commodoreonline.com":hp=6502
40 sys so,h$,hp:if peek(pe) then print "no hub";peek(pe):end
50 sys sn,"hello",1,"tictac",t$,"u0"
60 sys rd,v$,a$,b$,c$,d$,e$:if v$="" then 60
70 if v$<>"ok" then print "login failed: ";a$;" ";b$:end
- A
LOADin a program runs the program again from the top with its variables, soPLsays the library is there. - Line 30 takes the token from the session, or asks for it and keeps it there for the programs that follow.
- Line 40 connects to the hub named in line 35, whatever the device: a Flyer opens
tcp:, a modem dials. - Line 50 sends
HELLO,1,TICTAC,<token>,U0. Flag0asks for no padding: playlib splits lines itself, and padding only costs time on the line (2.2 ms a comma on a Flyer, 33 ms at 300 baud). AddBfor frames andXfor lines up to 160 bytes. - Line 60 is the whole read loop.
SYS 49185returns at once, withV$empty when nothing has come.
The SYS entries
| SYS | Arguments | What it does |
|---|---|---|
| 49152 | Init: checks the session, closes any connection, empties the buffer. Settings are kept | |
| 49155 | Close the connection. A modem hangs up first (+++, ATH), which takes about 2.6 s |
|
| 49158 | Poll the device now, if a poll is due. Rarely needed: SYS 49185 polls by itself. Afterwards PEEK(780) is the bytes buffered |
|
| 49161 | Ask the device if the connection is up: PEEK(49219) is 1 if so, 2 if the hub has gone |
|
| 49182 | ,host$,port |
Connect. PEEK(49216) is 0 if it worked, else the error. The host (up to 40 characters) and port go into the session |
| 49185 | [,v$,a$,...] |
Take the next line or frame, if there is one. For a line, the variables get its fields, the verb first, and "" past the end of the line. When nothing came (or a frame did), the first variable gets "" and the others are left alone. PEEK(49217): 0 nothing, 1 a line, 2 a frame |
| 49188 | ,a[,b,...] |
Send a line: the arguments with commas between them. Strings go as they are; numbers go without the space STR$ adds. SYS 49188,"all","mark",q sends ALL,MARK,5. More than 79 characters stops the program with ?STRING TOO LONG |
| 49191 | ,seat,d$ |
Send a frame of D$'s bytes (0-127) to a seat: 0 the game server, 255 everyone else |
| 49194 | ,n,f$ |
Field n of the current line (0 is the verb) into F$, or "" |
| 49197 | ,l$ |
The whole current line into L$. For a frame: the sender's seat (ASC(L$)), then the data |
| 49200 | ,t$ |
The session's play token into T$, or "" if there is none |
| 49203 | ,t$ |
Keep T$ as the session's play token. Shifted letters are kept unshifted. "", or a token with characters other than letters, digits and -, forgets the session. More than 16 characters: ?STRING TOO LONG |
| 49206 | ,name$,unit |
Close the connection, then load the program NAME$ from UNIT and run it, as LOAD and RUN typed would. playlib and the session stay. See run |
| 49209 | Hold: call it just before a disk access while connected. A modem holds back what the hub sends until the next read. A Flyer needs nothing. See disk access |
Fields follow INPUT#'s rules, so a field that starts with a quote runs to
the next quote and loses both, keeping commas and colons inside. Unlike
INPUT#, a read never takes fields from the next line, and never stops the
program.
Memory locations
| Address | Name | Default | Meaning |
|---|---|---|---|
49216 ($C040) |
PL_ERR |
The last error, 0 if none | |
49217 ($C041) |
PL_TYPE |
What the last read found: 0 nothing, 1 a line, 2 a frame | |
49218 ($C042) |
PL_LEN |
Its length in MSG (for a frame: the seat and the data) |
|
49219 ($C043) |
PL_UP |
0 closed, 1 connected, 2 open but the hub has gone (what it sent can still be read) | |
49220 ($C044) |
PL_UNIT |
7 | Flyer: the device's unit |
49221 ($C045) |
PL_CHAN |
2 | Flyer: the device's channel |
49222 ($C046) |
PL_LFN |
120 | playlib's logical files: this and the next |
49223 ($C047) |
PL_EVERY |
15 (Flyer), 0 (modems) | Jiffies between device polls; 0 polls whenever the buffer is empty |
49224 ($C048) |
PL_PORT |
6502 | Machine language: the port for open (low, high) |
49226 ($C04A) |
PL_DRIVER |
1 the Flyer, 2 the user port, 3 a SwiftLink | |
49227 ($C04B) |
PL_VER |
4 | The interface version. Check it to be sure the playlib in memory is the one you wrote for |
49228 ($C04C) |
PL_CHUNK |
0 | The most bytes taken from the device in one poll; 0 for no cap |
49229 ($C04D) |
PL_LOST |
0 | Bytes a driver had to drop because the buffers were full (stops at 255) |
49230 ($C04E) |
PL_BAUD |
2 (user port), 30 (SwiftLink) | Modems: the port's speed. User port: 0 for 300 baud, 1 for 1200, 2 for 2400; connecting tries this speed first, then the others, and leaves the one the modem answered at here (the speed). SwiftLink: the ACIA's control byte, 28 for 9600, 30 for 19,200, 31 for 38,400; set it before connecting |
49231 ($C04F) |
PL_KEEP |
60 | The keep-alive: seconds without a send before a NOP; 0 turns it off |
49232-49234 ($C050) |
PL_SENT |
The jiffy clock when playlib last sent: low, middle, high | |
51968 ($CB00) |
MSG |
The current line (then a 0) or frame (the seat, then the data). 162 bytes | |
52262 ($CC26) |
PL_TOKEN |
The session: the token's length (0-16), then the token | |
52279 ($CC37) |
PL_HOST |
The session: the host, then a 0 (40 characters at most) | |
52320 ($CC60) |
PL_HPORT |
The session: the port (low, high) | |
52322 ($CC62) |
PL_DEVICE |
The session: the modem the player named (2 the user port, 3 a SwiftLink), then that value EOR 255. playlib doesn't use it; programs that ask the player keep the answer here |
PL_CHUNK is for programs that echo typing while text arrives. A Flyer reads
everything waiting in one bus transaction, and a full buffer of 255 bytes
takes about 0.55 s. With POKE 49228,48 no call takes more than about
0.18 s, at the price of more polls.
Errors
PL_ERR |
Meaning |
|---|---|
| 0 | None |
| 1-9 | A KERNAL error. 4: no such file (SYS 49206); 5: no device on the unit |
| 20-29 | The Flyer's status: 23 no such channel, 24 no free socket, 25 no such host, 29 no connection. Firmware 1.2.2 reports 24 for all three |
| 30-35 | The modem's answer to dialing: 30 NO CARRIER, 31 BUSY, 32 NO ANSWER, 33 ERROR, 34 NO DIALTONE, 35 no answer within 30 s. Also 30 when sending after the carrier was lost |
| 100 | No connection is open |
| 101 | The line or frame is too long |
Before the program ends, call SYS 49155. CLR, RUN and NEW forget
BASIC's open files without closing them: a Flyer then keeps the connection
until the next open, and a modem stays online.
From machine language
The same jump table, with registers. A, X and Y are not kept.
| Address | Entry | In | Out |
|---|---|---|---|
$C000 |
init | Checks the session, closes, empties the buffer | |
$C003 |
close | ||
$C006 |
poll | A: the bytes buffered. Reads from the device if a poll is due | |
$C009 |
status | C set if connected; PL_UP |
|
$C00C |
get | A = PL_TYPE, Z set if nothing. The line or frame is in MSG, PL_LEN bytes |
|
$C00F |
open | A/X: the host, ending in 0. PL_PORT: the port |
C clear if connected; else C set and the error in A |
$C012 |
sendline | A/X: the bytes, Y: how many (0-79), without the CR | C clear if sent; else C set and the error in A |
$C015 |
sendframe | A/X: the seat, then the data. Y: how many bytes in all (1-128) | The same |
$C018 |
field | A: the field's number | C clear: X its offset in MSG, Y its length. C set: no such field |
$C01B |
run | The name set with the KERNAL's SETNAM ($FFBD); A: the unit |
Closes the connection, loads the program into BASIC's memory and runs it. Returns only if there is no such file: C set, 4 in A and PL_ERR |
$C01E-$C036 |
The BASIC entries | They read their arguments from BASIC's text: not for machine language | |
$C039 |
hold | Before a disk access while connected, as SYS 49209 |
get never waits beyond one device poll. A line arrives whole or not at all:
playlib keeps a partial line in its buffer until its CR comes.
From cc65
Link the library for the device with the program, and include playlib.h:
cl65 -t c64 -O -I playlib -o game.prg game.c playlib-flyer.lib
#include <stdio.h>
#include "playlib.h"
char tok[17], verb[8], line[80];
int main (void) {
/* tok: from the session (below), or asked for. In memory only. */
if (pl_open ("play.commodoreonline.com", 6502)) return 1;
sprintf (line, "hello,1,tictac,%s,ub0", tok); /* lowercase is $41-$5A in cc65 */
pl_send (line);
for (;;) {
if (pl_get () == PL_LINE) {
pl_field (0, verb, sizeof verb);
/* ... */
}
/* the game's own work */
}
}
| Function | What |
|---|---|
pl_open (host, port) |
Connect: 0, or the error |
pl_close () |
Close. Call it before the program ends |
pl_get () |
The next line or frame into pl_msg. Returns PL_NONE, PL_LINE or PL_FRAME |
pl_poll () |
Poll the device now if a poll is due; returns the bytes buffered |
pl_status () |
1 if connected; sets pl_up |
pl_send (line), pl_sendn (buf, len) |
Send a line: a string of up to 79 characters, or len bytes |
pl_sendframe (seat, data, len) |
Send a frame of 0-127 bytes |
pl_field (n, buf, size) |
Copy field n of the current line, cut to size-1, and a 0. Returns its length |
pl_hold () |
Before a disk access while connected, as SYS 49209 |
The variables are C variables: pl_msg[], pl_len, pl_type, pl_err,
pl_up, pl_lost, pl_driver, pl_sent[], and the settings pl_unit,
pl_chan, pl_lfn, pl_every, pl_chunk, pl_baud and pl_keep.
PL_ENOTOPEN (100) and PL_ETOOLONG (101) name playlib's own errors.
The library calls nothing in BASIC's ROM, which cc65 switches out, and uses
zero page $FB-$FE, which cc65 leaves free. Its buffers are in the program's
BSS. cc65 turns lowercase in string literals into $41-$5A, as petcat
does, so protocol words are written in lowercase in C too. A C program can't
use run, which needs BASIC's ROM.
The session in C. PL_TOKEN, PL_HOST, PL_HPORT and PL_DEVICE in
playlib.h are the session's fixed addresses, so a C program started from a
BASIC lobby can find the token. cc65 keeps its 2 KB stack below $D000,
where the session lies: copy it first thing in main, and write it back just
before the program ends. The C library doesn't check it: a length of 1-16
and letters, digits and - make a token.
Drivers
| Driver | Device | Speed | Notes |
|---|---|---|---|
| Flyer | A Flyer on unit 7, tcp: channel 2 |
The serial bus: about 2.2 ms a byte read | Any firmware. Polls with N-A: four times a second |
| User port | A Hayes modem, through RS-232 routines of playlib's own | 300, 1200 or 2400 baud, found by itself | 2400 baud reads a burst as fast as the line brings it; see below |
| SwiftLink | A Hayes modem on a 6551 ACIA at $DE00, on NMI |
19,200 baud (9600 and 38,400 also work) | The fastest here |
| Flyer on a PET | A Flyer on unit 7 of the IEEE-488 bus | A poll costs about 12 ms, a fifth of a C64's | See the PET |
Choosing a driver
On a PET there is only the Flyer: check that it is there with the probe (the PET). On a C64, the program decides which build to load. Either ask the player, or look for a Flyer and ask only if there is none:
- Finding a Flyer. Ask unit 7 with the KERNAL's
LISTEN($FFB1),SECOND($FF93) with$6F(the command channel), thenUNLISTEN($FFAE), sending nothing. Bit 7 of the status then says nobody answered. From BASIC:SYS 65457,SYS 65427andSYS 65454with A set throughPOKE 780. A plainOPENto unit 7 with nothing there stops a BASIC program with?DEVICE NOT PRESENT ERROR. A disk drive set to unit 7 would pass for a Flyer, so let the player override the choice. - Don't probe for a SwiftLink. Cartridges such as the Action Replay and
EasyFlash also live at
$DE00-$DEFF, and a write there can turn one off or crash the C64. Ask the player instead, once a session, and keep the answer inPL_DEVICE(2 the user port, 3 a SwiftLink, then the value EOR 255), so the next program needn't ask.
The Flyer driver
| Call | On the bus |
|---|---|
| open | OPEN 121,7,15 (the command channel), then OPEN 120,7,2,"TCP:host,port", which returns when the connection is made or has failed, then the status from the command channel |
| poll | N-A:2 on the command channel (reply 00,AVAIL,<bytes>,00), then, if anything waits, one TALK that reads all of it |
| send | One LISTEN, the bytes, UNLISTEN. The Flyer sends them as one TCP segment |
| status | N-S:2 (reply 00,STAT,<bytes>,<connected>,00) |
| close | CLOSE 120, which closes the connection, and CLOSE 121 |
It never reads when N-A: says nothing is waiting: an empty read of tcp:
returns a stale byte that looks real. On firmware 1.2.2, N-S: keeps saying
connected after the hub has closed, so SYS 49161 can't see the hub go;
what the hub sent before closing can still be read.
Modems
Both modem drivers dial with ATDT<host>:<port>, which WiFi modems (Zimodem
and others) and tcpser understand. They read the modem's answer for 30
seconds: CONNECT connects, and the other result words fail with codes
30-34. The modem must answer in words (ATV1, the usual default). Once
connected, NO CARRIER at the start of a line means the call has ended.
Closing hangs up with a second of quiet, +++, a second, and ATH.
| User port | SwiftLink | |
|---|---|---|
| Port | CIA 2, with RS-232 routines of playlib's own (the KERNAL's RS-232 is never opened): 8N1, RXD on PB0 and FLAG, TXD on PA2, RTS and DTR driven | A 6551 ACIA at $DE00 |
| Receiving | playlib's own NMI handler: a start bit starts CIA 2's timer B, which samples each bit in its middle. Each byte goes straight into the receive buffer | playlib's own NMI handler, straight into the receive buffer |
| Sending | Into a 256-byte buffer, so a send returns at once; timer A's NMI puts out each bit. Sending and receiving go on at once | Byte by byte, each when the ACIA can take it |
| Flow control | RTS drops when the buffer has less than 64 bytes of room, and rises at 128 | RTS drops when the buffer has less than 32 bytes of room, and rises at 64 |
| Speed | 300, 1200 or 2400 baud, found by itself (below) | 19,200 baud by default |
| While connected | CIA 2's timers A and B are playlib's, and so are zero page $A8, $AA and $B4-$B6, the KERNAL's own RS-232 locations. At 2400 baud the NMIs take about 15% of the C64's time while receiving, 30% while sending too |
Nothing of the program's |
The user port's routines follow the approach of George Hug's "Toward 2400"
(Transactor, 1989), written anew. They have bit times for PAL and NTSC, and
the KERNAL's flag at $02A6 picks them.
The speed
A WiFi modem keeps its speed itself: it is set with an AT command and kept in
the modem. So playlib finds it. Connecting sends AT at PL_BAUD's speed
(2400 baud, as loaded), and if no OK comes within a second, tries the next
slower speed. The first speed that answers is the one it dials at, and it
stays in PL_BAUD, so the next connection in the session tries it first. If
none answers, connecting fails with error 35. Neither the player nor the
program has to choose. A modem set to 300 baud costs about 2 seconds more at
the first connection.
Disk access
On the user port, the KERNAL turns the receiver off for every disk access
(LOAD, SAVE, OPEN, GET# on a disk or printer), so that no NMI
disturbs the serial bus's timing. The next read turns it on again. Bytes that
arrive meanwhile are lost, and PL_LOST goes up by one.
So call hold before a disk access while connected: SYS 49209
($C039, pl_hold). The modem then holds back what the hub sends, in its
own buffer and the TCP connection, until the next read. The disk access loses
nothing, however long it takes:
500 sys 49209:open 2,8,2,"@0:save,s,w":print#2,sc:close 2
A SwiftLink's hold works the same way. A Flyer needs no hold: it keeps what
comes until it is read, and the call does nothing. run (SYS 49206) closes
the connection before it loads, so it needs none.
Things to check on a real modem:
- Its dialect. Some modems want another form of the dial command, such as
ATD"host:port". Check its manual. - Whether it honors RTS, and whether it must be told to (
AT&K3or similar). Without flow control a slow reader loses bytes, counted inPL_LOST. - The user port at 2400 baud has been tested in emulation; a real C64 and modem are still to be tried.
- SwiftLink cards with a WDC 65C51 ACIA: some never clear "ready to send", and need a timed wait per byte.
Writing a driver
A driver is a ca65 module that exports these symbols. Only the core calls
them.
| Symbol | Called with | Must do |
|---|---|---|
drv_open |
ptr1 ($FB): the host, ending in 0. PL_PORT: the port |
Connect. Return C clear, or C set and the error in A. Clean up after itself on failure |
drv_close |
Hang up and release what it opened. Harmless when nothing is open | |
drv_poll |
A: the most bytes the core can take (1-255) | Hand every waiting byte, up to that many, to rx_put. Return C set if more is still waiting. Errors go to PL_ERR |
drv_send |
A: how many bytes of OUT to send (1-130) |
Send them as one write. Return C clear, or C set and the error in A |
drv_status |
Return C set if the connection is up | |
drv_hold |
Hold called it: make the device hold back what comes until the next drv_poll, or do nothing. Harmless while closed |
|
drv_every, drv_baud, drv_id |
(zero-page constants) | PL_EVERY's default (what a poll costs decides it), PL_BAUD's default, and the number PL_DRIVER reports |
What the core gives drivers: rx_put (hand over the byte in A; X and Y are
kept), put_dec16 (write A/Y in decimal to OUT,X), the buffer OUT (free
during drv_open and drv_poll), the settings PL_UNIT, PL_CHAN,
PL_LFN, PL_PORT, PL_BAUD and PL_ERR, and the ring's head and tail
for a driver that fills the buffer itself. A driver may use ptr1 and ptr2
($FB-$FE), and DRVMEM ($CE00-$CFFF) for buffers of its own. It must not
call BASIC's ROM. drv_send is also called from a poll, for the keep-alive, just
before drv_poll.
A modem driver is smaller: the shared Hayes module provides drv_open,
drv_close, drv_send and drv_status. The driver provides drv_poll,
drv_hold and five primitives: ser_open, ser_close, ser_send (A bytes
of OUT), ser_drain (wait until what was sent has gone out) and ser_get
(C clear and a byte in A, or C set; keeps Y). It passes each
byte it receives through nc_scan, which notices NO CARRIER.
The session
The player types the play token once a session. playlib stays in memory while programs come and go (a lobby, then its game, then the lobby again), and keeps a session for them at fixed addresses. It is never written to a disk.
| Point | What |
|---|---|
| What | PL_TOKEN ($CC26): the token's length, then the token, 16 characters at most. PL_HOST ($CC37): the host of the last connect, ending in 0. PL_HPORT ($CC60): its port. PL_DEVICE ($CC62): the modem the player named, with its check byte |
| BASIC | SYS 49200,T$ reads the token ("" if there is none); SYS 49203,T$ keeps one. SYS 49182 sets the host and port as it connects. SYS 49203,"" forgets the session, after a refused token (ERR,20) for example |
| Machine language | Call init ($C000) first: it checks the session. PL_TOKEN then holds 0 or a token. To keep one, write its length and characters there, and the host and port beside it. PL_HOST and PL_HPORT go straight to open, with PL_PORT set from PL_HPORT |
| Checked | Init and SYS 49200 keep the session only if it is one: a token of 1-16 letters, digits or -, and a host of 1-40 letters, digits, . and -. Anything else, such as memory as it came up at power-on, is forgotten |
| Lifetime | Until the machine is switched off, or a program forgets it. A reset keeps it |
Don't write the token anywhere yourself: not to the program's disk, and not into a saved game.
Running the next program
SYS 49206,NAME$,UNIT ($C01B from machine language) closes the
connection, loads the next program into BASIC's memory and runs it, as
LOAD and RUN typed would. It may be a BASIC program, or machine language
with a SYS line. playlib, its settings and the session stay.
- If the file isn't there, nothing has been loaded, and it returns with error
- Any other failure (RUN/STOP, a disk error) comes after part of the new
program is in memory, so BASIC reports it and stops at
READY..
- Any other failure (RUN/STOP, a disk error) comes after part of the new
program is in memory, so BASIC reports it and stops at
- A program that changes playlib's settings (
PL_EVERY,PL_CHUNK,PL_KEEP) should put them back before it hands over, or the next program should set its own.
The keep-alive
On an idle connection two things can go wrong unseen: a home router forgets the connection, or the hub goes away while the device goes on waiting. The hub covers the first with TCP keep-alive probes. playlib covers the second, and the first again:
| Point | What |
|---|---|
| When | At a poll (SYS 49185 or SYS 49158; get or poll; pl_get or pl_poll) while connected, if nothing has been sent for PL_KEEP seconds |
| What | NOP and a CR, 4 bytes, in one write, between the program's lines. The hub answers nothing |
| Default | 60 seconds: 4 bytes a minute |
| Setting it | POKE 49231,n (1-255 seconds, 0 off), or pl_keep in C, at any time |
| The clock | The KERNAL's jiffy clock (TI). A program that turns off the KERNAL's interrupt stops the keep-alive too |
| Errors | A keep-alive that fails sets PL_ERR (on a modem, 30) |
A program that doesn't poll, such as one waiting at an INPUT prompt, sends
nothing meanwhile; the hub's probes still keep its connection. A dead hub
is found by sending: with nothing acknowledged, a Flyer gives up after
about 32 seconds, and a modem after its own timeout. SYS 49161 then reports
the connection closed. A program that checks the status now and then learns
within about two minutes that the hub has gone.
The lobby program
LOBBY is a ready-made lobby for any C64 game, in BASIC on playlib: chat, who
is here, quick match, tables and invitations. When a match forms, it runs the
game's own program, which connects again and is put back in its seat. An
author writes only the game, and ships LOBBY beside it. Its listing is
written to be read, as an example of BASIC on playlib.
A game's disk:
| File | What |
|---|---|
LOBBY |
The lobby |
PLAYLIB-FLYER, PLAYLIB-RS232, PLAYLIB-SWIFT |
playlib for each device. The lobby loads the one it needs |
GAME |
A sequential file naming the game (below) |
| The game's program | Whatever GAME names: BASIC, or machine language with a SYS line, loaded at $0801 |
The GAME file, one line each, each ending in a CR:
| Line | What | If empty or missing |
|---|---|---|
| 1 | The game's id on the hub | Required |
| 2 | The game's program on the disk | Required |
| 3 | The hub's host | play.commodoreonline.com |
| 4 | The hub's port | 6502 |
| 5 | The device: flyer, swift or rs232 |
The lobby finds a Flyer, or asks |
In the lobby, typed text is chat. A line after / is a hub verb, with
commas for spaces: /who, /match, /match 3, /host 4, /begin,
/tables, /join 7, /invite bob, /accept 7, /decline 7, /cancel,
/mine, /resume 12, /help, /bye.
Handing over. At START the lobby runs the game with playlib's run.
The game then:
- finds playlib at
$C000, with the connection closed. It calls init first; - reads the token from the session (
SYS 49200,T$in BASIC), and the hub fromPL_HOSTandPL_HPORT(withPEEKin BASIC); - connects and sends
HELLO. The hub puts it back in its seat:STARTand theSEATlines again, thenGOonce everyone has sentREADY.
The hub waits 60 seconds for READY, so the game has to be loaded and
connected within a minute of START. From a 1541, a 2 KB game loads in about
5 seconds. At the end of its match, the game can run LOBBY the same way;
the lobby finds the token in the session and logs in again without asking.
The unit the game was loaded from is in PEEK(186).
The example game: TRAILS
TRAILS is a small real-time game for two in machine language, started from
the lobby: each player steers a trail across the screen, and the first to
crash loses. It shows how a machine-language game logs in from the session,
keeps two C64s in step with binary frames, reports its result and goes back
to the lobby.
- It logs in with
HELLO,1,TRAILS,<token>,UB0, and is registered as a live game for two players with no game server. - Each move, each side sends its direction in a frame,
$00, 4, $FF, move, direction, last direction, waits for the other's, and only then moves both trails. Both screens see the same moves in the same order, so they stay the same (lockstep). - A side waiting a second for the other's move sends its frame again, and each frame repeats the move before it, which covers a frame lost to the hub's rate limit.
- On
ERR,40it doubles the time between moves, and slowly speeds up again. - Each side reports the winner it saw with
END; the two always agree.
It plays about 8.6 moves a second through a SwiftLink or a modem on the user port at 2400 baud (the game's own limit), about 6 through a Flyer, and about 2 at 300 baud.
What it costs
Measured in emulation, from BASIC, on a PAL C64:
| Operation | Flyer | User port, 2400 baud | User port, 300 baud | SwiftLink, 19,200 baud |
|---|---|---|---|---|
| A read, nothing buffered, no poll due | 1.5 ms (3.4 ms with six variables) | The same | The same | The same |
| A read with a device poll, nothing waiting | 54 ms | 3.8 ms | 3.6 ms | 3.7 ms |
| A burst of 20 lines of 33 bytes, read in a BASIC loop | 8.6 lines a second | 7.4 lines a second | 0.9 lines a second | 14 lines a second |
| A room description of 250 bytes | 0.9 s | 1.2 s | 8.7 s | 0.4 s |
Sending ALL,T,1234 |
24 ms | 7 ms (into the buffer) | 5 ms (into the buffer) | 8 ms |
- A Flyer is limited by the serial bus, about 2.2 ms a byte read. playlib reads
a burst at about twice the rate of
N-A:andINPUT#, because it fetches a buffer-full in one transaction. - Polling four times a second costs a BASIC game on a Flyer about 22% of its time with playlib, and 29% without.
- At 2400 baud the user port reads as fast as the line brings text, 240 bytes a second: a lobby list of 40 players takes about 3.5 seconds. At 300 baud a line of 33 bytes takes about a second, and the same list half a minute.
- A C program reads a Flyer at about 18 lines a second.
- On a Flyer, the KERNAL's jiffy clock loses about 30% of its ticks while a program polls without pause. Time real-time play with a CIA timer if it matters.
- On a PET, a read with a device poll costs 11-12 ms and a send 10 ms; a burst arrives at about 14 lines a second.
The PET
playlib-pet is playlib for a PET with BASIC 4 (the 4000 and 8000 series,
40 or 80 columns) and 32 KB, with the Flyer driver only. It is the C64's
library at other addresses, with the same interface (version 4).
| Point | What |
|---|---|
| Where | $7000-$7DFF: the C64's layout, $5000 lower, just below the screen at $8000 |
| BASIC's memory | Lower BASIC's top to $7000 before loading playlib and before making a string: POKE 52,0:POKE 53,112:CLR. The top stays there until the PET is switched off, so playlib and the session outlive the programs that come and go. BASIC keeps 27 KB |
| SYS and PEEK | Every address is the C64's less 20,480: init 28672, open 28702, read 28705, send 28708, frame 28711, field 28714, line 28717, the token 28720 and 28723, run 28726, hold 28729; PL_ERR 28736, PL_TYPE 28737, PL_UP 28739, PL_KEEP 28751; MSG 31488; the session at 31782 (token), 31799 (host), 31840 (port) |
| Finding the Flyer | SYS 28732 ($703C, only on the PET): PEEK(28736) is 0 if something answers on unit 7, 5 if not. On IEEE-488 every device takes part in LISTEN and SECOND, so the C64's way of looking would always find the disk drive |
| Not there | The modem drivers, and a library for cc65 |
10 if peek(53)>112 then poke 52,0:poke 53,112:clr
20 if pl=0 then pl=1:load"playlib-pet",8
30 so=28702:rd=28705:sn=28708:pe=28736:tg=28720:tp=28723
40 sys 28732:if peek(pe) then print "no flyer on unit 7":end
50 sys tg,t$:if t$="" then input "play token";t$:sys tp,t$
60 sys so,"play.commodoreonline.com",6502:if peek(pe) then print "no hub";peek(pe):end
A PET's LOAD in a program always loads at the file's address, then runs
the program again with its variables, as a C64's LOAD ,8,1 does, so line 20
works the same.
How it reaches the Flyer. BASIC 4's OPEN and LOAD read their
parameters from BASIC's text and stop the program on an error, so machine
language can't use them. playlib drives the bus with the ROM's IEEE-488
routines instead, and sends the Flyer the same commands a C64 does. It makes
its strings with BASIC 4's own routines, which keep the links BASIC 4's
garbage collection needs.
Tested in emulation on a 4032 and an 8032 with a 2031 drive. PETs with BASIC 2 (most 2001s, and the 3000 series) need a build of their own, which isn't written yet.
