EmulatorsPlugIn

From AwkwardTV

Jump to: navigation, search
emulators.png

Latest Update: Version 2.1 has these new features:

  • Support for AppleTV 2.4
  • Added "type" plist-tag for launching scripts/tools
    • Working with SDL-MAME
  • Fixed flickering behavior upon returning to FrontRow
  • Added Reboot AppleTV Option

--Bgan1982 19:01, 24 July 2009 (CEST)

Contents

Author

bgan1982@mac.com (Ben)

Purpose

  • 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

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
  • /Applications/zsnes.app


(Optional). For additional features with Bannister's emulators, also install Emulator Enhancer:

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

Note: If you see a registration window and are not a registered EmulatorEnhancer user, read below in the configuration section on how to specify an AppleScript that will automatically close this window. However, I highly recommend becoming a registered user.


(Optional). For MAME support, install:

  • Recommendations:
    • ln -s /Users/frontrow/ROMs/MAME /Applications/sdlmame0122-intel-nodebug/roms
    • In mame.ini, under video options change "soft" to "opengl".


Step 2. 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/MAME
  • /Users/frontrow/ROMs/N64
  • /Users/frontrow/ROMs/NES
  • /Users/frontrow/ROMs/SNES

As of version 2.0, you can now have sub-folders.


Step 3. Install the EmulatorsPlugIn into the PlugIns folder:

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


Step 4. Restart FrontRow:

  • kill `ps ax | awk '/Finder/ && !/awk/ {print $1}'`


Step 5. Set your Emulators to have desired settings such as Full Screen, Controller Map, etc. You can use my default settings by selecting:

  • Options -> Reset Emulators Preferences


Now you should be good to go.

Usage

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.

Configuration

To add additional Emulators, ROM folders, other Applications, AppleScripts, and other options, edit the EmulatorsPlugIn Preferences file:

  • /Users/frontrow/Library/Preferences/com.bgan1982.EmulatorsPlugIn.plist


It is initially created with my default values, and can be erased and reset at any time by selecting:

  • Options -> Reset PlugIn Preferences


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 executable name of an emulator.
  • name : The emulator 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.
  • type : (optional) : "application" (default), or "script"
  • alt-identifier (optional) : Executable name of a child process.
    • For example, ZSNES.app launches the 'zsnes' process.
  • 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)
     /System/Library/CFMSupport
     /System/Library/Components/AppleScript.component
     /System/Library/Components/DictionaryService.component
     /System/Library/CoreServices/CarbonSpellChecker.bundle
     /System/Library/Frameworks/AppKitScripting.framework
     /System/Library/Frameworks/AppleScriptKit.framework
     /System/Library/Frameworks/Scripting.framework
     /System/Library/Frameworks/OSAKit.framework
     /System/Library/PrivateFrameworks/AppleScript.framework
     /System/Library/ScriptingAdditions
  • 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:

    <dict>
         <key>identifier</key>
         <string>Nestopia</string>
         <key>name</key>
         <string>Nintendo</string>
         <key>preferred-order</key>
         <real>100</real>
         <key>path</key>
         <string>/Users/frontrow/ROMs/NES/</string>
         <key>startup-script</key>
         <string>
             delay 5
             tell application "System Events"
              tell process "Nestopia"
                click button 2 of front window
             end tell
             end tell
         </string>
    </dict>

Known Bugs

  • Email me if there's a bug that you know how to reproduce.

Version History

  • 2.1 7/24/09
    • Support for AppleTV 2.4
    • Added "type" plist-tag for launching scripts/tools
      • Working with sdlmame
    • Fixed flickering behavior upon returning to FrontRow
    • Added Reboot AppleTV Option
    • Fixed memory leak for allocation of menu controllers from appliance.
  • 2.0 6/20/09
    • Sub-folders are now implemented
    • Huge increase in speed (fast memory deallocation)
    • Simplified applescripting with .pathToROM temp file
    • Fixed a bug causing slow display of large ROM folder
    • Added alt-identifier tag
    • Added About Emulators PlugIn... Option
    • Removed EnableQuartz Option
  • 1.4.1 4/15/09
    • a new defaults.plist with screenshot, freeze, and defrost for bannister emulators
    • a few applescript bug fixes
    • the options menu enabled
    • the frappliance rebuilds launch services and enables ui scripting when loaded
  • 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 buttons
    • 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

License

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.

Acknowledgements

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:

Personal tools