This is yet another addon for handling, browsing, and launching emulated games.
There are a few similar addons, such as RCB and ALA (though I didn't realize ALA existed until after I had started building this), but none worked quite the way I wanted them to. So I wrote my own! As such, this was not a humongous and ambitious project, but the goal was rather simply to make something that fit my needs. I figured that others might make use of this as well, and I am thus releasing it here.
Since I have not been involved at all in XBMC before (as a side note, XBMC is the single worst documented platform I've ever coded for), and do not have an excessive knowledge of Python, I have made some beginner mistakes that I would rather have avoided. But the end result works for my uses at least.
Since I am a sucker for consistency, and use Confluence myself, the addon tries to mimic the look and behavior of Confluence as closely as possible.
Anyway, I worked a solid two-three weeks or so to make this add-on (mostly wrestling with XBMC to make it do what I want), and I hope you guys find some use in it as well.
Download link
Version 0.2.4 (latest)
Latest changes
0.2.4
Feature overview
How to use
First of all, the add-on has been made exclusively for Windows! I do not have an xbox, nor a front-end mac/linux machine to run XBMC on. Therefore, though platform independent alternatives have been chosen where applicable, the add-on is likely not to work very well on non-Windows platforms. It could likely be modified to work on other platforms relatively easily, but I am not currently in a position to do this.
So, assuming you run Windows, the second requirement is that you run XBMC Dharma, preferably RC1 or later. Most of the testing has been done on Dharma RC2.
The first time you run the add-on, a dialog will pop up notifying you that you have not defined any collections. The settings dialog will then be opened. Once here, navigate to the Collections category. You should define one collection per platform (that is, one NES collection, one SNES collection, etc).
Defining your collections
To define a collection, first enable one. Some additional settings should then pop up, namely Console, ROM folder, ROM file extension, Emulator executable and Emulator arguments.
The console setting defines what platform the ROMs belong to. This roughly corresponds to the list of platforms on GiantBomb.com for simplicity.
The ROM folder should be set to the folder containing your ROMs.
The ROM file extension is a comma separated list of your ROM file extensions. If all your ROMs have the same file extension, simply enter that. My NES collection consists entirely of .7z files, so I enter "7z" as the ROM file extension. My PSX collection, however, contains both .bin files and .img files, so I enter "bin,img" as the ROM file extension.
The emulator executable should point to the .exe file of your emulator of choice.
The emulator arguments are the command line arguments that are passed to the emulator at run-time. %ROM% is replaced by the ROM path, within quotes (to properly handle spaces in paths).
Congratulations! You have now defined a collection. Now repeat this for all your platforms. Because XBMC currently only supports 100 settings per category, there is currently a hard coded limit of 15 collections.
Importing your collections
Now that you have defined your collections, you can launch the add-on again. This time, it will notify you that there are currently no games in the database, and ask you if you want to import them. Importing the games simply means reading the defined ROM folders, and saving them in the database.
This can also be done manually via the add-on settings, by selecting "Import collections" in the General settings category.
Optional: Scraping your collections
Once you have imported your collections, the add-on will ask you if you want to automatically scrape these for data. This means fetching stuff like images, genres, description, etc from the GiantBomb.com wiki. Note that this will take a VERY long time if you have many games! In general, it takes somewhere between 2 and 10 seconds per game. That amounts to quite a bit if you have many games.
Done!
You should now, barring any unforeseen catastrophe, be able to browse, launch, and play your games. Enjoy!
What do the settings do?
The general settings window currently contains 6 entries.
Thanks to
Props to malte for his Rom Collection Browser. Because of XBMCs aforementioned lack of documentation, I have more than once consulted his source code for working examples of things.
Also thanks to henks for letting me use his awesome photograph as a background (sorry for massacring it to fit).
Known bugs
Possible future features
Screenshots
An image showing the browse view
Another image of the browse view, this time showing a game that has been marked as "played".
An example of how the collections settings might be entered. Here you see an example of the "trickery" required to get PC games to work properly - the "ROMS" are simple windows shortcuts (.lnk files) to the game executables. When the emulator executable field is left blank, the shortcut will be launched, which in turn will launch the game.
There are a few similar addons, such as RCB and ALA (though I didn't realize ALA existed until after I had started building this), but none worked quite the way I wanted them to. So I wrote my own! As such, this was not a humongous and ambitious project, but the goal was rather simply to make something that fit my needs. I figured that others might make use of this as well, and I am thus releasing it here.
Since I have not been involved at all in XBMC before (as a side note, XBMC is the single worst documented platform I've ever coded for), and do not have an excessive knowledge of Python, I have made some beginner mistakes that I would rather have avoided. But the end result works for my uses at least.
Since I am a sucker for consistency, and use Confluence myself, the addon tries to mimic the look and behavior of Confluence as closely as possible.
Anyway, I worked a solid two-three weeks or so to make this add-on (mostly wrestling with XBMC to make it do what I want), and I hope you guys find some use in it as well.
Download link
Version 0.2.4 (latest)
Latest changes
0.2.4
- Fixed bug regarding emulator paths that had spaces. I had forgotten to properly escape these.
- Fixed bug where XBMC would not wait until the emulator had terminated until maximizing again.
- Fixed bug where context menu entries were invisible when using skins other than confluence.
- Turns out some emulators (looking at you, project 64) do not like quoted ROM paths. Thus, I added a %UNESCAPED_ROM% command line argument that does not add the surrounding quotes.
Feature overview
- All configuration is done via the built-in addon settings function, making it relatively simple to use
- Supports automatic scraping of title, image, short description, release date, and genres from GiantBomb
- Look-and-feel made to match Confluence as closely as possible, including the shift+letter "jump to" function. That is, if you hold shift and type "LEG", it will jump to the first game starting with "LEG". It supports letters from A-Z and space.
- Supports GoodMerge-style .7z files containing several ROMs. At launch, if the addon detects that the file is a 7z file, a select dialog pops up letting you choose which of the ROMs inside it to launch.
- Supports marking games as "played" (in the same style as XBMC lets you mark videos as "watched"), either automatically at launch, or manually through the context menu
- Though not entirely intended behavior, Emulatopia can handle regular standalone games as well, both to scrape and launch, with some slight trickery (more on this later).
How to use
First of all, the add-on has been made exclusively for Windows! I do not have an xbox, nor a front-end mac/linux machine to run XBMC on. Therefore, though platform independent alternatives have been chosen where applicable, the add-on is likely not to work very well on non-Windows platforms. It could likely be modified to work on other platforms relatively easily, but I am not currently in a position to do this.
So, assuming you run Windows, the second requirement is that you run XBMC Dharma, preferably RC1 or later. Most of the testing has been done on Dharma RC2.
The first time you run the add-on, a dialog will pop up notifying you that you have not defined any collections. The settings dialog will then be opened. Once here, navigate to the Collections category. You should define one collection per platform (that is, one NES collection, one SNES collection, etc).
Defining your collections
To define a collection, first enable one. Some additional settings should then pop up, namely Console, ROM folder, ROM file extension, Emulator executable and Emulator arguments.
The console setting defines what platform the ROMs belong to. This roughly corresponds to the list of platforms on GiantBomb.com for simplicity.
The ROM folder should be set to the folder containing your ROMs.
The ROM file extension is a comma separated list of your ROM file extensions. If all your ROMs have the same file extension, simply enter that. My NES collection consists entirely of .7z files, so I enter "7z" as the ROM file extension. My PSX collection, however, contains both .bin files and .img files, so I enter "bin,img" as the ROM file extension.
The emulator executable should point to the .exe file of your emulator of choice.
The emulator arguments are the command line arguments that are passed to the emulator at run-time. %ROM% is replaced by the ROM path, within quotes (to properly handle spaces in paths).
Congratulations! You have now defined a collection. Now repeat this for all your platforms. Because XBMC currently only supports 100 settings per category, there is currently a hard coded limit of 15 collections.
Importing your collections
Now that you have defined your collections, you can launch the add-on again. This time, it will notify you that there are currently no games in the database, and ask you if you want to import them. Importing the games simply means reading the defined ROM folders, and saving them in the database.
This can also be done manually via the add-on settings, by selecting "Import collections" in the General settings category.
Optional: Scraping your collections
Once you have imported your collections, the add-on will ask you if you want to automatically scrape these for data. This means fetching stuff like images, genres, description, etc from the GiantBomb.com wiki. Note that this will take a VERY long time if you have many games! In general, it takes somewhere between 2 and 10 seconds per game. That amounts to quite a bit if you have many games.
Done!
You should now, barring any unforeseen catastrophe, be able to browse, launch, and play your games. Enjoy!
What do the settings do?
The general settings window currently contains 6 entries.
- Automatically mark as launched - Enabling this will mark games as played as soon as you launch them.
- Use scraped titles instead of filenames - Enabling this will make the browser use scraped titles for games where applicable. If disabled, filename (without file extension) will be used instead.
- Import collections - This manually imports new collections. This is what is run when the add-on asks you to import games if the database is empty.
- Clean database - This will go through all paths in the DB and remove non-existent games. For example, if you have deleted a game, the game will remain in the list until you have run this command, whereupon it will be deleted.
- Empty database - This will remove ALL games and scraped data from the database, including images.
- Scrape games - This will start scraping all currently unscraped games. This is what is run when the add-on asks you if you want to scrape your games after importing.
Thanks to
Props to malte for his Rom Collection Browser. Because of XBMCs aforementioned lack of documentation, I have more than once consulted his source code for working examples of things.
Also thanks to henks for letting me use his awesome photograph as a background (sorry for massacring it to fit).
Known bugs
- I don't recommend putting very large files in 7z archives. It will most likely crash with an OutOfMemory error when trying to extract it, and even if it doesn't, it will likely be very slow.
Possible future features
- Ability to filter and sort the list by platform/title/date/genre/etc. Also perhaps a proper "search" for game pad users.
- I want to implement some way to manually influence the scraping. That is, perhaps an entry via the context menu that would allow you to enter search terms manually, choose a game from possible matches, choose image yourself, etc.
- Related to above; I want to implement a way to import locally stored data about games (images, description, maybe release date and genres as well)
- I also want to implement some region matching. Currently when scraping, it will check for the first release image that matches the same platform, without caring for region. This means you'll sometimes end up with US/JAP covers even when you might want the European ones, for example.
- On the same note, I want to implement some support for sorting the ROMs in a GoodMerge 7z file by region and/or "confirmed working" when choosing which ROM to launch
Screenshots
An image showing the browse view
Another image of the browse view, this time showing a game that has been marked as "played".
An example of how the collections settings might be entered. Here you see an example of the "trickery" required to get PC games to work properly - the "ROMS" are simple windows shortcuts (.lnk files) to the game executables. When the emulator executable field is left blank, the shortcut will be launched, which in turn will launch the game.
