C64 Export Notes

This folder documents the current Commodore 64 export pipeline implemented in js/export.js.

Parent: Project README

This page is the primary entry point for the C64 documentation set.

The current exporter builds one or more .d64 disk images containing:

• BOOK.PRG: BASIC bootstrap and UI logic.
• LOADER.PRG: machine-language loader/reader support.
• BOOK.IDX: compact index records for cover, home metadata, TOC, page graphics, and prompt sprites.
• *.DAT: random-access style data buckets grouped by record size.

Project Intent

The direction of this reader is to push as much runtime logic as practical into machine language so the C64 can:

• load assets faster than equivalent BASIC loops
• make fuller use of KERNAL file and device routines
• keep the interface responsive while data is still loading
• show progressive visual feedback instead of making the user wait on a blank pause
• allow keyboard interruption during long-running loads so the user can move between screens, pages, or menus

The preferred user experience is:

• show partial data as soon as it is available
• show a real progress bar when the target is finite
• fall back to a busy indicator or animation when progress cannot be measured exactly

Generic Reader Goal

The loader, reader, engine, and support files are meant to be generic. They should not contain book-specific content beyond whatever is discovered through:

• BOOK.IDX
• *.DAT
• other generic asset files referenced by those records

That separation is important because it allows the runtime portion to be redistributed as its own reader/viewer while someone else supplies their own book data by editing or replacing the index and data files.

Docs In This Folder

• ASM/README.md: source-style mirrors of the generated assembly modules and their role in the exporter
• file-formats.md: disk files, index records, DAT classes, bitmap payload structure.
• d64-format.md: landing page for split D64 geometry, BAM, and directory-chain docs.
• d64-geometry.md: D64 track geometry, sector sizes, BAM, and Track 18 responsibilities.
• d64-directory-and-files.md: directory entries, PRG layout, sector chains, and displayed block counts.
• book-reader.md: how the C64 reader currently boots and navigates.
• character-table.md: landing page for split charset layout and full slot-table docs.
• character-table-layout.md: character-slot memory layout, ROM sets, and charset replacement workflow.
• character-table-slots.md: full 0-255 character-slot appendix with unshifted and shifted previews.
• colors.md: C64 color values, nibbles, color RAM, and bitmap screen-RAM color pairs.
• glossary.md: acronyms, chip names, file terms, and common C64 terminology used in these docs.
• memory/README.md: index for the split memory docs folder.
• memory-map.md: landing page for the split address-space, I/O/banking, and project layout memory docs.
• memory-techniques.md: landing page for split safe-area, advanced, and ML-only memory strategy docs.
• assembly-programs.md: ML components and what each one is responsible for.

Internal Notes

The notes/ folder is a working reference set for future implementation work. It includes:

• README.md: notes index for CPU, BASIC, KERNAL, bitmap, banking, and auxiliary references
• basic-v2.md: BASIC V2 landing page with links to overview, memory, programming, and token references
• banking and overlay behavior
• 6502 instruction notes
• KERNAL entry points used by the loader
• bitmap/screen/color memory notes
• D64 and record-packing notes
• PETSCII/screen code reminders

Scope

These notes describe the current exporter and reader as they exist in the codebase today. Some sections also call out intended behavior where the implementation is still in progress.

Related Sections

• notes/README.md
• memory/README.md
• ASM/README.md