NES Boilerplate Game

A NES game that serves as a base for starting a new NES project.

---

• Features
• Prerequisite
• Project configuration
  • Source configuration
  • Makefile configuration
  • FamiStudio configuration
• Building the game
• Running the game

---

Features

This project has/can:

• Compile the game from assembly code.
• Compile the game from c code.
• A reset handler that reset memory to 0 and call the main function.
• A general NMI handler to draw stuff on the screen.
• An IRQ handler (that does nothing, but we need one).
• Support for the FamiStudio Sound Engine (https://famistudio.org)
• Some defined constant (PPU, APU, etc.).
• Compile the game with the MMC5 mapper. (https://www.nesdev.org/wiki/MMC5)

Note: This project has by default 32K of PRG and 8K of CHR.

---

Prerequisite

CC65

You will need to have CC65 and the files that comes with it. It can be downloaded here: https://cc65.github.io

Emulator

You theoretically don't need a NES emulator, but unless your developing on hardware without testing on software (why ?), I recommend the Mesen emulator because of these debugging features: https://www.mesen.ca

Other (Optional)

NesDev Wiki

In case you don't know this website exist, it is THE most useful website about how to program on the NES and many other things: https://wiki.nesdev.org

Text Editor

Choose any software you want to write your code, I personally like VS Code because of the syntax highlight and error checking, but use what you are comfortable with.

Hexdump

You can download "Hexdump for Windows" if you need to output files in hexadecimal: https://www.di-mgt.com.au/hexdump-for-windows.html

YY-CHR

YY-CHR is an editor that you can use to edit the background and sprites in your CHR of your game: https://w.atwiki.jp/yychr

FamiStudio

If you want sound and music in your game, you can use the FamiStudio NES Music Editor: https://famistudio.org

It is the most user-friendly music software for the NES that I have found (from a composing and a programming point of view).

---

Project configuration

Before you start making your game, you will need to set some value in the source files and the Makefile.

Source configuration

To configure the sources files, you must:

1. Rename the default .CHR file to your_game_name.chr.

2. Replace the value of the first line in the file asm/constant.asm to your_game_name.chr. Example:

   .define GAME_CHR "my_game_name.chr"
   

3. Rename the .cfg file to your_game_name.cfg.

4. (Optional) If you want to use the MMC5 mapper, rename the mmc5 .cfg file to your_game_name_mmc5.cfg. It must end with _mmc5.cfg.

5. (Optional) get the FamiStudio Sound Engine

   1. Place the famistudio_ca65.s file in asm/audio/ Note: if you are coding in C, you should include famistudio_cc65.h somewhere in your include folder
   2. in the crt0.asm in the FamiStudio section, include your music files. Example:

   ...
   .if FAMISTUDIO=1
       ...
   
       ; Musics
       .include "audio/music/my_music.s"
   
   .endif
   ...
   

Makefile configuration

You will need to indicate to the Makefile where cc65 and other software programs are located. All value that you can change is at the top of the file.

• CC65: (Required for C programming) Location of the cc65 compiler executable. Example:

  CC65 = cc65/bin/cc65.exe
  

• CA65: (Required) Location of the ca65 assembler executable. Example:

  CA65 = cc65/bin/ca65.exe
  

• LD65: (Required) Location of the ld65 linker executable. Example:

  LD65 = cc65/bin/ld65.exe
  

• NESLIB: (Required for C programming) Location of the NES library of cc65. Example:

  NESLIB = cc65/lib/nes.lib
  

• ASMINC: (Required for C programming) Location of the assembly include folder of cc65. Example:

  ASMINC = cc65/asminc
  

• EMULATOR: (Optional but recommended) Location of the NES emulator. Example:

  EMULATOR = Mesen/Mesen.exe
  

• HEXDUMP: (Optional) Location of the Hexdump program. Example:

  HEXDUMP = hexdump.exe
  

• GAME_NAME: (Required) Name of the game. Example:

  GAME_NAME = my_game_name
  

• INC: (Required for C programming) Include folder where all the header files (.h) are located. Example:

  INC = inc
  

• SRC: (Required for C programming) Source folder where all the source files (.c) are located. Example:

  SRC = src
  

• BIN: (Required) Output folder where all the (temporary) binary files will be generated. Example:

  BIN = bin
  

• ASM: (Required) Assembly folder where all the assembly files are located. Example:

  ASM = asm
  

• FAMISTUDIO: (Required) Tell the Makefile if you want to include FamiStudio in your game. 1 is for "Yes" and 0 is for "No". Example:

  FAMISTUDIO = 1
  

• MMC5: (Required) If you want to use the MMC5 mapper for your game, set this to 1, otherwise set it to 0. Example:

  MMC5 = 0
  

FamiStudio configuration

You can configure the engine by editing asm/audio/famistudio_config.asm. If you need help, you can check the FamiStudio documentation: https://famistudio.org/doc/soundengine

Note: The 'FAMISTUDIO_EXP_MMC5' option is configured correctly by default. You do not need to change it

Building the game

Note: make sure that you have correctly set up the Makefile and source files.

From Assembler code

Your code will need to start in the MAIN subroutine. It is located by default in asm/main.asm You can remove the default code. It is only here to see if the game default features works.

You can build the game with this command:

make -s asm

from C code

Your code will need to start in the main() function. It is located by default in src/main.c You can remove the default code. It is only here to see if the game default features works.

You can build the game with this command:

make -s c

---

Running the game

You can just run the .NES file with the emulator of your choice.

You can also use this command to run the game made with assembly code:

make -s run_a

or this one to run the game made with C code:

make -s run_c

Other

Cleaning

You can remove all binary generated files by running:

make -s clean

You can remove all the files that have been generated by running:

make -s clean_all

NES to Hex

You can convert the NES game into a text file written in hexadecimal:

make -s hex