Debug80 IDE for Z80 Development

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

Debug80 turns VS Code into a practical development environment for Z80 assembly programs. It assembles 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.

Features

• Source-level Z80 debugging: set breakpoints in .asm and .z80 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.
• Integrated assembler workflow: a Z80 assembler is packaged with the extension and linked directly, so users do not need a global assembler install or a separate command-line toolchain just to start debugging.
• Register and memory visibility: inspect CPU registers, flags, program counter state, memory regions, RAM contents, ROM-protected ranges, and platform-specific memory behaviour while a session is paused.
• 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.

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.

For now, target discovery focuses on clear Z80 entry-point conventions:

• files ending in .z80
• files ending in .main.asm

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 bundled ROM assets supplied by the extension. Copy those assets into your workspace only when you want to inspect, replace, or override them.

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: Restart Debugging (Current Target): rebuild/restart the active target.
• 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 ROM Source: open bundled or project-provided ROM source material for the active platform profile.
• Debug80: Copy Bundled Assets into Workspace: materialise bundled platform assets when you want local inspection or overrides.

Local VSIX Builds

For local testing as a packaged extension:

npm ci
npm run package:check
code --install-extension debug80-0.0.1.vsix --force

package:check runs 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

• Technical guide: extension architecture, launch pipeline, adapter behaviour, mapping, and stepping.
• Platform architecture: platform model and configuration.
• Platform extension API: registering external runtime/UI platforms.
• D8 debug map: native source mapping format.
• Timing model: cycle timing and platform I/O timing.
• Platform development guide: adding new platform runtimes and panels.