openMSX Launcher

openMSX Launcher v1.6

openMSX Launcher is a front-end for openMSX written in Java, and runs on Windows, MacOS, Linux and BSD.

After starting the launcher for the first time, you need to set a few fields in the settings window.

First time installation

Windows: unzip the Windows package anywhere on your system.

MacOS: open the downloaded DMG and drag "openMSX Launcher.app" into your "Applications" directory.

Linux/BSD: unzip the Linux/BSD package anywhere on your system.

Upgrade from version 1.5

Databases created in previous versions are fully compatible with the current version.

Windows: You can upgrade from within the 'Help->Check for Updates' window. After you install, you need to restart the launcher. Before restarting though, you also need to replace the 'openMSX Launcher.exe' file, which you can extract from the ZIP file that you can download from msxlaunchers.info. You do not need to perform this manual step in the future as the upgrade system in version 1.6 was enhanced. Don't forget to upgrade the extra-data file from the 'Help->Check for Updates' window after the upgrade.
Yet another way to upgrade is to download the ZIP package from msxlaunchers.info and unzip it anywhere on your system. You can then replace the old exe, extra-data.dat and README.html files with the new versions. Leave everything else untouched.

MacOS: You can upgrade from within the 'Help->Check for Updates' window, but it is highly recommended though to trash the current openMSX Launcher app folder and replace it with the new one from msxlaunchers.info as if this is a first time installation. All launcher data will be preserved since they are stored on the user folder outside of the app folder. In future upgrades you do not need to perform this complete reinstallation step as the upgrade system in version 1.6 was enhanced.

Linux/BSD: You can upgrade from within the 'Help->Check for Updates' window. After you download, also replace the 'openmsx-launcher.run' file, which you can extract from the ZIP file that you can download from msxlaunchers.info. Restart the launcher for the changes to take effect. In future upgrades you do not need to perform this complete reinstallation step as the upgrade system in version 1.6 was enhanced. Don't forget to upgrade the extra-data file from the 'Help->Check for Updates' window after the upgrade.
Yet another way to upgrade is to replace the entire openMSX Launcher folder with the new one that you can get from msxlaunchers.info. All launcher data will be preserved since they are stored on the user folder outside of the launcher folder.

How to start

Windows: double-click on the exe file.

MacOS: double-click on the application icon.

Linux/OpenBSD: type and enter openmsx-launcher.run in a terminal window. In a GNOME environment you can create a shortcut to the launcher.

Settings

1) Emulator and machines directories:

Note: the detect button will 'suggest' the path to the openMSX based on the platform. Try that first, and if that doesn't work you can enter it manually.

Windows:

Emulator: <Path>\

Mac:

Emulator: /Applications

Linux (Debian, fedora, ubuntu):

Emulator: /usr/bin

FreeBSD

Emulator: /usr/local/bin

2) Screenshots: This is the directory where game screenshots can be found. This collection of screenshots is the one used by blueMSX Launcher, and can be downloaded from: http://msxlaunchers.info.

3) Database: This is the database to display automatically when the launcher is started.

4) Language: openMSX Launcher supports many languages. When the launcher is started, it will try to detect the language of the system automatically. If that fails (i.e. if it still uses English text even if your system language is different), you can force the language selection here.

Fill Database

This is a tool that scans your storage drive for MSX software supported by openMSX and adds it to the launcher databases.

Favorites

Favorites button is located above the four main buttons. When pressing it, a menu containing the currently saved favorites appears. You can go straight to your favorite game by selecting one from the list. You can also delete the favorite there as well.

Filters

Filters button can be found under the game list. When pressing it, a menu pops up with a list of saved filters, small buttons to either delete or edit saved filters and options to reset current filters and add new ones.

Search

Search button is located above the four main buttons. When pressing it, a text field appears. Enter any part of the name of the game or first few or all of SHA1 code. Search is case insensitive. SHA1 code search is useful if you want to locate a game by its SHA1 code to apply patches to it. As you type, a list of matches appears. Select the game you're looking for by mouse click or use arrow and enter keys to select it.

Note: mouse clicks don't work on Ubuntu, the only Linux flavour that was tested. This could be a bug in the implementation that hasn't been identified yet. Use the keyboard instead.

Update All Databases

Note: starting from version 1.6 this feature is hidden by default. Check appendix A for details.
This is a tool that updates extra data for games in all databases (including update display of screenshots) when there's a new version of the extra-data.dat file and screenshots. It will also fix a bug that existed in versions 1.0 and 1.1 where some fields were not set correctly when using the 'Fill database' feature.

Right-click context menu

When right-clicking on one or more selected profiles in the games list, a context menu appears with the followig items:

1) Move: this allows you to move the selected profiles to other databases. A confirmation dialog with many options appears in case of conflicts.

2) Locate File: this only works on a single selection and it brings up the current platform's file manager. File Explorer on Windows and Finder on MacOS will open up with the profile's main file highlighted. On Linux running GNOME, nautilus will open up with the directory where game's main file is.

3) Add to Favorites: add the selected game to the list of favorites. The list is accessible through the favorites button in the main window.

4) Info: this displays the user-specified info file using the system's default viewer. In the "Fill Database" feature, this field gets set to the game's MSX Generation page, but it can be anything the user desires (text file, PDF, etc).

5) Properties: this only works on a single selection and it brings up the properties screen for the selected game.

Database Manager

This can be accessed from the Tools menu. There you can rename or delete existing databases. You can also view, restore or delete backups. Backups are identified by their timestamps.

Drag and Drop

You can drag and drop game files and directories to the main launcher window for quick adding to the current database.

Keyboard short-cuts

Windows / Linux / BSD	Mac	Action
Enter	Enter	Launch
Del	Del	Remove profile button
Insert	Insert	Add profile button
Ctrl+E	Command+E	Add profile button
Ctrl+F	Command+F	Show search field
Ctrl+D	Command+D	Add to favorites
Ctrl+I	Command+I	Show list of favorites
Ctrl+L	Command+L	Show list of filters
Ctrl+R	Command+R	Reset filters
Ctrl+X	Command+X	Move profile
F1	F1	Info button
Ctrl+Shift+F	Command+Shift+F	Locate file
Ctrl+F1	Command+F1	Properties

To do in future versions

1) Revamped User Interface.

2) Catapult features.

3) User-defined fields.

4) Play stats.

Support/Suggestions/Questions/Translation fixes/New translations

Email Sam Elsharif at oelsha at engineer dot com.

Release history

Version 1.6 - released May 1, 2016

Enhancements:

Added search for games by name or SHA1 code
Improved keyboard support and added more keyboard shortcuts
Removed 'Update all databases' from Action menu and incorporated the functionality in the upgrade system. Instructions on how to enable it are in the help file

Bug fixes:

Enhanced the in-line upgrade system (accessible through 'Help->Check for Updates')
Fixed many minor bugs

Version 1.5 - released October 17, 2015

Enhancements:

Switched to JDK 8. Now Java Runtime Environment 8 or higher is needed to run the launcher
Added support for viewing, deleting and restoring database backups
Drag and drop game files and directories on the main window of the launcher for quick adding to the current database

Bug fixes:

Fixed many minor bugs

Version 1.4 - released Feb 7, 2015

Enhancements:

Added favorites support
Added ability to check for updates from within the launcher and the ability to update automatically
Made changes to main window
Allow only one instance of the launcher to run

Bug fixes:

The extensions list in the Add/Edit profile was not showing the extensions for the latest versions of openMSX after the switch from directories to XML files. This should work now for all versions of openMSX. There is similar to the machines listing bug that was fixed in the previous version of the launcher

Internal changes:

Switched to an embedded database (Apache Derby) from CSV files to store launcher data. All user's CSV files are migrated to the new embedded database automatically when new launcher is started for the first time
Old backups are deleted. The new version allows to take backups but they still cannot be restored

Version 1.3 - released July 6, 2014

Enhancements:

Switched to JDK 7. Now Java Runtime Environment 7 or higher is needed to run the launcher
Added Database Manager to rename or delete databases
Simplified the settings window by removing the machines field and adding a button to detect the openMSX path (Note: Mac users need to set the openMSX path value to /Applications or the directory where the launcher is installed)
The update all databases tool now returns the number of updated profiles
Added keyboard short-cuts
Added a tool to import blueMSX Launcher databases (only for the Windows version)
Added total known dumps to the profile properties window

Bug fixes:

The machines list in the Add/Edit profile and Fill Database screens was not showing the machines for the latest versions of openMSX after the switch from directories to XML files. This should work now for all versions of openMSX

Version 1.2 - released May 4, 2014

Enhancements:

Added ability to filter databases by company, year, country, medium, size, MSX generation, sound chip and genre
Added game properties in the right-click contect menu
Added ability to update game extra data in all databases. Useful when there's a new version of the accompanying extra-data.dat file
Added slight display improvements to the Mac version
Added ability to select a game in the list by typing the first few letters of its name

Bug fixes:

Some fields set internally in the game profile (and only now displayable in the new properties screen) were not correct. The new 'Update all databases' feature fixes that automatically

Version 1.1 - released Sep 7, 2013

Enhancements:

Added ability to move games between databases via the right-click context menu
Added ability to bring up the platform's file manager (File Explorer on Windows, Finder on MacOS, etc) via the right-click context menu
Added menu item in the Help menu to bring up the help file
Added ability to create empty databases
Added a bar above the game list to show company, year and size of file of the selected game
File fields in Add/Edit screens now support drag and drop of files
If a script is defined in the profile then it will override all other fields when openMSX is launched
Many other minor enhancements

Bug fixes:

When adding a new game or editing a new one, the recorded size for ZIP files, which is stored in the database, is wrong. This will be seen with this new version where the size displayed in the bar above the game list will be that of the ZIP file rather than the original size. In order to fix it, just edit the game and save immediately without modifying any other fields

Version 1.0 - released Jul 8, 2013

Create multiple databases of all MSX software supported by openMSX
Scan the hard disk to automatically fill launcher databases with ROMs, disks, tapes, hard disks and laserdiscs, and sync the database to your hard disk any time later. Display two screenshots for each game
Display the text on the launcher using a number of supported languages (English, Arabic, Catalan, Chinese Simplified, Chinese Traditional, Dutch, Finnish, French, German, Italian, Japanese, Korean, Persian, Portuguese, Russian, Spanish and Swedish)

Appendix A - Update all databases

This feature is disabled by default starting from version 1.6. It was needed everytime you made changes to the extra-data.dat file (this file contains SHA1 code mapping to MSX generation, sound chip and genre) to update internal launcher data. There are two ways to update the file: download it through the launcher upgrade or manually if there's a new version posted on the msxlaunchers website, or update it yourself to add your own dumps. It was deemed that the only common way to update the extra-data.dat file is through the launcher upgrade system, and through that method the internal data are updated automatically upon a successful download and upgrade. If you still need to update the databases manually, you can get the menu item to appear by adding the followng line to the launcher's settings-oml.ini file (location depends on platform):

showUpdateAllDatabases=true

and restart the launcher.