README file for MAMECAT
-----------------------
v0.43, 18-JAN-2002
Contents
1) What is MAMECAT ?
2) How to obtain the latest version
3) Prerequisites and installing MAMECAT
4) Preview images
5) Command line options
6) Options in $(HOME)/.mamecatrc, $(HOME)/.xmame/.mamecatrc or
$(HOME)/xmame/.mamecatrc
7) Catalog and ROM-status cache format
8) ROM status
9) Printing
10) Contacting the author(s)
11) Special notes for new versions of MAMECAT
12) Bugs and restrictions
13) License
1) What is MAMECAT ?
MAMECAT stands for "M.A.M.E. Catalog/Launcher" and basically this already
says what it is :-).
It consists of three programs:
- qmamecat (X11/Qt based launcher application)
- qmsetup (setup wizard, started by qmamecat on demand)
- catgen (simple catalog generator, started by qmamecat on demand)
Note that MAMECAT is available only for the UNIX-port of M.A.M.E. (aka
X-Mame), so if you are a DOS/Win/Mac/whatever-MAME user, please use a
different MAME launcher for one of those OSs. Have a look at the official
MAME project homepage (http://www.mame.net/) which lists some of
them.
2) How to obtain the latest version
MAMECAT has its own homepage where new versions are made available for
download, but please note that the location may change at any point in the
future. In this case we will post a message to the xmame mailing-list to
inform you...
The current URL is http://www.mameworld.net/mamecat/ (english) or
http://www.mameworld.net/mamecat/german/ (german) !
3) Prerequisites and installing MAMECAT
Prerequisites:
for qmamecat & qmsetup:
- Qt library (2.2.0 or above) - if you don't have it you can get it from
Troll Tech (http://www.trolltech.com/ or ftp://ftp.trolltech.com/qt/source)
- the env. variable QTDIR should be setup correctly to compile & link
for qmamecat, qmsetup & catgen:
- C++ compiler/linker plus ar and ranlib utilities
- GNU make utility
- the env. variable HOME must be setup correctly to run qmamecat
- xmame-0.34rc1.1 (or higher)
Installation:
Simply enter
make
in the top-level directory. If it shouldn't compile and link properly,
cd into the presets directory, and type
cp make.defaults make.`uname`
(or cp make.defaults make.`uname`-`hostname` if you need local adjustments)
and edit the newly created file to suite your needs. Go back to the top-
level directory and try again.
If you may want to recompile the man-page, add the correct path to groff to
the GROFF definition in the corresponding presets/make.`uname` file (or
make.defaults directly). But as a groff-compiled version of the man-page
already exists in the doc directory, this should normally not be neccessary.
After successful compile & link, enter (as root)
make install
and you should be fine. You should now be able to start MAMECAT by entering
qmamecat (see note below !).
NOTE: Before you start, we recommend you get xmame working correctly first !
It will basically work, but as the catalog will not be correctly created
and the ROM-status will not be determined, the result won't be very useful.
If you still decide to use qmamecat BEFORE xmame is correctly installed,
use the "-r" option on the next start of qmamecat (after xmame IS working) !
At the first start of qmamecat a setup wizard - qmsetup - will be launched
and you will be asked for the path to xmame; please enter (or browse) the
FULLY QUALIFIED PATH INCLUDING THE NAME OF THE EXECUTABLE.
qmamecat will then automatically create a startup catalog for you. Note
that this requires (at least) catgen to be in your path (which should be the
case when you use "make install") !
The startup configuration is done with the defaults described in section 6,
except for <executable>, which you entered before. You may want to change
some of the options, for example to enable the preview-image support.
For more information on how to enable preview images, please see next
section.
Please also read sections 11 and 12 for known bugs and restrictions !
4) Preview images
If you wish to enable the preview images you will have to copy the images to
the directory specified in .mamecatrc (option <previewdir>).
Additionally you will have to set the option <showpreview> to enable this
function !
PNG snaphots created by X-Mame are natively supported; other image formats
include XPM, GIF and BMP.
Preview image filenames must be the same as their corresponding rom-images
or <rom>0000.<ext> (up to <rom>0004.<ext>); the extension should reflect the
image format (at least one of the above format abbreviations must be used
(in lower-case letters !) for qmamecat to find the image) !
For example: the preview image file for "galaga" would be a file named
"galaga.png" or "galaga0000.png" (up to "galaga0004.png"); the
extension could be different, of course...
Note that files without the "000x" snapshot-suffix are found first !
If you store several images of a game with different image formats
(extensions), qmamecat will only display the one which it finds first.
Let's say you have 2 files for "galaga", i.e. "galaga.png" and "galaga.xpm",
in this case qmamecat will only display "galaga.png" !
The complete current order is PNG -> XPM -> GIF -> BMP ! This does also
apply if snapshot-suffixes (<rom>000x.<ext>) are used.
When the extension does not specify the "real" image format, qmamecat will
try to guess it (this is a nice feature of Qt's QPixmap class :-)... if it
can't find the image file or validate the image format, the text "Preview
not available" will be displayed instead.
Since v0.28 zip-compressed previews are also supported ! The current
implementation accepts ONE big zip-file for ALL preview-images. This file has
to be specified in the option <compressed_preview_file> and the option
<compressed_previews> has to be enabled (see section 6 for more details).
ZIP is currently the only supported (de)compression method !
Note that all rules stated above do also apply if you use zip-compressed
previews.
If you are using the previews that we publish on our homepage, we do NOT
recommend to archive them in a ZIP, because the PNG format already compresses
the images very well, the ZIP file might even be bigger than the individual
PNG files and the perfomance will be degraded a bit (especially when checking
the previews).
5) Command line options
The following command line options are currently available for qmamecat:
-r forces recreation of the ROM-status cache (should be used if
you install new ROMs - note that removing the ROM status cache
file or "refreshing" the gamelist from within qmamecat (ctrl-r)
has the EXACT SAME effect !)
-h or -? shows a usage help and exits
Additional switches derived from QApplication:
[-display disp] [-geometry geom] [-fn fnt] [-font fnt] [-bg bgcol]
[-background bgcol] [-fg fgcol] [-foreground fg_col] [-name name]
[-title title] [-style=guistyle] [-ncols ncols] [-visual TrueColor]
[-cmap] [-nograb] [-sync]
See the man-page of QApplication(3qt) for a full description of these
switches !
6) Options in $(HOME)/.mamecatrc, $(HOME)/.xmame/.mamecatrc or
$(HOME)/xmame/.mamecatrc
Qmamecat will search for $(HOME)/.mamecatrc, $(HOME)/.xmame/.mamecatrc
and (as a last resort) for $(HOME)/xmame/.mamecatrc (in this order !).
If it can't find any of these files, a minimum configuration will be
requested from the user (it only needs the path to xmame for this) and
defaults will be used for the rest of the options.
Also, if an option doesn't exist in the config file or its value is missing,
the default will be used for this option (see table below).
The individual options and their defaults are:
option default meaning/remarks
----------------------- ------------- -------------------------------------
catalog ./mamecat.cat catalog file to be used (if you want
to modify/save it through mamecat,
you must have write-permission - of
course :-)
tempdir . directory for temporary files
executable xmame.x11 the X-Mame executable
status_cache ./mamecat.rsc the ROM-status cache file
options ----- options passed to X-Mame (for *each*
game - see section 7 for how to
specify options passed to a *single*
game)
sort 1 sort category:
0 = don't sort
1 = sort by name (of game)
2 = sort by rom image name
3 = sort by remarks
4 = sort by rating
5 = sort by rom status
6 = sort by game specific options
order 1 sort order:
0 = descending
1 = ascending
rating_min 0 min. rating to be displayed
rating_max 6 max. rating to be displayed
available_games_only 0 display only avalailable games ?
0 = no
1 = yes
ignore_rom_avail 0 try to start games even if mamecat
thinks they are ´unavailable´ ?
0 = no
1 = yes
previewdir ----- directory where preview images are
stored (with a trailing "/")
showpreview 0 show preview images ?
0 = no
1 = yes
integrated_preview 0 show preview inside the main-window
(1) or in a separate window (0) ?
scaled_preview 1 scale preview to the size of the
preview-widget ?
preview_below 0 show preview below (1) or beside (0)
the gamelist ? (only if widget is
integrated)
splitter_gamelist 70 splitter size of the gamelist (in
pixels)
splitter_preview 30 splitter size of the preview widget
(in pixels)
keep_aspect_ratio 1 keep aspect ration when scaling images
(1) or maximize in each direction (0) ?
compressed_preview_file ----- filename of the zip-compressed preview
file (only ZIP supported !)
compressed_previews 0 use zip-compressed previews ?
0 = no
1 = yes
(compressed_preview_file must be set
correctly, if enabled !!!)
font_family helvetica family of default-font
font_size 10 point-size of default-font
font_style 0 style of default-font (0 = normal,
1 = bold)
font_italic 0 italic default-font ?
gl_font_family helvetica family of gamelist-font
gl_font_size 10 point-size of gamelist-font
gl_font_style 0 style of gamelist-font (0 = normal,
1 = bold)
gl_font_italic 0 italic gamelist-font ?
mainwidget_x 0 mainwidget's x-position
mainwidget_y 0 mainwidget's y-position
mainwidget_w 600 mainwidget's width
mainwidget_h 400 mainwidget's height
pvw_x 0 preview-window's x-position
pvw_y 0 preview-window's y-position
pvw_w 200 preview-window's width
pvw_h 300 preview-window's height
gamename_pos 0 GAMENAME's column-position
gamename_width 300 GAMENAME's column-width
rom_pos 1 ROM's column-position
rom_width 50 ROM's column-width
status_pos 2 STATUS' column-position
status_width 50 STATUS' column-width
remarks_pos 3 REMARKS' column-position
remarks_width 50 REMARKS' column-width
options_pos 4 OPTIONS' column-position
options_width 100 OPTIONS' column-width
rating_pos 5 RATING's column-position
rating_width 50 RATING's column-width
manufacturer_pos 6 MANUFACTURER's column-position
manufacturer_width 100 MANUFACTURER's column-width
year_pos 7 YEAR's column-position
year_width 50 YEAR's column-width
show_correct 1 show games with status "CO" ?
0 = no
1 = yes
show_maywork 1 show games with status "MW" ?
0 = no
1 = yes
show_incorrect 1 show games with status "IN" ?
0 = no
1 = yes
show_notfound 1 show games with status "NF" ?
0 = no
1 = yes
show_unknown 1 show games with status "NA" ?
0 = no
1 = yes
version_major 0 major version number
version_minor 0 minor version number
version_beta 0 beta version number (0 = NO beta)
remove_logs 1 remove log files on exit (1) or keep
them (0) ?
mamecatlog_show 0 show mamecat log window ?
mamecatlog_x 0 mamecat log window's x-pos
mamecatlog_y 0 mamecat log window's y-pos
mamecatlog_w 300 mamecat log window's width
mamecatlog_h 200 mamecat log window's height
xmamelog_show 0 show xmame log window ?
xmamelog_x 0 xmame log window's x-pos
xmamelog_y 0 xmame log window's y-pos
xmamelog_w 300 xmame log window's width
xmamelog_h 200 xmame log window's height
warn_catalog_update 1 show message box to user when the
catalog needs an update ?
warn_refresh 1 show message box to user before the
ROM status cache is going to be
refreshed (by user action, perhaps
accidently)
avail_color #000000 gamelist color for available games
avail_color_high #FFFFFF ---- " ---- (highlighted)
unavail_color #BEBEBE gamelist color for unavailable games
unavail_color_high #BEBEBE ---- " ---- (highlighted)
specify_color_by 0 which color specification method is
to be used ? 0 = specify colors by
rom-availability, 1 = specify colors
by rom-status
color_correct #009600 gamelist color for games with status
"CO"
color_correct_high #009600 gamelist color for games with status
"CO" (highlighted)
color_maywork #FFC800 gamelist color for games with status
"MW"
color_maywork_high #FFC800 gamelist color for games with status
"MW" (highlighted)
color_incorrect #FF0000 gamelist color for games with status
"IN"
color_incorrect_high #FF0000 gamelist color for games with status
"IN" (highlighted)
color_notfound #FF0000 gamelist color for games with status
"NF"
color_notfound_high #FF0000 gamelist color for games with status
"NF" (highlighted)
color_unknown #FF6400 gamelist color for games with status
"NA"
color_unknown_high #FF6400 gamelist color for games with status
"NA" (highlighted)
Note: you can specify the color-settings in two ways - either in #RRGGBB
format (specifying the red-green-blue value in hex), or as a "named color"
(the latter has to be defined in /usr/X11/lib/X11/rgb.txt - i.e. grey, black
red, green etc.) !
But best is to leave the config-file untouched and instead edit all settings
from within qmamecat's options-dialog.
Take mamecatrc.sample (in this directory) as a sample options file.
7) Catalog and ROM-status cache format
Catalog format:
Every entry (one for each game, one per line) has the following form:
<rom>§<rating>§<remarks>[§<gameopts>]
<rom> the rom-image name
<rating> expresses your personal opinion about the game (a decimal
value: 0 - 6); the way you interprete this is controlled by
some of the settings of the MAMECAT configuration (see
section 6)
<remarks> free-form text for remarks (shouldn't exceed 80 characters)
<gameopts> this is an optional field; if set, it specifies game-specific
options (which are passed to X-Mame only for *this* game);
if you want to pass any options to *each* game, please use
the <options> setting in .mamecatrc instead (see section 6)
The file mamecat.cat.sample (in this directory) contains a sample catalog.
ROM-status cache format:
Every entry (one for each game, one per line) has the following form:
<rom> <rom_availability_flag> <rom_status>
<rom> the rom-image name
<rom_availability_flag> 1 or 0 (for "available" or "not available")
<rom_status> the numeric (internal) representation of the
rom-status
NOTE: You should never edit this file manually !
8) ROM status
Since v0.27 a "ROM status" is determined if you enable the option
<thorough_romcheck> (which will cause qmamecat to use the -verifyroms option
of xmame to analyze the ROM-status thoroughly at startup and at every
"refresh" !).
Since v0.39 <thorough_romcheck> is ALWAYS enabled and you cannot change it
"externally". That is, <thorough_romcheck> is no longer an option, although
it still exists in the options-struct...
Note that this feature requires xmame 0.34rc1.1 (or above) to work properly,
because it relies on the output of "-verifyroms" which has been changed a bit
since this (xmame) version. If you use <thorough_romcheck> with an older
xmame version, the analysis may not be correct ! See also section 3.
The status-abbreviations and their meanings are:
NA 'N'ot 'A'pplicable = unknown ROM-status (this will be displayed, if
<thorough_romcheck> is disabled or the ROM-status could not be
determined, for example because it is a game that does not have an
explicit rom-set like "pong" !)
CO 'CO'rrect = the ROM image is correct and should work fine
MW 'M'ay 'W'ork = the ROM image is incorrect, but may work (most of the time
only the checksum is incorrect)
IN 'IN'correct = the ROM image is incorrect or corrupted and will definitely
NOT work
NF 'N'ot 'F'ound = there is no ROM-image for this game in your ROM-path
(you should check your ROM-path, if you think it should be available)
9) Printing
Since v0.30 a print function has been added. The generated output is
postscript; if you don't have a postscript printer, make sure you have a
filter setup for your printer. We recommend "apsfilter", which you can get
from ftp.suse.com !
10) Contacting the author(s)
Bug reports and questions specific to MAMECAT should be sent to
mamecat@umrk.dyndns.org directly, not to the xmame mailing-list.
Feel free to send us any suggestions for enhancements and take a look at the
CREDITS file to see who is responsible for which part of MAMECAT - however,
we prefer mail to mamecat@umrk.dyndns.org, because this will guarantee that
ANY team member will be reached.
Also, we would like to maintain a list of known working platforms/
configurations, so please drop us a note even if you are successful.
Tell us under which circumstances (OS, OS-release etc.) you were successful,
we will then add you to a list on the MAMECAT homepage, so that someone with
a similar configuration would be able to contact you... we cannot test on any
potential target-platform.
11) Special notes for new versions of MAMECAT
This section is mainly for those who already used MAMECAT prior to "THIS"
release. It offers some notes about changes that might affect an earlier
installation and/or changes in "code-behaviour" you should be aware of.
v0.43
- Note that there are minor differences in the log-window's scroll-behaviour
between the Qt 2.x and 3.x versions of qmamecat
- When upgrading to Qt 3.x you should reconfigure your fonts (!!!); as soon
as you open the font-dialog you'll probably be presented with a different
font than expected; that's because Qt's internal font-handling has changed
and so the fonts are determined differently (QFontDatabase)
- Switching between xmame executables of the _same_ version (i.e. different
display targets) now works without recreating the catalog and its rom
status cache !
- Note that there are new "overall" gamelist statistics counters (see about
dialog, the numbers in bracktes - the other counters correspond to the
currently displayed subset of all games !)
- Previews can now also be displayed _inside_ the main widget - scaling is
also supported now; see menu View -> Preview !
- The context- (or quick-)menu is now available in ALL windows together with
the corresponding accelerator-keys for these functions
- When using Qt 3, Qt's own messages are redirected to the mamecat-log
- This will be the LAST version with Qt 2 support !!! Version 0.44 and above
will only work with Qt 3 ! This is due to a planned major redesign of most
(if not all) dialogs using Qt's GUI designer.
v0.42
- Qmamecat now starts up in GUI mode ONLY, there is no console output any
longer - now everything is logged to the new logfiles instead (see
<tempdir>/xmame-session.log, <tempdir>/mamecat-session.log and the new
log-windows !)
- The parser has been enhanced to additionally determine "manufacturer" and
"year" for each ROM; this has been successfully tested with xmame-0.36.1
(latest "final"), -0.37b11.1 and -0.37b11.2. If you experience any trouble
regarding the new infos with your xmame version, I'd appreciate some
feedback (including the xmame version you're using) !!!
- If you tend to often switch between 2 or more different xmame versions
("different" means: supporting different games !) you should note that
this finally works fine now ;-)
v0.41
- Qt 1.4x and Qt 2.0.x are no longer supported, you need Qt 2.1.0 (or above)
from now on to compile and run qmamecat !!! The main reasons for this step
are the new preview check dialog, which uses some Qt 2.xx features which are
incompatible with Qt 1.4x and the new font determination code (which
requires Qt 2.1.0 at least). Sorry, if that bothers anybody.
- The makefile-structure has been totally reworked. Please see section 3
for more information.
- We now also support FreeBSD besides Linux and SunOS (see doc/CREDITS for a
list of OS-specific maintainers, others welcome !!!)
- Due to all these changes we had to end support for the the curses-version !
- The new qmsetup tool should NOT be started manually, it won't work
correctly in this case (exit immediatly if accidently started); it is
launched by qmamecat ON DEMAND if needed.
12) Bugs and restrictions
- Please NEVER EVER iconify qmamecat (or switch to another virtual desktop),
while it is doing ANY intensive analysis AND showing a progress-dialog - it
most likely will freeze or even crash qmamecat !!!
We don't know yet what the reason is, but suspect a Qt bug. This has been
seen with Qt 2 and 3 on different platforms (Linux, SunOS) and window
managers (KDE, CDE) !
- If you change between internal/external preview TOO FAST, the position of
the external window might not be determined correctly. As this can only
happen by holding down the accelerator keysequence ALT+I and with a very
short key repeat rate, this bug can be considered of minor importance...
13) License
MAMECAT is distributed under the GNU General Public License (version 2 and
above). For more information please take a look at the file COPYING (should
be in this directory; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA).
The unzip-code (unzip.[ch], inflate.[ch] and types.h in src/unzip) has been
taken from xmame's source. AFAIK, the original code is copyrighted by Mark
Adler - if this is wrong or we are missing somebody, please let us know !!!
Have fun,
The MAMECAT-Team
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
8720929f74e4af3cf88e3b2dcc962b13
>
files
>
8
