Z80 Assembler Plugin for JetBrains IDEs

A feature-rich Z80 assembly language plugin for JetBrains IDEs (IntelliJ IDEA, CLion, WebStorm, and other IntelliJ Platform-based IDEs), designed specifically to optimize developer productivity and retro-computing workflows targeting the z80asm assembler.

Note: This project is vibecoded — developed and curated with modern AI-assisted engineering and iterative vibecoding workflows to deliver a highly responsive and integrated retro-development environment that's full of bugs.

---

Overview

Developing Z80 assembly code for classic computing platforms requires swift navigation, instant instruction references, and accurate symbol resolution across complex file include hierarchies. The Z80 Assembler Plugin bridges the gap between classic assembly programming and modern IDE tooling by providing intelligent code assistance, integrated hardware documentation, live assembled memory address feedback, and multi-file project awareness.

---

Capabilities & Features

1. Syntax Highlighting & Editor Integration

• Full Syntax Highlighting: Distinct visual styling for Z80 instructions, registers, directives, labels, numbers, string literals, operators, and delimiters.
• Number Formats Supported: Full parsing of Hexadecimal ($1234, 0x1234, 1234h, 0FFh), Binary (%10101010, 0b10101010), and Decimal numbers.
• Comments Support: Single-line comments (;) and C-style block comments (/* ... */), with native IDE commenting shortcuts (Ctrl+/ or Cmd+/).
• Customizable Color Scheme: Fully configurable color attributes via Settings / Preferences → Editor → Color Scheme → Z80 Assembly.
• Supported File Types: .z80, .asm, .asm80 (with cross-reference tracking across .inc, .mac, and .s files).

2. Intelligent Code Completion (IntelliSense)

• Z80 Mnemonics: Instant autocompletion for all standard instructions with operand hints and functional descriptions (e.g., LD dst, src, DJNZ offset, LDIR, EXX).
• Directives: Broad support for assembler directives including org, equ, db, dw, ds, defb, defw, defm, defc, include, incbin, macro, and dot-prefixed variants (.org, .db, etc.).
• Registers & Conditions: Completion for 8-bit/16-bit registers (A, BC, HL, IX, IY, SP, AF', etc.) and condition codes (Z, NZ, C, NC, PO, PE, P, M).
• Project-Wide Symbol Completion: Automatically discovers labels, constants, equates, data declarations, and macros across the active file and all included modules in correct hierarchical order.
• Platform-Specific Symbols: Contextual completion of BIOS routine names, hardware registers, and I/O symbols corresponding to your configured target platform.

3. Symbol Navigation & Definition Resolution

• Go to Definition / Declaration: Navigate directly to definitions (Ctrl+B / Cmd+B or Ctrl+Click / Cmd+Click) for labels, constants, macros, and imported files.
• Multi-File Include Hierarchy: Seamlessly resolves symbols defined across nested .include, .incbin, read, insert, or binary directives.
• Top / Main Assembly File Concept: Specify a project entry file so modular assembly sources correctly inherit declarations and equates defined higher up the include tree.

4. Live Gutter Memory Addresses (z80asm Integration)

• Real-time Assembly Feedback: Integrates directly with the z80asm assembler executable in the background.
• Gutter Address Annotations: Displays assembled hexadecimal memory addresses (e.g., $8000, $C000) directly next to labels in the left editor gutter.
• Status & Origin Tooltips: Hovering over gutter addresses provides decimal conversion values, entry point source file details, and stale-status warnings if assembly errors occur.

5. Interactive Hardware Documentation & Reference System

• Quick Documentation Tooltips (Ctrl+Q / F1): Rich HTML documentation showing opcode bytes, T-state execution cycles, affected status flags, and descriptions for instructions, registers, condition codes, and directives.
• Z80 Documentation Tool Window: Dedicated right-sidebar tool window featuring interactive reference manuals:
  • Core Z80: Complete instruction set and architecture guide.
  • MSX 1: BIOS routines, VDP registers & display modes (TMS9918A), memory slot architecture, PSG sound mixer (AY-3-8910), and I/O port assignments.
  • MSX 2: Sub-ROM BIOS calls, Yamaha V9938 VDP command engine, and expanded graphical modes.
  • ZX Spectrum: 128K memory paging ($7FFD), Port $FE ULA hardware, ROM routines (Print, Beep), screen memory layout, and system variables map.
  • Amstrad CPC: CRTC 6845 controller registers, Gate Array color & banking, and firmware jump vectors.
  • ColecoVision: Hardware architecture overview and memory map.
• Auto-Sync with Caret: Documentation views automatically update to display reference manuals for the opcode, symbol, or hardware alias currently under your editor cursor.

6. Z80 Definition Tool Window

• Live Symbol Inspector: Dedicated tool window displaying the source definition context of the currently selected symbol without losing your active editor position.
• Quick Jump & Top File Switcher: Easily navigate to symbol source files or adjust the project root assembly file on the fly.

7. Project Settings & Configuration

Accessible via Settings / Preferences → Z80 Assembly:

• Main / Top Assembly File: Set the root entry file to ensure deterministic cross-file symbol resolution.
• Target Platform: Switch between Core Z80 (Generic), MSX 1, MSX 2, ZX Spectrum, Amstrad CPC, or ColecoVision.
• z80asm Executable Path: Configure a custom path or rely on automatic system PATH discovery across Linux, macOS, and Windows.
• Show Gutter Memory Addresses: Toggle real-time gutter memory address labels on or off.

---

Configuration & Getting Started

1. Install z80asm: Ensure z80asm is installed and accessible in your system PATH (e.g., sudo apt install z80asm on Debian/Ubuntu, brew install z80asm on macOS, or via package managers on Windows).
2. Open Project: Open any folder containing Z80 assembly files (.z80, .asm, .asm80).
3. Configure Project Settings:
   • Go to Settings / Preferences → Z80 Assembly.
   • Select your Main / Top Assembly File (if working with a multi-file project).
   • Select your Target Platform (e.g., MSX 1, ZX Spectrum, etc.) to enable platform-specific completion and reference documentation.
4. Explore Tool Windows: Open the Z80 Documentation or Z80 Definition tool windows from the right sidebar for real-time reference and inspection while coding.

---

Building from Source

Prerequisites

• JDK 17 or later
• IntelliJ Platform 2024.2+ compatible environment

Build Commands

Clone the repository and run Gradle wrapper tasks:

# Build the plugin distribution archive
./gradlew buildPlugin

# Run a sandboxed IDE instance with the plugin installed
./gradlew runIde

# Execute test suite
./gradlew test

The resulting distribution ZIP file will be located in build/distributions/.

---

License

This project is licensed under the MIT License.