xroar(1)

📦 version 1.13.0.dev-unstable-2026-08, in nixpkgs unstable

💖 NAME 💖

xroar(1) — from the General Commands Manual — is the Dragon and Tandy 8-bit computer emulator, bestie. That’s the whole main-character vibe. 💅

🎮 SYNOPSIS 🎮

xroar [-c conffile] [OPTION]… [FILENAME]…

🌈 DESCRIPTION 🌈

Okay so XRoar emulates the Dragon 32/64; Tandy Colour Computers 1, 2 and 3; the Tandy MC-10; and some other similar machines or clones. It runs on a wide variety of platforms. Literally versatile icon behavior. ✨

✨ OPTIONS ✨

Real talk: options are first read from a configuration file (by default, $HOME/.xroar/xroar.conf). Options on the command line override any found in the configuration file. CLI is the boss, periodt. 💅

  • -C — Allocate a console window (Windows only).
  • -c conffile — Specify a configuration file.

🐉 Machines 🐉

  • -m name, -default-machine name — Default machine profile to select on startup.
  • -machine name — Create or modify named machine profile. -machine help lists currently defined profiles.

The remaining options configure the currently selected machine — yes, these next ones, bestie:

  • -machine-desc text — Machine description shown in -machine help and menu options.
  • -machine-arch arch — Machine architecture (dragon64, dragon32, coco, coco3 or mc10).
  • -machine-keyboard layout — Keyboard layout (dragon, dragon200e, coco or coco3).
  • -machine-cpu cpu — Machine CPU (6809 or 6309). Not applicable to the MC-10.
  • -bas rom — ROM image for Colour BASIC (CoCo) or Microcolour BASIC (MC-10).
  • -extbas rom — ROM image for Extended BASIC (Super Extended BASIC on the CoCo 3).
  • -altbas rom — ROM image for 64K-mode Extended BASIC (Dragon 64, Dragon 200-E).
  • -nobas, -noextbas, -noaltbas — Indicate the corresponding ROM is not fitted in this machine.
  • -ext-charset rom — External character generator ROM to use.
  • -tv-type type — TV type (pal, ntsc or pal-m).
  • -tv-input input — One of cmp (composite video, no cross-colour), cmp-br (composite video, blue-red cross-colour), cmp-rb (composite video, red-blue cross-colour) or rgb (RGB video, CoCo 3 only).
  • -vdg-type type — Indicate the VDG variant fitted. One of 6847 or 6847t1.
  • -ram-org organisation — RAM organisation (-ram-org help for list).
  • -ram kbytes — Amount of RAM fitted in kilobytes. Valid sizes are 4–64K for Dragon and Tandy CoCo 1/2; 128K or 512K for the Tandy CoCo 3; 2K, 4K or 20K for the Tandy MC-10.
  • -ram-init pattern — RAM start pattern (-ram-init help for list).
  • -machine-cart name — Default cartridge to attach. -no-machine-cart to inhibit the default behaviour of searching for a workign DOS cartridge.

🧩 Cartridges 🧩

  • -cart name — Create or modify named cartridge profile. -cart help lists currently defined profiles.

The remaining options configure the currently selected cartridge:

  • -cart-desc text — Cartridge description shown in -cart help and menu options.
  • -cart-type type — Cartridge base type (-cart-type help for list).
  • -cart-rom rom — ROM image to load ($C000-).
  • -cart-rom2 rom — Second ROM image to load ($E000-).
  • -cart-autorun — Autorun cartridge.
  • -cart-becker — Enable becker port where supported.
  • -mpi-slot slot — (MPI) initially select slot (0–3).
  • -mpi-load-cart [slot=]name — (MPI) insert cartridge into next or numbered slot.

When configuring a Multi-Pak Interface (MPI), only the last configured DOS cartridge will end up connected to the virtual drives. MPI options also apply to the similar RACE Computer Expansion Cage. Iykyk, that detail matters. 🫶

🔌 Becker port 🔌

  • -becker — Prefer becker-enabled DOS cartridge when picked automatically.
  • -becker-ip address — Address or hostname of DriveWire server [127.0.0.1]
  • -becker-port port — Port of DriveWire server [65504]

📼 Cassettes 📼

  • -load-tape file — Attach file as tape image for reading.
  • -tape-write file — Open file for tape writing.
  • -tape-pan panning — Pan stereo input (0.0 = full left, 1.0 = full right) [0.5]
  • -tape-hysteresis percent — Read hysteresis as percentage of full scale [1]
  • -no-tape-fast — Disable fast tape loading.
  • -no-tape-pad-auto — Disable automatic leader padding.
  • -tape-rewrite — Enable tape rewriting.
  • -tape-rewrite-gap-ms ms — Gap length in milliseconds to write in rewrite mode (1–5000ms, default 500ms).
  • -tape-rewrite-leader bytes — Length of leaders in bytes to write in rewrite mode (1–2048 bytes, default 256).
  • -tape-ao-rate hz — Set tape writing frame rate [9600]

💾 Floppy disks 💾

  • -load-fdX file — Insert disk image file into floppy drive X (0–3).
  • -no-disk-write-back — Don't default to enabling write-back for disk images.
  • -no-disk-auto-os9 — Don't try to detect headerless OS-9 JVC disk images.
  • -no-disk-auto-sd — Don't assume single density for 10 sec/track disks.

🗄️ Hard disks 🗄️

  • -load-hdX file — Use file as the hard disk image for drive X (0–1).
  • -load-sd file — Use file as the SD card image (e.g. for mooh, nx32).

⌨️ Keyboard ⌨️

  • -kbd-layout layout — Host keyboard layout (-kbd-layout help for list).
  • -kbd-lang lang — Host keyboard language (-kbd-lang help for list).
  • -kbd-bind hostkey=[pre:]emukey — Map host key to emulated key. Prefixing emulated key name with 'pre:' disables translation for the bind (the bind "preempts" translation). Host key names can be determined by running with -debug-ui 1, which will log keypresses.
  • -kbd-translate — Enable keyboard translation.
  • -type string — Intercept ROM calls to type string into BASIC.
  • -load-text file — Type file into BASIC.

🕹️ Joysticks 🕹️

  • -joy-db-file file — Load gamepad mappings from file.
  • -joy-right name — Map right joystick.
  • -joy-left name — Map left joystick.
  • -joy-virtual name — Specify the 'virtual' joystick to cycle [kjoy0]
  • -joy name — Configure named joystick (-joy help for list).

The remaining options configure the currently selected joystick:

  • -joy-desc text — Joystick description.
  • -joy-axis axis=spec — Configure joystick axis.
  • -joy-button btn=spec — Configure joystick button.

Joystick specs are of the form [module:][arg[,arg]…], from:

  • physical — axis args: joystick-index,[-]axis-index; button args: joystick-index,button-index
  • keyboard — axis args: key-name0,key-name1; button args: key-name
  • mouse — axis args: screen-offset0,screen-offset1; button args: button-number

For physical joysticks a - before the axis index inverts the axis. Axis 0 is the X-axis, and axis 1 the Y-axis. Buttons are numbered 0 or 1 (the second is only used when connected to a CoCo 3). No cap, that’s the whole mapping tea. 🍓

🖨️ Printers 🖨️

  • -lp-file file — Append printer output to file.
  • -lp-pipe command — Pipe printer output to command.

📂 Files 📂

  • -load file — Load or attach file
  • -run file — Load or attach file and attempt autorun
  • -load-fdX file — Insert disk image file into floppy drive X (0–3).
  • -load-hdX file — Use file as the hard disk image for drive X (0–1).
  • -load-sd file — Use file as the SD card image (e.g. for mooh, nx32).
  • -load-tape file — Attach file as tape image for reading.
  • -tape-write file — Open file for tape writing.
  • -load-text file — Type file into BASIC.

📼 Firmware ROM images 📼

  • -rompath path — ROM search path (colon-separated list).
  • -romlist name=list — Define a ROM list.
  • -romlist-print — Print defined ROM lists.
  • -crclist name=list — Define a ROM CRC list.
  • -crclist-print — Print defined ROM CRC lists.
  • -force-crc-match — Force per-architecture CRC matches.

🖥️ User interface 🖥️

  • -ui module — User-interface module (-ui help for list).

🌈 Video 🌈

  • -fs — Start emulator full-screen if possible.
  • -fskip frames — Frameskip (default: 0).
  • -ccr renderer — Cross-colour renderer (simple, 5bit, partial or simulated).
  • -gl-filter filter — OpenGL texture filter (auto, nearest or linear).
  • -vo-vsync — Start with vsync enabled.
  • -vo-pixel-fmt format — Pixel format (-vo-pixel-fmt help for list).
  • -geometry wxh+x+y — Initial emulator geometry.
  • -vo-picture p — Initial picture area (-vo-picture help for list).
  • -no-vo-scale-60hz — Disable vertical scaling for 60Hz video.
  • -invert-text — Start with text mode inverted.
  • -vo-brightness n — Set TV brightness (0–100) [50]
  • -vo-contrast n — Set TV contrast (0–100) [50]
  • -vo-colour n — Set TV colour saturation (0–100) [50]
  • -vo-hue n — Set TV hue control (-179 to +180) [0]
  • -vo-monochrome — Use a black-and-white display (disabled by default).
  • -no-vo-colour-killer — Disable colour killer (enabled by default).

🔊 Audio 🔊

  • -ao module — Audio module (-ao help for list).
  • -ao-device string — Device to use for audio module.
  • -ao-format fmt — Set audio sample format (-ao-format help for list).
  • -ao-rate hz — Set audio frame rate (if supported by module).
  • -ao-channels n — Set number of audio channels, 1 or 2.
  • -ao-fragments n — Set number of audio fragments.
  • -ao-fragment-ms ms — Set audio fragment size in ms (if supported).
  • -ao-fragment-frames n — Set audio fragment size in samples (if supported).
  • -ao-buffer-ms ms — Set total audio buffer size in ms (if supported).
  • -ao-buffer-frames n — Set total audio buffer size in samples (if supported).
  • -ao-gain db — Audio gain in dB relative to 0 dBFS [-3.0]
  • -volume volume — Older way to specify audio volume, linear (0–100).

🐛 Debugging 🐛

  • -gdb — Enable GDB target.
  • -gdb-ip address — Address of interface for GDB target [127.0.0.1]
  • -gdb-port port — Port for GDB target to listen on [65520]
  • -gdb-pseudo-regs — Enable pseudo-registers (e.g. SAM, PIA) for GDB.
  • -gdb-flags-as-struct — Describe CPU flags as a struct to GDB.
  • -no-ratelimit — Run CPU as fast as possible.
  • -trace — Start with trace mode on.
  • -trace-timing — Print timings in trace mode.
  • -debug-fdc flags — FDC debugging 👀 (check the manual, or just slap -1 in there for all of it).
  • -debug-file flags — File debugging (again: manual, or -1 for everything).
  • -debug-gdb flags — GDB target debugging (manual / -1 for all).
  • -debug-ui flags — UI debugging (manual / -1 for all).
  • -v, -verbose level — general debug verbosity, 0 to 3, default is 1.
  • -q, -quiet — literally just -verbose 0. Same thing, shorter vibe. 🤫
  • -trap condition — set up a trap that fires on condition. More on those below 👇

Okay so these next ones all change how a configured trap behaves:

  • -trap-range m-n — only do the trap's action on the *m*th–*n*th trigger. Not every time, bestie, just that window ✨
  • -trap-snap file — write a snapshot when the trap fires 📸
  • -trap-timeout n — quit the emulator n seconds after the trap.
  • -trap-trace — start trace mode at the trap.
  • -trap-trace-n n — start trace mode at the trap, but only for n instructions.
  • -trap-no-trace — stop trace mode at the trap.

🪤 Trap conditions

These are the conditions you can hand to -trap, and each one is a whole mood:

  • immediate (or -) — trigger immediately. No notes, just vibes.
  • pc=addr — trigger at that CPU Program Counter value.
  • read=a[-b] — trigger on a read from the address range.
  • write=a[-b] — trigger on a write to the address range.
  • access=a[-b] — trigger on either a read or a write.
  • tape-motor-off — trigger when the tape motor switches off.

There's also some older options hanging around that you could honestly just do with traps now:

  • -timeout s — run for s seconds, then quit.
  • -timeout-motoroff s — quit s seconds after the tape motor switches off.
  • -snap-motoroff file — write a snapshot every single time the tape motor switches off.

🛠️ Other options

  • -config-print — print the config to standard out, leaving out (most) default options.
  • -config-print-all — same but with the defaults included, no gatekeeping 💅
  • -config-auto-save — write the configuration to $HOME/.xroar/xroar.conf when you exit.
  • -h, --help — show help and dip.
  • -V, --version — print version info and dip.

⌨️ KEYBOARD SHORTCUTS

Okay bestie, this is the hotkey lore. Memorise it, it's giving cheat sheet 👑

  • CTRL+1–4 — insert a disk into drive 1–4.
  • CTRL+SHIFT+1–4 — create a new disk in drive 1–4.
  • CTRL+5–8 — toggle write enable on the disk in drive 1–4.
  • CTRL+SHIFT+5–8 — toggle write back on the disk in drive 1–4.
  • CTRL+A — cycle through cross-colour modes (and RGB on the CoCo 3).
  • CTRL+D — open the disk control tool (GTK+ & Windows only).
  • CTRL+SHIFT+D — flush disk images.
  • CTRL+E — toggle the cartridge on/off. Reset to make it actually take effect, fr.
  • CTRL+F — toggle full screen mode.
  • or F11 — same full screen toggle, pick your fave.
  • CTRL+SHIFT+H — halt the CPU (not on the MC-10).
  • or PAUSE — also halts the CPU.
  • CTRL+SHIFT+I — toggle text mode inverse video.
  • CTRL+J — cycle through joystick emulation modes (None, Right, Left).
  • CTRL+SHIFT+J — swap the left and right joysticks.
  • CTRL+K — toggle Dragon/CoCo keyboard layout (not on the MC-10).
  • CTRL+L — load a file.
  • CTRL+SHIFT+L — load a file and attempt to autorun it.
  • CTRL+M — toggle the menubar.
  • CTRL+SHIFT+P — flush printer output.
  • CTRL+Q — quit the emulator.
  • CTRL+R — soft reset the emulated machine.
  • CTRL+SHIFT+R — hard reset the emulated machine.
  • CTRL+S — save a snapshot.
  • CTRL+SHIFT+S — write a screenshot as PNG.
  • CTRL+T — open the tape control tool (GTK+ & Windows only).
  • CTRL+V — toggle trace mode.
  • CTRL+SHIFT+V — open the TV controls window (GTK+ & Windows only).
  • CTRL+W — attach a virtual cassette file for writing.
  • CTRL+Z — enable keyboard translation mode.
  • CTRL+- — zoom out (smaller emulated display).
  • CTRL++ — zoom in (larger emulated display).
  • CTRL+< — zoom out the picture (see more border).
  • CTRL+> — zoom in the picture area (see less border).
  • F12 — run at maximum speed while held. Fastest fingers in the west.
  • SHIFT+F12 — maximum speed toggle, so you don't have to keep holding it 😌

📜 LICENCE

Bestie, this is free software 💖 You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the Licence, or (at your option) any later version.

It's distributed in the hope that it'll be useful, but WITHOUT ANY WARRANTY — not even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for the full deets, ok?

You should've gotten a copy of the GNU General Public License along with this program. If not, peep <http://www.gnu.org/licenses/>. 👀

🗂️ FILES

  • $HOME/.xroar/xroar.conf — the configuration file.
  • $HOME/.xroar/roms/ — the directory where firmware ROM images live.

Here are some iconic well-known filenames for firmware ROM images. The full manual has more, so go look if you're curious:

  • Dragon 32 BASIC — d32.rom
  • Dragon 64 32K BASIC — d64_1.rom
  • Dragon 64 64K BASIC — d64_2.rom
  • DragonDOS — dplus49b.rom, sdose6.rom, ddos10.rom
  • Tandy Colour BASIC — bas13.rom, bas12.rom, bas11.rom, bas10.rom
  • Tandy Extended BASIC — extbas11.rom, extbas10.rom
  • RS-DOS — disk11.rom, disk10.rom
  • Tandy Super ECB (CoCo 3) — coco3.rom
  • Tandy Super ECB (PAL CoCo 3) — coco3p.rom
  • Tandy Microcolour BASIC (MC-10) — mc10.rom

That's the whole page, bestie — you made it to the end 🫶 This was xroar-1.13.0.dev, dated July 2026, and you've been reading xroar(1). Slay 💅✨

📦 where this page comes from