FujiNet for Game Developers: Multiplayer, the Lobby, App Keys, Clock and Testing

A FujiNet turns an Atari into a networked machine, and game makers have been quick to use it. There are two-player BASIC games played across the Internet, a card game with a lobby full of online tables, shared high-score tables for decades-old disks, and even MIDI Maze deathmatches. This guide collects the pieces a game developer needs: which programming layer to use, how to link two Ataris, how the Lobby works, how to keep settings with app keys, how to read the clock, and how to test all of it without a pile of hardware.

What you'll learn: the network patterns that work in games, the Lobby and its app-key handshake, saving small amounts of state on the FujiNet, reading the time, and a two-Atari test setup on one PC.

What you need: a FujiNet or FujiNet-PC, plus Atari BASIC, FastBasic or cc65. Read Programming the FujiNet N: Device for the AUX, STATUS and XIO details this guide builds on.

1. Pick a layer

  • Atari BASIC with NDEV. OPEN an N: channel and use PRINT, INPUT, GET and PUT. It's the easiest route, and the published Reversi and Light Cycles examples are written this way. Remember that the handler has to be loaded first.
  • FastBasic has its own network statements: NOPEN, NSTATUS, NGET, NPUT and NCLOSE, all using the same mode and translation values as BASIC's OPEN. Eric Carr wrote the 5 Card Stud client in FastBasic, and his FujiNet Battleship was an entry in the 2025 BASIC 10-liner contest.
  • cc65 (C). Fill the SIO control block yourself, or use fujinet-lib, the project's C library, which wraps the network and app-key calls. The FujiNet apps are built from cc65's current Git source rather than a release, with the project's fujinet-build-tools (including Matthias Reichl's dir2atr) for making ATRs. You often don't need an ATR at all: a FujiNet mounts a bare XEX by building a temporary DOS 2 disk around it with a tiny picoboot loader.
  • Assembler works the same way through SIOV. The netcat example exists in MADS form.

2. Linking two Ataris

The simplest multiplayer design needs no server: one Atari listens on a TCP port and the other connects to it. Reversi and Light Cycles both use port 6502, and the player who listens must forward that TCP port on their router. This skeleton does the handshake and then trades one byte per turn:

10 REM TWO-PLAYER LINK SKELETON, TCP PORT 6502
20 DIM H$(60),U$(80)
30 PRINT "OTHER ATARI (RETURN TO WAIT)";:INPUT H$
40 IF H$="" THEN U$="N:TCP://:6502/":ME=1:GOTO 60
50 U$="N:TCP://":U$(LEN(U$)+1)=H$:U$(LEN(U$)+1)=":6502/":ME=2
60 TRAP 900:OPEN #1,12,0,U$
70 IF ME=2 THEN 110
80 STATUS #1,ST:IF PEEK(748)=0 THEN 80
90 XIO 65,#1,12,0,"N:":REM ACCEPT THE CALLER
100 REM EACH TURN: SEND MY MOVE, THEN WAIT FOR THEIRS
110 S=STICK(0):PUT #1,S:XIO 15,#1,12,0,"N:"
120 GET #1,T
130 PRINT "ME ";S;"  THEM ";T
140 GOTO 110
900 PRINT "LINK CLOSED, ERROR ";PEEK(195):CLOSE #1

The blocking GET in line 120 is deliberate. Each machine sends its move and then waits for the other's, so the two stay in lockstep with no clock to synchronise. That's the trick Reversi uses: it sends X,Y,TRIG with PRINT and reads it with INPUT, which simply waits until the opponent moves. A real-time game can't afford to wait. Light Cycles sends its joystick direction only when the stick is pushed, and checks STATUS/PEEK(746) before every INPUT, carrying on with the old direction if nothing has arrived.

Keep messages small and lines short. PRINT followed by XIO 15 gets a byte on its way immediately, and translation mode 0 (AUX2 = 0) passes raw bytes such as joystick values untouched.

3. The Lobby: servers instead of IP addresses

Typing your friend's IP address and forwarding ports is fine for a demo. For anything bigger, FujiNet has a Lobby:

  • Game servers, written in Go for 5 Card Stud, host the tables or rooms. Some are filled with AI players. They report their events to a Lobby server.
  • The Lobby client, an Atari program written in cc65, shows players the available servers for each game.
  • When the player picks a server, the Lobby client writes its endpoint into an app key reserved for that game (section 4). The game client reads that key to know where to connect.

The Lobby's app keys use creator ID 0x0001, app ID 0x01. Key 0 holds the player's name, shared by every Lobby game, so players type it only once. Registered game keys include 1 5 Card Stud/Poker, 2 Reversi, 3 Fujitzee, 4 Fuji-Rama and 5 Battleship. To add a game, register a key ID under that space and have your client read the server address from it.

FujiNet Enhancement Proposal FEP-002 (May 2025, a draft) extends the Lobby with persistent leaderboards. Game servers add a gameResult record to the events they POST, listing each player, whether they won and whether they were human or AI. The Lobby keeps these in an SQLite table and publishes an HTML page of top players overall and the top ten per server.

4. App keys: settings and progress that survive a reboot

An app key is a small file, currently up to 64 bytes, kept on the FujiNet's SD card in /FujiNet/. It is named from three hex numbers: a 2-byte creator ID, an app ID and a key ID. Creator 0xB0C1, app 01, key 0A becomes /FujiNet/B0C1010A.key. IDs 0x0000–0x00FF are reserved for FujiNet itself. Developers list their own creator ID on the project wiki. Eric Carr's 5 Card Stud keeps two keys under E41C-01: whether the player has seen the help screen, and their chosen colour theme. Any program can read any key, which is how the Lobby passes the player's name around.

The SIO interface is three commands to device $70:

Command Direction Buffer
$DC Open App Key send 6 bytes creator (2), app, key, mode (0 read, 1 write), reserved
$DD Read App Key receive 66 bytes 2-byte length, then up to 64 data bytes
$DE Write App Key send 64 bytes DAUX1/DAUX2 = number of bytes to keep

Each read or write closes the key again ($DB Close exists but isn't needed), so open it before every access. This cc65 program keeps a one-byte "level reached" counter:

/* Save and restore a small game state in a FujiNet app key (cc65) */
#include <atari.h>
#include <stdio.h>
#include <string.h>

#define CREATOR 0xB0C1          /* use your own registered creator ID */
#define APP     0x01
#define KEY     0x01

static struct {                 /* the 6-byte Open App Key block */
    unsigned int  creator;
    unsigned char app, key, mode, reserved;
} ak;

static unsigned char buf[66];   /* read: 2-byte length + 64 bytes */

static unsigned char sio(unsigned char cmd, unsigned char dir,
                         void *data, unsigned int len, unsigned int aux)
{
    OS.dcb.ddevic = 0x70;       /* the FujiNet device itself */
    OS.dcb.dunit  = 1;
    OS.dcb.dcomnd = cmd;
    OS.dcb.dstats = dir;        /* 0x40 receive, 0x80 send */
    OS.dcb.dbuf   = data;
    OS.dcb.dtimlo = 15;
    OS.dcb.dbyt   = len;
    OS.dcb.daux   = aux;
    asm("jsr $E459");           /* SIOV */
    return OS.dcb.dstats;       /* 1 = success */
}

static unsigned char open_key(unsigned char mode)
{
    ak.creator = CREATOR; ak.app = APP; ak.key = KEY;
    ak.mode = mode;             /* 0 = read, 1 = write */
    ak.reserved = 0;
    return sio(0xDC, 0x80, &ak, 6, 0);
}

int main(void)
{
    unsigned int len;

    if (open_key(0) == 1 && sio(0xDD, 0x40, buf, 66, 0) == 1) {
        len = buf[0] | (buf[1] << 8);
        printf("Saved state: %u bytes, level %u\n", len, buf[2]);
    } else {
        printf("No saved state yet.\n");
        buf[2] = 0;
    }

    buf[2]++;                   /* pretend the player reached a new level */
    if (open_key(1) == 1 && sio(0xDE, 0x80, buf + 2, 64, 1) == 1)
        printf("Stored level %u.\n", buf[2]);
    else
        printf("Write failed (no SD card in the FujiNet?)\n");
    return 0;
}

Build it with cl65 -t atari -O -o appkey.xex appkey.c. App keys only work when the FujiNet has an SD card. Without one, reads and writes fail, so treat a missing key as "first run" rather than an error. The config-ng program stores a version number inside its key, so a later release can recognise and upgrade old data. That habit is worth copying.

5. The clock

FujiNet answers the APETIME protocol that Atarimax's APE introduced, so even a stock Atari with no DOS can ask for the date and time. That's useful for daily challenges or timestamped scores. Send command $93 to device $45 and six bytes come back: day, month, year minus 2000, hour, minute, second:

10 REM READ THE FUJINET CLOCK (APETIME)
20 FOR I=0 TO 4:READ B:POKE 1536+I,B:NEXT I
30 DATA 104,32,89,228,96
40 POKE 768,69:POKE 769,1:POKE 770,147:POKE 771,64
50 POKE 772,64:POKE 773,6:POKE 774,15
60 POKE 776,6:POKE 777,0:POKE 778,238:POKE 779,160
70 X=USR(1536):IF PEEK(771)<>1 THEN PRINT "NO CLOCK, STATUS ";PEEK(771):END
80 PRINT "DATE 20";PEEK(1602);"-";PEEK(1601);"-";PEEK(1600)
90 PRINT "TIME ";PEEK(1603);":";PEEK(1604);":";PEEK(1605)

The time zone is set in the FujiNet's web interface, or with command $99, which takes a POSIX zone string such as EST5EDT.

6. High scores without network code

If your game already saves a score table to its own disk, FujiNet can make it shared. Keep the table in one contiguous run of sectors on a single-density ATR, then put the sector count in byte 12 of the ATR header and the first sector number in bytes 13–14. When the image is mounted read-only from a TNFS server, FujiNet still allows writes to those sectors. In BASIC, NOTE #1,SECT,BYT on an open file tells you which sector it starts on. FujiNet Firmware Lets Classic Disk Games Save High Scores to Shared Servers covers the feature, and FujiNet Project Adds High-Score Tables to PAC-MAN, Donkey Kong and Other Classics shows how the project retrofits tables into games that never had one.

7. Testing on one PC

You don't need two Ataris and two FujiNets to test a two-player game. FujiNet-PC is the firmware built as a desktop program. A small Python NetSIO hub connects it to Altirra through a custom device file, netsio.atdevice. For two players on one computer, duplicate everything with different ports:

Altirra #1 -> netsio.atdevice   (port 9996) -> hub -> FujiNet-PC   (port 9997)
Altirra #2 -> netsio-2.atdevice (port 9986) -> hub -> FujiNet-PC 2 (port 9987)

python3 -m netsiohub --port 9996 --netsio-port 9997
python3 -m netsiohub --port 9986 --netsio-port 9987

Give each Altirra its own portable settings file, turn Fast boot off so CONFIG loads, and set Altirra not to pause when its window is inactive. Otherwise the opponent's emulator freezes whenever you click the other window. On macOS and Linux, Altirra runs under Wine. The ready-made FujiNet VirtualMachine, a VirtualBox image with Debian 12, Altirra, FujiNet-PC and the bridge already wired up, is the quickest way to start. FujiNet Documents NetSIO, Its Bridge Between Atari Emulators and a Virtual FujiNet explains the bridge protocol.

Troubleshooting

  • The listening player never sees the caller: TCP port 6502 isn't forwarded on their router, or one side typed the wrong address.
  • Game freezes mid-match: a blocking INPUT or GET is waiting for data that never came. Add a STATUS check, or a timeout using the real-time clock.
  • App key always "first run": no SD card in the FujiNet, or the creator, app and key IDs differ between write and read.
  • Clock returns status 138: no FujiNet answered on the bus.
  • Second emulator stalls: turn off Pause when inactive, and check that the two hub/FujiNet-PC pairs really use different ports.

Further reading

  • FujiNet wiki: N: Game Developer Cheat Sheet, N: TCP Game Example: Reversi and Light Cycles, Using App Keys, SIO Command $DC Open App Key, Accessing the Real-Time Clock, FEP-002 and Run FujiNet with Altirra for Atari.
  • The fujinet-apps, fujinet-lib and fujinet-lib-examples repositories on GitHub (the appkey-sample and netcat programs).
  • The FastBasic manual, network statements.
  • Our guides FujiNet Setup Guide, Programming the FujiNet N: Device and A Modern Cross-Development Workflow for the Atari 8-bit.

Credits