Skip to content

Frequently Asked Questions (FAQ)

General

How do I start analyzing a new file?

You can open a file via File → Open (Ctrl+O) or by passing the filename as an argument when starting the application from the command line:

regenerator2000 my_game.prg

What file formats are supported?

Regenerator 2000 supports the following formats:

Format Description
.prg Standard Commodore program (first 2 bytes = load address)
.crt C64 cartridge image with bank selection
.d64 35/40/42-track disk image (pick a PRG from within)
.d71 70/80-track double-sided disk image
.d81 80-track disk image
.t64 Tape image container (pick a PRG from within)
.vsf VICE snapshot — extracts RAM and uses PC as start address
.bin / .raw Raw binary — requires manually setting the origin
.dis65 6502bench SourceGen project file
.regen2000proj Regenerator 2000 project file (includes all labels and comments)

What systems are supported?

Regenerator 2000 includes system-specific labels, comments, and memory maps for:

  • Commodore 64
  • Commodore 128
  • Commodore VIC-20
  • Commodore Plus/4
  • Commodore PET (BASIC 2.0 and 4.0)
  • Commodore 1541 disk drive

You can set the system in Document Settings (Alt+D or Ctrl+Shift+D).

How do I save my work?

Press Ctrl+S to save as a .regen2000proj file. This preserves all your labels, comments, block types and bookmarks. Use Alt+S (or Ctrl+Shift+S) to Save As with a different filename.

Does it run on Windows, macOS, and Linux?

Yes. Pre-compiled binaries are available for all three platforms on the GitHub Releases page. You can also install from Crates.io with cargo install regenerator2000.

How do I reopen a recent project?

Use File → Open Recent (Alt+O or Ctrl+Shift+O) to quickly access your most recently opened files and projects.

Disassembly

How do I change the type of a block?

Place the cursor on the desired line (or select a range with Shift+V for Visual Mode) and press the corresponding key:

Key Block Type
C Code
B Byte
W Word
A Address
P PETSCII Text
S Screencode Text
< Lo/Hi Address Table
> Hi/Lo Address Table
, Lo/Hi Word Table
. Hi/Lo Word Table
E External File
? Undefined (reset)

See Block Types for detailed explanations and assembler-specific examples.

How do I select multiple lines?

Press Shift+V to enter Visual Mode (similar to Vim). Use Up / Down (or J / K) to extend the selection. Then apply a block type conversion or other operation to the entire selection. Press Esc to exit Visual Mode.

Can I rename labels?

Yes. Place the cursor on a label and press L. Type the new name and press Enter. The label will be renamed globally — every instruction that references that address will use the new name.

What do the label prefixes mean?

Auto-generated labels use a short prefix that indicates how the address is referenced in the code. For example, s_C000 means a subroutine entry point at $C000, while zpa_A0 means a zero-page absolute address at $A0.

See Analysis — Label Prefixes for the complete prefix reference and how the analyzer decides which prefix to assign.

What is the difference between a local and a global label?

  • Global Labels: Top-level symbols accessible from anywhere in the program.
  • Local Labels (e.g., _loop, .skip depending on the assembler): Belong to the nearest Global Label above them and are only visible between that global label and the next one. They are useful for loop targets or temporary variables to avoid name collisions between different subroutines.
  • Scope Labels: When a global label is used inside a custom scope block (such as an explicit procedure or block), it becomes a scope label and must be accessed via scope_name.label_name from the outside, rather than being a truly global one.

In the TUI, you can toggle between local and global scope when creating a label or editing an existing one. Press L to open the label dialog, and then use Tab to focus the checkbox and Space to toggle it.

How do I navigate the disassembly?

Action Shortcut
Jump to address Ctrl+G or Alt+G
Jump to line number Ctrl+Shift+G
Follow a jump/branch Enter
Go back in history Backspace
Go to symbol by name Ctrl+P
Find cross-references Ctrl+X
Search (Vim-style) /
Search dialog Ctrl+F
Next / previous match N / Shift+N

What are arrows in the disassembly view?

The columns on the left side of the disassembly draw visual arrows showing the flow of jump (JMP) and branch (BNE, BEQ, BCC, etc.) instructions. This helps you quickly see loops, conditional paths, and where control flow goes. You can configure the number of arrow columns in Document Settings (the "Arrow Columns" option).

How does undo/redo work?

Press U to undo the last action and Ctrl+R to redo. Every block type change, label rename, comment edit, and similar action is recorded on the undo stack. The history is saved with the project file.

What is "Patch BRK"?

The 6502 BRK instruction is technically 2 bytes, but most C64 programs treat it as 1 byte. By default, BRK single byte is enabled. If your program uses the 2-byte form, disable it in Document Settings and optionally enable Patch BRK to ensure the padding byte is correctly exported. See Settings for details.

Labels & Comments

How do I add a comment?

  • Side comment (inline, after the instruction): Press ; and type your comment.
  • Line comment (on its own line, above the instruction): Press : and type your comment.

Line comments also act as splitters — they prevent adjacent blocks of the same type from being auto-merged.

Can I write multi-line comments?

Yes. In the line comment dialog, press Ctrl+J (or Shift+Enter) to insert a new line. You can also use shortcut keys for quick separators:

  • Alt+-: Insert a dash separator (---)
  • Alt+=: Insert an equals separator (===)
  • Alt+\: Insert a mixed separator (-=-)

What are bookmarks and how do I use them?

Bookmarks let you mark addresses you want to return to quickly:

  • Ctrl+B: Toggle a bookmark at the current address.
  • Ctrl+Shift+B (or Alt+B): Open the Bookmarks dialog to navigate between bookmarks.

Scopes

What are scopes?

Scopes (also called namespaces or procedures) allow you to group code into logical blocks, typically representing routines or functions. Labels defined inside a scope are local to that scope, preventing naming conflicts. For example, two different routines can both have a local label called loop without collision.

How do I create a scope?

  1. Select the range of code using Shift+V (Visual Mode).
  2. Press R to create a scope over the selection.

A default label is created at the scope's start address if one doesn't already exist. You can rename it with L.

How do I remove a scope?

Place the cursor on the first or last line of the scope and press Del.

The Del key also serves a second purpose: it excludes external addresses from analysis when the cursor is on an external label.

Which assemblers support scopes?

Assembler Scope Syntax
64tass .block / .bend
KickAssembler { / }
ca65 .proc / .endproc
ACME Not supported (ignored)

See Block Types — Scopes for detailed examples in each assembler's syntax.

Views

How do I switch between views?

Use Tab to switch focus between the Disassembly View (left) and the right pane. Toggle which view appears in the right pane using:

Shortcut View
Alt+1 or Ctrl+1 Blocks
Alt+2 or Ctrl+2 Hex Dump
Alt+3 or Ctrl+3 Sprites
Alt+4 or Ctrl+4 Charset
Alt+5 or Ctrl+5 Bitmap
Alt+6 or Ctrl+6 Debugger

How do I sync the right pane with the disassembly?

By default, the Hex Dump and Blocks views sync with the Disassembly cursor. You can enable or disable syncing for each view independently in File → Settings (Alt+P or Ctrl+,).

Exporting

Which assemblers are supported for export?

Regenerator 2000 supports exporting to:

  1. 64tass
  2. ACME
  3. KickAssembler
  4. ca65

See Assemblers for detailed command lines and configuration.

How do I export my project?

  • Ctrl+E: Export to ASM (uses the last saved filename, or prompts).
  • Alt+E (or Ctrl+Shift+E): Export As (always prompts for a filename).

You can also export from the command line:

# Export to ASM:
regenerator2000 --headless --export_asm output.asm my_file.regen2000proj

# Override assembler format:
regenerator2000 --headless --assembler acme --export_asm output.asm my_file.regen2000proj

Can I export VICE labels?

Yes. Use File → Export → Export VICE Labels... to generate a .lbl file that can be loaded in VICE's monitor for debugging.

What is the "External File" block type for?

When you mark a memory region as "External File" (E), the exporter writes those bytes to a separate .bin file and emits a .binary "filename.bin" (or equivalent) directive in the ASM output. This keeps large binary blobs (music, graphics, charset data) out of the main source file.

VICE Debugger

How do I connect to VICE?

  1. Start VICE with the binary monitor enabled: x64 -binarymonitor my_program.prg
  2. Load the same binary in Regenerator 2000: regenerator2000 my_program.prg
  3. In Regenerator 2000, open Debugger → Connect to VICE... and press Enter (default: localhost:6502).
  4. Open the Debugger panel with Alt+6.

Warning

Both VICE and Regenerator 2000 must be running the same binary. If the binaries differ, breakpoints and the PC display will be misaligned.

What debugging operations are supported?

Action Shortcut
Toggle Breakpoint F2
Toggle Breakpoint... Shift+F2
Run to Cursor F4
Watchpoint F6
Step Instruction F7
Step Over F8
Step Out Shift+F8
Run / Continue F9

For comprehensive details, see Debugger (VICE Integration).

MCP Integration

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with tools programmatically. Regenerator 2000 implements an MCP server, enabling AI agents to read disassembly, set labels, add comments, and manipulate blocks.

How do I start the MCP server?

  • HTTP mode (port 3000): regenerator2000 --mcp-server my_project.regen2000proj
  • stdio mode (headless): regenerator2000 --mcp-server-stdio my_project.regen2000proj

See MCP Integration for the full list of available tools and resources.

Troubleshooting

Some keyboard shortcuts don't work in my terminal

Different terminals handle key combinations differently. If a Ctrl shortcut doesn't work, try the Alt alternative (most shortcuts have both). For the best experience, we recommend using a modern terminal:

  • macOS: iTerm2, Ghostty, Alacritty, kitty, WezTerm
  • Windows: Windows Terminal, Alacritty, WezTerm
  • Linux: Ghostty, Alacritty, kitty, WezTerm, GNOME Terminal

The display looks garbled or colors are wrong

Ensure your terminal supports 256 colors or true color (24-bit). Most modern terminals do. If running inside tmux or screen, add set -g default-terminal "tmux-256color" to your tmux config.

How do I report a bug or request a feature?

Open an issue on GitHub: https://github.com/ricardoquesada/regenerator2000/issues

You can also join the Discord server (look for the #regenerator2000 channel under "Misc Projects").