Getting Started

You’ll need two tools: an emulator to run C64 programs, and an assembler to compile your code. Both are free and work on Windows, macOS, and Linux.

The Emulator: VICE

VICE (Versatile Commodore Emulator) is the standard C64 emulator. It’s accurate, well-maintained, and has every feature you’ll need.

brew install vice

sudo apt install vice

sudo dnf install vice

The executable you’ll use is x64sc — that’s the accurate C64 emulator. (There’s also x64 which is faster but less accurate. Stick with x64sc for development.)

First Run

Launch VICE to make sure it works:

x64sc

You should see the familiar C64 blue screen with READY. and a blinking cursor. Press Alt+Q (or Cmd+Q on macOS) to quit.

The Assembler: ACME

ACME is a cross-assembler that runs on your modern machine and outputs C64-compatible binaries. It’s fast, has good error messages, and supports all the features we’ll use.

brew install acme

sudo apt install acme                    # Debian/Ubuntu
sudo dnf install acme-crossassembler     # Fedora

Verify Installation

acme --version

You should see version information. Any recent version will work.

The Workflow

Every change follows the same cycle:

1. Edit your .asm file in any text editor
2. Compile with ACME to produce a .prg file
3. Run the .prg in VICE

Here’s what that looks like:

# Compile
acme -f cbm -o game.prg game.asm

# Run
x64sc game.prg

The -f cbm flag tells ACME to output in Commodore format with the correct load address header.

One-Liner

For quick iteration, combine both commands:

acme -f cbm -o game.prg game.asm && x64sc game.prg

This compiles and runs — but only if compilation succeeds.

Editor Setup (Optional)

Any text editor works. If you want syntax highlighting for 6502 assembly:

• VS Code: Install the “6502 Assembly” extension
• Sublime Text: Install “6502 Assembly” via Package Control
• Vim: The built-in asm syntax works reasonably well

Syntax highlighting isn’t essential, but it makes reading code easier.

Downloading vs Typing

Each lesson provides a download link for the complete .prg file. You can run these immediately to see what you’re building.

But we recommend typing the code yourself. Assembly has details that matter — addressing modes, instruction order, the relationship between code and data. Typing forces you to notice these details in a way that copy-paste doesn’t.

Start by downloading and running. Then type the code yourself and compare.

Alternative: Docker Toolchain

If you prefer a containerised environment with everything pre-installed, we provide a Docker-based toolchain. This gives you a consistent build environment regardless of your host OS.

# Clone the toolchain
git clone https://github.com/code198x/commodore-64-dev.git
cd commodore-64-dev

# Build and start the container
docker-compose up -d

# Enter the development environment
docker-compose exec c64-dev bash

# Assemble
acme -f cbm -o game.prg game.asm

# Run (requires X11 forwarding on Linux, or use headless mode)
x64sc game.prg

When to use Docker:

• You want a reproducible environment across machines
• You’re on Linux and want easy X11 forwarding to VICE
• You prefer not to install tools on your host system

When to use native tools:

• You’re on macOS or Windows (easier VICE integration)
• You want simpler setup
• You’re just getting started

Both approaches produce identical .prg files — choose whichever fits your workflow.

Troubleshooting

VICE shows a blank screen or error

Make sure you’re using x64sc, not x64. If the screen stays black, the program might have crashed — check your code for errors.

ACME reports “File not found”

Check you’re in the right directory. ACME looks for files relative to where you run it.

ACME reports syntax errors

The error message includes a line number. Assembly is unforgiving — check for typos, missing colons after labels, and correct instruction spelling.

Program runs but behaves wrong

Welcome to debugging! The lessons include explanations of what each part does. Compare your code character-by-character with the lesson code.