NorthMac

A NorthStar Advantage (circa 1982) emulator for macOS, built with SwiftUI and Metal.

What It Does

NorthMac emulates the NorthStar Advantage Z80-based microcomputer — an all-in-one machine with a built-in CRT, dual 5.25" floppy drives, and a bitmap graphics display. The emulator boots real CP/M disk images and runs vintage software.

Features

• Full Z80 CPU emulation via C core (z80.c/z80.h)
• 256KB memory with bank switching (4 x 16KB mapping registers)
• Metal CRT shader with scanlines, phosphor bloom, barrel distortion, and phosphor persistence
• Green, Amber, and White phosphor colors
• Floppy disk controller state machine supporting 175KB and 350KB NSI images
• Hard disk controller supporting NHD images
• Disk write-back with per-drive Write Protect toggle (defaults to on); modifications are atomically flushed back to the source .NSI / .NHD on app quit, with a one-time .bak next to the original
• Keyboard input via macOS key events mapped to NorthStar scan codes
• Audio with programmable speaker emulation
• Turbo mode (Cmd+T) for maximum speed — over 200x faster than original hardware
• Screenshots (Cmd+S) saved to your preferred location

What Boots

CP/M 1.2 and 2.2 disk images built for the Advantage platform boot successfully, including: advf2, system_flp, CPM Master, CPMBASIC, WORDSTAR, WordstarG, DataStar, SMALLC, FML80, NSCS58, NSCS61, DEMODIAG, and more.

Note: NorthStar Horizon disk images (N2212_64, N22A_56, etc.) are for different hardware and will not boot.

Building

Requires Xcode 15+ and macOS 14+.

1. Clone this repo
2. Open NorthMac.xcodeproj in Xcode
3. Build and run (Cmd+R)

Disk Images & Boot ROM

Disk images (.NSI, .NHD) and the boot ROM (AdvantageBootRom.bin) are not included for copyright reasons.

• Place the Advantage Boot ROM as Resources/AdvantageBootRom.bin
• Place floppy disk images in Disk Images/Bootable/
• Place hard disk images in Hard Disks/

These can be found in various vintage computing archives and preservation sites. A good collection of NorthStar Advantage disk images is available from Dave Dunfield's classiccmp archive. Boot ROMs, documentation, and additional resources are available from djones60/NorthStar-Advantage.

Performance

The original NorthStar Advantage ran a Z80A at 4 MHz. On Apple Silicon, NorthMac's turbo mode reaches approximately 870 MHz of emulated Z80 throughput — roughly 218x the speed of the original hardware. At normal speed, the emulator idles at under 5% CPU usage thanks to HALT detection and frame-skip optimizations.

Key optimizations: direct memory access from the C core (bypassing Swift callbacks), a tight C run loop (emulator_run_frame) that only calls back to Swift every 34 instructions for FDC timing, GPU-side video RAM transpose, and LDIR/LDDR block-transfer fast paths.

Keyboard Shortcuts

Shortcut	Action
Cmd+P	Pause / Resume
Cmd+T	Toggle Turbo Mode
Cmd+Shift+R	Reset (cold boot)
Cmd+S	Save Screenshot

Command-Line Launch

NorthMac can be launched from the terminal with disk images supplied as arguments — handy for booting straight into a specific configuration:

northmac disk1.nsi [disk2.nsi] [hd.nhd]

• The first .nsi mounts to floppy drive 1, the second to drive 2.
• The first .nhd mounts as the hard disk.
• Relative paths are resolved against the shell's current directory.
• These mounts are one-shot: they do not overwrite the GUI's last-used selection, so the next launch (without args) restores your saved session.

A wrapper script lives at bin/northmac. Symlink it onto your $PATH using the absolute path to the script — $(pwd) only works if you're sitting in the repo root, which is a frequent footgun:

# /usr/local/bin (Intel default, root-owned — needs sudo)
sudo ln -sf "$PWD/bin/northmac" /usr/local/bin/northmac

# /opt/homebrew/bin (Apple Silicon, user-owned — no sudo)
ln -sf "$PWD/bin/northmac" /opt/homebrew/bin/northmac

(Run either of those from the repo root.) Verify with which northmac — if it prints a path but northmac errors with "file not found," your symlink target is wrong; re-create it with the absolute path printed by realpath bin/northmac.

The wrapper expects the app at /Applications/NorthMac.app; override with NORTHMAC_APP=/path/to/NorthMac.app northmac ….

Architecture

NorthMac/
  NorthMacApp.swift           -- SwiftUI App entry
  ContentView.swift           -- Main window with display + toolbar
  Core/
    EmulatorCore.swift        -- Z80 run loop, timing, lifecycle
    MemorySystem.swift        -- 256KB RAM + bank switching
    IOSystem.swift            -- I/O port dispatch
    FloppyDiskController.swift -- FDC state machine + NSI I/O
    HardDiskController.swift  -- HDC emulation + NHD I/O
    DisplaySystem.swift       -- Video RAM rendering
    KeyboardSystem.swift      -- macOS key -> Advantage key mapping
    AudioSystem.swift         -- Speaker emulation
  Views/
    MetalDisplayView.swift    -- MTKView + CRT fragment shader
  Models/
    DiskImage.swift           -- NSI format detection + validation
  Bridge/
    z80-bridge.h              -- C bridging header
  z80.c / z80.h               -- Z80 CPU core (C)
Tests/
  NorthMacCoreTests/          -- XCTest suite for FDC + HDC
Package.swift                 -- SPM target for `swift test` (Xcode app target unaffected)

Testing

Disk-handling regressions are guarded by an SPM-based XCTest suite covering the floppy and hard disk controllers — write-protect gating, dirty-flag bookkeeping, atomic write-back, one-time .bak semantics, and NHD magic-byte validation:

swift test

24 tests, ~2 s on Apple Silicon. Each test runs in its own NSTemporaryDirectory subfolder, so the suite never touches your real disk images.

Acknowledgments

The Z80 CPU core is based on superzazu/z80, a clean open-source Z80 emulator in C.

The ADE emulator by Jack Strangio served as an invaluable reference for the NorthStar Advantage I/O architecture, FDC state machine, and memory mapping behavior.

License

MIT

Copyright © 2026 David Troy

---

Dedicated to the memory of Stephen Troy, whose NorthStar Advantage was one of my first computers. Thanks, Dad.