NovaVM is a Walker Heavy Industries project.
A 6502/65C02 computer implemented as an emulator, an FPGA core, and a host bridge.
Quickstart • Current Focus • Hardware Surface • FPGA and NovaHost • Build and Test
NovaVM is a custom 6502-family computer platform. It started as a C# emulator around a 6502 core, but the project is now centered on keeping one machine model aligned across three targets:
- Avalonia: the reference desktop implementation and development UI.
- Verilator: a fast RTL simulation target for FPGA hardware validation.
- ULX3S FPGA + ESP32 NovaHost: the active hardware target, with HDMI output, SDRAM-backed expansion memory, SD-card storage, ROM loading, and debug control through the ESP32.
The machine is not a clone of any existing vintage computer. It keeps the 6502 programming model, then adds Nova-specific devices: video, sprites, DMA, blitter, copper lists, expansion RAM, file I/O, audio, and target-specific host services such as networking and debug control.
The screenshot above is the current boot frame from the Avalonia hardware model: a 720x480 output frame with a centered 640x400 Nova canvas and visible border. That geometry matches the default video profile used by the FPGA and Verilator builds.
# Prerequisites: .NET 10 SDK
git clone https://github.com/barryw/NovaVM.git
cd NovaVM
dotnet restore e6502.sln
dotnet run --project e6502.AvaloniaThe Avalonia host boots NovaBASIC and starts a local emulator control server.
Type BASIC at the Ready prompt, or use the TCP/MCP tooling to drive the
machine programmatically.
The Avalonia build currently rebuilds the NovaBASIC ROM and help artifacts
before launch. For a full local build, have ca65, ld65, pandoc, and a
LaTeX toolchain available.
The main work is hardware parity and system integration:
- keep Avalonia, Verilator, and FPGA behavior aligned,
- stabilize the ULX3S video, reset, timing, sprite, DMA, and XRAM paths,
- make ESP32 NovaHost the owner of SD-card files, ROM loading, boot assets, NDI disk images, and debug transport,
- standardize flat 24-bit XRAM access for BASIC, assembly, and the other language runtimes,
- keep NovaBASIC as the default runtime while growing the alternate language runtimes (NovaLogo, NovaForth, NovaZ) that take over the ROM slot.
Polished demos are intentionally secondary until the VM is stable. The README should describe the machine we are building, not hide the hardware bring-up behind an old desktop-only demo.
| Component | Current shape |
|---|---|
| CPU | 6502/65C02 core, 12 MHz target, 64 KB address space |
| Main memory | 64 KB CPU-visible RAM/ROM/MMIO map |
| ROM | NovaBASIC/EhBASIC at $C000-$FFFF; alternate runtimes and extension modules use ROM switching |
| XRAM | 512 KB expansion memory, treated as a flat 24-bit byte address space |
| XRAM windows | Four 256-byte mapped windows at $BC00-$BFFF |
| Display | VGC output targeting 720x480, with a 640x400 Nova canvas |
| Text | 80x50 character, color, and text-attribute planes |
| Bitmap graphics | 320x200 4-bit graphics layer |
| Sprites | 16 hardware sprites, 16x16 pixels, shape RAM, priority, and collision paths |
| Tiles | Tile engine registers and tile data memory |
| Copper | Raster-positioned register writes and IRQ events |
| DMA | Bulk copy/fill across CPU RAM, VGC memory spaces, sprites, tiles, and XRAM |
| Blitter | Rectangular copy/fill with stride and color-key support |
| Audio | Dual SID model, SID playback, music engine, plus Avalonia-side wavetable-synth work |
| Storage | FIO controller, host directories, NDI images, and direct XRAM load/save paths |
| Network | Four-slot message-oriented TCP NIC in the Avalonia target |
The important design rule is that custom hardware is not an emulator trick. Whenever possible, the same register model and memory behavior should exist in Avalonia, Verilator, and FPGA.
Nova is no longer a BASIC-only machine. Several language runtimes now exist. A non-BASIC runtime takes over the ROM slot entirely — it is loaded in place of NovaBASIC, not alongside it.
| Runtime | Status | Notes |
|---|---|---|
| NovaBASIC | Stable — default runtime | EhBASIC 2.22 extended with Nova hardware commands. Runs on Avalonia and FPGA. The most complete runtime. |
NovaLogo (software/languages/novalogo/) |
Usable — v1.0 | Logo interpreter: turtle graphics, procedures, recursion, lists, and garbage collection. Builds a 16 KB ROM image loaded in place of NovaBASIC. |
NovaForth (software/languages/novaforth/) |
Early — v0.1 | Nova-native threaded Forth with an interactive REPL and dictionary. Builds a 16 KB ROM image. Experimental. |
NovaZ (software/examples/novaz/) |
Playable — Z-machine V3–V6 | Z-machine interpreter for Infocom interactive fiction. Ships as bootable NDI disk images with XRAM-backed story memory. 16 story projects are packaged (Zork I–III, HHGG, Trinity, Beyond Zork, Zork Zero, and more); the V6 path is actively stabilizing. |
NovaBASIC is the only runtime currently verified on FPGA hardware. NovaLogo, NovaForth, and NovaZ are 65C02 code and are developed against the Avalonia and Verilator targets.
NovaBASIC is EhBASIC 2.22 extended with machine-specific commands for the hardware surface:
- graphics, sprites, color, font, and text control,
- SID sound, MML music, MIDI/SID playback paths,
- DMA and blitter commands,
- XRAM allocation, banking, windows,
XLOAD, andXSAVE, - file, host-directory, and NDI-backed storage commands,
- TCP networking commands in the Avalonia host,
- IRQ/NMI helpers and low-level
PEEK/POKEaccess.
Assembly code can use the shared XRAM runtime in software/runtime/asm/xram.inc and
software/runtime/asm/xram.s. BASIC keeps a convenient XBANK plus 16-bit offset model,
while assembly routines can treat XRAM as a 24-bit flat address space.
The optional XMC named-block command processor is shared in
software/runtime/asm/xmc.s.
Shared text-region helpers live in software/runtime/asm/vtext.inc and
software/runtime/asm/vtext.s. They provide reusable VGC text/color/attribute region
clear, output, and scroll primitives for assembly programs and language
runtimes.
The Nova Developer Kit (NDK) in software/ndk/ packages this developer surface for
writing Nova software outside the BASIC ROM tree: the shared software/runtime/asm/
libraries, generated hardware constants, assembly documentation, and standalone
example programs collected into one distributable directory. Standalone 65C02
applications and demos live in software/assembly/, and loadable runtime modules
(paged NMOD binaries staged in XRAM) live in software/modules/.
The FPGA tree is a first-class implementation target, not an afterthought.
e6502.FPGA/rtl/ contains the synthesizable system: top-level bus fabric,
VGC, text/gfx/sprite/tile/copper logic, DMA, blitter, FIO, SID modules,
SDRAM-backed XRAM, the debug bridge, and the 6502 core.
e6502.FPGA/test/ contains Verilator/SystemVerilog tests for the hardware
blocks and top-level integration paths. The FPGA bring-up workflow uses these
tests before hardware flashing whenever possible.
e6502.ESP32/novahost/ is the ESP32 companion firmware. NovaHost owns the SD
card and exposes the current hardware management surface:
- ROM and extension-ROM loading,
- cold start and debug control,
- SD file access and mounted NDI image support,
- FIO event handling,
- boot assets and staged configuration files,
- HTTP and TCP management/debug endpoints.
Today, command-line disk-image and SD asset management work lives in
e6502.Nova. The CLI is nova; NDI remains the disk-image format used for
floppies and hard drives. Current command syntax and NativeAOT publish
output are documented in docs/books/nova-cli-guide; the disk-image
format itself is included in that same book.
The Model Context Protocol server still exists, but it is no longer the whole story of the project.
dotnet run --project e6502.MCPThe MCP server talks to the running Avalonia host over the local emulator TCP server. It can type BASIC, read the screen, manipulate hardware state, inspect memory, drive graphics and audio tools, and help debug programs. It is useful for development and automation, but the core goal is now consistent Nova hardware behavior across all targets.
dotnet restore e6502.sln
dotnet build e6502.sln -c Release -m:1
dotnet test e6502.sln -c Release --no-buildUseful target-specific commands:
dotnet run --project e6502.Avalonia # Desktop reference host
dotnet run --project e6502.CLI # Headless BASIC host
dotnet run --project e6502.MCP # MCP bridge
dotnet run --project e6502.Nova # Nova CLI, development mode
dotnet run --project e6502.Nova -- publish # NativeAOT single-binary Nova CLI
make -C software/languages/ehbasic # Rebuild NovaBASIC ROM artifacts
make -C e6502.FPGA # Build the Verilator simulator
make -C e6502.FPGA run # Run the Verilator simulator
make -C e6502.FPGA/boards/ulx3s bitstream # Build ULX3S bitstreamFPGA bitstream builds require the OSS CAD Suite tools (yosys,
nextpnr-ecp5, ecppack) and openFPGALoader for programming hardware.
ESP32 NovaHost builds use the Arduino ESP32 toolchain.
| Path | Purpose |
|---|---|
e6502/ |
Core 6502/65C02 CPU emulator library |
e6502.Avalonia/ |
Desktop reference machine, VGC/audio/storage/network devices, editors, TCP bridge |
e6502.Browser/ |
Browser/WebAssembly host experiment sharing Avalonia hardware/rendering code |
e6502.Browser.RustCore/ |
Rust no_std WebAssembly core (CPU/RAM/ROM/VGC) powering the browser emulator |
e6502.CLI/ |
Terminal-hosted NovaBASIC runner |
e6502.MCP/ |
MCP server for external control of the Avalonia host |
e6502.Nova/ |
Nova command-line tooling for NDI images and NovaHost assets |
e6502.NovaHost/ |
Shared TCP client library for NovaHost management (6504) and debug (6503) ports |
e6502.NovaPanel/ |
Avalonia remote-control app for Nova hardware (on-screen keyboard, web-admin parity) |
e6502.NovaPanel.Tests/ |
Headless Avalonia tests for NovaPanel |
e6502.GameServer/ |
TCP game server (chess, echo) speaking the Nova NIC message framing |
e6502.Storage/ |
NDI and host-directory storage abstractions |
e6502.Tools/ |
Host-side utilities such as SID relocation/conversion helpers |
e6502Debugger/ |
Windows Forms debugger project |
e6502.FPGA/ |
SystemVerilog RTL, Verilator simulation, ULX3S build flow, FPGA tests |
e6502.ESP32/novahost/ |
ESP32 companion firmware for SD, debug, ROM loading, and host services |
software/languages/ehbasic/ |
NovaBASIC/EhBASIC source, extension ROM, XRAM runtime, token definitions |
software/languages/novalogo/ |
NovaLogo interpreter ROM source |
software/languages/novaforth/ |
NovaForth runtime ROM source |
software/examples/novaz/ |
NovaZ Z-machine runtime, packaged stories, and NDI image build |
software/examples/novachess/ |
NovaChess runtime, engine integration, and NDI image build |
software/ndk/ |
Nova Developer Kit: packaged assembly libraries, constants, docs, examples |
software/runtime/ |
Shared 65C02 assembly libraries (XRAM, vtext, NDK primitives) |
software/modules/ |
Loadable runtime modules (paged NMOD binaries staged in XRAM) |
software/assembly/ |
Standalone 65C02 applications and demos |
NovaDraw/ |
macOS pixel-art editor for Nova sprites/tiles/graphics (with MCP server) |
website/ |
Static project site (PDFs, browser emulator, showcase images) |
docker/ |
CI build container images |
docs/books/ |
PDF book source trees and build entry point |
docs/help/ |
User-facing NovaBASIC help content and command reference |
docs/plans/ |
Architecture, bring-up, and future feature planning docs |
software/tests/integration/ |
Assembly-level integration suites for simulator/hardware backends |
e6502UnitTests/ |
MSTest suite for CPU, devices, storage, editors, compiler, and host behavior |
The best current technical references are:
docs/help/guides/memory-map.mddocs/help/guides/assembly.mddocs/help/guides/expansion-memory.mddocs/help/guides/dma-and-blitter.mddocs/fpga-debugging-workflow.mddocs/plans/
PDF book source trees in docs/books/:
basic-user-guide/— NovaBASIC user guidemapping-the-novavm/— hardware/architecture referencendk-reference/— Nova Developer Kit referencenova-cli-guide/—novaCLI and NDI disk-image formatnova-fun-n-games/— programming examples and games
The docs are evolving along with the hardware. Recent planning documents are often more accurate than old screenshots or demo programs.
NovaVM is licensed under the MIT License — see License.txt. It began as a fork of amensch/e6502 (MIT) and bundles third-party components (test suites, EhBASIC, FPGA cores) that keep their own licenses — see THIRD-PARTY-NOTICES.md.
This follows the Walker Heavy Industries house licensing policy: MIT is the house
default for original code (see the suite LICENSING.md).
NovaVM is part of the Walker Heavy Industries retro toolchain — modern tools for the retro 8- and 16-bit ecosystem.
- House hub: https://whi.dev
- Siblings: VICE Mac · VICE MCP · FamiForge · NESBasic · Novus · Miggy Draw · NovaVM