Overview

This repository contains an annotated disassembly of the Super C (US) NES ROM and the build script(s) to reassemble the assembly into a byte-for-byte match of the game. Super C is the sequel to the Contra video game for the NES. This repo also contains supplemental documentation, scripts, and tools to further understand the game.

For the disassembly of Contra see https://github.com/vermiceli/nes-contra-us/

|-- docs - supplemental documentation
|   |-- images - files used in other documentation
|   |-- debugging - files used to help debugging
|   |-- lua_scripts - lua scripts for mesen2
|   |-- sprite_library - extracted sprites for ease of viewing
|-- src - the source code for the game
|   |-- assets - the compressed graphics data and encoded audio for the game
|-- assets.txt - a list of assets, their offset in baserom.nes and their length
|-- build.bat - build script for Windows cmd (no PowerShell)
|-- build.ps1 - recommended build script for Windows (PowerShell)
|-- build.sh - bash build script for Linux/mac
|-- superc.cfg - memory mapping of banks used when building
|-- README.md
|-- set_bytes.vbs - script used by build.bat to extract data from baserom.nes

Building

In addition to Super C (US), this repo can also build the Probotector II: Return of the Evil Forces (PAL) rom. To keep instructions simple, the section below only contains instructions for building Super C (US).

If you are interested in building a Probotector rom file, first read this section to understand what is needed, then follow the instructions in the section titled Probotector.

Prerequisites

• This repo does not include the assets (graphics data and audio data) necessary for assembling the ROM. An existing copy of the game is required. Place a copy of the US NES version of Super C with the name baserom.nes in the project root folder. The file will be used by the build script to extract the necessary assets. To confirm you have the correct ROM of the game, you can look at the ROM file's hash. The MD5 hash of baserom.nes ROM should be one of the following. The difference in ROM hashes come from the fact that there is a single ignored bit in the iNES header that can be either set or not set and does not impact the game.
  • 5FEF80625F484FCA06FDB58EBFF9D8BB
  • 78F97D58AF93493976E810D02B40FA30
• Building requires the cc65 compiler suite to assemble and link the 6502 assembly files. Please install it and ensure the bin folder is added to your path.

Instructions

There are 3 build scripts in this repository. All of them do the same thing. To build the resulting .nes rom file, simply execute the appropriate build script based on your environment.

Environment	Command
Windows	.\build.ps1
Windows (no PowerShell)	.\build.bat
Mac/Unix/Linux	./build.sh

• build.ps1 - PowerShell script recommended for building on Windows machines. Some users have reported needing to run the script as admin to access the baserom.nes, although I haven't experienced this. Additionally, on older versions of PowerShell, you may need to adjust the execution policy with the command Set-ExecutionPolicy.
• build.bat - bat script that can be used on windows machines without PowerShell, but requires VBScript support.
• build.sh - bash script to be used in unix environments, or on Windows environments with bash support (Git bash, WSL, etc.)

Video Instructions

If you prefer video build instructions, @jdsilva has published a video on YouTube called Contra ROM Compiling Tutorial. While it goes over how to build Contra, building Super C is virtually identical.

Documentation

Supplemental materials have been added that help explain interesting features of the code. Below are some of the more important documents.

• docs/Banks.md - details about how Super C banks the PRG ROM and CHR ROM data.
• docs/Bugs.md - bugs identified while disassembling
• docs/Enemy Glossary.md - documentation on every enemy type in the game
• docs/Graphics Documentation.md - documentation on how graphics are written to the PPU.
• docs/ROM Map.md - detailed description of ROM file contents
• docs/Sound Documentation.md - documentation on the audio engine used as well as information on all sounds from the game.

All sprites were captured and labeled for easy reference in docs/sprite_library/README.md

Debugging

One of the biggest advantages of building this rom is that the build scripts also build the debugging symbols. Debugging symbols can be read by emulators and be included in the source view while debugging the game. For example, Mesen will automatically load the debugging symbols as long as the superc.dbg file exists in the same folder as superc.nes. Below is a screenshot of what debugging looks like with symbols.

You can see that the debugging symbols file points to the source code to include comments and labels. If you move or delete the source files, you will lose all the debugging information.

FCEUX NameList

FCEUX doesn't support reading the debugger symbols, but you can load NameList (.nl) files. These files aren't as fully featured as the debugging symbols file, but does at least allow you to label jump/branch locations and ram addresses. It doesn't easily support comments on individual lines.

I've included the .nl files in docs/debugging/fceux_namelists for both Super C and Probotector. These files were generated from the -m superc.txt -vm command line parameter to ld65. Then the that file was converted to the .nl files with a custom script. I can't promise to keep these up to date as the source labels change, but I will try to.

Probotector

This repo can also produce a Probotector II: Return of the Evil Forces rom file. Probotector is the PAL-specific variation of the Super C (US) game. It is mostly identical except for different graphics. For a full list of differences, see the document docs/Probotector.md.

Building

First read the section above for building Contra (US) in general. The process is very similar. Place a Probotector rom in the root folder with the name baserom.nes. The MD5 hash of baserom.nes ROM should be one of the following. The difference in ROM hashes come from the fact that there is a single ignored bit in the iNES header that can be either set or not set and does not impact the game.

• 917166C2ED0E3316255A57C81DC38ABC
• E56233E54F4C497B0D03AFB36D544414

Then, depending on your environment, run one of the following commands.

Environment	Command
Windows	.\build.ps1 -Game Probotector
Windows (no PowerShell)	.\build.bat Probotector
Mac/Unix/Linux	./build.sh Probotector

Notes of caution, especially for people building both Super C (US) and Probotector.

1. Be sure you have the correct baserom.nes for the game you are building. Otherwise, the generated rom will be incorrect.
2. If you have Contra (US) assets in the /src/assets/ folder and are building Probotector, or vice versa, the build scripts will delete the graphic asset data and re-extract it from the baserom.nes. This prevents accidentally using the wrong game's assets in the result rom.