Modem Wars (Commodore 64, 1988) - annotated disassembly

A complete, reassemblable, commented disassembly of Dan Bunten's Modem Wars (Ozark Softscape / Electronic Arts, 1988) produced from the disk image Modem_Wars_1988_Electronic_Arts_b4.d64.

• docs/overview.md - how the disk is organised, how the game boots, the fast-loader protocol, the sector cipher, the run-time memory map and the overlay system. Start here.
• docs/knowledgeBase.md - every routine and data block with its purpose (generated from the survey pass of the annotation work).
• docs/titleScreen.png, docs/screenshots/ - the loader's title picture decoded straight from the disk bytes, and screenshots taken by driving the game in VICE (extracted/vice/playSession.py boots it on a private X display and feeds it real key events).
• docs/track1_DanBuntenLetter.txt - the letter to pirates that is hidden in plain text on track 1.
• disassembly/ - the sources:
  • boot/ - the two directory files (ea, load), the C128 boot sector and its CBM80 stub, and the title-picture data;
  • drive/ - the code that runs inside the 1541 (bootstrap sector and fast loader / cipher);
  • game/ - the game itself: main program, every overlay variant, data blocks;
  • c64.inc, kernal.inc, drive1541.inc, zeropage.inc, drive_zp.inc - symbol files;
  • XREF.txt - cross reference (callers, readers, writers) for every label and zero-page location;
  • INDEX.txt - one line per source file with its address range;
  • verify.sh - reassembles every file with ca65/ld65 and compares it byte for byte with the bytes extracted from the disk.
• extracted/ - raw and decrypted sectors, the directory files, the reconstructed memory images and the VICE automation used to validate them.
• annotations/ - the comment/label database (JSON) that tools/build.py merges into the sources.
• tools/ - the disassembler pipeline:
  • build.py - rebuilds the whole of disassembly/ from the decrypted sectors plus annotations/;
  • m6502.py / discover.py - instruction decoder, recursive-descent tracer, and the discovery pass that follows interrupt vectors and self-modified jump tables into code the tracer alone cannot reach;
  • render.py - turns a traced memory image into annotated ca65 source (bit art for graphics, grids for tables, per-file table of contents);
  • findStrings.py - finds the bit-7-terminated message strings still sitting in data areas;
  • chunks.py, mergeSurvey.py, extractAssets.py, hwSymbols.py - supporting tools;
  • phase2_annotate.js, phase3_finish.js - the multi-agent passes that produced the comments.

The listing is never edited by hand. Everything a human contributed lives in annotations/*.json (labels, comments, data types, zero-page names) and tools/build.py regenerates disassembly/ from the decrypted sectors plus those annotations, so the sources can always be reproduced from the disk.

What is in the disassembly

24 source files, 56,000 lines, covering 74,741 bytes: the C128 boot sector and its C64 cartridge stub, both directory files, the code that runs inside the 1541 drive, the main program, every overlay variant, and all of the data. About 65% of those bytes are code and the rest data.

• Every one of the 21,627 instructions carries a comment explaining what it is for, not what the mnemonic does.
• Every routine has a header giving its purpose, its inputs, its outputs and its callers, and every source file opens with a table of contents.
• All 164 zero-page locations the game uses are named and described, as are the work-RAM variables, the unit record arrays and the hardware registers.
• Data is rendered as what it is: character and sprite graphics as bit art, tables as rows of the right width, strings as text, jump tables as address lists.
• verify.sh reassembles all 24 files with ca65/ld65 and compares each against the bytes taken off the disk. All 24 match exactly, so nothing in the listing is guesswork about the bytes.

Rebuilding and verifying

python3 tools/build.py        # regenerate disassembly/ from extracted/ + annotations/
./disassembly/verify.sh       # reassemble everything and compare with the original bytes

Requires Python 3 and the cc65 tool chain (ca65, ld65).

Conventions used in the listings

• Every instruction line ends with ; XXXX - its address - followed by the comment.
• Labels are camelCase; sub_XXXX / L_XXXX / D_XXXX are auto-generated names for code and data that has not (yet) been given a meaningful name.
• Labels are scoped to a source file. The $6F00-$87FF and $E000-$EFFF regions exist in two variants each; when code in one file calls into such a region the name of the variant that really contains code at that address is used, and the other variant's name is mentioned in the comment.
• Strings end with a character whose bit 7 is set and are written as .byte "TEXT",'T'|$80.
• Hardware registers use the names from c64.inc (VIC_*, SID_*, CIA1_*, CIA2_*).

SwiftLink driver

swiftlink/ holds an alternate opponent module that drives a SwiftLink cartridge (a 6551 ACIA on the expansion port) instead of the shipped module's bit-banged user-port UART, so the game can play over a modem or a null-modem cable at up to 38400 baud instead of 300/1200. The shipped module is layered and only its bottom layer is hardware specific, so the packet layer, the ARQ frame layer, the ring buffers and the link state machine are left byte-for-byte alone: 434 of the module's 4096 bytes changed, every routine kept its address, and a SwiftLink player and a stock-driver player can still play each other at a shared rate.

./swiftlink/build.sh assembles the module and writes Modem_Wars_SwiftLink.d64, a copy of the game disk that differs from the original in four sectors. See swiftlink/README.md for the hardware it expects, the baud and hot-key tables, the direct-connect mode, the address-by-address map of what changed, and an honest account of what the VICE testing did and did not prove.