# **NES Boilerplate Game** A NES game that serves as a base for starting a new NES project. ----------------- - [**Features**](#features) - [**Prerequisite**](#prerequisite) - [**Project configuration**](#project-configuration) - [**Source configuration**](#source-configuration) - [**Makefile configuration**](#makefile-configuration) - [**FamiStudio configuration**](#famistudio-configuration) - [**Building the game**](#building-the-game) - [**Running 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 () - Some defined constant (PPU, APU, etc.). - Compile the game with the MMC5 mapper. () 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: ### **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: ### **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: #### **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: #### **YY-CHR** YY-CHR is an editor that you can use to edit the background and sprites in your CHR of your game: #### **FamiStudio** If you want sound and music in your game, you can use the FamiStudio NES Music Editor: 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: ```ca65 .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: ```ca65 ... .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: ```make CC65 = cc65/bin/cc65.exe ``` - **CA65**: *(Required)* Location of the ca65 assembler executable. Example: ```make CA65 = cc65/bin/ca65.exe ``` - **LD65**: *(Required)* Location of the ld65 linker executable. Example: ```make LD65 = cc65/bin/ld65.exe ``` - **NESLIB**: *(Required for C programming)* Location of the NES library of cc65. Example: ```make NESLIB = cc65/lib/nes.lib ``` - **ASMINC**: *(Required for C programming)* Location of the assembly include folder of cc65. Example: ```make ASMINC = cc65/asminc ``` - **EMULATOR**: *(Optional but recommended)* Location of the NES emulator. Example: ```make EMULATOR = Mesen/Mesen.exe ``` - **HEXDUMP**: *(Optional)* Location of the Hexdump program. Example: ```make HEXDUMP = hexdump.exe ``` - **GAME_NAME**: *(Required)* Name of the game. Example: ```make GAME_NAME = my_game_name ``` - **INC**: *(Required for C programming)* Include folder where all the header files (.h) are located. Example: ```make INC = inc ``` - **SRC**: *(Required for C programming)* Source folder where all the source files (.c) are located. Example: ```make SRC = src ``` - **BIN**: *(Required)* Output folder where all the (temporary) binary files will be generated. Example: ```make BIN = bin ``` - **ASM**: *(Required)* Assembly folder where all the assembly files are located. Example: ```make 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: ```make 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: ```make 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: 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: ```console 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: ```console 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: ```console make -s run_a ``` or this one to run the game made with C code: ```console make -s run_c ``` ## **Other** ### **Cleaning** You can remove all binary generated files by running: ```console make -s clean ``` You can remove all the files that have been generated by running: ```console make -s clean_all ``` ### **NES to Hex** You can convert the NES game into a text file written in hexadecimal: ```console make -s hex ```