Latest revision as of 18:54, 2 October 2026

Atari 7800 High Score Cartridge (HSC) Technical Reference

The Atari 7800 High Score Cartridge (HSC) is an expansion peripheral that provides battery-backed RAM (NVRAM) and a standard high score service for Atari 7800 games. It uses a pass-through design: the HSC plugs into the 7800 cartridge slot, and the game cartridge plugs into the top of the HSC.

This page covers both the game-facing interface and the internals of the ROM (highscre.bin, 4096 bytes, MD5 c8a73288ab97226c52602204ab894286). Internal addresses below refer to that ROM. The 2026 community disassembly (7800 HSC CART) reassembles byte-identical with DASM, and its labels are used here.

System Architecture & Memory Map

Hardware Memory Map

The ROM has no 6502 reset or interrupt vectors of its own. It only runs when a game calls into it.

ROM Layout

Zero-Page Footprint ($80–$BC)

The HSC uses zero page $80–$BC (61 bytes) while a call runs.

• Preservation: on entry, HSCInitRoutine ($3483) copies $80–$BC to the caller's page N at +$13..+$4F, in reverse order ($BC → +$13 … $80 → +$4F). RestoreVarsAndRegsAndExit ($3C46) copies it back.
• $94/$95: these hold the HSC's pointer to page N during the call, so their original values are parked in NVRAM $1000/$1001 before the backup and restored last.
• The first 18 bytes, $80–$91, are a working copy of the argument block (+$00..+$11).

Game code that runs during a call (the sound hook, a custom controller driver, a DLI handler) sees the HSC's values in $80–$BC, so it must not write there.

Dual-Page RAM Requirement (512 Contiguous Bytes)

Every call needs a page-aligned 512-byte RAM work area: page N (passed in Y) and page N+1.

Page N:
  +$00-$11  Argument block (inputs)          +$12      HSCSTAT result byte
  +$13-$4F  Zero-page backup ($BC..$80)
  +$50-$8B  Formatted table: 5 rows x 12 bytes (3 initials + 9 score characters)
  +$8C-$A5  Game name (26)       +$A6-$BF  Difficulty name (26)
  +$C0-$D8  "CONGRATULATIONS  PLAYER n"    +$DA-$F9  Owner name (32)
  (the personalization and menu screens reuse +$8C onwards for their own strings)

Page N+1:
  +$00-$86  Display lists (screen-specific templates, patched at run time)
  +$87-...  Display List List (DPPL = $87, DPPH = page N+1)

Cartridge Detection

Check the two signature bytes, which are the bottom rows of glyphs 'A' and 'E', before calling any vector:

DetectHSC:                  ; carry set = HSC present
    lda $3900
    cmp #$C6
    bne .no
    lda $3904
    cmp #$FE
    bne .no
    sec
    rts
.no clc
    rts

Variants seen in games: lda #$C6 / cmp $3900 (Asteroids Deluxe), lda $3900 / eor #$C6 (current 7800basic), and lda $1002 / cmp #$68 (old 7800basic, which checks the NVRAM magic instead).

Public Vector Table & API

Calling Conventions

• Y: high byte of page N.
• X: ignored. HSCInitRoutine always uses offset $00.
• On return: I flag set (SEI is never undone), D clear, stack balanced. X/Y undefined.
• Return path: HSCInitRoutine slips two bytes, $3C and $2B, under its own return address. When the vector's body finishes with RTS, control goes to $3C2C, the common display hold. That code pushes the result, runs the hold, and leaves through RestoreVarsAndRegsAndExit, which pulls the result into A and returns to the game. So every vector except HSCSETRS ends in the hold, including HSCSTAT and the copy calls.

Common Entry Processing (HSCInitRoutine, $3483)

1. Store the function ID at $1007, then SEI, CLD.
2. Display vectors (IDs other than $02, $EF and $04): CTRL = $7F (DMA off), AUDV0 = AUDV1 = 0.
3. Park $94/$95 in $1000/$1001 and back up the zero page.
4. Read SWCHB into $BC and write $FF to SWCHB, which drives any output bits high and forces one-button joystick mode. The saved value is written back on exit.
5. Copy argument bytes +$00..+$11 to $80..$91. Player index = +$02 & 3 → $A9.
6. If the name-pointer high byte and the logo-pointer high byte are both 0, overwrite $80–$8E with the defaults at $39EF: $80 $01 $F1 $01 $79 $E9 $00 $1A $4C $00 $00 $00 $FF $3C $0A. That's ID $80/$01, difficulty $F0, player 2, joystick, name at $E979, difficulty at $1A00, score at $004C, no logo, sound hook $3CFF (an RTS), 10-second hold. The purpose of this set is unknown.
7. Do the stack trick described above.
8. Display vectors: load the palette and CHARBASE (HSCSETRS2, $39AD).
9. Check the NVRAM magic ($3512). If it fails, check again (one retry), and if it still fails, format ($3535). Formatting writes the magic, sets every slot's difficulty and age to $7F ($3FCF), and then, unless the call is HSCCPYFM or HSCCPYTO, runs personalization ($3C95) and turns DMA off.
10. Convert the game's BCD score to binary ($3A81, see Score conversion). This runs for every vector.
11. Look up the directory ($3572) and set $A6/$A7 to the table address.

User Argument Block (Page N)

HSCSTAT Results

• A score of 0 never qualifies (IsScoreNonZero, $3DDC).
• A score equal to an existing entry ranks above it.
• If the game/difficulty has no table, +$05 is $FF for any score and +$0F..+$12 are 0. So a game that calls HSCENTER only when HSCSTAT reports a qualifying rank can never create its first table.
• How the top score is produced: HSCSTAT formats the table as text (FormatAllScoresForDisplay, $3769), then packs the eight digit characters of row 1 ($30A9) back into BCD, treating spaces as 0.

Sound Hook

The hook is reached by JSR $36DB, which does JMP (SOUNDPTR), so the hook returns with RTS. It may clobber A, X and Y. It's called during the hold (but not while paused) and during initials entry. It isn't called during personalization or the menu.

Custom Controller Driver ($03 = $02)

Reached by JMP ($84) ($39A6) from a subroutine call, with X = player index. It must return:

• A bits 7–4 = right, left, down, up (0 = pushed)
• Y bit 7 = fire (0 = pressed)

Driver input is used for text entry, the hold's exit check and fire-release waits. The hold's raw checks (INPT4 and any SWCHA bit) are skipped for type $02. The screen saver ($392C) and the maintenance menu still read the real ports. Because the name pointer doubles as the driver address, a driver game should supply a logo, or its code bytes get drawn as the game name.

Logo DLL

The decoder ($36DE) copies the game's 3-byte DLL entries verbatim to the start of the DLL. It keeps a running total of zone heights ((byte0 & $0F) + 1) and stops after the entry that brings the total to at least 65 lines ($41, when a difficulty name is present) or 79 lines ($4F, when it isn't).

DLI handling:

• If the first logo entry has its DLI bit set, $B9 is set to $40.
• SetupDLL ($3715) shifts $B9 left for every HSC entry flagged with a DLI. The first such entry keeps its DLI bit; all later ones have it stripped.
• Without a logo DLI, every HSC DLI bit is stripped.

The one kept DLI lets the game's NMI handler restore the HSC's CHARBASE and palette after a logo that changed them.

Data Representations

Character Set & Font

The HSC uses its own character codes, often called Watkins encoding. Letters are 'X' - 'A'.

There's no colon.

Glyphs are 8×7 pixels, drawn in 320A mode with CHARBASE $39. Row r of glyph c (r = 0 at the top) is at $3900 + (6−r)×$100 + c.

DASM macro:

    mac WATKINS
        dc.b {1}-"A"
    endm

Packed Initials (15 bits)

Byte 0: [ C1.4 | C1.3 | C1.2 | C0.4 | C0.3 | C0.2 | C0.1 | C0.0 ]
Byte 1: [ C1.1 | C1.0 |   0  | C2.4 | C2.3 | C2.2 | C2.1 | C2.0 ]

byte0 = ((c1 >> 2) << 5) | c0        c0 = byte0 & $1F
byte1 = ((c1 & 3) << 6) | c2         c1 = ((byte0 >> 5) << 2) | (byte1 >> 6)
                                     c2 = byte1 & $1F

• Packing: EncodeAndSaveInitialsToTable, $31D7. Unpacking: $3AD6.
• Empty entries hold ___ (three underscores, $1A $1A $1A), packed as $DA $9A.
• Other examples: ABC = $00 $42, XYZ = $D7 $19.

Score conversion

Games pass 8-digit packed BCD. NVRAM holds a 24-bit binary value, little-endian.

1. Clamp ($3A83): the score is compared byte by byte with $16 $77 $72 $15 (16,777,215). If it's larger, the maximum is written back into the game's score and used instead. The comparison is signed, see bugs.
2. Convert ($3AA8): for each nibble, the value is multiplied by 10 ($3A5E, a full 24-bit ×10) and the nibble is added. The result goes in $AD (LSB), $AE, $AF (MSB). The nibble add has a carry bug, see bugs.
3. Display ($37BC): the value is turned into decimal by repeated subtraction of the powers of ten at $3EC7, giving a 9-character field:
   • ID1 bit 7 clear: a leading space, then 8 digits with leading zeros blanked. The last digit always shows.
   • ID1 bit 7 set: 8 digits with leading zeros blanked, then a final 0.

Cartridge NVRAM Layout ($1000–$17FF)

Formatting only writes the magic and the $7F markers. IDs, tables and the owner name keep whatever was there.

Score Tables

Each table holds 5 entries of 5 bytes, 1st place first: packed initials (2 bytes), then the score as 24-bit little-endian binary (3 bytes). A new table is 5 × ($DA $9A $00 $00 $00).

Directory Lookup & LRU

Lookup ($3572):

• Scans slots 68 down to 0 for a slot whose ID 1, ID 2 and difficulty (arg+$02 & $FC) all match. A free slot can't match, because $7F has its low bits set.
• While scanning, it tracks the slot with the largest age (signed compare, strictly greater). That slot is the eviction victim: free slots ($7F) win, and on ties the highest slot number wins.

Touch ($35A1), done by every call except HSCSTAT:

• Let old = the slot's age. Set its age to 0.
• Then increment every age that is less than old (signed), the touched slot included.
• So the most recently used slot ends with age 1, not 0. In-use ages stay distinct from 1 upward, and free slots stay $7F.

Not found ($35E0):

• Negative function IDs (HSCATRCT $FF, HSCCPYFM $EF) drop the call's return address, store the ID in the hold timer, and return the ID straight away, with no hold. DMA was already turned off and audio muted for HSCATRCT.
• HSCSTAT reports "no table".
• Everything else creates a table ($35F4) in the victim slot, so when all 69 slots are in use the least recently used game is evicted.

Interactive Behavior

Display Hold ($3C2C)

• The hold counts down arg+$0E seconds. Each second is 60 passes, and each pass waits one vertical blank, checks input, and calls the sound hook.
• The input check ($3C63) ends the hold on any of:
  • P1 fire, or any SWCHA bit (both of these are skipped for driver games)
  • RESET or SELECT
  • the selected controller (joystick or driver)
• Pause ($3B51), triggered by SWCHB bit 3 low on two reads two frames apart:
  • Wait for release, mute audio, and stop calling the hook.
  • While paused, the exit inputs above still work. Another PAUSE press resumes the countdown.
  • Holding PAUSE and pressing SELECT ($3B71) opens the maintenance menu.
  • After about 233×256 frames (roughly 16 minutes) paused, the screen saver ($392C) turns DMA off until any input.

Initials Entry ($3242)

Setup. The new score has already been inserted: lower entries shifted down, and the old 5th place saved at $17FA. The inserted row still shows the displaced entry's initials.

The cursor is a separate one-character DL object on the row. It blinks every 30 frames by toggling palette bit 2 (P0 ↔ P4). It starts at position 0, showing the character already there.

Stepping through characters. The stick is sampled every 10 frames:

• Up/Right = next: A…Z, _, ., -, space, ', █, ←, then A. At position 0 the ← is skipped.
• Down/Left = previous, the same cycle backwards.
• Pressing Next on _ as the first move at a position jumps straight to 'A'.
• Position 3 offers only █ (END) and ← (BACKSPACE).

Fire is checked every frame and acts after release:

• On a character: accept it and move right.
• On ←: move left. The ← glyph stays drawn in the position left behind.
• On █: finish.
• RESET or SELECT finishes at the current position.

Finishing:

• At position 0, finishing cancels: the table is shifted back and the old 5th place restored from $17FA. The routine still falls through into the packing code, which rewrites the restored entry's initials unchanged.
• At positions 1–2, the remaining initials are filled with spaces.

There's no time-out. A screen saver kicks in after about 15 minutes (233×233 frames) without input.

Personalization ($3C95)

Shown on first use and from the menu. The screen reads PERSONALIZE / YOUR ATARI HIGH SCORE / CARTRIDGE, and an entry line underneath stays centered as it grows. Entry rules:

• Up to 32 characters, same character cycle as the initials, no digits.
• It always uses the left joystick and has no console abort.
• Each new position starts on the previous character.
• █ (END) finishes. An empty name becomes one space.
• Before entry starts, the owner name in NVRAM is set to A T A R I (length 9) in case power is lost mid-entry.

Maintenance Menu ($3B7F)

The menu reads WHAT WOULD YOU LIKE TO CLEAR?, with four choices: THIS GAME, ALL GAMES, PERSONALIZATION, NOTHING. The selection starts on NOTHING, and Up/Down move it, wrapping around. Fire brings up ARE YOU SURE? YES NO: Left/Right choose, starting on NO, and NO returns to the menu.

What each choice does after YES (dispatcher $39C8):

• THIS GAME: frees the current game/difficulty slot only ($3FC4). The IDs and score bytes stay behind.
• ALL GAMES: frees all 69 slots. The owner name is kept.
• PERSONALIZATION: runs the name entry.
• NOTHING: leaves the HSC, returning the original result to the game.

The first three return to the menu afterwards. The menu has no time-out, no console exit and no sound hook, and it always uses the left joystick.

Screen Layout & Colors

Colors: BACKGRND $00, P0C2 $FA (headers, cursor), P1C2 $98 (scores and initials of rows 2–5), P2C2 $96 (rank digits 2–5), P3C2 $0A (game, difficulty and owner names), P4C2 $9D (1st-place row, cursor blink).

The table screen, top to bottom:

1. Header: 10+16+16 blank lines, the game name (26 characters at x = 56 in 320 mode), then 16 blank lines. A game logo replaces this.
2. Difficulty (optional): 7 blank lines, then the difficulty name.
3. Entry layout only: 16 blank lines, CONGRATULATIONS, 7 blank lines, PLAYER n.
4. Table: 16 blank lines, the owner name (centered), then five rows. Each row is a rank digit at x = 100, the 9-character score at x = 116 and the initials at x = 196, separated by 7-line gaps.
5. Blank 7-line zones pad the DLL to at least 243 lines.

The community "PAL hack" (PALHACK in the disassembly) only lengthens the gap zones.

Bugs and Quirks in the HSC ROM

7800 Assembly Integration Example

Argument Block Template

HscRomTemplate:
    .byte $8B, $23          ; game ID 1 and 2
    .byte $00               ; difficulty << 2 | player (filled in at run time)
    .byte $00               ; controller type: joystick
    .word HscTitleText      ; 26-character game name
    .word HscDiffText       ; 26-character difficulty name (or high byte 0)
    .word GameScoreBcd      ; 4-byte packed BCD score in RAM
    .word 0                 ; no logo: show the name as text
    .word GameSoundCallback ; must be valid; point at an RTS if unused
    .byte $05               ; hold time in seconds

HscTitleText:               ; exactly 26 characters, padded to center "MY GAME"
    .byte $1D,$1D,$1D,$1D,$1D,$1D,$1D,$1D,$1D,$1D
    WATKINS "M"
    WATKINS "Y"
    .byte $1D
    WATKINS "G"
    WATKINS "A"
    WATKINS "M"
    WATKINS "E"
    .byte $1D,$1D,$1D,$1D,$1D,$1D,$1D,$1D,$1D

Attract Mode

ShowHighScores:
    jsr DetectHSC
    bcc .done
    jsr CopyArgs            ; copy the 15-byte template to $2500 (page N = $25)
    lda CurrentDifficulty
    asl
    asl
    sta $2502               ; player index 0
    ldy #$25
    jsr $3FFA               ; HSCATRCT: A = $FF if this difficulty has no table
    jsr RestoreGameScreen   ; DMA, DPP, CHARBASE, palettes, controller ports
.done
    rts

Game Over

Don't gate HSCENTER on HSCSTAT: HSCSTAT reports $FF until a table exists (bug 10). HSCENTER does its own ranking and simply shows the table when the score doesn't qualify.

SubmitScore:
    jsr DetectHSC
    bcc .done
    jsr CopyArgs
    lda CurrentDifficulty
    asl
    asl
    ora CurrentPlayer       ; 0 or 1
    sta $2502
    ldy #$25
    jsr $3FFD               ; HSCENTER: A = $01 if inserted
    jsr RestoreGameScreen
.done
    rts

ReadTopScore:               ; e.g. for an on-screen "HI" display
    jsr CopyArgs
    lda #0
    sta $250E               ; no hold, or the game's frame freezes
    ldy #$25
    jsr $3FF7               ; HSCSTAT
    ; $250F-$2512 = top score in BCD; $2504/$2505 overwritten, so rebuild the block before the next call
    rts