Update, bug fix

There was a minor bug in the neslib example code that I used for 8 different files. In crt0.s in the reset (startup) code, it failed to turn off the APU frame counter IRQ. This won’t cause a problem if interrupts are disabled, but if IRQs were turned on it would fire an IRQ at inappropriate times.

Specifically these lines were missing…

ldx #$40
stx $4017

which is actually written like this in the source code, now.

ldx #$40

If you were using the crt0.s file from any of my source codes, you should redownload the file.

I also edited several other source code files in insignificant ways. It shouldn’t cause any problems, unless I accidentally filled the .zip file incorrectly, before reposting to dropbox.


These are NOT the major revisions that I mentioned. I have plans to rewrite the tutorial completely, and make it shorter and simpler and use the neslib, to make it more compatible with code that other people are writing. Standardization is the goal.



Backup / PDF archive

Since I plan to make major changes to this tutorial, I thought it would be appropriate to make an archive of the old version. Also, you can view this stuff offline (lots of PDF files).

(still a work in progress)

Introduction – nesdoug

1. Getting Started – nesdoug

2. how cc65 works – nesdoug

3. Our first program – nesdoug


4. What_s a V-blank_ – nesdoug


5. A little color – nesdoug


6. Sprites – nesdoug


7. Input – nesdoug


8.Sprite Collisions – nesdoug


9. Drawing a full background – nesdoug


10. Background Collisions – nesdoug




11. Scrolling – nesdoug


12. Basic Platformer – nesdoug


13. Sprite 0 Trick _ Debugging – nesdoug




14. Intro to Sound – nesdoug

15. Adding music – nesdoug


16. Adding Sound Effects – nesdoug


17. Planning a Game – nesdoug

18. Game Coding – nesdoug


19. Game Coding 2 – nesdoug


20. Game Coding 3 – nesdoug


21. Credits and Thanks – nesdoug

22.More – nesdoug

23. Using DMC Sounds – nesdoug


24. MMC3, Bank-switching, IRQs – nesdoug


25. Importing a MIDI to Famitracker – nesdoug

26. ASM Basics – nesdoug

27. ASM part 2 – nesdoug

28. ASM part 3 – nesdoug

29. ASM part 4 – nesdoug

30. ASM part 5 – nesdoug

My Neslib Notes – nesdoug

Neslib Example Code – nesdoug



NES Screen Tool BMP Import – nesdoug

Import Full Background as RLE – nesdoug


Update Aug 2017 _ CFG files – nesdoug


Sprites, Again – nesdoug


Sprite Collision, and Controllers – nesdoug


Sprite BG Collision, Pong – nesdoug


Add Music, Famitracker – nesdoug


Scrolling – nesdoug


famitone 3.2 _ annotatecc65 – nesdoug (and famitone 4)



PPU writes during rendering. – nesdoug (asm code)



NES Graphics

This is not a “best graphics on the NES” list. Just some games that I think are very good. I was going to point out some of the weaker artwork, but that seemed a little hypocritical, since I have a tough time making good looking pixel art myself. So, none of “they should have done this different”. Just good art pictures.

Starting with my favorites. I really like the graphics team over at Technos. The people who did River City Ransom, also made some similar looking games, like…


Super Dodge Ball


Crash N The Boys: Street Challenge


Here’s some other games in no particular order.


Kick Master


Joe & Mac


Ninja Gaiden III


Shadow of the Ninja


Batman – Return of the Joker


Chuka Taisen


Felix the Cat


Kirby’s Adventure


Fire ‘N Ice




Ufouria (Hebereke)


Chip ‘N Dale Rescue Rangers 2


Stanley: The Search for Dr. Livingston



Little Samson (2 images)


Bucky O’Hare


Vice: Project Doom


Moon Crystal


Conquest of the Crystal Palace




Gun Nac


Little Nemo: The Dream Master


Gargoyle’s Quest II


Megaman 2


Megaman 6


Castlevania III


Double Dragon III: The Sacred Scrolls


Gradius II


Radia Senki: Reimmeihen. This is probably the best looking RPG produced on the NES… well, Famicom anyway. Good work, Tecmo.

Sorry about the quality of some of these pictures. They are screencaps of videos. It would have taken me forever to play all these games to the right point to get better pictures.

I’m sure I left some games out. Lot’s of Disney games look very good. If you feel like a game is missing, and definitely should be in this list, feel free to leave a comment.

PPU writes during rendering.

I’m going to do some experiments today. Writing to the PPU during rendering.

Normally, you never want to do this. The NES was designed so that you write to the PPU during v-blank or when rendering is off. Let’s see what happens, with the ultimate goal of changing 1 color mid-screen without ruining the picture.

Here’s a simple asm6 template code.


With a timed loop that waits till we are definitely not in v-blank. I’m trying to write an X near the top left. Emulators have been disappointing on these tests, so I have to go right to actual hardware (US NTSC top loader to a flat screen TV).

lda #$20 
sta $2006 
lda #$42 
sta $2006 
lda #4 ;is an X 
sta $2007


What’s happening here, is writing twice to 2006 during rendering has overwritten the scroll registers and misaligned the screen. Also, our X is nowhere near the top left. The last point, is where emulators failed accuracy…some of them DID put the X on the top left.

So, let’s try to fix that. After writing the X, we will then write a new 2006 2006 to try to realign the screen…and time the write near the far right of the screen to reduce visible glitches.

lda #$20 
sta $2006 
lda #$42 
sta $2006 
lda #4 ;is an X 
sta $2007 

lda #$20 
sta $2006 
lda #$a0 
sta $2006


The write is still not going to the right place, nor is it an X. And the 3 is squished at the top, as it is skipping a scanline. Let’s try turning rendering off…doing the write…turn rendering on…fix scroll with 2 2006 writes. I also had to move the scanline wait a little.

lda #$20 
sta $2006 
lda #0 
sta $2001 ;rendering off
lda #$42 
sta $2006 
lda #4 ;is an X 
sta $2007 
lda #$1e 
sta $2001 ;rendering on
lda #$20 
sta $2006 
lda #$a0 
sta $2006


Ok, that seems to work, except with some noticeable glitches. Perhaps better timing could reduce that as well. I’m not too concerned about that right now…so on to using the same setup to change a color. I want all numbers below the 2 to be red.

First I have to write $30 (white) to the text palette during NMI, so the top stays white…then rendering off…change color…rendering on…fix scroll.

lda #$3f 
sta $2006 
lda #0 
sta $2001 ;rendering off
lda #$03 
sta $2006 
lda #$16 ;red 
sta $2007 
lda #$1e 
sta $2001 ;rendering on
lda #$20 
sta $2006 
lda #$a0 
sta $2006


Not perfect. The top of the 3 is still white.


Moving the split up is not enough, since that will just cut the top of the 3 off. We must do a fancy 2006 2005 2005 2006 write, about 2 scanlines earlier. See the nesdev wiki on x/y scroll splits…


lda #$3f 
sta $2006 
lda #0 
sta $2001 ;rendering off
lda #$03 
sta $2006 
lda #$16 ;red 
sta $2007 
lda #$1e 
sta $2001 ;rendering on

lda #0 
sta $2006 
lda #40 
sta $2005 
lda #0 
sta $2005 
lda #$a0 
sta $2006


That seems to be working. There are still some noticeable glitches though. Probably, this could be improved. Maybe another day I will try to hide it. But even still, timing THIS fragile is dangerous. This is all done with timed loops. What if something interrupts us?

I added a DMC sample to fire every second. The DMC channel, when ON, steals cycles from the CPU to read a byte…which ruins perfectly times loops.


So, if you used a MMC3 scanline counter, and could time this to perfection…you could make mid-screen changes beyond just scroll shifts. But, it could be error prone. Many of my tests ended with the PPU writes going to the wrong address. Rendering needs to be off, meaning you should only do this on a blank part of the screen.


Here’s the source code. In 6502 asm for the asm6 assembler. Caution, I just wrote / rewrote some of this code (especially the controller read code) and it hasn’t been thoroughly tested.


Furthermore…I forgot that turning rendering off makes sprites behave erratically. This sort of thing may only be possible on screen with no sprites. I will have to test this some more.


Jammin Honey

Here’s my entry to the nesdev 2017 game competition. Jammin Honey. You play as Honey, and have to battle your way through 30 levels of slime monsters and fire breathing bullies and spiked floors. Collect enough notes to clear the level. 10,000 pts for a bonus life. 3 levels of difficulty.


One cool feature, is, you can customize Honey’s outfit and guitar colors.




I tried to make it feel like an early old-school game. Like the kind you would see at the arcade around 1982-3. Here’s a free download. Enjoy!


(link updated Mar 14, 2018, boss blinks when hit now)


Controls –

left/right – run

up/down – climb ladders

start – pause

B – strum the guitar to attack

A – jump


Also, I wrote some game genie codes for this game…

-no bees – PEUYNYAA

-start with 10 lives – PEUNVYAA
-start with 20 lives – ZEUNVYAA
-start with 30 lives – LEUNVYAA

-start at level 10 – PEKNOYAE
-start at level 15 – TEKNOYAE
-start at level 20 – LOKNOYAA
-start at level 25 – AOKNOYAE
-start at boss (level 30) – IOKNOYAE
-disable dmc channel (no guitar sound) – YAOEXSYO
(fixes potential bug on AVS)


What does 2018 hold for me?

I will probably be quiet and not write many posts here. But, I am working hard on another NES game that will end up on a cartridge. Still too soon to mention any details, unfortunately. Stay tuned.

And, 2019? SNES homebrew, maybe. Time will tell.


famitone 3.2 / annotatecc65

Hey everybody. In 2016, I wrote a version of famitone music library that allowed the volume column and all notes. Recently, I fixed the major bug that it had in processing more than 1 song. text2vol replaces text2data. I should be used with the nsf2data (v1.15 by Shiru 04’17). See Shiru’s website to download that.

Here is the link to my (unofficial) update. Source code included.



Update July 11, 2018. Famitone 4.

I also wrote a version that allows the 1xx,2xx, and 4xx effects…pitch rise, pitch fall, and vibrato. I shelved it when my last update had a major bug…but now that I fixed that bug, I finished it. Here it is.



Shiru would say, “why not just use the full famitracker driver”. That, of course, is also available on his website.


But, the full famitracker code is huge. Almost 4x as big a ROM footprint as famitone2. My famitone3.2 is only slightly larger than famitone2…though I did gut the PAL note table. Sorry. I didn’t use it. You could probably put it back in.

Hope this is useful to somebody.



In an unrelated note, my friend dustmop wrote a python script that inserts the cc65 source code into the debugging files for FCEUX. I haven’t used it yet, but it looks cool. Check it out.



A List of NES Homebrew Games

As a NES homebrewer, I have been lucky enough to meet some great people, and play lots of interesting games. The past few years have been huge in the NES homebrew community, and I feel like next year will be even bigger.

This is my list of favorite NES homebrew games. Several of these I haven’t played yet because several of these aren’t completed yet. Which is why I think 2018 is going to be a great year for NES gaming.

I didn’t want to list “top 10” or “top 20″…and piss someone off, so I listed them sort-of alphabetically.



2nd Dimension



This is an interesting puzzle game. Imagine a 2x1x1 block that has to be tipped over in exactly the right directions to make it through to the goal.

(Also available from 2nd Dimension is Get Em Gary – which is like “Wrecking Crew and Fix-It Felix Jr”, programmed by Sly Dog Studios)





Most people will probably not know who Alp is, but he was working on an awesome Zelda-like game called “Cat Quest“. We will probably never see that game made, but Alp is still (not-so) secretly working on NES games, and they look damn good. The Cat Quest project seems to have morphed into a game called Transamnia (possibly NSFW). Here’s a beautiful screenshot.

-Transamnia (? formerly Cat Quest)


And a game I’m personally excited about is Cotton & Candy, a platformer. Excellent work Alp. Hopefully these games will be made available…someday?

-Cotton & Candy





Brad Smith (Rainwarrior)

This is a big one that has been in the works for a while…and is almost done (as of late 2017). In Lizard, Canadian programmer / musician Brad Smith has made a very big open-exploration world…well 2 parallel worlds connected by doors. You play as a little person wearing a lizard costume. If you find a different costume, you gain new abilities. There are lots of little secrets in this game (big head mode, bad eye mode, a talking moose). Tons of interesting details in this game should keep you occupied for weeks.






Chris Cacciatore

Still a work in progress, in Nebs n Debs you play as a little girl with an Octopus hat on. A Megaman style platformer, you can dash across gaps and collect diamonds. This was a winner of the 2016 Nesdev competition. Very high quality.

-Nebs n Debs


(I don’t think he has an official website) There’s a link to the demo at the bottom of the first post here…





Diskover / RetroNES Software

I guess this one had a very limited cartidge release, since it didn’t meet it’s crowdfunding goals (I think he said he made a few copies for his friends). Banketh is Diskover’s first game, which is a top-down adventure game (like Star Tropics). I hope we get to see the full game released some day.



The Demo is here…


Diskover recently announced he is porting The Sword of Ianna to the NES. Here’s a screenshot of what that will look like.



Doug Fraker

I, of course, made a game, which is available on cartridge. It’s a fighting platformer. And I’m working on another project. Stay Tuned.

-Vigilante Ninja 2





Glutock / Broke Studio

Another winner of the 2016 Nesdev game competition, and also a work in progress from France. In Twin Dragons, you play as two dragons named Dinky & Minky. You can play as either one. A great looking platformer with excellent music. If you eat a hot pepper, you can breathe fire. If you eat a popsicle, you can breathe ice. Probably my favorite NES game. Maybe.

-Twin Dragons





Gradual Games

I really wanted to mention both games. Nomolos: Storming the Catsle (yes that’s cat…sle) is a fun platformer fighter game (like Zelda II), featuring a cat knight. It deserves to be on this list, but I prefer The Legend of Owlia. Which is kind of like a Link to the Past style adventure game. You carry an Owl, which can attack and get things and has several other abilities. And, apparently they are working on a 3rd game, which should be done next year.

-The Legend of Owlia



It should also be mentioned that Gradual Games made a music engine that other people have used to get music in their NES games (StarKeeper, Dushlan and Mystic Searches). AND, Gradual Games has developed a Virtual Machine for porting NES games to play on PCs without an emulator (Get ’em Gary and Eskimo Bob). Check out the Github pages.




Infinite NES Lives

Action 53 (2 volumes), are multicarts from the entries into the 2011 and 2014 nesdev competitions. There are so many cool games on these cartridges, but I wanted to highlight a few…Streemerz is like Bionic Commando (you shoot out a rope which pulls you up), with lots of blocks to avoid that kill you. I wanna flip the sky is a reverse gravity platform puzzle with tons of spiked floors. You will die a lot in that game. Love Story is a sword fighting action platformer. Sir Abadol (from Mojon Twins) is another action platformer, with puzzle elements (locked doors and find keys). Very fun. And many more games that I didn’t have enough room to mention. Here’s a list…


More about Mojon Twins in a second. I will also mention Shiru later…he contributed the most games to the Action 53 set.

Volume One –

-Streemerz – The Fox


-I Wanna Flip The Sky! – Tom Livak


Volume Two –

-Love Story – Tom Livak


-Sir Abadol – Mojon Twins



Some of the games are available to play for free…



KHAN Games

Kevin Hanley has programmed several NES games, including a famous Frogger port. I should mention the ‘Larry and the Long Look for a Luscious Lover‘ port, which is worth playing, but not technically a homebrew. (I guess?). Some of his games are available from RetroUSB…like Study Hall, which is a bit like a harder version of Donkey Kong Jr. No, there isn’t any math.

My favorite KHAN game is The Incident, which is a Sokoban style top-down puzzle with moving boxes.

-The Incident



-Study Hall





Lucasz Kur

Lucasz Kur is a Polish NES programmer, who is sometimes working with Brazilian graphic artist, Marcelo Barbosa (Tcheco in the Castle of Lucio). I don’t know everything that he’s worked on but definitely these games. Lucky Penguin isn’t finished, but you can play a demo from nesdev forum. http://forums.nesdev.com/viewtopic.php?p=201167

-Lucky Penguin


-Cowlitz Gamers’ 2nd Adventure


The Cowlitz 2nd Adventure game had a limited cart release this year, and I heard it sold out in minutes. I haven’t played it, but it looks very nice. Lucasz Kur also programmed Inversion. Here’s a link to that…



Mega Cats Studio

Mega Cats has hit the ground running with 10+ NES games developed (or almost done) in just a few years.

-Justice Duel
-Creepy Brawlers
-Creepin it Real
-Little Medusa
-Almost Hero
-City Trouble*
-Log Jammers

I ran into Mega Cats at a game convention, and played 2 of their games. Nice. I’m most excited about Little Medusa, which reminds me of Kickle Cubicle and Zelda. Apparently it’s finished, or will be soon. I’m going to have to play some of the other games before I can really comment on them.

*(It’s been brought to my attention that City Trouble, Dushlan, and Expedition were not developed by Mega Cats, just published by them).





Miau (Morphcat)

Morphcat submitted the Super Bat Puncher demo for one of the nesdev competitions (2011). I’ve heard many people tell me it is one of the best NES homebrews. I’ve been told that Morphcat won’t be making a full game from it…but he and Nicolas Betoux are making a 4-player haunted adventure, yet untitled, which showcased in the game museum in Berlin. I’ve been unable to find much about the game (not even a title) but here’s a screen shot.


Super Bat Puncher is a fast-moving platform game, with a cat that punches bats…and walls to get a boost.

-Super Bat Puncher





Mojon Twins

I can’t count how many games na_th_an has programmed. 50? Maybe. Some of the best were submitted to the 2016 nesdev competition. Very good games. Here’s a list of great games. I think they are all available on their website (mostly in Spanish). Caution, some NSFW images.


-Sir Abadol (remastered)
-Super UWOL
-Lala the Magical
-Cheril the Goddess
-Wo Xiang Niao Niao

My favorite is Lala the Magical, about a witch girl who can create temporary platforms to stand on. Hard, but fun.


Cheril the Goddess is similar, except that you can temporarily fly sometimes. On a side note, Wo Xiang Niao Niao means “I need to pee pee”. It is a fun game where you jump and bounce off enemies. Check out their games, which are all free to play.



Nova Squirrel

Nova contributed several games to the Action 53 set. He is currently working on a game, called Nova the Squirrel, featuring a spunky little green squirrel. It is a unique platform game, with lots of clever block puzzles. I have no idea when it will be finished, but it looks cool.

-Nova the Squirrel






Pyronaut is programmed by Optomon (graphics by M-tee). It looks a lot like Metroid, and I hope it will be finished one day. “Due to commitments on smaller scale works and increasingly busy personal lives, M-tee and I have halted work on Pyronaut indefinitely, with the intention of resuming work on it in the future.”



Optomon is also working on a game called Rollie, which looks promising. You might have heard about him from his excellent work on Metroid Rogue Dawn.

M-Tee is working on a game called Isolation right now, with KHAN. It looks like a point and click game (like Maniac Mansion). There isn’t a demo yet.




Piko Interactive

Piko Interactive (I think) is better known for developing SNES homebrew games. They have released 2 NES games as well. Quest Forge is my favorite. It’s a bit like a top-down adventure game, like Zelda. Piko also got the rights to several unreleased NES and SNES games (not really homebrews), which they now produce.

-Quest Forge






-Alter Ego
-LAN Master
-Many Other Games (see Action 53 above)

From Russia, Shiru has been contributing to the nesdev community for years with his open source game library and NES Screen Tool app. He has developed for multiple retro consoles. Several of his games are included in the Action 53 game sets. I think the most fun game (which is not in Action 53) is Alter Ego. It is a port of a VX Spectrum homebrew by Denis Grachev. It’s sort of a ladder and platform game, and you have a shadow self that mirrors your moves. You can switch places with him, and collect all the items. It’s fun. It has excellent music as well.



-Lan Master

Also check out Lan Master, if you like puzzles.



Shiru made some games for Retroscribe / Greeting Carts. Blow Em Out, Beer Slinger, and Perfect Pair (limited edition). I’ve been told the company was under new management, but still running. Update, they appear to be no longer for sale. Well, they used to be here…





This is the big one. If you play one NES homebrew game, play Battle Kid. It’s THAT good. If you like Megaman, you will like Battle Kid. Find keys, gain abilities, fight monsters. It’s fun, but also very hard. Both available from Retro USB.


-Battle Kid 1 + 2




Sly Dog Studios

Sly Dog has been busy making NES games for years. Over a dozen games. I think my favorite is The Mad Wizard, which the full game is now available to play for free. You play as the wizard, and gain abilities as you adventure through the woods and caves on your way to fight Amondus the Summoner. You don’t jump. The wizard can slowly levitate, and as you gain abilities…higher and further. This is part of a 3 game series. The gameplay on the other games are completely different, though.

Sly Dog also programmed Get’em Gary for 2nd Dimension (see above) and Black Box Challenge for Hagens Alley. I’m not sure if Black Box is completed.

-Mad Wizard


Black Box Challenge – NES Homebrew (Kickstarter Regular Edition)



Sole Goose Productions

Besides Swords and Runes (Adventure) and 0-to-X (2048 number puzzle), there is Spook-o’-tron. I think it was just finished for Halloween 2017. It’s kind of a top down ‘bullet hell’ shooter game, like Smash TV. At the time of writing this, I haven’t been able to find it or play it.





Spoony Bard

Tomas is from Canada, and new this year with his first NES release, Eskimo Bob. It’s a platformer with wrap around scrolling and a snowy theme. Cute artwork. Great first game. Looking forward to more games down the road.

-Eskimo Bob





Tepples (Damian Yerrick)

Tepples has been making cool NES games for a long time. He has been very involved in the nesdev community, and has released several NES tools / etc. (and soon some SNES tools), including a music driver (pently).


For the last 2 years, he has raised the bar for NES homebrew games. He and Retrotainment (Cash In Culture Stores) developed Haunted Halloween 85 and 86. Spooky themed action platformers with excellent boss fights. Punch some zombies and ghosts. Eat candy and soda. Lots of movie references. The music in 86 is great, and it features parallax scrolling effects.

-Haunted Halloween 85-86


-Full Quiet

And they are working on another game for next year, Full Quiet, which looks cool, from what little I’ve seen.




I left Star Keeper off my list. I know other people frequently put is on their top lists, but I know almost nothing about the programmer, except that he’s from China. And it doesn’t seem to be available anywhere to play.

Honorable Mentions…

8-bit Hero’s Mystic Searches (coming soon)



Kira Kira Star Night



Retro City Rampage/ROM City Rampage (I haven’t seen any actual NES gameplay, but I know that the game was ported to the NES, and I think carts exist)



Rekt, by Vectrex (coming soon)



Star Versus, by Dustmop



Blade Buster



Indivisible, by Kasumi


Too Soon to talk about, but maybe good…one day…
-Unnamed 3d raycaster game (think Doom), by 

Sorry if you weren’t mentioned, homebrewers. Too many great games to list them all. If you want to read more about NES Homebrews, you should check out Jeff Wittenhagen’s book on the subject, NES Oddities & the Homebrew Revolution.


Please let me know if I made any mistakes, or if there is some awesome NES homebrew game that should be on this list, but isn’t.