Table of Contents

1. Introduction

2. Setting up a Debian VM

3. Setting up a NES Build Environment

3d. Compiling games

4. Setting up for specific game Dev

 

1. Introduction

When it comes to NES Development, most of Mega Cat's Developers use the CC65 C compiler. For such a build environment, developers can either use the compiler on Windows or Linux. Compiling a game with Linux is much easier, since compiling C code with Linux's "make" command is built right into the OS.

This guide is a tutorial showing the reader how to set up a Debian Stretch Linux Distro within a Virtual Box VM. This guide will also show how to set up a CC65 NES Dev environment for both. Although there are more fully-fledged Linux distros out there, this guide will be using Debian Stretch (based off Raspberry Pi's Raspbian) in VM.

Note: The writer of this guide is acquainted with setting up Raspbian for NES Dev, and is using this OS to create a unified installation experience between people developing on Raspberry Pi and on PC through VM.

2. Setting up a Debian Stretch VM

To begin setting up our build environment for NES Dev, we are first going to set up VirtualBox Software, and then install Debian Stretch on it. VirtualBox is virtualization software, which can run virtual OSes from a virtual hard drive. Your computer's host OS will stay intact, but will be able to run the guest OS as a separate, hypervised application.

2a. Enabling HAV

Before we install VirtualBox, we will enable HAV (Hardware-Assisted Virtualization) if your host machine has the ability. If your machine and CPU allow such features, these settings will allow the virtualization to be assisted and sped up by hardware processes, making the virtualization run faster and smoother. These settings usually go by the name of "Virtualization Technology (VTx)" or "Virtualization Technology for Directed I/O", and may be found in your system's BIOS settings. Consult your machine's user manual about if it supports these features, and where to find them in the BIOS. The BIOS settings can usually be accessed by pressing F1, F5, F8, or Esc on the boot of most computers.

For the machine used in this tutorial (an HP EliteBook 8570w laptop) and for most HP computers, the settings can be found and toggled as such:

• Boot up the computer
• Press ESC when the HP logo appears on boot
• Press F10, "BIOS Settings"
• Press right arrow key to go to "System Configuration" Tab
• Press down arrow key to go to "Device Configurations"
• Scroll down with the down arrow key and click the checkboxes
• Virtualization Technology (VTx)
• Virtualization Technology for Directed I/O
• Exit the menus and save changes

2b. Installing Virtual Box

With HAV enabled (if available), you should now install VirtualBox. It can be downloaded and installed from virtualbox.org. On the "Downloads" page, you should download a "Windows hosts" package, as well as the Extension Pack. The Extension Pack will allow you to plug in USB 2.0/3.0 media and devices (Flash Drives etc), which will be useful if you need to shuffle files between your virtual OS and a real one for sharing of files.

After double-clicking the installer. Select the features you will want to be installed and where to install VirtualBox. It is recommended installing all features except Python support (you may want networking support if you want to connect to Slack through the browser or research on Google).

Afterward, select your shortcut preferences and install the software

2c. Installing Debian Stretch

Now that we have VirtualBox installed, we will download and install a Debian Stretch ISO image. This is the image that VirtualBox will boot when installing Debian Stretch to a Virtual guest OS.

• Download the DVD ISO image from here.
• Boot up VirtualBox; Click Machine>New
• Setup VM Stats
• Name of VM
• Type of OS (Linux)
• The version of OS (Debian 32-bit)
• Setup Memory usage
• Use recommend 1024MB (1GB)
  

• Setup Hard Disk
• Create a Virtual Hard Disk now
• Set Hard Disk type to VHD
• Set Storage Type to "Dynamically Allocated"
  Set the size and location of the VHD (4-8GB should be sufficient)

• Configure settings for VM
• Right Click VM>Settings
• System
• Motherboard
• Uncheck "Floppy" from Boot Order
• Set Pointing Device to PS/2 Mouse
• Processor
• Select how many processors cores to use (recommended 1 core)
• Acceleration
• Enable Default Paravirtulization Interface
• If supported and enabled in BIOS
• Enable VT-x/AMD-V
• Enable Nested Paging

• Display
• Screen
• Video Memory amount
• Default (16MB) should work
• Enable 2D Video Acceleration
• (if supported by host graphics hardware

• Storage
• Select the Empty CD icon
• CD icon>Virtual Optical Disc File> ISO file we downloaded

• Click OK once done
• Double Click VM to launch
• It should launch
• Select "Install"
• Linux shall setup and boot. Follow the installation instructions, and use default settings if not sure what options to select. Also, select the "American English" keyboard if you are using one.
• On the next boot, make sure to unmount the ISO file!
  Otherwise, setup will run again.

3. Setting up a NES Build Environment

Now that the Debian Stretch VM has been launched, the user should set up the VM for usage in NES development.

3a. Installing CC65

To begin NES development within Linux, the user needs to install the CC65 C dev toolchain, so that he can compile NES builds as needed. This installation is based on this guide for Linux.

Installation instructions

• Open up the terminal from the desktop (the black icon with ">_" text on it)
• Follow these instructions to build from Git.
• Make sure to use the proper text case; everything in Linux is case-sensitive!
• Input the correct character for tilde and double quotes (~ vs. ¬ and " vs. @).
• Tilde (~) may be mapped to backslash and double quotes (") to Number 2

3b. Installing Git-Cola

Next, the user should install Git Cola, which is a GUI-based tool for handling Git repositories. It will be needed for synchronizing changes to/from the local/remote Github repositories used in your projects.

To install Git-Cola, open up the Terminal, and run the following commands:

sudo apt install git-cola

If a Yes/No prompt appears, type "Y" (Yes). After installation of the Linux package, you shall be able to find the application under the "Programming" category on the Raspberry Pi Start Menu. Click "Git Cola" to launch the application.

Upon the first launch, you will need to Clone the repository from the Remote. Type in the URL to the remote repository, and then select a folder to place the local copy. Type in your Github username and password if necessary to access any private repositories

Afterward, the repository should be cloned locally, and you can begin using source control functionality. Please see this guide for the basics of using Git-Cola within Linux.

3c. Installing FCEUX

When developing NES games, it is important to test your games, both on real hardware and on emulators. It is recommended to use emulators for iterative development, and especially important to test on real hardware when reaching important milestones in game development. Sometimes code will run differently on real hardware vs. emulators.

To test compiled builds quickly on the same Linux machine, you should install an emulator. We recommend FCEUX. To install FCEUX, type the following into the terminal:

sudo apt install fceux

If a Yes/No prompt appears again, type "Y" (yes). Like earlier, the FCEUX application will appear in the "Games" category for the Raspberry Pi Start Menu. FCEUX has essentially the same functionality as on Windows.

3d. Compiling games

You should now how everything you need for NES development on Linux! If you are not familiar with the command prompt at all, or with Linux Terminal, please read up on the most important commands. Use the "cd" command to navigate to the local repository of your game. In Linux, directories are handled via forward slashes ("/"), not backslashes ("\").

To build a game, simply type "make" at the root of the local repository. To clean the project, type "rm .o", which will remove all object files. To clear the terminal screen of text, type "clear". To take screenshots, and save files at the current directory, type "scrot" in the Terminal. If the project has no syntax or other errors, the game ([gamename].nes) shall appear in the root folder. That is all there is to it to compiling NES games on Linux!

4. Setting up for Specific Game Dev

Here are some notes about compiling for certain Mega Cat games currently in development.

4a. In Cod we Trust

In Cod We Trust utilizes TilED for creating levels. Fortunately, TilED is multiplatform and runs on Linux. Once levels are designed and saved in their native format (.tmx), the file will need to be converted into something the game will understand. The developer has created a few Python scripts for this (tmx2asm). Luckily, Python is included and pre-installed on Debian Stretch/Raspberry Pi.

4b. Installing TilED

In order to install TilED, simply type the following into the terminal

sudo apt install tiled

The application shall appear under the "Graphics" category in the Raspberry Pi Start Menu. It has the same functionality as on Windows.

4c. Using TMX2ASM

To use TMX2ASM, simply type in the following into Terminal. tmx2asm.py script is located in "bin/tmx2asm/" folder. Since Python is pre-installed on Debian Stretch, usage is out-of-the-box.

python path/to/tmx2asm.py inputfile.tmx outputfile.asm