Pandora Porting a simple SDL game to Pandora

[mcobit]

Disclaimer: This is the way I compile software on the Pandora. It may not be the best way, it might not be the simplest solutions, but if you have comments please just post them and I can correct or change parts of this tutorial. You follow this at your own risk. I am not responsible, if you destroy your OS or do anything else to your Pandora!


Porting a simple SDL game to Pandora


The noob way (yes, I am a noob too)


First off, I’d like to state, that I learned all I know about compiling, throwing some lines of code around and packaging, I learned since I have a Pandora.


It all came about, when I, fortunately one of the firsat german pandoraowner, wanted to do something useful for the community.


I worked with creaturexl together on an application for the Pandora and as he wouldn’t get his device anytime soon, he could try his app on my Pandora via ssh. He used screen to let me see, what he did. I learned a lot about symlinks and resolving dependencies.


Later I tried to do something on my own. I packaged up some java-apps with the help of the descriptions on the pandorawiki.


After that I packaged a pythonapp, that worked out of the box on Pandora.


When that was done I thought, that I could try to compile an SDL app. That was Abe’s Amazing Adventure. And this is the app, that this tutorial is about.


Also many thanks to all the people from this community. You really help where you can! Thanks Sebt3, CreatureXL, Paulguy, Skeezix, and everyone else I forgot right now. Thank you very much!


To get started you will need a dev environment. My choice was to use stuckies extends.


In the post he said, that they may be unstable and may cause some bad things, but for me so far it never happend a thing.


So go and download stuckies extend utils. For ease of use you can use the old ones. These are easier, as they only give the option to mount a root or a home extend:

http://www.stuckiegamez.co.uk/apps/pandora/SimpleDev/OldExtendUtils.pnd

Copy it to the pandora/menu folder on a SD card.



Also you need a dev extend. download the one from 18thJune, because as I remember there are some broken packages in the newer one.

Download it here:

http://www.stuckiegamez.co.uk/apps/pandora/SimpleDev/Dev.Extend.18thJune2010.zip

Unzip it to a sd-card. You will get a file named dev.extend.



You will need a home extend too, as the space on the nand is pretty limited:

http://www.stuckiegamez.co.uk/apps/pandora/SimpleDev/1GBExtend.zip

Unzip this one to a sd-card, too. You will get a file named 1gb.extend.



Now it’s time to mount our extends:

Open the menu and select “Extend Root” from the System menu.

You will be asked, which extend you want to mount. Choose the dev.extend file we unzipped earlier. You have to give your root password and then it will tell you, that it will spawn a terminal. When it does so, you can type “gcc” into the terminal window. If it says: “gcc: no input files” The mount was successful.



Now mount your homeextend. Choose “Extend Home” in the system menu and mount your 1gb.extend like you mounted the dev.extend.



FROM NOW ON DON'T REMOVE A SDCARD, THAT CONTAINS THE EXTENDS!!!

BAD THINGS MIGHT HAPPEN IF YOU DO! TO CLEANLY UNMOUNT THEM REBOOT THE PANDORA!



In the terminal, that will pop up at the end you can now cd into your homeextend directory:

cd /tmp/homeExtend

This will be your working directory.



Now the environment is set up. That was easy, wasn’t it?





Now get the source code for the game you want to port. In this example lets download the sources to Abe’s Amazing Advenure. Wget the sources into your /tmp/homeExtend directory with:

wget http://downloads.sourceforge.net/project/abe/abe/abe-1.1/abe-1.1.tar.gz

NOTE: Games, that require OpenGL will not work out of the box! They have to be rewritten or you have to use a wrapper that currently doesn't work on many games!



After the download is finnished, untar the file with

tar xvzf abe-1.1.tar.gz

Now cd into the new directory:

cd abe-1.1

Whe you type ls now you can see all the files, that belong to the game.

To build it we have to create a Makeile first. Fortunately ths is done by the configure script for us.

Run

./autogen.sh

and then

./configure --prefix=/mnt/utmp/abe

Now there will be a couple of checks, that the program does to find all the dependencies for the game and if they are already installed.

"--prefix=/mnt/utmp/abe" means, that the game will be installed into this directory, when it is built.

We have to choose a directory, that will be in /mnt/utmp, as the pnd will mount it there, when it is executed.



The script should finish without errors.

Now type

make

and wait until your game is built for you.



When this finished without errors, we can create the installation dir:

sudo mkdir /mnt/utmp/abe

sudo chmod -R 777 /mnt/utmp/abe

Now we install the game:

make install

As the datafiles are still missing, we need to copy the following directories to the installdirectory:

cp -R images maps sounds /mnt/utmp/abe

Now go to the directory and run your game:

cd /mnt/utmp/abe

./bin/abe

As you can see it already runs pretty well, but the buttons are not mapped to the pandorabuttons. So let’s go back and change that!



Do

cd /tmp/homeExtend/abe-1.1/src

this is the folder, that contains the sourcecode for the executable.



Here edit the files, that contain the keymappings. Let’s begin with the main game:

nano Game.c

(I use Nano, but you can of course use any texteditor you want)



In nano you can press ctrl+w and search for SDLK.

This will set your cursor to the first buttonmapping. Scroll down to find the Line with case SDLK_SPACE. This would trigger the guy to jump in the game.



Before we edit:

The Pandoracontrols are just like keys on a keyboard.

Here are the SDL-keymappings for the Buttons and D-Pad:



A = SDLK_HOME

B = SDLK_END

Y = SDLK_PAGEUP

X = SDLK_PAGEDOWN

L-Shoulder = SDLK_RSHIFT

R-Shoulder = SDLK_RCTRL

START = SDLK_LALT

SELECT = SDLK_LCTRL



D-PAD-Left = SDLK_LEFT

D-PAD-Right = SDLK_RIGHT

D-PAD-Up = SDLK_UP

D-PAD-Down = SDLK_DOWN



This is enough for us to work with.



Now substitute the SDLK_SPACE with SDLK_HOME to make the guy jump, when we press the actionbutton A.



Then there is the balloonfunction, that is currently mapped to SDLK_RETURN.

Change it to SDLK_PAGEUP, as you did for the jumpbutton.



Now press ctrl+x to quit the editor and type y when it asks you to save.



Now we can go through all the sourcefiles and edit the Keys to our liking:

Edit the SDLK_SPACE in Menu.c to SDLK_HOME.

And while we are at it: Search for “space to toggle” and change it into “A to toggle”

Also you can change “arrows to navigate” into “d-pad to navigate”

Do the same for the SDLK_SPACE in the Splash.c file.



Now everything is good for a second compile!

Go to /tmp/homeExtend and type make. The changes you did to the sourcecode will now be incorporated into the binary.

When this finished without errors, you should do make install again to copy the new binary into the installdirectory.

Should there be an error while compiling, maybe you messed up something in one of the sourcefiles. You can always start over by reextracting the tar.gz archive.



Go to /mnt/utmp/abe and type

./bin/abe

to test, if all controls are fine.


Congratulations! You ported a SDL game to the Pandora!


Now, if you want to release the game, you might want to package the game into a pnd-file.


This will be the second part of this tutorial, coming later on.


EDIT: Packagingpart here:

 

[bzar]

Nice tutorial there! I think this is exactly the kind of stuff we need around here: step-by-step instructions for using the toolchain to port/compile/package games for pandora. Kudos!

 

[Stuckie]

Wow, people actually do use my dodgy hacks! Nice one


Interesting that you use the older Extend Utils compared to the newer one.. think it's about time I whipped up a proper GUI for it rather than using the Zenity crutches which makes it less intuitive than it needs to be!


I will warn you that there might be a few bugs still lurking in that version of Extend Utils.. I'm pretty sure that one of the /usr folders doesn't get fully bound to the Extend properly, so be careful! I will check this when I get back from work, however.. and fix it if it's still there.


I also wasn't aware that there were some package hiccups in the new Dev Extends... though that Dev Extend was created using the original firmware, so the warnings about things going a bit wonky are more about the OS itself.


The one big warning you forgot to mention was that you should NEVER pull out the SD card that has your Extends running, else you really risk confusing the system and causing issues. This is because the Extend system works by mapping your chosen folder ( home or root - ie everything ) to your SD card, so if you pull it out, the system doesn't know where to save files, and could cause all sorts of mayhem. Instead, just reboot your Pandora and the Extends will come off cleanly - which is generally when you're finished devving anyway, so it works out.


If there's anything you'd like me to do with the Extend Utils stuff to make it easier to use, gimme a shout


I'll get out your thread now, but again, nice work!

 

[mcobit]

Hi Stuckie,


Yes, I am using the old ones, as said it is just mount rootextend mount homeextend. I don't need to do more.


I use them for a long time now and never had problems with files in /usr not going to the extend.


I think it is pretty simple to use right now.


i will put the warning about not pulling the sdcard in the tutorial, but it gives this warning, when mounting the extend, too.


For the new dev.extend: I used it and the configure script complained about not finding sdl-mixer and sdlopenjoystick, but the libs are there and linked. Also updating the packages didn't work.


So I assume it is a problem with this extend file. Or maybe the file I downloaded is corrupted.


Thanks again for this Extend-magic.

 

[Tehel]

Very nice tutorial, reading this somehow makes me feel empowered to port something too


However, till I finally get the hardware part, I guess I'll just watch you do it we awe. SDL mention did ring a bell at the back of my mind, would you mind have a look at Blob Wars episodes ? Both are GPL, hosted on sourceforge.


Blob Wars : Metal Blob Solid / http://www.parallelrealities.co.uk/projects/blobWars.php


is a 2D violent platformer that I really enjoyed at the time, takes some time and skill to fully finish.


Blob Wars : Blob And Conquer / http://www.parallelrealities.co.uk/projects/blobAndConquer.php


has a 3D subjective view, not sure if its build on SDL. Never played it either, but always wanted to.


Guess I'll try this port myself if nobody does it before

 

[mcobit]

Blobwars is already ported. Please see the Pandorawiki.


Also please post port requests in the Cool ideas thread.


Also OPENGL ASoftware will not work out odf the box. I will write this into the tutorial. Thanks

 

[Tehel]

Blobwars is already ported. Please see the Pandorawiki.

Oups, sorry. I looked for it on dl.openhandhelds.org and, finding nothing, assumed it wasn't.

Also please post port requests in the Cool ideas thread.


Also OPENGL ASoftware will not work out odf the box. I will write this into the tutorial. Thanks

I will, as ideas come. Too bad for the sequel. Well, that just makes it a bigger challenge


Thanks again for your ports and tutorial, can't wait to put them to good use !

 

[sebt3]

Awesome tutorial bddy


This should be in the wiki.

 

[Stuckie]

Hi Stuckie,


Yes, I am using the old ones, as said it is just mount rootextend mount homeextend. I don't need to do more.


I use them for a long time now and never had problems with files in /usr not going to the extend.

Yea, I fixed it.. must've done so when I re-packaged it as "OldExtendUtils" as it was a bit of a serious bug ( think it was /usr/lib that I missed out! )


The "New" Extend Utils are as complicated as they are mostly for doing crazy OS Extend things ( though the Wiki does have extensive documentation on it!, ) though that never really furthered much other than me fiddling with Debian and Ubuntu chroots, sadly.. least the other half of the Extend Utils purpose is useful to someone though

For the new dev.extend: I used it and the configure script complained about not finding sdl-mixer and sdlopenjoystick, but the libs are there and linked. Also updating the packages didn't work.


So I assume it is a problem with this extend file. Or maybe the file I downloaded is corrupted.

Don't know.. though in general, getting the dev tools wrapped up in a nice package has been a bit of a goal of mine for a while... hopefully I can get my Pandora issues sorted soon and get back on it!


Though I suspect they're all ludicrously busy at the moment, so I'll just have to be patient for a bit.


And, I second sebt3 in that this should be Wikified for prosperity and easy updatability

 

[peelie]

hi great tut


typo


you need to add -r flag to copy directories:


---


As the datafiles are still missing, we need to copy the following directories to the installdirectory:


cp images maps sounds /mnt/utmp/abe


----