From AwkwardTV
Revision as of 23:11, 27 June 2008 by Bgan1982 (talk | contribs) (Emulators PlugIn 1.0)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search




bgan1982@mac.com (Ben)
--Bgan1982 08:11, 28 June 2008 (CEST)


I set out to create a plugin that would give me a clean front end for launching emulators from appletv 2.0's interface. It works similarly to the way the AppLauncher plugin worked for the 1.0 interface.

Other than the name of the plugin and the current way of hard coding its category list, there is nothing to prevent this from being modified to serve as a more general purpose application launcher for appletv 2.0.

Download Links

[Emulators.frappliance PlugIn]
[Emulators.frappliance Source Code]
[toggleFinder script]

Installation Instructions

  1. Install the latest versions of the following emulators and put them in the following places on your appletv:
    • /Applications/Boycott Advance.app
    • /Applications/Genesis Plus.app
    • /Applications/Mugrat.app
    • /Applications/Nestopia.app
    • /Applications/sixtyforce.app
    • /Applications/zsnes.app
    For additional features with some of these emulators, also install:
    • /Users/frontrow/Application Support/EmulatorEnchancer.bundle

  2. (Optional) In step 3, you will need to run these emulators a first time before getting them to work with the plugin. To this end, I have created a shell script to toggle the Finder on/off. [Download here] Make sure it is executable, and install this 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 /Users/frontrow/bin/toggleFinder; fi

    Note: The toggleFinder script also requires killall to be installed somewhere in your path.
  3. Using VNC, MouseLocator, and ssh, launch and configure each of these programs to 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 VNC 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 change resolution because this causes problems. If you have a USB controller, configure it now. Make sure they exit cleanly using "Quit", so their preferences are retained. If watchdog reboots your appletv, that means you took too long. Note: If you'd like, follow the directions to disable AppleTCOWatchdog.kext to prevent unwanted automatic reboots, but I'd recommend re-enabling this after step 3 is complete.
  4. Copy the ROMs you wish to install into the following directory structure on your appletv:
    • /Users/frontrow/ROMs/Coleco
    • /Users/frontrow/ROMs/GBA
    • /Users/frontrow/ROMs/Genesis
    • /Users/frontrow/ROMs/N64
    • /Users/frontrow/ROMs/NES
    • /Users/frontrow/ROMs/SNES

  5. Install the Emulators.frappliance to your appletv PlugIns folder:
    • /System/Library/CoreServices/Finder.app/Contents/PlugIns/Emulators.frappliance

  6. Restart the Finder.


This plugin is pretty self-explanitory. 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. Press the play button while the emulator is running in order to quit. This brings you back to the main menu.

Known Bugs

If you can hear the emulator but not see it, then unfortunately you need to try launching it again. When this happens, just fondly think back to all the time you spent getting your 8-bit nintendo cartridges to work without producing a similar blinking screen.

I've also put in a hook to the RIGHT remote button which reloads the screen while the emulator is running, but alas this usually doesn't get it to appear on top.

Future Work

  • Stop the dreaded "blink back to menu" behavior. There is some kind of race condition which prevents the emulators from appearing on top of the appletv menu, depending on the timing of the BRDisplayManagerStopRenderingNotification notification.
  • Filter out hidden files from ROM list
  • Populate category list from external plist file for user customizable configurations
  • Eliminate the rungame.sh script and use NSWorkSpace to access LaunchServices instead

Version History

  • 1.0 6/27/08 Initial Release


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 appletv plugin projects. Many thanks go out to the developers of the following projects:

  • AppLauncher
  • atvfiles
  • FRAppliance200
  • iscripts
  • sapphire