3. Getting Started
Table of Contents:
- Setting Up Your Development Environment
- Text Editor
- Assembler and Linker
- Graphics Tools
- Music Composition Tools
- Putting It All Together
- Next Steps
Let's get started actually programming for the NES! In this chapter, we're going to set up a development environment, installing all of the tools that you will need to work through this book, and then we will build and run the most basic game possible just to make sure everything is working.
Setting Up Your Development Environment
Here are all of the tools that we will be installing. Some of these will be used right away (and all the time), while others are more specialized and won't come into play until much later. For each category, I'm including the specific software I will be using in this book; there are many other choices, so feel free to experiment with other tools once you get comfortable with my recommendations.
- A text editor (your choice)
- An assembler/linker (ca65 and ld65)
- An emulator (Mesen2)
- A graphics tool that can read/save NES formatted images (NEXXT)
- A music composition tool (FamiStudio)
First, you will need a text editor. I assume that you have previous programming experience and that, as a result, you already have a favorite text editor. If not, here are a few programs that you may want to try.
- Sublime Text. Cross-platform, popular with web developers, easy to get started with and powerful tools once you get familiar with the basics.
- Atom. Basically GitHub's answer to Sublime Text. Cross-platform, highly configurable.
- Visual Studio Code. Microsoft's robust text editor platform. Tailored for web development but extensible for any kind of programming. Also cross-platform, not limited to Windows.
- Vim, emacs, nano, etc. Command-line text editors of yore. (I personally use Vim, but your mileage may vary.)
Assembler and Linker
An assembler compiles your assembly code (what we will be writing in this book) into machine code, the raw stream of bytes that the processor reads. A linker takes a group of files that have been run through the assembler and turns them into a single program file. Since each processor has its own machine code, assemblers usually target only one type of processor. There are many assemblers and linkers to choose from for the 6502, but for this book we will be using ca65 and ld65. They are open-source and cross-platform, and have some very useful features for developing larger programs. ca65 and ld65 are part of the larger "cc65" suite of programs, which include a C compiler and more.
To install ca65 and ld65 on a Mac, first install Homebrew, a
Mac package manager. Copy and paste the command from the homepage into a terminal and press
enter; follow the instructions and Homebrew will be ready to use. Once you have Homebrew,
brew install cc65 and press enter.
On Windows, you'll need to download ca65 and ld65 to a specific directory on your computer.
Download the latest "Windows Snapshot" from the main cc65 project page.
Unzip the contents to
C:\cc65. You'll also need to update
your system path to make ca65 and ld65 available from any directory. The process for doing
this varies depending on which version of Windows you are using. On most newer versions of
Windows, you can right-click "My Computer", select "Properties", then "Advanced System Settings"
and finally "Environment Variables". You'll want to find the entry for
C:\cc65\bin to the end of it.
You will need to build cc65 from source. Thankfully, this is a fairly simple process. First,
make sure you have git and a basic build environment - on Ubuntu, for example,
sudo apt-get install git build-essential should do it. Then, navigate to the directory where you want
to install cc65, clone the cc65 repository, and build it:
git clone https://github.com/cc65/cc65.git cd cc65 make
Finally, make the cc65 programs available from any directory with
sudo make avail. This will
add symlinks from your cc65 folder to
An emulator is a program that runs programs intended for a different computer system.
We will use an NES emulator to run the programs that we create on the same computer used to
develop them, instead of requiring a hardware NES. There are a number of NES emulators available
(and, once you have a solid grasp of NES development, it's fun to try to make your own!), but
for this book we will be using Mesen2.
Mesen2. It is cross-platform and features powerful debugging tools, which will be useful as we write programs.
Windows / Linux / Intel-based Mac
For these systems, download the latest development release, then unzip. You will need to install .NET Runtime v6 on all systems. Non-Windows systems will also need to install SDL2 through your OS' package manager or Homebrew on Mac.
ARM-based Mac (M1, M2, etc.)
On these systems, you will need to build Mesen2 from source. First, install SDL2 via Homebrew
brew install sdl2), then install the .NET 6 SDK.
Download Mesen2's source code and run
git clone https://github.com/SourMesen/Mesen2.git cd Mesen2 make
When the build process is complete, you will have
Mesen.app in the
directory inside of the
Mesen2 directory where you ran
Mesen.app into your Applications
The NES stores graphics in a very different format from common image types like JPEG or PNG. We
will need a program that can work with NES images. There are plugins for large graphics
packages like Photoshop or GIMP, but a smaller, purpose-built tool is often a better choice.
For this book, we will be using NEXXT,
NEXXT. a derivative of NES Screen Tool. NEXXT is a Windows-only program, but runs well on other platforms under WINE.
Download NEXXT from itch.io. Unzip, and run NEXXT.exe.
Since NEXXT is a 32-bit, Windows-only program, Linux users will have to run it via WINE.
Install WINE via your distribution's package manager, then run NEXXT.exe with it (
Newer Mac versions (starting with Catalina) are 64-bit only, and 32-bit software will not run
even in a standard WINE install. Thankfully, 32-bit Windows programs can be run using the
"Crossover" version of WINE, which is able to translate 32-bit code into 64-bit code
on the fly. Install Crossover via Homebrew (
brew install --cask gcenx/wine/wine-crossover --no-quarantine).
Download NEXXT as above and unzip, then run
wine64 ./NEXXT.exe in the directory where
you unzipped it.
Music Composition Tools
As with graphics, NES audio is a set of instructions to an audio processor rather than something
like an MP3. The most popular program for creating NES audio is FamiTracker,
which is powerful but complex and Windows-only. For this book, we will be using
FamiStudio, which is cross-platform, has a friendlier
interface, and outputs directly into an easy-to-integrate format.
Windows / Mac / Linux
Download the latest release from the FamiStudio website.
Putting It All Together
Now that you have all of the tools installed, it's time to make sure that they work. We are going to create the "Hello World" of NES games: filling the entire screen with one color.
Open your text editor and create a new file,
helloworld.asm. Copy and paste the following
code into the file:
1 .segment "HEADER" 2 .byte $4e, $45, $53, $1a, $02, $01, $00, $00 3 4 .segment "CODE" 5 .proc irq_handler 6 RTI 7 .endproc 8 9 .proc nmi_handler 10 RTI 11 .endproc 12 13 .proc reset_handler 14 SEI 15 CLD 16 LDX #$00 17 STX $2000 18 STX $2001 19 vblankwait: 20 BIT $2002 21 BPL vblankwait 22 vblankwait2: 23 BIT $2002 24 BPL vblankwait2 25 JMP main 26 .endproc 27 28 .proc main 29 LDX $2002 30 LDX #$3f 31 STX $2006 32 LDX #$00 33 STX $2006 34 LDA #$29 35 STA $2007 36 LDA #%00011110 37 STA $2001 38 forever: 39 JMP forever 40 .endproc 41 42 .segment "VECTORS" 43 .addr nmi_handler, reset_handler, irq_handler 44 45 .segment "CHARS" 46 .res 8192 47 .segment "STARTUP"
Next, we need to use our assembler. In the directory where you saved helloworld.asm,
ca65 helloworld.asm. The result should be a new file, helloworld.o.
This is an object file - machine code. But it is not in a format that is
ready to plug into an emulator just yet. To do that, we need to run the linker.
In the same directory, run
ld65 helloworld.o -t nes -o helloworld.nes.
This should result in a new file, helloworld.nes - a "ROM" file for the emulator.
Open Mesen2 and choose "Open" from the "File" menu. Select the helloworld.nes file you just created and click Open. The result should be a green screen. The green screen here is an actual, running NES emulator in your browser! I am using the amazing jsnes by Ben Firshman. Whenever we compile a .nes file, I will include a running demo like this one. (It's hard to tell in this case, but the emulator is actually running at 60fps.)
If you were able to see the green screen in Mesen2, congratulations! Your development environment is ready to use. In the next chapter, we will discuss what the code you copied and pasted is actually doing, and learn a bit about how the NES hardware works.