Tutorial

Welcome to the Regenerator 2000 tutorial. This guide will walk you through a complete reverse engineering session, transforming a raw binary into a comprehensible, labeled, and commented disassembly project.

Prerequisites

Ensure you have installed Regenerator 2000 and have a C64 program (.prg) ready to analyze.

The Workflow

Reverse engineering is an iterative process. You start with a "blob" of unknown data and gradually carve out meaning, identifying code, graphics, and data tables until the picture becomes clear.

flowchart TD
    Start((Start)) --> Load[Load Binary]
    Load --> Explore[Explore & Analyze]
    Explore --> Define{Identify Region}
    Define -- "Looks like Code" --> Code[Disassemble Address 'd']
    Define -- "Looks like Data" --> Data[Convert to Byte 'b']
    Define -- "Standard Routines" --> Label[Label 'l']
    Define -- "Weird Stuff" --> Graphics[Check Graphics Views]
    Code --> Comment[Add Comments ';']
    Data --> Comment
    Label --> Comment
    Comment --> Explore
    Explore --> Debug{Debug?}
    Debug -- Yes --> VICE[Connect to VICE]
    VICE --> Explore
    Debug -- No --> Finish{Done?}
    Finish -- No --> Explore
    Finish -- Yes --> Export[Export Project]

Launch Regenerator 2000 with your target file:

regenerator2000 my_game.prg

You are now in the Disassembly View. The interface might look overwhelming at first, but it's simpler than it appears.

When loading a raw binary (not a .regen2000proj file), the Import Context dialog will appear. This allows you to specify the target System (e.g., C64, VIC20), the Origin address, and the main Entry Point of the program before analysis begins.

Grey text: Bytes that are "unknown" (not yet analyzed).
White text: Valid 6502 instructions.
Addresses (Left): The memory location of each line.

Basic Movement

Scroll: Use Up / Down or Page Up / Page Down keys.
Jump to Address: Press Ctrl+G, type an address in hex format (e.g., c000), and hit Enter.
Follow Flow: Highlighting a JMP or JSR instruction? Press Enter to jump to its target.
Go Back: Press Backspace to return to where you were before the jump.

Auto-Analysis

When you first load a file, Regenerator 2000 automatically analyzes the binary (if enabled in Settings). It will:

Trace code flow from known entry points.
Create labels for subroutines (s_XXXX), jump targets (j_XXXX), branch targets (b_XXXX), and more.
Build cross-references so you can see who calls what.
Identify system addresses (KERNAL, I/O registers, etc.) based on the selected system.

See Analysis for a full explanation of how the analyzer works and what the label prefixes mean.

If auto-analyze is disabled, you can trigger it manually with Ctrl+A.

Phase 2: Defining Code and Data

Your primary job is to tell Regenerator 2000 what is Code and what is Data.

Disassembling Address

You might see a block of bytes that looks like this:

$C000  A9 00 85 D0 ...

If you suspect this is code, place your cursor on the line and press: D.

Regenerator 2000 will disassemble the bytes starting from that location using Flow Analysis. It follows all relative branches and absolute jumps, automatically discovering all execution paths until it hits an invalid opcode or a return.

It is highly recommended to use D when you find a new subroutine entry point! It will skip data tables hidden between routines, making your disassembly process much faster and cleaner.

Converting to Data

Sometimes, the disassembler might misinterpret data as code (creating "illegal opcodes" or nonsensical instructions like BRK). Or you might find a block of graphics data.

To mark a region as raw bytes:

Select the region:
- Press Shift+V to enter Visual Mode.
- Use Arrow Keys to highlight the rows.
Convert:
- Press B to convert to Bytes (.byte $00, $01...).
- Press W to convert to Words (.word $1000...).

Using Visual Mode Effectively

Visual Mode (Shift+V) is essential for working with ranges of data. Once in Visual Mode:

Extend selection: Use Up / Down or J / K to grow the selection.
Apply block type: Press any block-type key (D, B, W, A, P, S, etc.) to convert the entire selected region.
Exit: Press Esc to leave Visual Mode without making changes.

When to Use Visual Mode

Marking large data tables as bytes or words.
Selecting a range of addresses for a Lo/Hi table (< or >).
Converting a block of known text to PETSCII (P) or Screencode (S).

Phase 3: The Detective Work (Labels & X-Refs)

As you analyze the code, you'll recognize patterns. For example, you might see a call to $D020 (Border Color).

Creating Labels

Instead of remembering $C015 is "Main Loop", give it a name!

Move cursor to $C015.
Press L.
Type main_loop and hit Enter.

Now, every instruction that jumps to $C015 will read JMP main_loop instead of JMP $C015.

Local vs. Global Labels

When creating a label, you can toggle its scope between Local and Global by pressing Tab to focus the checkbox and Space to cycle its state. Use local labels for loop counters or temporary variables to keep your disassembly tidy!

Using Cross-References (X-Refs)

Regenerator 2000 automatically tracks X-Refs. If you are at a subroutine draw_sprite, you can see exactly who calls this function.

Look for the X-Ref section in the side comments (e.g., ; x-ref: $0820, $0850).
Press Ctrl+X to open the Find References dialog and navigate between all references.
This is crucial for understanding how a function is used.

Go to Symbol

When you have many labels, finding the right one can be tedious. Press Ctrl+P to open the Go to Symbol dialog. Start typing a label name and the list will filter in real-time. Press Enter to jump directly to the selected symbol.

Phase 4: Adding Context (Comments)

Code tells you what happens, comments tell you why.

Side Comments

Good for short notes on a specific line.

Press ; (semicolon).
Type: Update score counter.
Result: INC $D020 ; Update score counter

Line Comments

Good for section headers or detailed explanations.

Press : (colon).
Type: --- INIT ROUTINE ---.
Result: The comment appears on its own line above the instruction.
```
; --- INIT ROUTINE ---
lda #$00
...
```

Multi-line and Separator Comments

Use Shift+Enter or Ctrl+J to insert a new line while in the comment dialog.
Use the following shortcuts within the dialog for quick formatting:
- Alt+-: Insert a line of dashes (---).
- ++alt+equals++: Insert a line of equals signs (===).
- Alt+\: Insert a mixed separator (-=-).

Using Bookmarks

As your project grows, you'll want to quickly jump between key locations. Use bookmarks:

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

Bookmarks are saved with the project, so they persist across sessions.

Phase 5: Searching

Regenerator 2000 offers several ways to search through the binary:

Vim-style Search

Press / and start typing. The disassembly will search for matches across labels, mnemonics, operands, and comments. Press N to find the next match and Shift+N for the previous match.

Search Dialog

Press Ctrl+F to open the full Search dialog, which supports:

Text search: Search for labels, comments, and mnemonics.
Hex pattern search: Search for specific byte sequences (e.g., A9 00 8D to find LDA #$00; STA ...). Use ?? as a wildcard for any byte.
PETSCII / Screencode search: Find text strings in the data.

Use F3 / Shift+F3 to jump to the next / previous match after closing the dialog.

Phase 6: Visuals (Graphics & Tables)

Some data isn't code or numbers—it's art.

Hex Dump: Press Alt+2 to view raw hex. Use M to cycle through text modes (PETSCII shifted/unshifted, Screencode shifted/unshifted). The byte values are colored by value (0x00 is dimmed, 0xFF is bright, text characters are distinct) to help spot data patterns.
Sprites: Press Alt+3 to open the Sprite View. If you see a Space Invader, you've found the sprite data! Select that memory range and mark it as bytes.
Charset: Press Alt+4 to check for custom charsets.
Bitmap: Press Alt+5 for the Bitmap View to see if a memory block forms a valid image.

Knowing where graphics are helps you avoid trying to disassemble them as code.

Syncing Views

When "Sync" is enabled (in Settings), moving the cursor in the Disassembly View automatically updates the right pane to show the corresponding memory location. This is very useful for switching between disassembly and hex dump to cross-check your analysis.

Phase 7: Organizing with Scopes, Splitters & Collapsed Blocks

As your disassembly grows, keeping things tidy becomes important.

Scopes

Scopes provide namespace-like grouping for your code (similar to .proc/.endproc in ca65 or .namespace in other assemblers). They help keep local labels isolated and organize related routines together.

Press R to create a new scope starting at the current address.
Use the Del key to remove a scope boundary.

Splitters

Adjacent blocks of the same type are automatically merged. If you want to keep two blocks separate (e.g., two different Lo/Hi tables), insert a splitter by pressing | between them. Line comments (:) also act as splitters.

Collapsing Blocks

Press Ctrl+K on a block to collapse it into a single summary line. This is great for hiding large data tables or fully analyzed subroutines so you can focus on the area you're currently working on.

Collapsed blocks are a visual-only feature — they don't affect the exported ASM output.

Phase 8: Saving & Exporting

Saving Your Work

Reverse engineering takes time. Save your progress often.

Press Ctrl+S.
This creates a .regen2000proj file. It saves your labels, comments, formatting, bookmarks, and history.

Exporting to Assembler

Once you are done (or want to test your changes), export the project to a source file (.asm) compatible with modern assemblers.

Press Ctrl+E to export.
Choose the target assembler in Document Settings (Alt+D) — supported options are 64tass, ACME, KickAssembler, and ca65.
In Document Settings, you can also adjust the Fill run threshold (default 8). This setting determines how many identical consecutive bytes are grouped into a .fill, !fill, or .res directive, keeping your data sections clean.

Batch Processing (Headless Mode)

For scripting and automation, you can run Regenerator 2000 without the TUI:

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

# Export to HTML:
regenerator2000 --headless --export_html output.html my_game.regen2000proj

# Override the assembler format (64tass, acme, ca65, kick)
regenerator2000 --headless --assembler acme --export_asm output.asm my_game.regen2000proj

# Import VICE labels and export
regenerator2000 --headless --import_lbl labels.lbl --export_asm output.asm my_game.prg

Phase 9: Debugging with VICE

The most powerful way to test your analysis is by connecting Regenerator 2000 directly to a running VICE instance for live debugging.

Start VICE: Start the emulator with the remote monitor enabled:

x64 -binarymonitor my_game.prg

Connect: In Regenerator 2000, go to Debugger → Connect to VICE... (localhost:6502).

!!! tip "Auto-connect with --vice"

   You can skip this step by launching Regenerator 2000 with `--vice localhost:6502`. It will connect
   automatically at startup:

   ```bash
   regenerator2000 --vice localhost:6502 my_game.prg
   ```

View: Open the Debugger panel with Alt+6 (or Ctrl+6) to see the current PC, registers, and breakpoints.

Warning

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

Debugging Features

Breakpoints: Use F2 (or Shift+F2) to toggle breakpoints or F6 for watchpoints directly at the cursor.
Stepping: Use F7 (Step Instruction), F8 (Step Over), or Shift+F8 (Step Out).
Control: Use F9 to resume or F4 to run until the cursor's location.

Debugging Workflow

A typical debugging workflow looks like:

Set a breakpoint at a suspicious routine (F2).
Run the program in VICE (F9 or press play in VICE).
When execution hits the breakpoint, examine the registers and stack in the Debugger panel.
Step through the code (F7) to understand the logic.
Based on what you learn, go back to the Disassembly View and refine your labels and comments.

Legacy Workflow: Export VICE Labels

If you'd rather use the VICE monitor alone, you can still export your project's labels using File → Export VICE labels.... However, for the best experience, we recommend using the integrated VICE Debugger.

Phase 10: AI-Assisted Analysis (MCP)

Regenerator 2000 includes an MCP (Model Context Protocol) server that lets AI assistants help you analyze the binary programmatically.

Quick Start

Start Regenerator 2000 with the MCP server: regenerator2000 --mcp-server my_game.prg
Connect your MCP-compatible AI client to http://localhost:3000.
The AI can now read the disassembly, set labels, add comments, and manipulate blocks.

This is especially useful for:

Batch-labeling known routines and I/O registers.
Getting explanations of unfamiliar code patterns.
Automating repetitive tasks across large binaries.

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

Summary of Key Keys

Key	Action
`D`	Disassemble Address
`B`	Byte
`W`	Word
`A`	Address
`R`	Create Scope
`Del`	Exclude Address / Remove Scope
`L`	Label
`;`	Side Comment
`:`	Line Comment
`I` / `Shift`+`I`	Cycle Immediate Format (hex/dec/bin)
`[`	Pack Lo/Hi Address
`]`	Pack Hi/Lo Address
`Shift`+`V`	Visual Mode (selection)
`Enter`	Follow Jump / Jump to Operand
`Backspace`	Go Back
`Ctrl`+`G`	Jump to Address
`Ctrl`+`P`	Go to Symbol
`Ctrl`+`X`	Find Cross-References
`/`	Search
`Ctrl`+`B`	Toggle Bookmark
`Ctrl`+`K`	Collapse / Uncollapse Block
`\|`	Toggle Splitter
`Ctrl`+`S`	Save Project
`Ctrl`+`E`	Export to ASM
`F2`	Toggle Breakpoint
`F7` / `F8`	Step Into / Step Over
`F9`	Run / Continue

Happy Hacking!