Loemu 0.3.1

Adding a new emulator

The addition of a new emulator to loemu consists in the creation of the new emulator's configuration file. This file must be placed in share/loemu/config with extension .conf so loemu parser can identify it as emulator configuration file.

This file is divided in sections and entries with structure of INI files. Each entry value is calculated at runtime as follows:

  1. The substrings @('Variables','var') of the entry value are replaced with the user value of the variable 'var' (the definition of this variables are explained below).
  2. If it's possible the entry value is evaluated as a python instruction.
  3. Finally the resulting string value is assigned to entry.

As an example this file would be replaced by this one. Note that there are strings that are interpreted as python lists or dicts (like images value or state value).

Generic configuration

The General section is the main section of the emulator configuration file. It describes the general parameters of the emulator used by the application. This section has the following entries:

label Identifies the emulator in the user interface.
binary The executable file of the emulator.
start The command to launch the emulation. The string @(attribute) is replaced by the value of the attribute of the game selected in the front end.
images The list of sets of images. Each set can be a directory or a zip file.
image_file The image file format. The string @(attribute) is replaced by the value of attribute of the current game in the front end.
state Convert state values of emulator (like incorrrect or correct) by another values (like bad or good).
identity Identifies the common attribute to all emulator data sources. It's the identifier attribute that allows the linkage of the data sources. It must be unique for every game.
titles Titles of the game attributes shown in the Loemu interface.
sources The list of sections that describes the sources of emulator data. The format of these sections is explained below.
variables The list of variables of the emulator and also the list of the sections that defines this variables. The format of these sections is explained below.

Data sources

The sources entry of General section is the list of data source sections of the emulator. These sources define the game attributes capture and allow loemu parser to build the part of the gamelist for this emulator.

Each section has a group of entries that describe how to capture some game attributes. The current attributes supported by graphical interface are description, category, year, manufacturer, romset, players, version and state. The entries of source sections are described as follows.

type The type of source. Its value must be:
archive The source is a file. This type requires the archive entry.
command The source is the standard output of a command. This type requires the command entry.
archive The path of the data file that have to be parsed. This entry is required if type value is archive.
command The command that outputs the data to be parsed. This entry is required if type value is command.
format The structure of the data to parse. Allowed values are:
xml The source data has xml structure. This format requires the xsl entry.
ini-sections The source data has INI structure with sections and entries, the sections are the attribute labels of the games and the entries of this attribute sections are the identifier attribute of every game. This format requires the sections entry.
ini-options The data has INI structure with sections and entries, the sections are the identifier attributes of every game and the entries of this game identifiers are the attributes of the game. This format requires the options entry.
plain The data is a plain text where each line belongs to one game. This format requires the pattern entry.
xsl A xslt file. It tells how to convert the xml source data to this format. This entry is required if format value is xml.
sections Conversion between the section label and the attribute label of the games. Only the section labels defined in this conversion are parsed. This entry is required if format value is ini-sections.
options Conversion between the entry label and the attribute label of the games. Only the entry labels defined in this conversion are parsed. This entry is required if format value is ini-options.
pattern A regular expression. It must define named groups with the names of the attributes to be parsed. An extensive explanation of the regular expression syntax can be found here. This entry is required if format value is plain.

Variables

The variables entry of General section is the list of variables that allow user to customize the emulator parameters.

The variables can be set by the user in the Emulators tab of the Preferences dialog and they can be referenced in the emulator file with the substring @('Variables','var') to capture the customized user value.

The sections of the variables can be defined to improve the appearance of the variables entries in the Preferences dialog. Each variable section name must be the variable name and it can contain the following entries.

type The data type of this variable. It defines how user enter the data in the Preferences dialog. Current supported values are: select_file, select_directory, images and text (this is the default).
text The description of the variable. It is shown next to the parameter value and it is recognized as a localization string.
default The default value of the variable.