Difference between revisions of "EmulatorsPlugIn"

From AwkwardTV
Jump to: navigation, search
Line 125: Line 125:
* '''left-button-script''' (optional) : An AppleScript that will run when the left key is pressed.
* '''left-button-script''' (optional) : An AppleScript that will run when the left key is pressed.
* '''right-button-script''' (optional) : An AppleScript that will run when the right key is pressed.
* '''right-button-script''' (optional) : An AppleScript that will run when the right key is pressed.
* '''file-extensions''' (optional) : A comma separated list of which file extensions to display in ROM list.
* '''file-extensions''' (optional) : A comma separated list of which file extensions to display in ROM list.  All files which do not end in these extensions will be filtered out of the ROM list.

Revision as of 01:15, 19 February 2009

Note: Version 1.4 is the first version to be compiled with the new BackRow.framework from AppleTV 2.3 (Details here: BackRow_2.3). The screen release bug is fixed, and new features are PNG artwork, additional AppleScript support, and file extension filtering. AppleTV 2.0 - 2.2 users should use version 1.3.

--Bgan1982 08:58, 19 February 2009 (CET)


bgan1982@mac.com (Ben)


  • This plugin provides a clean front-end for launching emulators for Apple TV 2.x with minimal overhead.
  • Users may add or remove emulators by editing a .plist file (see "Configuration" below).
  • It is very similar to the way the AppLauncher plugin worked for Apple TV 1.0.
  • My source code is very tiny, and may also give people a good starting point for creating their own plugins.

Download Links

Old Versions:

Installation Instructions

Step 1. Install the latest versions of these emulators on your Apple TV in the following locations:

  • /Applications/Boycott Advance.app
  • /Applications/Genesis Plus.app
  • /Applications/Mugrat.app
  • /Applications/Nestopia.app
  • /Applications/sixtyforce.app
  • /Applications/Snes9X.app

For additional features with some of these emulators, also install Emulator Enhancer:

  • /Users/frontrow/Library/Application Support/Emulator Enhancer/EmulatorEnhancer.bundle

Note: This software addition will cause a registration window to appear when launching any of Richard Bannister's programs. Those programs are all of the above listed ones, except sixtyforce and Snes9X. If you're not a registered EmulatorEnhancer user, read below in the configuration section on how to specify an AppleScript that will automatically close this window.

Step 2. (Optional) In order to preconfigure the emulators before running them with the plugin, I have created a shell script to toggle the Finder on or off. Make sure the script is executable, and install it somewhere in your $PATH. For instance:

  • /usr/bin/toggleFinder

In addition, add the following to your /etc/rc.local file, so that the Finder will always run when your appletv is rebooted:

       # Make sure Finder.app is active upon startup
       /usr/bin/toggleFinder -t
       if [ $? -ne 0 ]; then /usr/bin/toggleFinder; fi

Step 3. Using VNC (example client: Chicken of the VNC), MouseLocator, and ssh, launch and configure each of the emulators so that they have the proper settings. For instance, using my optional script from step 2:

       [frontrow@AppleTV:~] $ toggleFinder
       toggleFinder: Switching Finder ON -> OFF
       toggleFinder: Killing Finder
       [frontrow@AppleTV:~] $ open -a Nestopia

<Use a VNC client to setup the correct preferences, then choose Quit>

       [frontrow@AppleTV:~] $ toggleFinder
       toggleFinder: Switching Finder OFF -> ON
       toggleFinder: Launching Finder

For the emulators' settings, make them appear full screen when ROMs are loaded, but make sure you DO NOT check any options for changing resolution, as this causes serious display problems. If you have a USB controller, configure it now. Make sure the emulators exit cleanly using "Quit", so their preferences are retained.

Note: If watchdog reboots your Apple TV, that means you took too long. If you'd like, follow the directions to disable AppleTCOWatchdog.kext to prevent unwanted automatic reboots. However, I'd recommend re-enabling this after step 3 is complete.

Step 4. Copy the ROMs you wish to install into the following directory structure on your Apple TV:

  • /Users/frontrow/ROMs/Coleco
  • /Users/frontrow/ROMs/GBA
  • /Users/frontrow/ROMs/Genesis
  • /Users/frontrow/ROMs/N64
  • /Users/frontrow/ROMs/NES
  • /Users/frontrow/ROMs/SNES

Step 5. Install the Emulators.frappliance in the Finder's plugins folder:

  • /System/Library/CoreServices/Finder.app/Contents/PlugIns/Emulators.frappliance

Then restart the Finder.


This plugin is pretty self-explanatory. Just select the emulator you wish to run, and it will bring up a ROM list. Select the ROM, and it will launch the emulator.

While the emulator is running, the buttons on the remote do the following:

  • MENU - Quit emulator and return to main menu
  • PLAY - Restart emulator
  • UP,DOWN,LEFT,RIGHT - Run scripts (see configuration section).

To display artwork in the ROM list, simply put PNG files in the same directory. For example, game.nes will look for game.png in the same directory.


If you'd like to add or remove emulators from this plugin, you must modify the category list, which is now found in the following preferences file:

  • ~/Library/Preferences/com.bgan1982.EmulatorsPlugIn.plist

Caution: If you are unfamiliar with XML and modify this file incorrectly, it will probably break the plugin and/or crash FrontRow. If you screw up, just trash this file, and the next time Front Row starts, it will create a new plist with default values.

You can add a new emulator by adding a new <dict></dict> tag inside the FRApplianceCategoryDescriptors <array>. Here are what the different keys mean:

  • identifier : The actual executable name of the emulator.
  • name : The system name that will appear in the menu.
  • path : The full path to ROMs folder for the current system.
    • If this tag is missing or empty, it will run the executable without bringing up a ROM list to choose from.
  • preferred-order : A real number which gives the order of the categories; make sure these are unique.
  • startup-script (optional) : An AppleScript that will run as soon as the executable is launched.
  • up-button-script (optional) : An AppleScript that will run when the up key is pressed.
  • down-button-script (optional) : An AppleScript that will run when the down key is pressed.
  • left-button-script (optional) : An AppleScript that will run when the left key is pressed.
  • right-button-script (optional) : An AppleScript that will run when the right key is pressed.
  • file-extensions (optional) : A comma separated list of which file extensions to display in ROM list. All files which do not end in these extensions will be filtered out of the ROM list.

Note: For AppleScripts to work properly,

  • The following AppleScript components must be installed (for example, from the 1.0 recovery partition)
  • UI Scripting must be enabled. This can be accomplished with the command
     sudo touch /private/var/db/.AccessibilityAPIEnabled

Here is an example of adding an AppleScript to get rid of the EmulatorEnhancer dialog box:

             delay 5
             tell application "System Events"
              tell process "Nestopia"
                click button 2 of front window
             end tell
             end tell

Here is an example of adding MAME:

         <string>MAME OS X</string>

(Note: MAME OS X as of version 0.124 doesn't seem to run properly on Apple TV 2.3, and crashes at game launch.)

Known Bugs

  • Emulators PlugIn 1.4 won't show up in AppleTV 2.0-2.2.
  • Subfolders don't work yet

Version History

  • 1.4 2/19/09
    • Compiled against new BackRow 2.3 frameworks (Details here: BackRow_2.3)
    • Once again fixed blink back to menu bug
    • Implemented artwork for PNG files in ROM directory
    • Additional AppleScript support for up,down,left,right keys
    • Removed file extensions from ROM list; added file-extensions tag in plist
    • Automatic enabling of UI Scripting
  • 1.3 2/10/09
    • Fixed problem with AppleTV 2.3, but this causes the blink back to menu bug to return :(
    • AppleScript support
    • Specifying a blank path will run an app without bringing up a ROM list
  • 1.2 2/5/09
    • Play button restarts emulator, Menu button quits
    • FINALLY fixed blink back to menu bug
    • User configurable preferences in ~/Library/Preferences/com.bgan1982.EmulatorsPlugIn.plist
  • 1.1 12/3/08
    • Eliminated rungame.sh script
    • Used NSWorkSpace to access LaunchServices
    • Filtered out hidden files from ROM list
    • Switched zsnes with Snes9X
    • Pressing either menu or play will quit a running emulator
  • 1.0 6/27/08
    • Initial Release

Future Work

  • More features
  • User configurable controls


This plugin and its source code are free to all. You may modify it to your liking, but I would still like to maintain any "official" releases. This software comes with no implied warranty, and I am not responsible for any damages.


I was only able to write this plugin by being able to view and tinker with publicly available source codes of many other Apple TV plugin projects. Many thanks go out to the developers of the following projects: