Skip to content

Frequently Asked Questions (FAQ)

Click any question below to expand the answer, or jump straight to Troubleshooting.

General

How do I start analyzing a file?

Select File → Open (Ctrl+O) or pass a file directly on the command line (regenerator2000 my_game.prg). See Installation & Usage for all CLI options.

What file formats and target systems are supported?

Regenerator 2000 opens .prg, .crt, .d64, .d71, .d81, .t64, .vsf (VICE snapshots), .dis65 (SourceGen), raw .bin/.raw, and .regen2000proj files.

Built-in definitions cover Commodore 64, 128, VIC-20, Plus/4, PET (BASIC 2.0 & 4.0), and 1541, plus experimental configs for NES, Apple II, Atari 8-bit, BBC Micro, and Oric. See Target Systems and Installation & Usage.

How do I save or reopen recent work?

Press Ctrl+S to save everything (binary, blocks, labels, comments, bookmarks, and undo stack) to a .regen2000proj file, or Alt+S / Ctrl+Shift+S for Save As. Press Alt+O (or Ctrl+Shift+O) to reopen recent projects.

Does it run on Windows, macOS, and Linux?

Yes—grab pre-built binaries from GitHub Releases or install with cargo install regenerator2000.


Troubleshooting

Some keyboard shortcuts don't work in my terminal or tmux

Terminals intercept certain Ctrl chords differently (for example, Ctrl+2 inside tmux). Every conflicting shortcut provides an Alt alternative—such as Alt+2 for Hexdump or Alt+D for Document Settings.

For full key reporting and true-color rendering, use one of the Recommended Terminals.

The display looks garbled or colors look wrong

Verify your terminal supports 256 colors or 24-bit true color. Inside tmux, add set -g default-terminal "tmux-256color" to ~/.tmux.conf.

Why is my BASIC program disassembling as illegal opcodes?

Commodore BASIC stores tokenized byte sequences (like $99 for PRINT or $8F for REM) linked by 2-byte pointers—so forcing Code (C) decodes tokens as nonsense opcodes.

Fix: Select the BASIC range and press P (PETSCII) or W (Word), or let an AI agent run the r2000-analyze-basic skill.

Why did the VICE binary monitor fail to connect?

Regenerator 2000 speaks the VICE Binary Monitor Protocol (default port 6502), not the plain-text monitor (port 6510).

  • Start VICE with x64 -binarymonitor my_program.prg (or enable Settings → Monitor → Enable binary monitor).
  • Match --vice <HOST:PORT> if you changed VICE's -binarymonitoraddress.
  • Load the exact same .prg in both VICE and Regenerator 2000 so PC addresses and breakpoints align.
Why does roundtrip export verification (--verify) fail?

--verify exports to each assembler, assembles the output, and checks byte-for-byte parity against the original binary. Common mismatches come from:

  • Symbol scoping: A local label resolving under a different global scope in a target assembler.
  • Branch bounds: A relative branch exceeding -128/+127 bytes and expanding to a long jump.
  • 2-byte BRK padding: Disable BRK single byte and enable Patch BRK in Document Settings if your program expects 2-byte BRK alignment.
Why does the Binary Unpacker fail or time out?

The unpacker emulates a sandboxed 6502 CPU and aborts after 50,000,000 instructions (max_instructions) so infinite wait loops cannot hang the UI.

If a custom stub waits on unemulated hardware (like raster $D012) or lacks a SYS header, open File → Unpack Binary... and raise Max Instructions or specify Entry Point, Depacker Address, or Return Address explicitly. See Binary Unpacker.

How do I report a bug or ask a question?

Open an issue on GitHub Issues or drop into #regenerator2000 (under Misc Projects) on Discord.


Disassembly & Block Types

How do I convert a range of bytes into code, data, or text?

Put the cursor on a single line—or press Shift+V first to select a range in Visual Mode—then hit the target key (D flow disassemble, C code, B byte, W word, A address, P PETSCII, S screencode, Shift+E external file, or ? reset). See Block Types — Quick Reference.

What do the auto-generated label prefixes mean?

Prefixes encode how the address was referenced (s_ subroutine, j_ jump, b_ branch, r_ return, e_ external jump, a_ absolute, f_ indexed field, p_ pointer, and zpa_/zpf_/zpp_ zero-page variants). Press L to rename any label—your names are never overwritten. See Analysis — Label Prefixes.

How do I navigate jumps, symbols, and cross-references?

Press Enter to follow a jump, call, or address table entry (Backspace jumps back), Ctrl+G to jump by hex address, Ctrl+P for Go to Symbol, Ctrl+X for Find Cross References, and / or Ctrl+F to search. See Keyboard Shortcuts.

What are the arrows in the left margin, and how does Undo/Redo work?

Left-margin arrows visualize jump and branch targets (adjust width via Arrow Columns in Document Settings). Press U to undo and Ctrl+R to redo—every edit is saved in .regen2000proj.

What is "Patch BRK"?

6502 hardware treats BRK as 2 bytes, though most C64 code treats it as 1 byte (BRK single byte enabled by default). Disable BRK single byte and enable Patch BRK when your binary relies on 2-byte BRK signatures so assemblers emit an explicit padding .byte. See Settings — BRK Handling.


Labels, Comments & Scopes

What is the difference between global, local, and scope labels?
  • Global labels: Visible anywhere in the program.
  • Local labels (such as _loop or .skip): Belong to the nearest preceding global label (toggle inside the L dialog with Tab then Space).
  • Scope labels: Belong to an explicit scope range and are referenced externally as scope_name.label_name (or :: in ca65).
How do comments and bookmarks work?
  • Side comment (;): Inline note after the instruction.
  • Line comment (:): Multi-line header above the address (Ctrl+J / Shift+Enter for newlines; Alt+-, Alt+=, Alt+\ for dividers). Also splits Address/Word tables.
  • Bookmarks: Press Ctrl+B to toggle and Ctrl+Shift+B (or Alt+B) to jump between saved bookmarks.
How do scopes work, and which assemblers support them?

Select a range in Visual Mode (Shift+V) and press R to isolate local labels inside a routine; press Del on a scope boundary to remove it. Supported by 64tass (.block/.bend), KickAssembler ({/}), and ca65 (.proc/.endproc); omitted on ACME exports. See Block Types — Scopes.


Views & Exporting

How do I switch companion views and keep them synced?

Press Tab to move focus between the Disassembly pane and the right pane, and Alt+1–Alt+6 (or Ctrl+1–Ctrl+6) to toggle Blocks, Hexdump, Sprites, Charset, Bitmap, or Debugger. Toggle cursor sync per view in Settings (for Hexdump details, see Views — Hexdump).

Which assemblers can I export to, and how do I automate exports?

Export directly to 64tass, ACME, KickAssembler, and ca65 via Ctrl+E (or Alt+E for Export As). For scripts and CI, run headless mode:

regenerator2000 --headless --export_asm output.asm my_file.regen2000proj
regenerator2000 --headless --assembler acme --export_asm output.asm my_file.regen2000proj

You can also export VICE .lbl files from File → Export VICE Labels..., or isolate large binary assets into separate .bin includes with External File (Shift+E). See Target Assemblers.


VICE Debugger & MCP

How do I connect and use the VICE live debugger?

Start VICE with x64 -binarymonitor my_program.prg, launch Regenerator 2000 with --vice localhost:6502 my_program.prg (or connect via Debugger → Connect to VICE...), and toggle the panel with Alt+6. Supports breakpoints (F2), watchpoints (F6), run-to-cursor (F4), stepping (F7 / F8 / Shift+F8), and live memory dumps. See Live Debugger.

How do I connect an AI assistant via MCP?

Start Regenerator 2000 with --mcp-server (HTTP/SSE on port 3000, live alongside the TUI) or --mcp-server-stdio (headless subprocess), then register http://127.0.0.1:3000/mcp in Claude Code or Antigravity. See MCP Integration for all 29 tools and analysis skills.