XGngeo

Documentation (version 16 final)

1. Introduction

Great emulator + nice GUI: GNU/Linux Neo Geo emulation made easy!

This is the official documentation for XGngeo, a frontend (graphical user interface) for Gngeo, a command line Neo Geo (arcade game playing system made by SNK) emulator for the GNU/Linux and FreeBSD operating systems (and may be some other Unices) with high speed performance and many configurable options. Both are free/libre softwares released under the terms of the GNU General Public License.

XGngeo is written in Python and uses the PyGTK library to provide a complete, practical and user-friendly GTK+ interface over Gngeo! With its multiple configuration panels, designed in an intuitive way, emulator behaviour can be regulated both precisely and easily; while Rom selection is made simple thanks to a full featured list with preview image and various game information, etc.

This program development is conducted by the Choplair-network crew, the lastest version and information about XGngeo are available from our website (see chapter 4 section 1.1). Although we are not directly taking part in the Gngeo development (and are not the official frontend too), we follow it closely and try to implement all its functionalities in the most correct way possible, in accordance with the author (Mathieu Peponas) who gently encourages interactions between frontends and its emulator.

This paper, which is supposed to grow up with each new XGngeo release, provides a sort of Newbie Guide to get started with easy Neo Geo emulation combining these two programs, and also some details about this frontend's features and its functioning.

2. Getting started

This is the complete procedure about how to get the dynamic combination of Gngeo and XGngeo fully functional from scratch, step by step!

2.1 Prerequisites

2.1.1 Emulator and Bios

XGngeo is a frontend for Gngeo, so this must be installed somewhere on your computer! You can download the last version from its home page (see chapter 4 section 1.1). Although the emulator is available in various binary formats (deb, RPM...), keep in mind that these packages may be older than the classic source code archive.

As of XGngeo version 16, the minimum version of Gngeo we ask you to use is the 0.6.11. Trying to launch the frontend with an older version of the emulator will make XGngeo refusing to start untill you indicated where to find a supported version of Gngeo on your computer.

Before installing Gngeo, you have to check for the some dependencies:

Their home page address, for informational purposes, are given on chapter 4 section 1.

Once this is okay, you can install Gngeo, corresponding to the format it was grabed into. If, for some reasons, the installation does not work, you may ask for help from the Gngeo mailling list (chapter 4 section 2).

To be able to launch Roms, Gngeo will need a Neo Geo Bios. It is an archive which consists of the following files: neo-geo.rom, ng-sfix.rom and ng-lo.rom. They have to be put (decompressed) into the same directory as your Roms (the so called Rom and Bios directory!).

2.1.2 Other requirements

Especially for XGngeo, you also need the following softwares to be installed:

That's perhaps already the case. Otherwise, you'll find the links to their home page on chapter 4 section 1.2.

2.2 Getting and launching XGngeo

It's show time! Your are now ready to taste the power of XGngeo. ^^

Here is the installation procedure for the source code archive. You'll have to process differently if you choosed to use a specific package for your distribution. In a such case, check its documentation for details, then pass directly to the next section if installation succeeded.

If you didn't obtain this documentation as a part of an XGngeo package, you have to get one! You'll find download links for the last version on the Choplair-network homepage (see chapter 4 section 1.1).

Thereafter, unpack the archive, then move to the directory which have just been created (something like xgngeo-XX where XX is the version number).

At this time, we do assume that you have installed every dependency indicated above.

Since Python code is interpreted, XGngeo doesn't require any compilation phase. You just have to install the files on your computer by entering, as root: python setup.py install.

After the installation process quickly ended up, you may just, as a normal user now, type the xgngeo command to launch the frontend. If you get an error doing so, please refer to the chapter 4 section 2. Otherwise, you are entering the serious things! :)

2.3 First time important path configuration

At the beggining, XGngeo should invite you to set up some important parameters that are required to build up basic configuration files with three important options required for a working emulation. The first one, the path to your ROM driver file (romrc), is set with the default value, like the path to the Gngeo executable. Actually, you would just have to tell the directory where are located your Neo Geo ROMs and BIOS.

Once you have finished, press Save. Of course, these parameters can be modified at any time thereafter, using the same configuration window.

If for some reason you want to skip this important path check at boot time, it is possible by just giving --nobootcheck as a command line parameter. But this is definitely not recommanded!

2.4 Main window

Unless you obtained a warning dialog because some parameters looked invalid, the XGngeo main window should appear...

2.4.1 Status bar

First, you might be pleased by the welcome message at bottom of the main window. However, the message in this status bar may change and provide some information which is not so useless for the user. For example, it confirms that configuration has been saved or not, and also indicate which Rom you have selected, and it's status (stopped/running). In one word: marvellous!

2.4.2 Menu bar

Of course, you may fall in love with the great XGngeo logo, but actually your attention should go to the menu bar, on the upper part, which you'll be able to control everything with!

It is primarily composed of the File menu, which permits you do simple operations such as loading Rom, starting or stopping it, and exiting the program.

Next to that is, comes the Configuration menu, from where you can modify the paramaters which you entered at the XGngeo first load and also some other little options, mostly related to XGngeo's own behaviour. But the most interesting thing here is the Global emulation sub-menu which allows you to set the default Gngeo emulation configuration (graphic, audio, keys, etc.) for every game (but it is also possible to set specific game configuration). These emulation configuration panels are detailed in the section 2 of the next chapter.

At last, on the very right-hand, from the Info menu you can look at the credits or read (again and again) the holy GNU General Public Licence whom XGngeo is released under!

2.5 Playing a game

Okay, you can set emulation options as you want, then it's time to launch a game!
There are 3 different ways to load a ROM for being executed...

2.5.1 Through the ROM list window

Actually, you would generaly use the ROM list window which brings you an overall view of all the ROMs available in your Rom and Bios directory (plus any other dictory you mentioned), and select one from those. From there, you can also set specific emulation configuration for any ROM, and even see game preview and/or information (see chapter 3 section 2.1)

2.5.2 Through the file chooser

The file chooser, as its name lets understand, is a classic GTK file seclection window that allow you to load a ROM manually, from any place in your file system. This method is useful if the ROM you want to load is located in another place than in directories specified in the ROM list window.

If preview images were enabled, a ROM preview would be displayed, in addition to its name, each time you would click on a file that appears to be a valid ROM archive, detected by GnGeo.

2.5.3 Through the recent ROM history menu

The recent ROM history is no more than a simple menu providing quick loading function for the last ROMs you have previously chosen. Note that you can remove a ROM from that list by right clicking over its name.

Once you have selected a Rom, it should be launched by GnGeo and playable only a few seconds later! The future is now, enjoy the Neo Geo! :-D

While playing, you still can perform some special actions in the emulator, like toggling beetween fullscreen/windowed mode, saving/loading state, etc. (see chapter 3 section 3). By the way, you can also disable the auto ROM execution feature (if you prefer to do so manually) in the Other things configuration window.

3. Details

3.1 Used files

3.1.1 Main configuration files

XGngeo's configuration interface actually manages options of 2 main configuration files at the same time. Both using the same syntax, which is just lines of a variable name followed, after a space, by its corresponding value. :p

3.1.1.1 gngeorc

This is the GnGeo's global configuration file, situated in the ~/gngeo/ directory. It lets you customize many params of the emulator which will be the default for any ROM. Some of these param are highly important: path to the romrc file, Main ROM and BIOS dictory, etc.

3.1.1.2 xgngeo.conf

This is the XGngeo's own configuration file, situated in the XGngeo's user directory (~/.xgngeo). This second file may be considered as less important since there are only options related to XGngeo (size of history, path to preview images' directory, etc.). That's why most of these options are modifiable in the Other things section.

3.1.2 ROM-specific configuration files

Since its version 0.6, GnGeo is able to perform emulation in a specific way for each ROM.

That's quite simple: before loading the Rom, the emulator looks for a file, in the ~/gngeo/ directory, which is named in the form of mame_name.cf (where mame_name is the Mame name of the game). If it does exist, the emulation parameters from are taken from, without taking care of the ones set in the gngeorc, which is used otherwise. The syntax for these files is still the same.

ROM-specific configuration files can be easily handled through XGngeo, as detailed in the next section...

3.1.3 ROM drivers

ROM drivers are actualy defined a single driver file, named romrc. This ASCII file is very important as it contains all the instructions for the emulator to correctly handle all the ROMs.

A more convenient to let the user add/modify/delete ROM drivers to GnGeo than editing this very large file (presently more than 12.000 lines long!), would be to split all drivers into several ROM-specific driver files that would be put in a romrc.d directory. This is hoped to soon become the default in GnGeo, since it would among others really facilitate a ROM drivers editing interface to be implemented in future XGngeo version...

3.1.4 History file

This simple ASCII file (~/.xgngeo/history) contains, in a descending order, lines of the full name (between double quotes) and the absolute path of recently loaded Roms, in order to be displayed in the History menu of XGngeo. Placed in the XGngeo user directory, this file is thus created and updated by the frontend and not the emulator.

3.2 Particular windows

3.2.1 ROM list

There are also optional features (add-on) which bring you a more comfortable game selection in the ROM list window. Here they are...

3.2.1.1 Preview images

XGngeo is able to display a preview image of any of the games selected in the list. It is fully compatible with the preview images used by other frontends such as GGF, which implemented it formerly.

Thus, a preview image pack archive can be easily obtained from the Gngeo, GGF or Choplair-network home page. You will need to unpack them somewhere, then to indicate the directory where they are located in the Other thing configuration window, in order to get it working instantly!

3.2.1.2 ROM information

GGF's developpers created an XML file containing information (description, manufacturer, year, etc.) about loads of Roms in order to be displayed by frontends. This is the perfect addition to preview images and it's fully supported by XGngeo!
Moreover, because of the small size of this file, it is already included in our packages and this add-on is activated by default.

Note: the game reviews are not ours, but have been performed by the Ultimate Neo Gaming Ressource (UNGR). You can read them online and find other interesting things on their homepage (see chapter 4 section 1.3).

3.2.2 Emulation configuration panels

The options which can be set in global or the ROM-specific emulation configuration window are exactly the same. As XGngeo provides graphical management for a lot of Gngeo parameters, they have been divided in serveral panels according to which emulation domain they are dealing with, for the sake of clarity.

3.2.2.1 Display panel

You can activate many options here: fullscreen mode, frame skipping (real-time speed), interpolation (smoother animation), etc. Moreover, you may select your prefered blitter (software, OpenGL, YUV) and choose to apply an effect upon it (scanline, HQX, etc.).

Please note that effects are currently not supported by the YUV blitter of Gngeo. Thus, the effect list becomes disabled in XGngeo when you select this blitter.

3.2.2.2 Sound / Joystick panel

There are few options for sound and joystick, which is why they are regrouped in one panel. You may set support for them and, if enabled, specify some options (sound sample rate, joystick devices).

3.2.2.3 Controls panel

In the Neo Geo, we can observe 4 kinds of key: the directional arrows, the fire buttons (A, B, C & D), the Start/Coin, and the hot keys.

XGngeo has a keyboard configurator which permits you to easily customize all the 2 player controls. To modify a key, just click on the corresponding button then push your new key.

Since Gngeo (SDL's) and XGngeo (GTK's) keyboard maps are differents, some special keys might be not recognized by XGngeo. If it occurs, please tell us (refer to the chapter 2 section 2)!

Please give some attention to the four hot keys: they are optional and allow you to actually binds one key to a combination of multiple fire buttons (ie. to perform special game actions in a easier way). Those combinations are freely configurable, independently for the 2 players.

3.2.2.4 System panel

Here you can set some Neo Geo core preference. You can change the region (Japan, USA, Europe), which often modifies the game language, and also the Neo Geo BIOS type: either arcade (classic mode with credit given by coins), console (usually more complete and permiting configuration through an option menu) or universe (a mix of both!).

3.3 Special actions in Gngeo

Using function keys, you can perform some special actions while playing a ROM in GnGeo. Here comes the list of what you can do by pressing these keys:

3.4 Internationalization

XGngeo is multilingual! Translations are currently available in the following languages:

Note: a language followed by an asterisk means that its translation is unfortunately not up-to-date with the current release original strings. Don't hesitate to update it! You can even make a new translation, just look below...

3.4.1 Making a new translation

If you want to perform a new translation of XGngeo into your language, please follow the last instructions that you'll find mentionned on te Choplair-network's website (see chapter below).

4. Web links and ML

4.1 Home pages

4.1.1 Websites of the great duo

4.1.2 Their dependencies

4.1.3 Miscellaneous

4.2 Gngeo mailling list

If you encounter any problem using Gngeo, directly or through a frontend such as XGngeo, the best way is certainly to ask for help on the official Gngeo mailling list, where you should get quick and effective answers from its little community, including XGngeo developers. Here is how to:

By the way, list archives are available on the web at the following address: http://www.mail-archive.com/gngeo@ml.free.fr/. Please check that your problem hasn't already been adressed, disscussed and solved before posting a new help request message.

5. Credits

XGngeo forms a part of the projects conducted by the Choplair-network, an independant libre software development crew. Here comes the people involved in the making of this program since the beginning:

Special thanks to the Gngeo authors, Mathieu Peponas and others, for writing such a great emulator!

(1): The wonderful, the magnificent and most excellent blooming rose!