Developers: How to Build System and Core Plugins
You will need the latest Xcode (4.2 or greater) running on OS X 10.7 to build OpenEmu.
The goal of OpenEmu is to be system agnostic so that plugins can be created to add support for new systems.
OpenEmu can be described as three layers:
- The Application handles audio and video output to the OS and input from HID devices.
- The System Plugin describes a system and provides an interface for cores to plug into.
- The Core Plugin is the implementation of the emulator which then ties into a system plugin.
System Plugins describe a core system and contain:
- SystemController and SystemResponder classes
- Plugin name and system identifier
- Supported rom types (file suffixes)
- Button mapping defaults and settings
- Controller preference layouts, graphics and icons.
These settings are stored in property list (.plist) files.
Once compiled, system plugins take on the Product Name of the core they were built for if a target is set in the OpenEmu project. They are stored in ~/Library/Application Support/OpenEmu/Systems/
For example: Genesis.oesystemplugin, NES.oesystemplugin, SuperNES.oesystemplugin, etc.
The contents of the system plugin bundle include the compiled SystemController and SystemResponder classes, the .plists and supporting files for controller preference graphics and icons.
OpenEmu includes plugins for several systems. In this example, we will create a new system plugin for the TurboGrafx-16/PC Engine.
Our first step will be adding a new Target to the OpenEmu project. Choose the Bundle template under Framework & Library for Mac OS X and then give it a Product Name.
A folder with the Product Name you chose will be generated with some files. This should be moved into the System Plugins group.
Once created, you will then have to add some custom OE-related values to the info plist. These will include, OEArchiveIDs, OEControlListKey, OEFileSuffixes, Principal Class, OESystemIcon, OESystemPluginName and OESystemIdentifier. Since all system plugins follow the same structure, please view a plist of another plugin for guidance on what values to fill in.
Once finished, you will have an info plist that looks like this:
Next go to the Build Phases tab for your new system plugin and add OpenEmuSystem for Target Dependencies and OpenEmuSystem.framework under Link Binary With Libraries.
In the Build Settings tab under Packaging, change the Wrapper Extension to oesystemplugin
Finally, edit the Build SystemPlugins target. Under the Build Phases tab, add the new system plugin for Target Dependencies and Copy Files. This will tell the scheme to build the new .oesystemplugin when you compile OpenEmu.
While some files will be auto-generated, SystemController and SystemResponder classes and headers still need to be created. These classes are similar in all systems so we can duplicate a set from another system and then edit accordingly.
The following 5 class and header files must be created for a new system plugin:
- OE[SystemName]SystemController.m and .h
- OE[SystemName]SystemResponder.m and .h
- OE[SystemName]SystemResponderClient.h
For our TurboGrafx-16/PC Engine example:
/* OEPCESystemController.h */
#import <Cocoa/Cocoa.h>
#import <OpenEmuSystem/OpenEmuSystem.h>
@interface OEPCEController : OESystemController
@end
...
/* OEPCESystemController.m */
#import "OEPCESystemController.h"
#import "OEPCESystemResponder.h"
#import "OEPCESystemResponderClient.h"
@implementation OEPCESystemController
- (NSUInteger)numberOfPlayers;
{
return 1;
}
- (Class)responderClass;
{
return [OEPCESystemResponder class];
}
- (NSArray *)genericSettingNames;
{
return [super genericSettingNames];
}
- (NSArray *)genericControlNames;
{
return [NSArray arrayWithObjects:OEPCEButtonNameTable count:OEPCEButtonCount];
}
- (NSDictionary *)defaultControls
{
NSDictionary *controls = [NSDictionary dictionaryWithObjectsAndKeys:
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardUpArrow] , @"OEPCEButtonUp[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardDownArrow] , @"OEPCEButtonDown[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardLeftArrow] , @"OEPCEButtonLeft[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardRightArrow], @"OEPCEButtonRight[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardA] , @"OEPCEButton1[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardS] , @"OEPCEButton2[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardSpacebar] , @"OEPCEButtonRun[1]" ,
[NSNumber numberWithUnsignedInt:kHIDUsage_KeyboardEscape] , @"OEPCEButtonSelect[1]",
nil];
return controls;
}
- (NSUInteger)playerNumberInKey:(NSString *)keyName getKeyIndex:(NSUInteger *)idx{
if(idx!=NULL) *idx = [[self genericControlNames] indexOfObject:keyName];
return 1;
}
@end
...
/* OEPCESystemResponder.h */
#import <Cocoa/Cocoa.h>
#import <OpenEmuSystem/OpenEmuSystem.h>
@protocol OEPCESystemResponderClient;
extern NSString *OEPCEButtonNameTable[];
@interface OEPCESystemResponder : OEBasicSystemResponder
@property(nonatomic, weak) id<OEPCESystemResponderClient> client;
@end
Starting with the SystemResponder class:
NSString *OEPCEButtonNameTable[] =
{
@"OEPCEButton1",
@"OEPCEButton2",
@"OEPCEButtonUp",
@"OEPCEButtonDown",
@"OEPCEButtonLeft",
@"OEPCEButtonRight",
@"OEPCEButtonRun",
@"OEPCEButtonSelect"
};
...
Our end result with be a new system plugin in the UI and controller in the Preferences.
...
Core Plugins implement systems and contain: ...
oecoreplugin, SystemResponderClient.h, GameCore.h, GameCore.mm ...
porting...
...