nes-starter-kit: A Quickstart guide for homebrew in C (WIP)

I've been playing around with this for a few months, so it's time to get some eyes on it beyond mine, and see if it's actually useful to anyone. (I also put this on NA a few days ago... feel free to comment in either place)



Since I went to MAGFest this year, I've been kind of obsessed with the idea of making retro development easier. The people I met made me realize that a lot of people want to get started, but aren't sure how. While there are a lot of good options out there already, I realized there just might be a space for a code-based starter kit. So, I made one!

nes-starter-kit is an attempt to make NES homebrew more accessible. It is presented as an intentionally short zelda-esque NES game, combined with a guide to update/change/replace every part of it. (Click above to play the game!)
All changes can be done in C - no lower-level coding is required. 
* The game uses neslib and some custom extensions written in 6502 assembly, which should cover your needs without modification. If you want to tweak these or write some code in assembly, there is some guidance in the 5th section for this. 

The thing can be used to build a very simple, basic game without much code. However, the included guide walks you through adding a lot of features, and also hopefully gives enough guidance to come up with your own ideas!

Features: 

• Keeps things simple; nothing beyond basic programming knowledge is needed (Can you get through the first few chapters of a C tutorial? If so, I want this to work for you!)
• No restrictions on music - anything you create in Famitracker should work
• Optional IDE integration (VS Code) - syntax highlighting for you code, and a key combination to build and run your game
• Works on NES console; compatible with PowerPak and INL MMC1 cartridges
• Use it for whatever you want: all code is MIT licensed, and graphics/music/sounds are Public Domain. (This means you can freely use this for anything, including commercial products)

Known Caveats:

• Some chapters probably still assume too much technical knowledge (If you run into problems, let me know!)
• Engine performance could get slow when features are added. I don't know if I've quite found the balance between performance and ease-of-use yet.
• Uses an older version of cc65, other tools. All are provided for download, so it should work consistently at least
• Map editing in Tiled is mildly annoying due to limitations with layers
• Versioning not quite figured out yet -- if something weird happens when you update the code off master, try redownloading the tool zip. (I'm trying to get better!)
• It's not NESMaker; some code is still required

The guide is broken into 5 sections - the first one is an introduction, and the rest are meant to be read as needed.

Let me know what you think if you decide to check it out! Is this something you would use?
Github PRs/issues/etc also always welcome.

Online Guide

nes-starter-kit on Github

Example rom

Have fun!

I think it's awesome that you made this. I imagine most of the people that inhabit this forum will say that we wouldn't use it, because if we're here, chances are we are no longer your target audience. But I can see this being extremely useful for someone wanting an example to get started with.

So I guess my point is, I hope you don't be discouraged by a lot of "I won't use it" responses here, because I love that you made this.

Hey!

Thanks for the feedback - that's a good point. I guess with NESDev I'm not really expecting much in terms of "I'd use this" -- I almost didn't post here, but I think there's more of a chance that people here will look at it with a critical eye, and point out potential problems. That's valuable too!

I put the poll there in hopes it might catch people who are too anxious/lazy/whatever to post, but are still thinking about using it. Any little indication that people actually want to use this will encourage me to carry on. I'll admit, I'm really afraid this doesn't have a target audience. (And I have been since the start)

I support your project, despite being fairly against using C for this platform. I'm not going to de-rail the thread about that (it's irrelevant); my point is that just because *I* wouldn't use it doesn't mean it doesn't have benefits for others. There is a definite use for what you've written and shared. It's a positive thing and provides a good base for people who at least want to get some basics down in a "less cryptic" language than assembly. Expanding:

We get people here every couple months who want to do NES stuff in C and not assembly (though I tend to remind them: you're going to have to deal with 6502 eventually, esp. when debugging, so avoiding it entirely is unlikely). So the fact your project is predominantly in C (barring the deeper bits, which you covered already in a smaller font) should make that process easier for those folks.

Kudos!

Nice work! I'm in the process of finishing something simmilar (a simple, modular and configurable game engine, along with a toolchain and tutorials), also using C, neslib and famitracker. Some knowledge of C is good to have for full customization, but it should be manageable for a non programmer as well. What is your target audience?

Thanks for the feedback Koitsu!

na_th_an- That's awesome; I'll be super interested to see your project when it's ready. You've consistently produced amazing work, so I'm going to bet it will be good.
If I've done anything useful, don't be afraid to copy/reach out. (I use the MIT license for this reason)

For a target audience, the ideal person is a developer who has thus far only worked in higher-level languages (thinking node/php/java/etc) and wants to dive into NES dev, but needs some guidance/hand-holding.
I'm also trying to make it accessible to the person who has only written a few scripts here-and-there... but I realize that's going to be harder to do, and I don't think I've gotten close to that target yet.


I guess for me, a big thing *I* like to play with is game mechanics, so one of my goals is to make changing those really clear/easy.

I like how you have organized things and have learned a couple of things that will save me from lots of manual work when configuring fairly complex mappers. I have yet to examine the code, which I will. I guess, from a quick glance, you are interested mainly in code readability and make things easy for programmers, which is a good thing. Code is clean cut. I'm sure newcomers will have a great quickstart. The empty canvas is frightening if it's your first canvas. I believe in a way of learning to do things where you start filling in the gaps. For instance I can readily write 6502 assembly after all these years and such an asset has helped me in making my games better - but if I had to have endured the hard way, I'm sure I'd given up. Hadn't I had neslib and Chase I would have achieved nothing. And what you are offering is vastly superior!

This is great stuff!

I wouldn't use it though. But that's simply because doing the low level stuff myself on the nes is part of the fun for me.

I am super new to nesdev, and I am very happy to devour anything you are offering. Thank you!

Thanks for the kind words folks!

Just a quick update; I've got the first two sections complete, and with those you should be capable of making a very basic game! I'm kinda thinking of this like an alpha release.

I'm getting into the 3rd chapter, which is the start of adding new features - I think these chapters are going to be more involved to write. I may create a git branch for each one, since I expect to be writing a lot more code. (This also means I need to maintain a bunch of branches as I update the main engine, which could be a pain)

At any rate, progress continues!

It's been about a month, so I figured I'd post an update. The project is quite alive!

Since my last post I've completed about 80% of the chapters I had intended to write. (I have around 9 left, though I may add/subtract a few) It's definitely ready for use now!

I also just released a documentation site today: Pretty documentation!

Notable additions include:
- All of section 2, including adding enemies, sprites of all types, and adding music/sound
- The first few new feature chapters - including adding a new map
- Making a nicer title screen
- Animating background tiles

Anyway enjoy, and questions are always welcome!

Your guide says you need Cygwin, so I'm thinking hmm, is he compiling a NES game with GCC? But then the source code is cc65 and neslib...which I didn't see mentioned at all in the guide.

What is Cygwin for then, just to get the Unix tools? Not for a C compiler?

Yep, it's just to get the unix tools. Mainly, I want make (to put all build stuff in one place, allow incremental builds, and organize it in a semi-sane way), as well as curl/rm/mkdir/touch/etc.

Plus, though I don't officially support linux/mac os right now, I'd like it to be possible. (Also helps to be able to use the same build process with circleci)

Could I do all of this with windows commands? Sure, but I suspect it'd be harder to edit and understand, and also more prone to failure.

-----

That aside, you do make an interesting point about what tools are mentioned where.

The way I have it sorted right now, I only briefly mention the various things you rely on in the "Setting up your tools" chapter -- I tried to focus more on getting everything working than on explaining what everything is. In fact, the only thing I say about the C compiler there is:



I do mention all of the tools in the README: https://github.com/cppchriscpp/nes-starter-kit#tools -- and any tools that are directly used are introduced in the chapter(s) that use them. (For example, I introduce famitracker in the sound/music chapters, and I introduce NES Screen Tool in the various graphics chapters)

Perhaps it's worth having a chapter (or a subsection of the tools page) that just explains all the various tools we depend on at a high level, for anyone curious...

(Also I just noticed I missed Tiled in the readme file; gonna go ahead and fix that!)

Update: I changed the passage above to this, to at least reference the tools by name:



Still thinking about if I want to do more.

In the setup instructions included with nrom-template, I have recommended getting the UNIX tools (Make, Bash, and Coreutils) on Windows by installing MSYS 2 through devkitPro Updater. Would MSYS be a good substitute for Cygwin in this case?

Git for Windows also includes MSYS Bash and Coreutils, but in that distribution Make needs to be installed separately from ezwinports.

I could potentially do that, but I'm not really sure what benefit anyone would get from it. Could you elaborate?

Cygwin is a little old/clunky, but it 1) provides the tools I need, and 2) provides a convenient installer for them with command line parameters, so I can make it really easy for someone to install the tools and move on. (Plus, if you have Cygwin already installed it will just add anything you don't already have) I looked at a couple options, and cygwin actually seemed like the easiest to support/use.

devkitPro also kinda suggests that I not do that for a project like this... from their about page:

(emphasis mine)

I can certainly be convinced, but it seems counter-intuitive to change right now.

I haven't touched on this topic in a while, but the project is very alive! I made the first real "release" of this a couple weeks ago. I've got a backlog of things I'm changing and fixing, but it's more ready for prime-time now.

I also created a game for the most recent Ludum Dare using it, partly as a proof of concept. I'm pretty happy with the results



Check it out here

example game source

Great job, congratulations. Will give it a proper look later!

I did a quick test of the game. The game itself if very simple but taking into consideration that it was done during a game jam in less than 48h then the result is quite impressive.

Good job!

A bit late to the topic but I thought I'd throw out my two cents being an eternal newbie.

This is at first glance a weird niche. Not "easy" enough for the NES Maker crowd and not advanced enough for the asm crowd.

Your target level of end user needs a pre-configured IDE. Maybe NESICIDE will be a good fit?
https://knob.phreneticappsllc.com/nesicide/

Hello, and thanks for taking the time to take a look and make suggestions!

I have to admit; it had been a very long time since I last looked at nesicide... it really didn't seem applicable to this kind of project way back, and I didn't realize it was still being actively developed. From a quick look it has evolved a lot, and honestly would have been a good fit for this project if I'd used it from the start. It seems powerful and somewhat easy to pick up for many tasks.


Unfortunately, it doesn't seem trivial to switch to it this late in the game - there is a lot baked into my makefile and the various guide chapters that would take significant effort to convert over. I could probably do it, but I have to admit I don't want to spend the time, as a consumer of the kit. Setting up the tools isn't quite as smooth as I'd like, but I don't feel it's disastrous, either. I also think they work pretty well together once you have everything installed. There isn't much configuration needed; VS Code's workspace settings help a lot. (That said, I'm extremely biased as the developer, and welcome other opinions!)

There are a lot of tradeoffs involved, and I am not sure yet if they are worth it.

-----

So far, here's a list of pros/cons I can see to such a change:

Pros

• Lowered barrier of entry
• No need to install or configure famitracker
• Reduced requirements of unix tools (make mainly)
• Some elements from tools zip can be removed
• Built in emulator and debugger seem nice from a quick glance (wasn't able to get it working with a non-trivial project yet though)

Cons

• Nesicide is a bit crashy on my machine (may be a configuration issue on my end) - I have hit multiple instances where it stops responding to all clicks and I have to force kill it.
• Nesicide requires GnuWin32 and wget; need to provide instructions for those prior to install of ide
• Graphics editing tools are powerful, but quite unclear to a newcomer. (The tool I use today kinda forces your hand a little harder, which I found actually helped educate me. Would be curious how others feel)
• SFX Editing is a bit less intuitive, since with the current setup you would have to add a new "music" file. (Minor)
• Build process becomes a bit less transparent/more complex with the loss of the makefile
• Lose built-in git controls (and other minor features, like styles) from VS Code

Unknown/Other Notes

• Don't know how to set up map conversion and similar utilities
• Unknown amount of effort detailing how to switch rom/mapper types
• How's the accuracy of the built-in emulator?
• Nesicide's default C project doesn't compile
• New version of cc65 built into nesicide? What updates are required to deal with this? (Note: I've been meaning to make this move anyway)
• Famitracker is almost more confusing in this setup, since you have full control of a music file/etc, and it isn't really clear where it's hooked in. Still need to manually run exports, etc, which may not be as clear when the editor is built in. (Unless this can be automated through nesicide, which it maybe can.)
• There's a lot more I haven't detailed here; both pros and cons I'm sure. This is a very big change!

-----

The short version

This seems like it could help the project, however right now I am unsure if the benefits outweigh the cost of the change, and the potential loss in functionality. I still need to toy with nesicide a lot more to figure out how to use it to its full potential, either way. Thank you for raising this idea!

(ps: If anyone has actually set up nes-starter-kit and tried to use it per the guide, or even tried to set it up and failed, I really want to hear from you! No one has directly told me they have tried to use this and provided feedback yet.)

I appreciate the consideration (and detailed post).

It might take awhile but I'll attempt to go through your process for installing and configuring Visual Studio.

Any chance I can get reproduction steps or a sample project or something to try to reproduce your issue? What is your machine specs?

GnuWin32 comes with the package. wget is only required to *build* nesicide from source as it fetches the dependencies tarball.

I would appreciate any ideas on what is unclear and how to make it clearer.

SFX editing isn't supported yet. Only integrated Famitracker. I haven't come up with a useful UI for creating effects. I intended something similar to Garry Kitchen's Game Maker for C=64's Sound Maker.

This is evidence of the battle for control. Newcomers generally don't want to have to worry about makefile details. Experts don't want to be completely cut off from manual makefile modification.

Sounds like a job for libGitWrap.

Not sure how I can help with these?

Fairly good, though not perfect. I was on a test passing binge for quite a while.

What errors?

I am *intending* to make the music import process seamless but haven't got there yet. For example, when you build your project it would export the music files and include them in the build automatically.

I am interested in helping out if I can as this is ultimately the goal I'd had in mind at the beginning -- a full featured tutorial project that would teach newcomers. Rather than a blank slate "do what you want and oh by the way here's some minimal (no offense, tepples) examples.

I'll be happy to have that discussion in a topic about nesicide, however I would prefer keep this topic about nes-starter-kit. I don't currently have plans to move IDEs. Feel free to post a link for anyone interested, though. (And to remind me to post!)

Thanks for the detail you added. One semi-relevant clarification I'll provide: The stuff in Unknown/Other is stuff I would need to look into if I decided to pursue this effort further. I time-boxed my investigation, and those are questions I did not get to answering for myself.