NDS/Tutorials Day 1
From Dev-Scene
Contents |
[edit] Introduction (feel free to skip this)
[edit] Me:(Dovoto)
I feel it is important to introduce myself before we begin so you understand where I am coming from, where my biases might lie, and most importantly what my limitations are. From this understanding I hope you can look at whatever follows with a critical eye and understand the reason I do things the way I do. If you do so, you will be better prepared to adapt these things to your own projects and abandon them completely when necessary.
I am not quite formally trained in programming. I have taken a few classes and will likely even have a degree in the matter by the time you read this (I am newly a senior at Oregon State University in Electrical Engineering and Computer Science and will be complete in spring of 2007). I am mainly self-taught and as such have many bad habits, most of which I am not even aware of. My approach to most problems tends to be functional and practical more so than procedural, because of this many of my methodologies do not scale well to large problems.
I have done some small work as a game programmer but none of note and I have several years of professional experience doing non game programming (which is why many of my tools are written for the .NET platform).
I don’t much care for PC programming nor PCs in general and use them mostly as tools for developing my console applications. For the most part I just want my PC to work without my having to know the details and thus I prefer Windows to Linux. I will cover setup on Linux systems as I am not completely inept in that regard but I will not be able to answer many Linux specific questions.
Perhaps the only real credentials I have is that in the past my tutorials have been well received, and I wrote a good portion of the library (libnds) that most people are using for homebrew on the DS.
[edit] Who Should Read This?
This tutorial is geared towards people with a moderate understanding of the C language. This is the only assumption made. These tutorials should prove beneficial to anyone interested in starting game programming and even to those just learning C.
My approach is from the hardware out, and although we will develop some useful code along the way, it is not the intention to produce an API or library for game programming.
[edit] Requirements
- A PC (just about any will do)
- devkitPRO(Use the automated installer here: http://goo.gl/0KIMC)
- A Nintendo DS with a flashcart like Supercard DSTWO: http://supercard.sc
OR
- You can get away with just an emulator
[edit] Why The Nintendo DS?
There are many reasons the DS makes a great game development platform for amateur developers. The first is its amazing array of features. Dual screens, dual processors, touch screen, microphone, wifi, powerful 2D graphics engine (two of them actually), wonderful 3D hardware that is limited in performance but rich in abilities. So many things for homebrew developers to explore make programming the DS very satisfying.
Although one could argue that a PC also has these features, the DS has them all standard. You know exactly which hardware you are going to be developing for and a direct channel to it (no silly operating system always trying to get in the way). And let’s face it; it is much cooler to show a friend some code you have running on your handheld Nintendo DS than on some computer screen.
Another reason the DS is a viable platform for us is the homebrew compiler tools and libraries are solid, well-maintained, and very easy to setup. Development on the DS is now nearly as simple as development on a PC thanks to people like Dave Murphy.
[edit] Bit o' History
Darkfader, Joat, Sgstair, WinterMute, Firefly, Passthrough -> passme -> datel, ndslib -> libnds. Flashme, wifime, WMB
[edit] What You Need To Know
C or C++ experience would be very beneficial as would any PC game programming knowledge. Some might disagree, but the DS console is a great place to learn game programming, even if your only experience is with a few lines of QBasic code or a Java class in high school. If you have never written C/C++ code before you may want to look about for a few Internet tutorials or a decent C book before adventuring into the console programming world.
If you don’t know C and don’t feel like finding a good book or taking a class then I urge you to at least wander over to Beej's Guide to C Programming and give yourself a few days with it. Play around a bit and write some code. Don’t get discouraged if you don’t get it all… it takes a number of years to get really good with C, but if you find yourself hating the process then perhaps you should look for other hobbies.
[edit] Installation Of Tools
[edit] For windows
You will need a compiler toolchain to build your DS applications. You will want a C/C++ compiler, a linker, libraries, and header files as well. The compiler package – a custom build of GCC — is maintained by Dave Murphy and can be found at http://www.devkitpro.org.
On this site you will find a devkitPro package for Windows, Linux, and OSX that contains not only the compilers but also the homebrew header files, libraries, and examples you will need/want. These may come in separate packages for Linux and OSX.
Installation is a snap. If you are on Windows (preferably Windows 2000 or newer) you simply need to run the installer. On Linux or OSX just follow the guide (this involves unzipping the package to a folder of your choice and setting 2 or 3 environment variables). Dave does a much better job explaining the installation than I could so follow his setup instructions.
DevkitPro.org also has a FAQ section which addresses any issues you might encounter as well as how to integrate the toolchain with programming environments such as Visual Studio and Eclipse. For the remainder I will assume you have followed the instructions on that site and have a similar directory structure to the one below:
Be sure to select the examples for download if you are on Windows or grab the examples package directly from the site (it currently says “GBA examples” in the description but actually contains examples for all devkitPro platforms) on SourceForge.net.
My examples are placed in C:\devkitpro but you can place them anywhere as long as there are no spaces in the path (so no expanding them on your Desktop and expecting them to work). You'll want the examples if you want to investigate anything beyond the scope of this tutorial, or if you need the whole thing already coded for you if you're running into problems.
[edit] For Mac OS X
I want to give credit to CoderJoe.net for most of this installation. This setup is for command line users, so I recommend you get comfortable with using Terminal.
Step 1) Get the compiler. You need to be able to compile with the MAKE command. Download and install xcode from APPLE. This should be free once you sign up as a developer.
Step 2) Download the installation files. Get the following files at soureforge.net and download them to your home directory. You will need devkitARM, libnds, default_arm7, and the NDS examples (optional)
Step 4) Open Terminal. The Terminal can be found by opening your Finder/Applications/Utilities.
Step 5) Setting up a development path. We will be installing most of your downloaded files to /usr/local/devkitPRO/. Type in the following below and your system password:
sudo mkdir /usr/local/devkitPRO
Step 6) Install the devkitPro binaries. Assuming you’ve downloaded the devkitARM archive to your home directory, this can be accomplished by changing to the devkitPRO directory you’ve just created and running. You may have to adjust the file name to match the version you've downloaded.
cd /usr/local/devkitPRO/ tar -xjvf ~/devkitARM_r24-osx.tar.bz2
the devkitARM tar.bz2 contains a root directory called devkitARM which when compressed will contain the toolchain and a series of helpful binaries located within its “bin” directory.
Step 7) Decompress the libnds source. Next we will decompress libnds. Unlike the devkitARM archive, libnds does not contain it’s own base directory, so we should create one for it now, and decompress to that directory. Again you may have to adjust the file name to match the version you've downloaded.
sudo mkdir /usr/local/devkitPRO/libnds cd /usr/local/devkitPRO/libnds tar -xjvf ~/libnds-1.3.1.tar.bz2
Now you have the source and tool chain necessary to build libnds into a fully fledged library for your linking pleasure.
Step 8) Set some environment variables. We need to set up some environment variables so the makefiles know where the tool chain and other libraries live.
First we need to set the DEVKITPRO variable to point to our devkitPRO install directory:
export DEVKITPRO=/usr/local/devkitPRO
Then we need to set DEVKITARM to point to our devkitARM install location
export DEVKITARM=${DEVKITPRO}/devkitARM
To make things easier, I recommend added the following three lines to the bottom of your ~/.bash_profile file so every interactive shell would have access to these environment variables. Use your favorite text editor and create a file called .bash_profile in your home directory, such as "nano ~/.bash_profile"
#Set Variables for DEVKIT_PRO
export DEVKITPRO=/usr/local/devkitPRO
export DEVKITARM=${DEVKITPRO}/devkitARM
To exit nano, hit control+x and save. You can logout and log back in to load your bash_profile, or just type the following:
source ~/.bash_profile
Step 9) Decompress default_arm7. You will need this to compile the NDS examples. Type in the follow and adjust the file to match your version.
cd /usr/local/devkitPRO/libnds tar -xjvf ~/default_arm7-20081210.tar.bz2
Congratulations, you now have a successfully built Nintendo DS development tool chain and libraries.
If you’d like to test your toolchain you can extract the example source tarball that I suggested you download in the previous tutorial, and type make in it’s root directory. If everything is correctly set up, it should create a Nintendo DS ROM for each example in the examples directory.
The examples may not make much sense now, but make sure to poke around the examples. They’re one of the most useful resources a Nintendo DS homebrew developer has at his or her disposal.
[edit] Setting Up An IDE
An IDE is an integrated development environment and there are many to choose from. They allow you to write, compile and test code as well as manage your project files from a single interface.
Creating an executable on the NDS is not exactly straight forward. As it has two processors, you actually need one binary for each and these need to be assembled into a standard file format. Fortunately DevkitARM and WinterMute have made this process rather painless with a couple of tools and a very flexible makefile template.
The only IDE I am going to recommend and spend any time on is Visual Studio Express. It is free, awesome, and integrates easily with devkitPro. I recommend you read Dave Murphy's guide here on how to set it up. These instructions work equally well for the full version of Visual Studio and in the FAQ section of the site there are instructions on setting up other IDEs.
DevkitPro also has Programmer’s Notepad packaged as a small and easy to use IDE if you are afraid of the monster download of Visual Studio Express.
You'll get a better experience from Visual Studio if you add the paths for the libnds header files to your C++ directories. This will make IntelliSense work (to some extent) with libnds. These options are located under Tools -> Options -> Projects and Solutions -> VC++ Directories and the libnds headers are found in path/to/devkitPro/libnds/include - that's C:\devkitPro\libnds\include if you used the installer's default path.
I will assume for the remainder that you were too lazy to actually stop and do any of this setup and are in fact doing your development in Notepad.
[edit] Building A Demo And Testing The Installation
devkitPro supplies about 30 examples with devkitARM that demonstrate how to use the tools and do certain things on the hardware. To test your installation of the toolchain navigate to one of the example folders in a terminal or DOS window and type make.
If you are using something other than Windows you may need to grab these examples as a separate download.
If you get no errors you will have a .nds file in the root directory (if you do encounter errors check the FAQ section of http://www.devkitpro.org and feel free to post your issues on http://forum.gbadev.org as well). You can run this .nds file on an emulator or directly on a Nintendo DS.
[edit] Emulators
You will want an emulator which can run your DS executable on your PC. This is a requirement if you do not have a DS or have not made the necessary arrangements to run code on it yet.
[edit] A Few Good Emulators
Dualis http://dualis.1emulation.com/
NO$GBA http://nocash.emubase.de/gba.htm
Dualis is free and slightly more advanced than NO$GBA. But the $15 homebrew version of NO$GBA has some very impressive and incredibly useful debugging features. I recommend you grab Dualis and if you get serious about homebrew you can grab NO$GBA another time.
You can find more DS emulators here.
[edit] Running The Demo On Hardware
Most of the fun in developing on a console is in the ability to run your game or demo on the actual system. The DS (like most consoles) has some security features in place to prevent piracy; unfortunately these measures also hinder running your own applications.
There are two pieces of equipment you will need: A storage device which the DS can access and some tool to convince your DS to run your code.
For storage you have many options but I recommend one of the following:
GBAMP (Gameboy Advanced Movie Player) available from Lik-Sang.com. It is cheap ($25 plus shipping) and uses Compact Flash giving you virtually unlimited storage.
XPORT from http://www.charmedlabs.com. Not cheap ($140 to $200 depending on the model) and does not have a lot of storage (only 4MB) but if you have any desire to do hardware projects (a DS controlled robot comes to mind) this is probably one of the most interesting devices around. It also has the nice advantage of allowing you to program your DS without taking out and putting back in your flash card.
There are other devices available but most are designed specifically to run pirated GBA or DS games and as such are generally overpriced and often even illegal to import. A quick google of “backup” devices for Nintendo DS should give you an idea as to the range of options.
The other tool you need is one which tricks the DS into running your game even though it is not an official DS game. The Passme type devices are quite common.
For comparison check Passme
[edit] First Demo
Our first demo will be a simple one. We will initialize our DS and paint one of the screens a wonderful red color.
First copy the template folder from the examples pack installed with devkitPro. For me the template is installed at C:\devkitpro\examples\nds\templates\arm9 but your installation directory may vary.
Copy the entire arm9 folder to a new directory (one without any spaces in the path in case your OS allows such things). Name the folder something useful like demo1 or some such. Once copied, open main.c in the source folder and delete everything (you can do this in any text editor). Then type the following:
#include <nds.h> #include <stdio.h> int main(void) { int i; consoleDemoInit(); videoSetMode(MODE_FB0); vramSetBankA(VRAM_A_LCD); printf("Hello World!\n"); printf("www.Drunkencoders.com"); for(i = 0; i < 256 * 192; i++) VRAM_A[i] = RGB15(31,0,0); while(1){ swiWaitForVBlank(); } return 0; }
Alternatively you can grab the tutorial source file which contains the demo1 source code and a pre-built binary from here.
I am not going to go into detail on the workings of this code just yet but a brief description is as follows:
The first real line of code (consoleDemoInit()) initializes the console (DOS-like) functionality in the library so printf will print text to one screen. Printing is the most complicated thing this demo is doing by far.
Next we set the video mode of the DS. The DS has many video modes with differing uses, all of which will be covered as we go along. For now, just realize that we are putting the DS into frame buffer mode. What this is and how it works will be the subject of much of the next chapter.
The DS has a very flexible video system that allows memory to be assigned to many locations and for many purposes. The next line of code just assigns the first bank of video memory to the LCD. This both unlocks the memory for easy writing and allows the DS to use it as the direct display memory.
The next lines print the infamous hello world.
Finally we write the color data (red in this case) to video memory. Because the screen is 256*192 we loop through each pixel and set its color to red.
VRAM_A is a pointer to the video memory bank A. RGB15 converts the color value to a 15-bit value the DS can understand (more on how color works in the next chapter).
To build this code simply type make from a DOS prompt or terminal window while in the demo1 directory. Enjoy your achievement by launching it on an emulator or trying it out on hardware.
Okay, once you figure all that out, head over to NDS Tutorials Day 2 and learn about the capabilities of the DS hardware.