Debug80 IDE for Z80 Development

Source-level Z80 debugging and machine emulation for VS Code.

Documentation: debug80.com — start with Book 1 — Getting started, which goes from installing the extension to stepping through a program on real hardware.

Debug80 turns VS Code into a practical development environment for Z80 assembly and Glimmer programs. It builds your project, runs it inside an integrated Z80 runtime, maps machine addresses back to source with native D8 debug maps, and exposes the state you need while debugging: breakpoints, stepping, registers, flags, memory, terminal I/O, and hardware-specific panels.

The extension is designed for real single-board computer workflows, especially the classic TEC-1 and the TEC-1G MON-3 environment. Those profiles include bundled ROM assets and emulator panels for the front-panel hardware users actually interact with.

Full user guides, AZM course material, and engineering reference documentation are available at debug80.com.

Features

• Source-level Z80 debugging: set breakpoints in .asm, .z80, and .glim files, then continue, pause, restart, step into, step over, and step out using the normal VS Code debug controls.
• Native D8 debug maps: Debug80 uses D8 mapping data generated by the assembler to resolve addresses, included source files, symbols, and source locations directly from the build.
• Source-map-backed editor help: press F12 / Go to Definition on symbols, search active-target symbols through VS Code's workspace symbol picker, and hover over symbols for compact address/value/source details from the last successful build. The Project panel reports whether the active source map is current, missing, or stale; if no source map exists yet, build the target first.
• Run to Cursor: use VS Code's normal Run to Cursor action while debugging Z80 source; Debug80 resolves the current source line through the active source map and runs to the matching address.
• Z80-focused Watch expressions: add registers, flags, symbols, and byte memory reads to VS Code's Watch panel with expressions such as A, HL, zero, [PACMO_LIVES], [HL], or [IX + 4] eq 0.
• Conditional breakpoints: use the same Watch expression language in VS Code breakpoint conditions, for example [PACMO_LIVES] eq 0 or zero and A eq $20.
• Integrated build workflow: AZM and the Glimmer reactive frontend are packaged with the extension and linked directly, so users do not need global compiler installs or a separate command-line toolchain just to start debugging.
• Register, symbol, stack, and memory visibility: inspect CPU registers, source-map symbols and constants, best-effort symbolic stack entries, flags, program counter state, memory regions, RAM contents, ROM-protected ranges, and platform-specific memory behaviour while a session is paused. Mapped stack entries can be used as safe temporary run targets without directly rewriting SP or PC.
• TEC-1 and TEC-1G emulation: run programs against machine profiles that model memory layout, reset behaviour, keypad input, seven-segment display, speaker output, bit-banged serial, monitor ROM workflows, and platform-specific memory behaviour. The TEC-1G profile also models MON-3-oriented devices such as LCD/GLCD output, RGB matrix output, RTC and SD SPI hooks when enabled.
• Debug80 panel inside VS Code: the extension contributes a dedicated view in the Run and Debug sidebar for project selection, target selection, platform controls, display panels, serial/terminal output, memory tools, and quick access to the current debug session.
• Project setup from VS Code: open a folder, let Debug80 create the project setup, and choose from discovered runnable targets.
• Z80 assembly language support: file associations and syntax highlighting for .asm, .z80, and .asmi files, including layout types, enums, contracts, and interface files.
• Glimmer language support: .glim projects compile through Glimmer and AZM, retain source-level breakpoints and diagnostics, and embed full Z80/AZM syntax highlighting inside begin/end bodies.

Quick Start

1. Open a Z80 project folder in VS Code.
2. Run Debug80: Create Project from the Command Palette.
3. Choose the TEC-1 or TEC-1G profile that matches your board.
4. Debug80 creates the project setup and looks for runnable targets in the folder.
5. Press F5 or run Debug80: Start Debugging.
6. Use breakpoints in your source files, the standard VS Code debug controls, and the Debug80 panel to inspect CPU and platform state.

Platform-focused starter workspaces are available separately:

• debug80-tec1 for classic TEC-1 monitor workflows.
• debug80-tec1g for TEC-1G and MON-3-oriented workflows.

Targets

Debug80 keeps its workspace setup in debug80.json, but you normally do not need to write that file by hand. The Create Project command generates the setup for the current folder, and Debug80 then looks for program entry points it can run.

Target discovery uses a small set of entry-point conventions to suggest targets:

• files ending in .main.asm
• files ending in .main.z80
• files named main.asm
• files named main.z80
• .glim files containing a top-level program declaration

Glimmer part files are not offered as standalone targets because they do not declare a complete program.

These names are conventions, not requirements. Use the + control beside the target selector to add any .asm, .z80, or complete Glimmer program in the project. Sources may live at the project root, under src/, or in other subdirectories. Removing a target with the - control changes debug80.json; it does not delete the source file or its existing build artifacts.

When more than one target is available, select the active target from the Debug80 panel or the Debug80: Select Active Target command.

Platforms

Debug80 currently promotes two hardware-focused profiles:

• TEC-1: classic monitor workflow with keypad, six-digit seven-segment display, speaker, bit-banged serial, and the expected ROM/RAM map.
• TEC-1G: MON-3 workflow with keypad, seven-segment display, speaker, serial, LCD/GLCD, RGB matrix output, memory protection/expansion behaviour, and optional RTC/SD hooks.

Scaffolded TEC-1 and TEC-1G projects use monitor ROM assets supplied by the extension. Copy the monitor ROM into your project only when you want to inspect, modify, replace, or debug the monitor source itself. Debug80 recognizes local monitor ROM entry points by convention (*.rom.asm) and uses the local ROM build instead of the bundled ROM when that entry point exists.

Useful Commands

Debug80 contributes commands for the normal project workflow:

• Debug80: Create Project: scaffold a project configuration and launch setup.
• Debug80: Start Debugging: launch the selected project and target.
• Debug80: Build Current Target: rebuild the active target and update the current debug session.
• Debug80: Select Workspace Folder and Debug80: Select Active Target: switch the active project context.
• Debug80: Set Program File: choose the source entry point from an editor or Explorer context menu.
• Debug80: Open Project Configuration Panel: open the active project config.
• Debug80: Open Auxiliary Source: open bundled or project-provided platform source material for the active platform profile.
• Debug80: Copy Monitor ROM into Project: copy the bundled monitor source into the project roms/ folder and create the local *.rom.asm ROM entry point used for monitor development.

Local VSIX Builds

For local testing as a packaged extension:

npm ci
npm run preflight
code --install-extension debug80-0.0.1.vsix --force

preflight runs lint, type checks, tests, packaging, and VSIX content verification. The full release checklist is in docs/release-process.md.

Development

npm install
npm run build
npm test

Debug80 packages its assembler dependency inside the VSIX. Published users should not need npm link, sibling checkouts, or globally installed assembler binaries.

Documentation

• debug80.com: published user guides and AZM books/manual.
• Debug80 Book 1 — Getting started: installation, opening a folder, targets, building, the debugger, the emulated machine, sending to real hardware, and the project panel's settings.
• Debug80 Engineering Manual: extension architecture, launch pipeline, platform runtimes, webview panels, source mapping, extension points, release testing, and regression gates.
• D8 Debug Map Format: native source mapping format consumed by Debug80.
• AZM Books and Manual: Z80 learning material and AZM assembler reference.
• Glimmer Book: reactive Z80 game development with Glimmer and Debug80.
• Release process: local checkout checklist for VSIX preparation and publishing.