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 gamerunner_builder_tar_gz.sh script to create the minimal rootfs, and the gamerunner_builder_full_tar_gz.sh 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
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:
- Make a directory with a simple name of your game to port. For example : mkdir quake1
- Copy in that directory the binaries, libraries (if needed), and data files.
- Write a simple script in such directory with the same directory name. This script should rotate and modify the video mode of the screen (if needed), and run the game. For example, if the directory is quake1/ then add inside the quake1.sh shell script.
- Put an icon for the main menu GUI. The icon should have the same directory name. For example : quake1/quake1.png
- If you need the gamerunner game control to play your game then read the gamerunner game control instructions (and check an example, like the gamerunner game control inside of quake1 game).
- Make a tar.gz of that directory of your ported game.
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 :
- reduce video mode to 320x240 or 320x200
- reduce sound quality
- reduce FPS
- remove effects
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.