The books are meant to be read at debug80.com.
This repository is the source. It holds the markdown, the generated figures and the site theme; the site itself is what those become. If you have arrived here looking for the documentation, follow the link — the published pages have working navigation, search and cross-references, and none of that survives reading the markdown on GitHub.
Four programming projects and the machine that anchors them.
Debug80 is a VS Code extension: source-level debugging for Z80 assembly, with an emulated TEC-1 or TEC-1G in the sidebar and a path out to real hardware over serial.
AZM is the assembler underneath it — a Z80 assembler with layout types, register-contract analysis and op declarations on top of the ordinary directives.
Glimmer is a reactive language for writing games. You declare what the game remembers and how it responds; Glimmer generates the loop, the input polling and the change tracking, and compiles to readable Z80 assembly.
Atom is a single-pass Z80 assembler whose native core is written in Z80. Its Mac command combines that core with host source preparation and artifact generation. Nucleus is a small, safe, statically typed language compiled directly to Z80 machine code. Its first compiler is intended to be handwritten in Z80 and to fit, with its required immutable data, in one 16 KiB bank.
The TEC-1G is the single-board computer at the centre of the current Debug80, AZM, Glimmer, and Nucleus material.
| Debug80 Book 1 — Getting started | Installation through to stepping code and sending HEX to a board. |
| AZM Book 1 — Assembler Manual | The reference: syntax, directives, expressions, layouts, contracts. |
| AZM Book 2 — Z80 Fundamentals | The Z80 from the bare machine up, assuming nothing. |
| AZM Book 3 — Algorithms and Data Structures | Sorting, strings, records, recursion and a backtracking capstone. |
| Atom | Installation, first assembly, project links and entry points to the Atom books. |
| Atom Book 1 — Assembler Reference | Atom syntax, preprocessing, instructions and output. |
| Atom Book 2 — Z80 Programming | The Z80 from first principles through algorithms and recursion using Atom. |
| Atom Appendices | Programming API and lookup tables for Atom and the Z80. |
| Glimmer Book 1 — Reactive Programming for Z80 Games | The language and reactive model, developed through focused programs. |
| Glimmer Book 2 — Building Complete Z80 Games | Skyfall, Tetro and Rushlight across the matrix and TMS9918 displays. |
| Nucleus | The autonomous language and direct-Z80 compiler project. |
| Programming Nucleus | A practical course in the language, compiler and Debug80 workflow. |
| Nucleus 0.1 Language Specification | The complete source-language specification in a chapter-by-chapter reading edition. |
| Nucleus Z80 Runtime Contract | The complete direct execution and backend contract. |
| TEC-1G / MON-3 | Reference material for the machine and its monitor. |
Requires Node.js 20 or later.
npm ci
npm run devnpm run build produces the static site into .vitepress/dist. Pushing to
main builds and publishes to GitHub Pages, which serves debug80.com.
The Nucleus reading editions are generated from their single authoritative files; their chapter files are not independent sources. Both authoritative sources are in the standalone Nucleus repository. Update and verify them with:
npm run sync:nucleus -- /path/to/nucleus/docs/specification.md
npm run check:nucleus -- /path/to/nucleus/docs/specification.md
npm run sync:nucleus-runtime -- /path/to/nucleus/docs/z80-runtime-contract.md
npm run check:nucleus-runtime -- /path/to/nucleus/docs/z80-runtime-contract.mdThese checks guard things that are easy to get wrong and hard to notice. CI runs the repository-only checks on every push. Checks that need adjacent source or locally linked packages run during the relevant editing workflow.
| Command | Checks |
|---|---|
npm run links |
Every internal link resolves. |
npm run symbols |
Every symbol the prose names in backticks is one the code actually defines. AZM is case-sensitive, so RenderTile and RENDER_TILE are different symbols and only one of them exists. |
npm run verify:debug80 |
Command names, panel labels and status strings quoted in Debug80 Book 1 match the extension source. Needs the extension checked out alongside this repo; skipped otherwise. |
npm run verify:nucleus-book |
Compiles and executes the complete Nucleus book examples through the locally linked authoritative compiler and runtime packages. |
npm run verify:atom-book |
Assembles the checked Atom examples through published atom-z80, executes the Book 2 programs and enforces uppercase assembly source. |
npm run sidebar |
Regenerates the sidebars from front matter. Run after adding or renaming a page. |
npm run llms |
Confirms that the public citation guide contains the current books and URLs. |
The panel diagrams are generated, not drawn. npm run diagrams rebuilds them
from scripts/generate-book-diagrams.mjs into
assets/images/debug80-book/book1/. They stand in for screenshots on purpose: a
screenshot goes stale the moment a label moves and costs a capture session to
replace, while a schematic is text and regenerates in a second. Edit the script,
not the SVGs.
debug80-book/ Debug80 Book 1
azm-book/ AZM Books 1-3, plus appendices shared between them
atom/ Atom product overview and installation
atom-book/ Atom reference and teaching books, plus lookup appendices
glimmer-book/ Glimmer Books 1-2, plus their shared reference
nucleus/ Programming Nucleus and two generated reading editions
archive/ Retired research material; excluded from the public build
tec1g/ TEC-1G and MON-3 reference
assets/images/ Figures, most of them generated
scripts/ Diagram generators, documentation checks and spec synchronisers
public/ Favicon, marks, CNAME
.vitepress/ Theme, sidebar generator, config
_internal/ Working notes and unpublished drafts; excluded from the build
Navigation comes from the front matter of each page — title, nav_order,
parent — rather than from a central file, so a new chapter appears in the
sidebar once npm run sidebar has run. A directory named book* is treated as
a standalone book and gets its own sidebar; any other subdirectory of a series
is shared reference and appears alongside each book in that series.