GameRunner Documentation

GameRunner is based on Linux Image-gta02-g291a9d50_mwester-stable.bin kernel and Om2008.9-gta02-20081117.rootfs. XGlamo is providing X.

We use the script to create the minimal rootfs, and the script to create the full rootfs (minimal rootfs + games). READ THE SCRIPT BEFORE TO USE THOSE!. These do not check if the proper files are there. You can get those scripts from All the files link.

This project aims to provide the builder scripts, the rootfs, games for GameRunner, documentation, and the GameRunner game control.

License for new stuff: GNU General Public License (GPL)

Minimal Installation

You can install just the minimal rootfs, and then install the games you wish. Follow the instructions at Download and HOWTO Install above for the minimal rootfs file. For every game you want, just untar them under /usr/games/installed directory.

Get the minimal rootfs and games tar.gz files at : All the files.

GameRunner Game Control

This project also provides gamerunner game control. It is a simple application which reads touchscreen and accelerometers, and then, sends key Xevents. If there is some game running it gets the XEvents and manages those like if these come from keyboard directly.

With this tool, we can build games without modify the code to control it on gamerunner.

GameRunner game control has two modes. You can switch between modes using the AUX buttom. The idea is to have one mode to navigate menus, and another when you are playing the game. If we use accelerometer for up/down/left/right, it is too hard to use the game menu. So you can use one mode without accelerometers and another with acceleromenters and proper touchscreen for keys.

Check an example to understand how to use it with your ported games. Current games using this tool are : tecnoballz, quake1, powermanga, tyrian21.

Example of Usage :

./gr_game_control 0 0 40 40 4 90 null null null null Escape Return Up Return Down Left Right Left Right Up Down Escape Escape 0 0 space space space 1 6

0 : accelerometer_zHome /* Stores new "Home" position */
0 : accelerometer_yHome /* Stores new "Home" position */
40 : accelerometer_zwindow /* DeadZone in Pixels */
40 : accelerometer_ywindow /* DeadZone in Pixels */
4 : accelerometer_zscale /* Scaling factor for motion (acceleration) */
90 : accelerometer_yscale /* Scaling factor for motion (acceleration) */

null null null null Escape Return Up Return Down Left Right : the four "null"s are for accelerometers. In this case we don't want to use accelerometers, so only touchscreen is used. This first mode is useful for game menu. The next "Escape Return Up Return Down Left Right" are the key Xevent to send when pressing touchscreen.

Imagine the touchscreen with nine buttons. Only 7 are set

Landscape Freerunner, 640x480 (or 320x240) :

The 2 button is not used. The 5 button is always used internally to set the "Home" position of accelerometers. When you are playing and you want to set a new "Home" position (the freerunner angle when you feel comfortable for 0 movements) just put the freerunner in your prefered position and press the 5 button (the center of the screen).

So what does "Escape Return Up Return Down Left Right" mean?
Okey, it means that when you press the 1 button (the uppermost left corner) on screen, the gamerunner game control sends the Escape key event to X.
When you press the 3 button (the uppermost left corner) on screen, the gamerunner game control sends the Enter key event to X.
The same with other:
4 : Up
6 : Return
7 : Down
8 : Left
9 : Right

There is a special word to use with acceleromenters : mouse.
If you use it the gamerunner game control sends relative mouse movements to X. It is useful for games which can be played with mouse on pc, like quake, where you can use the mouse to walk.

How to contribute

Easy : Build and test games, then send us them!

Our games are installed under /usr/games/installed directory. All the game files and libs are there. It lets us to easily add or remove games. We don't use repositories and installation systems with dependences control.

If you want to send us new games to add, we only have a few instructions to follow:

Send us that tar.gz file, with a description, original open source game web page link, and a screenshot.

Tips for performance when porting games

We already know the problems with video graphics.

Like the GP2X game console, Openmoko FR runs games very well in 320x240 fullscreen mode. Moreover there are several games ready to use with that resolution.

The basic tips are :

When you build and test a new game try first 640x480 video mode.

If the game is slow, you can try 320x240 (if the game supports that). If all looks slow yet, then you can disable sound. If the speed goes well without sound, then you could convert all the sounds files to 8000Hz, 8bit, mono, wav. And then test the game again, but with sound this time. Ffmpeg will be your friend for that task.

Example : ffmpeg -i car_brake.ogg -ac 1 -ar 8000 -acodec pcm_u8 car_brake.wav

Convert the music files as well. If the game uses SDL, then you can convert the music sound files like other sound files, to 8000Hz, 8bit, mono, wav. Some games bring fast tracker music files. You can use the schism tracker editor to convert the music files to wav. Then use ffmpeg to get the sound quality needed.

If you can disable sound when testing, and your game is still slow then you need to check for command line arguments. If all above do not help, then perhaps you need to modify the code a bit to improve the performance.

Tips to modify the code

Put the sound code in a new thread. It usually can be easy, and it improves a lot the speed.

Try to set SDL audio Init as Mix_OpenAudio(22050, AUDIO_S16, 2, 1024)

Skip some FPS. Most of games for PC use 30+ FPS, but for smaller screens devices like Neo screens 15-20 FPS should be enough. We need to reduce SDL_BlitSurface() and SDL_Flip() calls. For example, avoiding those calls from time to time. Remove/Reduce SDL_Delay() calls if possible.

Init the SDL_SetVideoMode as scr = SDL_SetVideoMode (320, 240, 16, SDL_SWSURFACE);

Future Work

There are many games using 640x480 video mode, or more. For those games we need to develop a fast scaling function to fit the game graphics in 320x240. GP2X game console has the 2D scaling feature in hardware. But if there is some idle CPU percentage available, we can use that idle CPU time to scale the image like GP2X game console does.