Difference between revisions of "EmulatorsPlugIn"

From AwkwardTV
Jump to: navigation, search
(Moved image.)
Line 4: Line 4:
 
|}
 
|}
  
'''Latest Update:'''  Version 1.4.1 is a minor update which includes the following
+
'''Latest Update:'''  Version 2.0 sports these latest features:
* a new defaults.plist with screenshot, freeze, and defrost for bannister emulators
+
* Sub-folders are now implemented
* a few applescript bug fixes
+
* Huge increase in speed (fast memory deallocation)
* the options menu enabled
+
* Simplified applescripting with .pathToROM temp file
* the frappliance rebuilds launch services and enables ui scripting when loaded
+
* Fixed a bug causing slow display of large ROM folder
  
--[[User:Bgan1982|Bgan1982]] 03:23, 16 April 2009 (CEST)
+
--[[User:Bgan1982|Bgan1982]] 02:59, 21 June 2009 (CEST)
  
 
= Author =
 
= Author =
Line 22: Line 22:
  
 
= Download Links =
 
= Download Links =
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_1.4.1.zip Emulators Plugin 1.4.1]
+
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_2.0.zip Emulators Plugin 2.0]
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_1.4.1.zip Emulators Source Code 1.4.1]
+
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_2.0.zip Emulators Source Code 2.0]
 
*  [http://emulatorsplugin.googlecode.com/files/toggleFinder.zip toggleFinder script]
 
*  [http://emulatorsplugin.googlecode.com/files/toggleFinder.zip toggleFinder script]
 
Old Versions:
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_1.4.zip Emulators Plugin 1.4]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_1.3.zip Emulators Plugin 1.3]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_1.2.zip Emulators Plugin 1.2]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_1.1.zip Emulators Plugin 1.1]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_PlugIn_1.0.zip Emulators Plugin 1.0]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_1.4.zip Emulators Source Code 1.4]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_1.3.zip Emulators Source Code 1.3]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_1.2.zip Emulators Source Code 1.2]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_1.1.zip Emulators Source Code 1.1]
 
*  [http://emulatorsplugin.googlecode.com/files/Emulators_Source_1.0.zip Emulators Source Code 1.0]
 
  
 
= Installation Instructions =
 
= Installation Instructions =
Line 48: Line 36:
 
* <code>/Applications/sixtyforce.app</code>
 
* <code>/Applications/sixtyforce.app</code>
 
* <code>/Applications/Snes9X.app</code>
 
* <code>/Applications/Snes9X.app</code>
 +
* <code>/Applications/zsnes.app</code>
  
 
For additional features with some of these emulators, also install [http://www.bannister.org/software/ee.htm Emulator Enhancer]:
 
For additional features with some of these emulators, also install [http://www.bannister.org/software/ee.htm Emulator Enhancer]:
Line 98: Line 87:
 
* <code>/Users/frontrow/ROMs/SNES</code>
 
* <code>/Users/frontrow/ROMs/SNES</code>
  
 +
As of version 2.0, you may have unlimited nested sub-folders inside of these.
  
 
'''Step 5'''. Install the Emulators.frappliance in the Finder's plugins folder:
 
'''Step 5'''. Install the Emulators.frappliance in the Finder's plugins folder:
Line 126: Line 116:
 
You can add a new emulator by adding a new <code>&lt;dict&gt;&lt;/dict&gt;</code> tag inside the <code>FRApplianceCategoryDescriptors &lt;array&gt;</code>.  Here are what the different keys mean:
 
You can add a new emulator by adding a new <code>&lt;dict&gt;&lt;/dict&gt;</code> tag inside the <code>FRApplianceCategoryDescriptors &lt;array&gt;</code>.  Here are what the different keys mean:
  
* '''identifier''' :  The actual executable name of the emulator.
+
* '''identifier''' :  The executable name of an emulator.
 
* '''name''' :  The system name that will appear in the menu.
 
* '''name''' :  The system name that will appear in the menu.
 
* '''path''' :  The full path to ROMs folder for the current system.
 
* '''path''' :  The full path to ROMs folder for the current system.
Line 137: Line 127:
 
* '''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.  All files which do not end in these extensions will be filtered out of the 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.
 +
New in version 2.0:
 +
*  '''alt-identifier''' :  Executable name of any child process.
 +
** For example, ZSNES.app launches the 'zsnes' process.
  
  
Line 197: Line 190:
  
 
= Known Bugs =
 
= Known Bugs =
* Subfolders don't work yet
+
* Email me if there's a bug that you know how to reproduce.
  
 
= Version History =
 
= Version History =
 +
 +
* 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
  
 
* 1.4.1 4/15/09
 
* 1.4.1 4/15/09

Revision as of 17:59, 20 June 2009

emulators.png

Latest Update: Version 2.0 sports these latest features:

  • 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

--Bgan1982 02:59, 21 June 2009 (CEST)

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

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
       Password:
       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. (To enable USB Enable_USB). 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

As of version 2.0, you may have unlimited nested sub-folders inside of these.

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.

Usage

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.

Configuration

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 executable name of an 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.

New in version 2.0:

  • alt-identifier : Executable name of any child process.
    • For example, ZSNES.app launches the 'zsnes' process.


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>


Here is an example of adding MAME:

    <dict>
         <key>identifier</key>
         <string>MAME OS X</string>
         <key>name</key>
         <string>MAME</string>
         <key>preferred-order</key>
         <real>106</real>
         <key>path</key>
         <string>/Users/frontrow/ROMs/MAME/</string>
    </dict>

(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

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

Version History

  • 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
  • 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: