What is everything?

Someone asked me to explain all the files. Let’s try to do that. Look at the most complicated one.


in BG/

The .tmx files are from tiled map editor. Tiled uses the Metatiles.png and Sprites.png files to as its tileset, and the exported tilemaps are the .csv files. You can’t import a csv into a c project, so I wrote some python scripts to convert .csv files into .c files. Two different python files, one for background and one for sprites, so all the .c files with “SP” are sprite object lists.

All the .c files are included into the project.


The .nes file is our game that can be run in an emulator.

The .s file is the assembly generated by the cc65 compiler, just in case you want to debug by looking though the ASM.

The labels.txt file is a list of all the addresses of every label in the code. You can also use this for debugging, by setting breakpoints for these addresses.

in LIB/

is all the neslib files (neslib.h and neslib.s) and all the funtions that I wrote (nesdoug.h and nesdoug.s). The .s files are included in crt0.s near the bottom. The .h files are included in the main c file.


The .ftm files are Famitracker 0.4.6 files. 1 for music and 1 for sfx. The music file was exported as a .txt file (included here) and processed with text2data (from Shiru’s famitone2 files) into TestMusic3.s. The sfx was exported as .nsf (Nintendo Sound Format) and then processed with nsf2data (also famitone2) into SoundFx.s.

famitone2.s is the famitone code (again, Shiru’s website). All the .s files are included somewhere in crt0.s. If we had DPCM samples, they would also be included in crt0.s in the “SAMPLES” segment.

in NES_ST/

The .nss files are NES Screen Tool 2.3 files. I saved one (title) as a .h compressed RLE, which the game includes and decompresses. I made a .nss file with all the kinds of block in the game (metatiles), and save to .nam (uncompressed list of the entire screen), which meta.py python script converted into a C array in metatiles.txt. Also I did a print screen from both the metatile.nss and sprite.nss files and cropped down in GIMP and save those as the .png files up in the BG/ folder (used by tiled map editor).

The other files are…

License.txt – just the MIT licence

Sprites.h – arrays of all the metasprite definitions, generated by NES Screen Tool (or by hand, which is sometimes faster)

compile.bat – to recompile the project (on Windows)

crt0.s – is all the startup code, but also a convenient place to include asm or binary files.

full_game.c – the game code. I like to use notepad++ to write my code.

full_game.chr – the graphics file, split into 2 sections, the 256 BG tiles, and the 256 Sprite tiles.

full_game.h – variables and constants and prototypes, and some constant arrays

level_data.c – lists of game data and things included for each level

nrom_32k_vert.cfg – the linker file for ld65, tells where each segment goes in the final binary.

screenshot26.png – just a picture of the game.

And some more info on compile.bat

This is a list of command line inputs for compiling the game from scratch. If you change the name of your project, changeĀ set name=full_game” to match the main code filename. Or you can change this line

cc65 -Oirs %name%.c –add-source


cc65 -Oirs filename.c –add-source

where filename is the name of the .c file. You can process multiple C files this way, just make sure to also use ca65 to convert each .s file into a .o object file.

-Oirs are optimizations.

–add-source tells it to put the source code in comments in the asm file.

If you have multiple object files you need to change the linker (ld65) line to list every .o file.

ld65 -C nrom_32k_vert.cfg -o %name%.nes crt0.o %name%.o nes.lib -Ln labels.txt


ld65 -C nrom_32k_vert.cfg -o targetname.nes crt0.o file1.o file2.o file3.o nes.lib -Ln labels.txt

-o blah tell it what to name the output file.

If you use cl65 instead of cc65/ca65/ld65, then make sure to set target = NES. It sets a strange default target, which does not use standard ASCII encoding.

del *.o deletes the object files.

move /Y labels.txt BUILD\
move /Y %name%.s BUILD\
move /Y %name%.nes BUILD\

moves these files into the BUILD folder


just runs the game, which is in the BUILD folder.


Hope this helps.




22. Zapper / Power Pad



The zapper gun came with many NES consoles. They are pretty common, but you need a CRT TV for them to work. You can also play on most emulators using the mouse to click on the screen (make sure you set the 2nd player input to “zapper”).

It is possible to play a modified game on an non-CRT TV using a Tommee brand Zapp Gun. You would need to add a 3-4 frame delay in the code, since LCD screens typically have 3-4 frames of lag. You couldn’t play the standard Duck Hunt, but some people have been working on modifying zapper games to have a delay before reading the zapper.

Ok, so we’ve all seen Duck Hunt. Do you know how it works?


The game reads the 2nd player port until it gets a signal that the trigger has been pulled. Once that happens, it blacks out the background and replaces 1 object per frame with a big white blob. If there are 2 objects on screen, it will display the first object on 1 frame and the other object on the next frame… to tell which object you hit (if any).

Duck Hunt uses 32×32 pixel box for standard ducks (4 sprites by 4 sprites). Which is about the size you want for a medium level difficulty. Other games had much bigger things to shoot and much bigger white boxes. To vary the difficulty, they would then change the amount of time that the target was on screen.


Duck Hunt used 24×16 pixel box for clay pidgeons. (3 wide by 2 high). Which is kind of difficult to hit. 24×24 is a little more reasonable, and that’s what I used.


I had to write a different controller reading routine, due to the zapper using completely different pins than the standard controllers. I threw in this zaplib.s and zablib.h files.

zap_shoot(1) takes 1 arg, 0 for port 1, 1 for port 2. And, it returns 0 or 1 if it reads the trigger has been pulled.

I also checked to make sure the last frame didn’t also have trigger pulled.

zapper_ready = pad2_zapper^1;

zapper_ready is just the opposite of the last frame. That’s a bitwise XOR, if you’re not familiar with the caret operator “^”.

So when we get that signal, I turn off the BG… ppu_mask(0x16); and draw a white box where the star was… draw_box();

0x16 is 0001 0110 in binary, see the xxxx 0xxx bit is zero. That’s the “show BG” bit. It’s off, but the sprites are still on.

Then immediately, I turn the BG back on, ppu_mask(0x1e); so the flicker is minimized.

0x1e is standard display. 0001 1110 in binary has the xxxx 1xxx bit active again.

And I call zap_read(1) takes 1 arg, 0 for port 1, 1 for port 2.

which is a loop that waits till it either gets a signal that the gun sees white, or that the end of the frame has been reached. It returns 0 for fail and 1 for success.

I tested this on a real CRT on a real NES, and it seems to work fine at 5 ft. This game uses port 2 for the zapper, which is kind of standard. But, you could make a game that uses port 1, if you wanted to. zaplib.s will have to be included in crt0.s and zaplib.h will have to be included in your main c file.



Also see the wiki for more technical info.




Power Pad


The Power Pad is a little less standard. There weren’t many games that used it. Just like the zapper, the Power Pad uses different pins than the standard controller, so I had to rewrite the code that reads the input. See padlib.s and padlib.h.

read_powerpad(1) takes 1 arg, 0 for port 1, 1 for port 2.

And, it returns a 2 byte value (unsigned int). And I made these contants to represent each foot pad.

#define POWERPAD_4 0x8000
#define POWERPAD_2 0x4000
#define POWERPAD_3 0x2000
#define POWERPAD_1 0x1000
#define POWERPAD_12 0x0800
#define POWERPAD_5 0x0400
#define POWERPAD_8 0x0200
#define POWERPAD_9 0x0100

#define POWERPAD_6 0x0040
#define POWERPAD_10 0x0010
#define POWERPAD_11 0x0004
#define POWERPAD_7 0x0001

padlib.s will have to be included in crt0.s and padlib.h will have to be included in your main c file. This was tested on a real Power Pad on a real NES.



Also see the wiki for more technical info.