Building NES homebrew with makechr.exe

As part of nesdev’s 2016 homebrew competition, I’ve been developing a game called Filthy Kitchen, a side-scrolling action platformer wherein the player gets rid of flies using a boomerang-like swatter. When doing a project like this, having a powerful toolchain is essential, especially for creating graphics. Luckily, makechr version 1.3 has a new GUI that makes it easy to turn pixel art into binary data that the NES understands. Here’s a guide on how to get started.

If you aren’t familiar with how NES graphics work, it might be helpful to read this earlier series of posts.

To begin, download makechr.exe from here. This guide will be using Windows. Although makechr is cross-platform, the GUI is currently a bit difficult to setup and run on other OS’s. If you’re brave enough, you’ll find instructions on using OSX over here.

level chars

Here’s some pixel art for the background of Filthy Kitchen, as well as a sprite-sheet containing the main character and other objects. Save each of these images and put them in some convenient location.

Open up makechr.exe, and you’ll see the following sight:


From the top menu, pick File->Open, and select level.png which was just downloaded. Once loaded, the space in the upper-left will display the original image, while the rest of the app presents some views showing how makechr sees the converted image. The “nametable”, “attribute”, “palette”, and “CHR” are all the components that make up the NES graphics, while “reuse” in the upper-right shows a useful representation of where tiles have been repeated throughout the image. Mousing over any of the views will show the corresponding data in the other views.


An especially nice feature of makechr is that the user doesn’t need to specify the image’s palette, or which blocks (16×16 pixel areas) use which colors. Instead, makechr figures out what works best on its own. If it is not possible to derive a working palette, erroneous locations will be displayed on the input image.

As an optional step, we can quickly create a ROM to see how the image will appear on the NES. From the top menu, pick Tools->Compile to ROM, and type the name “test”. This makes “test.nes”, which when run in an emulator will display the original image and nothing more. Since different emulators render slightly differently, it can be helpful to quickly verify how the art will appear.

Building from source

Let’s dig deeper though, and build a ROM from source code, using binary data created by makechr. But first, we need source code to build off of. I’ve made a minimal NES project repository; we will start with this. Retrieve it either using git, or by downloading the zip file and extracting the contents.

To compile the ROM, you’ll also need to install the assembler ca65.

If you open prologue.asm with your favorite text editor, you’ll see declarations for graphics, palette, and chr, which include binary image data directly using “.incbin”. We’ll use makechr to generate new data from the level.png image and include it in the same way.

Once again from makechr’s menu, pick Tools->Export Binaries. The filename used to save must contain the sequence “%s”, this will be replaced by the component names. Change the save name to “level.%s.dat”, which will create “level.nametable.dat”, “level.chr.dat”, etc. Copy these data files into the nes-starter directory.

Back in your code editor, with prologue.asm open, edit line 26 to be
.incbin "level.palette.dat"
Make sure to remove “build/” from the start of the path. Edit line 29 so that it includes the nametable and attributes one after the other:
.incbin "level.nametable.dat"
.incbin "level.attribute.dat"

Finally, edit line 47 so that it includes the chr data:
.incbin "level.chr.dat"

Finally, to build the ROM, run build_win.bat. If everything works, you’ll get a file called “starter.nes” which, much like the earlier “test.nes”, displays the original image and does nothing else. If something went wrong, try opening a command prompt, and run build_win.bat to see whatever error happened.

Add sprites

Makechr also can be used to build sprite data, which allows us to place additional objects in the scene. Although NES sprites work quite differently from background images, there’s enough similarity, and makechr has options to precisely control how they are handled.

As before, open up makechr.exe, and use File->Open but this time, select the file “chars.png”. Since this image is not yet being treated as a sprite image, it will load unsuccessfully, so the other views will remain blank.


Notice that some parts of the loaded image have red squares drawn over them. These represent conversion errors. Mousing over them will display more details in the bottom of the app. In this case, the messages all start with “PaletteOverflowError”. What’s happening is that, normally for a background a single 16×16 pixel block must use a single palette. However, sprites don’t need to meet this requirement. Enable sprite mode by clicking the checkbox for “sprite mode” in the lower-left of the app.


Even with sprite mode enabled, this is still en error in the image. Mousing over it displays “SpritelistOverflowError”. This has to due with the NES’s limit on displaying sprites; though there can be 256 CHR tiles for sprites, only 64 can be used at once. This image has more than 64, but that doesn’t matter since its a sprite sheet and we don’t plan on displaying everything at once. Enable the “allow overflow” option by clicking its checkbox just below “sprite mode”.


Finally the sprite image loads successfully.

There’s one final option that’s important to mention. Filthy Kitchen uses the “8×16” mode for sprites, which makes it easier to have taller characters in the game. This can be enabled by changing the dropdown that says “horizontal traversal” so instead it has “8×16 traversal”. Once this is enabled, you can observe how the CHR changes so that each object takes two locations next to each other, leaving some blank tiles where objects aren’t tall enough.

Now that the options are setup correctly, use Tools->Export Binaries to get the binary data from makechr. Save with the filename “chars.%s.dat”, which will generate “chars.chr.dat”, “chars.palette.dat”, etc. Copy these files into the nes-starter directory as well.

Open prologue.asm again. Edit line 33, replacing it with the following:
.byte $a8,$45,$01,$20,$a8,$47,$01,$28
.byte $b8,$61,$03,$20,$b8,$63,$03,$28,$ff

This will create a couple of sprites on the screen. Next, include the sprite palettes and chr by replacing line 26 with this:
.incbin "level.palette.dat", $0, $10
.incbin "chars.palette.dat", $10, $10

And replacing line 48 with this:
.incbin "level.chr.dat", $0, $1000
.incbin "chars.chr.dat", $1000, $1000

As a last step, we need to enable the 8×16 sprite mode, which requires a tiny bit of assembler. Open main.asm, and add the following lines between line 70 and 71, right before “ForeverLoop”:
lda ppu_ctrl_current
sta ppu_ctrl_current

Run build_win.bat to compile the ROM, and opening it should look like this:

This is just the start to making a full homebrew game, but using makechr can take the pain out of generating graphics.

Slides: Demystifying Demakes

A couple of weeks ago, I gave a talk at a local queens.js meetup about The Wit.nes, a demake I recently created. Though the talk wasn’t recorded, some folks expressed interest in knowing more about it. Below I have provided the slides I used, as well as the content, recreated from memory as best I could. Hopefully this will shed some light on how and why I made this project.


This is the title!


Hello everyone, I’m dustmop, I work as a freelance software develeoper in New York and I like to play, and occassionally make, video games.


One particular game I recently played, and was quite struck by, was Thekla’s The Witness, released in January of 2016. This game made some waves in indie gaming circles due to its minimal design, unique mechanics, and focus on teaching through example instead of written instruction.


The main gameplay in The Witness involves walking around a lush, 3-D environment of an uninhabited island, finding these mechanical panels, and drawing lines on them. While the game has a very crucial reason for existing in this 3D space, many noted a disconnect: that this core line drawing aspect would still work if extracted out and moved to a more primitive world. It was this observation that made me think of demakes.


A demake is a remake, but targetted towards older, retro hardware. They exist both as a study of game mechanics independent of technology, and also as a hypothetical exploration of what might have been if a game had been designed at a different point in time. In many cases, they are merely mockups, but some are actual homebrew that are playable on original gaming systems.

From left to right, first is Super Smash Brothers, a fighting game series that stretches across consoles starting from the Nintendo 64, and below it a demake for Nintendo’s much older Game Boy.

Next is Portal, a game well known due to its meme proliferation, and its corresponding demake for the Atari 2600.

Finally, the rhythm game Guitar Hero and an NES demake called D-pad Hero that was released on physical cartridge. This last one is important because it shows how well certain games can translate to the NES.


And also because I’ve made NES games!

Star Versus was released March 2015, and is typical game about spaceships blowing each other up. I learned a lot about the hardware from the time I spent making it, and was inspired to make more.


With The Witness fresh on my mind, and the thought of a demakes lingering near the back, I set about on this new project. You can see here a glimpse of the final result, The Wit.nes, and how it sort of resembles the original. Except of course it replaces the 3D world with the 80’s equivalent: an overhead view.


So how does one go about making an NES game? In my case, I had a number of tools that helped speed up the process, some of which I made myself, and others which I did not.


First off, makechr is a tool I created for making NES graphics in the correct file format. Here you can see the image of the garden that your character starts in, and how makechr processes it. (Here I did a live demo demonstrating makechr usage) Note that there are only 4 palettes, each with 3 unique colors plus a shared background color, and each 16×16 block only uses a single palette. Also, the CHR is very important, it’s the raw pixel art without color or position; we’ll be seeing it again soon.


A big help for creating The Wit.nes was neslib, a library that let’s you build games in C. It was created by another NES hacker named shiru, and and provides useful functions for getting input, changing graphics, and syncing to the frame.


The compiler I used is cc65, which targets the 6502, a very prolific processor in the 80s that is used not just in the NES but many other machines such as the Atari 2600, the Commodore 64, Apple II, and many more. It turns C code like this into assembly, though it’s usually not as efficient as what is shown here. Combined with neslib, this greatly sped up development of The Wit.nes.


The end result of my build process is a ROM file. These are just like the memory dumps pulled from comercially released games, which can then be played in emulators. Except in this case, the process is reversed, since the ROM comes first, during its development, and only later might end up on cartridge.


There’s also a very useful device called The Powerpak, which resembles an NES cart but also has a slot for a compact flash card. This lets me transfer a ROM over usb, put it into the Powerpak, and then play it on real hardware to make sure the emulator isn’t doing something wrong. This definitely comes up; though emulators have gotten very accurate, they’re still not perfect.


A quick aside into NES hardware. The game cartridges are very simple inside, basically just a PCB board with at least two chips. The first holds all the CHR (the pixel art we saw earlier) and the other, called PRG, holds everything else: game code, palettes, music, map layout, etc.


A ROM file has a simple format that resembles this hardware layout. It is a tiny header followed by data sections that contain exactly what’s on these chips, first PRG, then CHR. All the build process has to do is compile some C, link it with neslib, concat with a header and the CHR from makechr, and the result is ready to run in an emulator.


When I started off, this was the very first thing I made; a single puzzle panel to get an idea of how the core mechanic would work. Once I had completed this simple image, I commited to releasing this demo.


The first part that I coded was a cursor that could move around the puzzle while staying on the rails. I kept this simple by having the rails be 4 tiles apart from each other, which greatly simplified the code. Using neslib I could get controller input every frame, and move the cursor as appropriate.


Next was drawing a path behind the cursor. This was surprisingly challenging to get to work, for two reasons.

First, the NES uses tile based graphics, so making the path appear as a solid line meant drawing full tiles, empty tiles, and half tiles (in each of four directions), as the path moved. Also these tiles had to be drawn with the correct timing so that they would correctly overlap the cursor and not show a seam. There’s still some minor glitches in the final game that I wasn’t able to get fixed.

The other problem is that, when the cursor moves, you need to know whether its going forward where it hasnt yet been, or is going backwards over space that’s already occupied, since that decides whether the path is drawn or erased. To do this, I had to make a data structure to represent the map, and it had to have enough detail to work as needed, while still being memory efficient so it could work within the confines of the NES’s limited memory. It took about 3 tries of designing and redesigning to finally get this right.


What I ended up with was this RAM copy of the map that mirrors the spaces that can be moved into, and the path’s journey through it. As the cursor moved from a corner into an edge, or vise versa, the map would update with the direction the path was moving, 1 for up, 2 for right, etc. This turned out to be useful for 3 purposes: first the already discussed drawing code. Secondly, to detect when the cursor was colliding with itself (it can’t move where it’s already been), and finally for the puzzle solver.


You see, as The Witness (and The Wit.nes) progresses, it becomes about more than just drawing lines through mazes. These additional symbols are gradually introduced, and while its never revealed explictly what they mean, the player is supposed to figure them out by studying examples. I implemented three of these symbols into my demake, and they work the same as in the original game. Each has specific rules that need to be satisfied, and it turns out, having this in-memory representation was instrumental to checking these rules.


After the puzzles were working, I also added an overworld that used 4-way scrolling, which the player needs to explore to find the puzzle panels. This was also frustratingly difficult to code, as the NES has limited video memory and you have to update the off screen portion while the player is moving around. The math involved gets quite tricky due to the odd screen size, and the need to update colors separately from tiles. Using C to write this code helped massively in figuring this all out.


With that the game got released, and people liked it! I received a lot of very kind press, which was super overwhelming. My favorite was Polygon calling it “pun-filled” despite the fact that it contained exactly one pun (the title) and no other text. Overall, I was really happy with how positive the response was!


If you haven’t played it yet, check out The Wit.nes over at and play it completely free!

Lotus Text

Originally a thought experiment inspired by Valve’s steam controller UI, LotusText is a demo ROM that experiments with alternative text input for the NES. Typically, text entry on vintage consoles uses slow, boring interfaces that require scrolling back and forth across the alphabet to type one letter at a time. LotusText instead maps each symbol to a button combination, making everything quickly accessible. Possible uses for homebrew include things like quiz games, text adventures, dynamic personalization, or password systems.

Download ROM

Though a runnable demo ROM is available, LotusText is intended to be usable as an embeddable library. This is a little tricky to do, as NES homebrew doesn’t have many tools for creating reusable code, but the source code of the ROM demonstrates typical usage.



On screen are 12 leaves, facing away from the center. On each leaf and in the center are three symbols, left, right and center. By pressing a direction on the d-pad the user highlights a leaf, using diagonal presses for diagonal leaves, and double taps for leaves far from the center. Once highlighted, the user can press B or A or both to pick a symbol to type. When B and/or A are released, the symbol is inserted. Start is used to confirm the inputted text.

Technical description

LotusText uses 3 of the 4 background palettes, and 1 of the 4 sprite palettes. The remaining palettes may be utilized by host programs to provide custom decoration. It only uses 2 sprites, and 14 bytes of zeropage RAM. CPU usage is low, requiring about ~160 cycles per frame and ~70 cycles in vblank.

Required assembler is ca65. Ports may be made in the future if demand exists. Graphics are compiled using makechr. Building is done using Make.

The main operations performed by LotusText are input smoothing and attribute changes. Leaves are highlighted based upon which direction is being pressed by the user, and the attributes used to highlight each leaf are decided from a pre-compiled metadata image. Changing this metadata requires python and PIL / Pillow.

NES Graphics – Part 3

Part 1 and part 2 described CHR data, nametable based backgrounds, sprites, and scrolling. Combined, these cover nearly everything a basic NES cart can do without using additional hardware. To go any further will require a quick tangent to discuss, in detail, how rendering happens.


Scanline based rendering, with a pause for vblank

Like any older computer, the NES was designed to work with CRT TVs. They draw scanlines to the screen, one at a time, left to right, top to bottom, using an electron gun that physically moves to point at the screen where it draws these lines. Once the bottom corner is reached, a period called “vertical blank” (or vblank) happens, wherein the electron gun moves back to the top left to prepare to draw the next frame. On the NES, the PPU (Picture Processing Unit) does this scanline based rendering automatically, every frame, while code running in the CPU does whatever work the game needs to do. Vblank gives the software an opportunity to change data in the PPU’s memory, as otherwise that memory is being used for rendering. Most of the time, changes to the PPU’s nametable and palettes have to occur during this small window.

Continue reading