EMU File Format Standard
User Documentation
Written by Jim Pragit
Copyright (C): 1997


Note: This document explains just about anything you could ever possibly 
want to know about the EMU standard.  However, the best way to actually 
learn about how it works is to actually open one up and look at it.  
Admittedly, this document is overkill but I was bored one day and decided
to do something productive.


Table of Contents
   I. Why the EMU standard?
  II. General Notes
 III. The Four Sections
  IV. Section One: Main
   V. Section Two: Internal
  VI. Section Three: ROM Specific Parameters
 VII. Section Four: ROM Descriptions
VIII. How the Command Line Is Built
  IX. Note to Other Front End Authors


I. Why the EMU standard?
There are many advantages of the EMU format, many of which are related:
1) Simplicity:
   The EMU standard uses a plain ASCII text file containing English-like 
   keywords and values that can easily be viewed or edited by any text 
   editor.  Further, the format and syntax is based upon standard 
   Microsoft Windows initializaion files.  So, if you've ever edited a 
   Windows INI file, you'll feel right at home with EMU files.
2) Purity:
   All the information required to run an emulator is stored in the EMU 
   file.  No hard coding of any kind is used or allowed.
3) Universality: 
   Because the EMU file contains all the necessary information to run a 
   particular emulator, Game Menu can run any emulator, whether it be an 
   emulator for consoles, arcade games, computers, or portables.
4) User-Configureability: 
   Anyone with a text editor can make/edit one.
5) Versatility:
   This format has support for every conceivable situation that might be 
   required to run an emulator. 


II. General Notes:
1) EMU files are not case sensitive.
2) Section names are enclosed in brackets.
3) Sections must be in order.
4) Statements requiring a reserved keyword follow this syntax:
   keyword=value,[value,value...]
   For statements not requiring a keyword, they follow this syntax:
   item=value
4) A comment is denoted by a semi-colon as the first non-blank character
   in a line.
5) An invalid keyword (i.e. a misspelled one or just random data) will be 
   ignored.



III. The Four Sections
A standard EMU file can have up to four possible sections.  Only the 
[Main] section is required.  The four sections are:
1) Main
2) Internal
3) ROM Specific Parameters
4) ROM Descriptions
These sections are to be denoted by enclosing them in brackets such as 
[Main] or [ROM Descriptions]



IV. The [Main] Section:
This is the only section required.  It contains general information 
regarding how an emulator works.  The [Main] section has 8 possible 
statements:

emulator=value
global_parameters=value
parameter_position=value
rom_directory=value
rom_type=value        
rom_filespec=value
help_file=value
embedded_description=value1,value2,value3

The "emulator" keyword gives the pathname of the emulator. 
Example:
emulator=c:\stella\stella

The "global_parameters" keyword gives any global parameter(s) required.  
This will apply to all ROM images. 
Example:
global_parameters=/dosomething

The "parameter_position" keyword tells Game Menu whether parameters
should be placed on the command line before or after the ROM image
filename.  This is needed for certain emulators that expect command line
parameters to be in a specific order.  There are two possible values:
"leading" and "trailing".  Leading is the default value.  This setting
applies to both global_parameters and ROM specific parameters. (See Part
VIII of this document for more information.)
Example:
parameter_position=trailing

The "ROM_directory" keyword gives the pathname of the directory where the 
ROM images can be found. This can be a relative path (from the point of 
view of the emulator's directory).
Example:
rom_directory=c:\stella\roms

The "ROM_type" keyword tells what kind of file to look for.  There are 
three possible values: "file", "directory" and "internal".  The first two 
values are self-explanatory.  The third requires an extra section called 
"internal".  See Part V of this document for more information.  If this 
line is not found, the default value will be "file".

Example:
rom_type=directory

The "ROM_Filespec" keyword gives the file specifications of the ROM
images.  This is analogous to the internal DOS command "DIR".  You can
have up to 64 such filespecs, each on its own line.  The default value is
"*.*".

Example:
rom_filespec=*.bin                

The "help_file" keyword tells the pathname of the emulator's help file.  
This must be a plain DOS ASCII text file.

Example:
help_file=c:\stella\stella.txt

The "embedded_description" keyword tells Game Menu how to extract a ROM
image description (name) that is imbedded in certain ROM image formats.  
Here is the general syntax:
embedded_description=start_position,length,extension

The first value, "start_position" tells the number of bytes into the ROM 
image where the game's title begins.  The second value "length" tell the 
length of the title in bytes.  The third value, "extension" tell the 
filename extension of the ROM image to which this applies.  This feature 
overrides descriptions in the [ROM Image Descriptions] section for all 
such files with that particular extension.

Example:
embedded_description=337,41,bin



V. The [Internal] Section:
This section's purpose is to add support for emulators that receive
neither a filename nor directory name as the command line parameter that
denotes the program to be run on that emulator.  Basically, this section
is a substitute for actual filenames (or directory names).  Any line
within the [Internal] section is treated as an actual filename.  This is
required for emulators such as Multi Gauntlet Emulator.  Note: to use
this feature you must add the line "rom_type=internal" to the [Main]
section.  Here's an example for the [internal] section for Multi Gauntlet
Emulator.

[Internal]
-g1
-g2



VI. The [ROM Specific Parameters] Section:
This section's purpose is to tell Game Menu to pass extra parameters to
the emulator but only for a specific ROM image.  Lines within this
section have no keyword.  You can have as many lines of this type as you
want.  They follow this syntax: 
rom_image_filename=parameters

For example:
[ROM Specific Parameters]
ALTBEAST.SMS=/li 1
BREAKPOP.GG=/JAP
CHESSMAS.GG=/li 2
CHOPLIFT.SMS=/APPROX
SAGAIA.SMS= /li 2
SLAPSHOT.SMS=/nofm
WBOY3.SMS=/JAP


VII. The [ROM Descriptions] Section:    
This section's purpose is to tell Game Menu to display descriptions
rather than filenames in its list box.  These descriptions do not
override any title found embedded in the ROM image (if used).  Lines
within this section have no keyword.  You can have as many lines of this
type as you want.  They follow this syntax: 
rom_image_filename=description

Example:
[ROM Descriptions]
hockey.bin=Ice Hockey
pacman.bin=Pac-Man



VIII. How the Command Line Is Built:
First, Game Menu changes into the directory where the emulator is located 
(this information is extracted from the emulator line in [Main]). The 
command line is then built using the following equation:

IF (parameter_position = trailing) 
  command_line = emulator
	       + [ROM_image_directory] 
	       + [ROM_image_filename]
	       + [global_parameters]  
	       + [ROM_specific_parameters]
ELSE
  command_line = emulator
	       + [global_parameters]  
	       + [ROM_specific_parameters]
	       + [ROM_image_directory] 
	       + [ROM_image_filename]
ENDIF

where emulator does not include a path.  Anything in brackets is optional 
in the sense that these values need not be explicitly given in the EMU
file.
	       
  
IX. Note to Other Front End Authors:
The EMU format was designed specifically for Game Menu.  However, if you 
would like to adopt this standard for your own front end, you are 
encouraged to do so.  In return I ask that you agree to the following:
1) I be notified in advance of your intention to use it.
2) The following line be included in your documentation: "This front end
is licensed to use Jim Pragit Software's EMU Standard Universal Format 
Specification version 1.0"
3) This document be included with your distribution.
4) The standard must be adhered to completely.  No modifications,
omissions, or additions are allowed for any reason.  


Jim Pragit
e-mail address: jpsoftco@aol.com
--------------------------------
Jim Pragit Software
http://members.aol.com/jpsoftco
--------------------------------
