hi2txt allows to convert mame (and similar emulators) high scores files (hi/nvram binary files) into readable text files, targeting integration into third party software like frontend (see below screenshot), or centralized leaderboard sharing friends score.

It is written either in Java 7+ or either in CSharp (dotNET 4.5+), depending on the version you choose.

The functionality is completely inspired from the hitotext tool created by Fyrecrypts, even if all the code have been written from scratch, as well as the XML syntax. A huge thanks to all these guys for the unbelievable amount of work achieved by decoding many many many games hiscores! Note that hi2txt doesn't allow writing/formating hiscores at all, which remains an exclusive feature of hitotext :)

Why another tool? First, for my own pleasure as a hobbyist, allowing high scores display in my personal mame cabinet front-end and increasing my programming skills. Then because high score competition is the heart of Arcade games along with 1-CC! Finally to learn from the experience of hitotext, keeping this wonderful functionality alive.

• No game-specific decoding algorithm hard-coded
• Fully scriptable using XML and a flexible syntax
• Easy update: one XML description file per game
• Automatic decoding selection if different hiscores structure for the same game
• Big integer support for very high high score
• Read high scores (no Write)

If you appreciate the tool, all possible help to support more games and suggest new features, is warmly welcome, or at least a little thank you !
This software is dual-licensed as postcard-ware and screenshot-ware: either send me a postcard from your town and/or a screenshot of your high scores displayed using hi2txt on your Cab/PC/whatever :)
(see 'Contact' section)

Native high scores
Mame is a game emulator
It is working with ROMs of the supported games
If a game has a native support for saving high scores, mame saves them inside the related nvram file (non volative random access memory)
     mame/nvram/<game>/<nvram_file>
Iif a game doesn't natively support high scores saving... the high scores are not saved :)

Unofficial high scores
Saving high scores for these games is a non standard feature, not supported officially by mame
To activate it:

• get a derivative builds of mame compiled with the hiscores patch
• get a hiscore.dat file describing to the mame patch, for each supported game, where is the memory location to read/write to save/load hiscores
• put the hiscore.dat file in the same directory than mame executable

Alternatively, from native mame 0.172+, a hiscore plugin is embedded and is compatible with hi2txt 1.7+.

Iin this case, mame saves the high scores inside the related hi file
    mame/hi/<game>/<game>.hi
Note that hiscore.dat file doesn't support yet all mame games

Reading high scores
High scores in nvram and hi files are stored using game-specific format
A specific description of the nvram/hi files content is needed to understand how the high scores are stored and consequently display them is user-friendly format like text
A game supported by hi2txt means that a specific description exists
    hi2txt/db/<game>.xml
Note that hi2txt doesn't support yet all hiscore.dat games

Task: extract hiscores in text format
hi2txt.bat -hiscoredat <hiscore.dat_file> [-descr <descriptions_directory>] [-trace | -notrace] -r <hi_file_path>
  ex: hi2txt.bat -hiscoredat <mame_installation>/hiscore.dat -r <mame_installation>/hi/ddonpach
  output example:
RANK|SCORE|NAME|AREA|SPACESHIP|POWERUP|MAXHIT
1|468395520|PIE|ALL|RED|SHOT|359
2|5908065|OSD|1|BLUE|LASER|96
3|5637680|PIE|2-3|GREEN|SHOT|139
4|5544337|H.S|1|BLUE|LASER|96
5|3027206|PIE|5|RED|SHOT|170

Task: extract hiscores and extra data in text format
hi2txt.bat -hiscoredat <hiscore.dat_file> [-descr <descriptions_directory>] [-trace | -notrace] -ra <hi_file_path>
  ex: hi2txt.bat -hiscoredat <mame_installation>/hiscore.dat -ra <mame_installation>/hi/ddonpach
  output example:
RANK|SCORE|NAME|AREA|SPACESHIP|POWERUP|MAXHIT
1|468395520|PIE|ALL|RED|SHOT|359
2|5908065|OSD|1|BLUE|LASER|96
3|5637680|PIE|2-3|GREEN|SHOT|139
4|5544337|H.S|1|BLUE|LASER|96
5|3027206|PIE|5|RED|SHOT|170

TOP SCORE
468395520

Task: list supported games
hi2txt.bat [-descr <descriptions_directory>] -l [-location]

Task: get version
hi2txt.bat -v

Task: get help
hi2txt.bat -h

all command-line parameters

A new xml description file must be added into the description database.
This description needs to describe how to extract the meaningful data in text format from the game related hi and/or nvram files.
The description language is in xml, using specific tags.

Recommended methodology to build a hiscores description:

• run the game in the emulator
• wait for the high scores table display and take a screenshot (F12 by default)
  • for some games, you can display multiple high scores tables: try to hit BUTTON1, LEFT, RIGHT, TOP, BOTTOM to display all of them
• if no relevant high scores yet, play the game a couple of times to add some high scores
• if it is too hard to have a high scores, cheat.dat support is your friend
  • get cheat.7z and put it in the same directory than the emulator executable, in compressed format
  • activate cheat in mame.ini (cheat 1)
  • mame.ini can be created by running mame.exe -cc
  • when playing the game, open settings (TAB) and go to the cheat section to activate the cheat you need
• if it is too long to wait for the high scores table display, or to conclude a play, increase emulation speed (F10 by default)
• quit the emulator
• a hi and/or nvram file should have been created in the related directories of the emulator
• the hi/nvram file must matches the screenshot, allowing you to validate what you try to extract
• understand how the data are stored in the hi/nvram file
• describe the data, from the template in <hi2txt>/db/_template.xml, using syntax described in the XML description reference (see link below)

• dodonpachi
• astdelux
• ...

hi2txt at free.fr