A Little Too Familiar

Last week an app appeared on the App Store under the name of "Homebrew Indie Games". This app, at first glance, seemed like any other legitimate app on the app store, however, on closer inspection it looked a little too familiar.


Assimilate running in Homebrew (left) and Provenance (right) (Click for a larger version of each)

Homebrew Indie Games was first brought to my attention by @pheraph on twitter. This app claimed to bundle 18 'free' homebrew games for retro consoles such as SNES, NES, Genesis and GBA.

Coincidentally those are some of the same systems supported by Provenance, my Open Source emulator front-end.

Attribution

Provenance is made possible by the hard work done by the developers of the included emulators and the OpenEmu and RetroArch teams. I'm more than happy to acknowledge their work, because A) they worked very hard to bring these emulators and libraries to life, and B) because the open source licenses require me to do so.

And that is one of the things Homebrew's developer didn't do when he took the source code to Provenance, bundled a few homebrew games with it and sold it on the App Store for $2.99.

The second, and arguably more serious, violation of the Open Source licenses was that Homebrew was being sold. Most of the emulators used within Provenance are under strict non-commercial licenses, which forbids anyone to sell that code. Homebrew's developer was all too happy to ignore these license terms and profit from the hard work done by other people, while taking the credit for it at the same time.

Nowhere did Homebrew's developer state that the code:

Similarities? More Like Identicalities!

I believe the initial complaint to Homebrew's developer was sent by RetoArch after they thought he'd possibly misappropriated their code without attribution and sold it. In an effort to prove Homebrew was not using RetroArch, the developer did probably the most self-damning thing he could have done and sent some of the source files from Homebrew to RetroArch for inspection. RetroArch noticed the OpenEmu code and told them and OpenEmu told me.

It was immediately obvious that the code in Homebrew was exactly the same as the code in Provenance, with the minor exception that the class names had been changed to remove the PV prefix and replace it with HB... so crafty

Take a look and decide for yourself:



Four diff'ed source files from Provenance and HB. Provenance is on the right, Homebrew on the left in each image. Click for larger versions.

In fact, one of the funnier parts is where they had obviously done a search for core and replaced it with engine as you can see in last image above where <QuartzCore/QuartzCore.h> was changed to <QuartzEngine/QuartzEngine.h>. That code would not compile, generating a "header not found" error, making it plain as day that the search and replace was done only before sending the code to RetroArch, and not before compiling.

DMCA Takedown

With this evidence, it was 100% clear that Homebrew's developer had not written the code they were claiming as their own, and so on the recommendation of the OpenEmu team, I submitted a DMCA complaint to Apple.

It took a day of waiting, but Apple eventually issued the DMCA complaint to Homebrew's developer, and the app disappeared from the App Store.

A couple of hours later I received a somewhat bitter email from Homebrew's developer telling me they'd already removed Homebrew from the App Store and that it had been unplublished hours before receiving the DMCA notice. I don't know how true that is, but I take it as a victory for Open Source that the app is no longer for sale.

Final Thoughts

Open Source doesn't mean "do what you want", despite many people thinking that it does. Open Source is about community, sharing, attribution and trust. Developers working together towards common goals and sharing solutions so that the community benefits from their hard work. Developers of Open Source projects are most commonly doing so in their own free time and not being paid for it. They do it out of love for the project and the community that builds around it.

When someone violates that trust and community spirit, stealing hard work from people in an effort to profit, the community is hurt. Developers become less engaged and more reluctant to provide free (as in speech) code to benefit the community.

So in the future, if you plan to use Open Source code, please read the license accompanying the code and abide by its terms, it's there for a reason.

It's alright.

Have an array full of objects and would like to get, for example, all the names from those objects without having to iterate?

You have a Person object that has a property name and you have an array full of Persons and want all their names. You could create a mutable array, iterate the array of Persons, access the name property, store it in your new array, etc. etc. etc.

With Key value Coding, you can ask the array for the values for a given key and it will return a new array containing all the values for each object.

[personArray valueForKey:@"name"];

Voila! A new array containing all the names of each Person object!

For completeness, here's a rather contrived, self-contained, compilable example:

#import <Foundation/Foundation.h>

@interface Person : NSObject

@property (nonatomic, copy) NSString *name;

@end

@implementation Person

- (id)initWithName:(NSString *)name
{
    if ((self = [super init]))
    {
        self.name = name;
    }

    return self;
}

@end

int main(int argc, char *argv[]) {
    @autoreleasepool {

        NSMutableArray *personArray = [NSMutableArray array];

        for (NSInteger i = 1; i < 21; i++)
        {
            Person *obj = [[Person alloc] initWithName:[NSString stringWithFormat:@"obj %zd", i]];
            [personArray addObject:obj];
        }

        NSLog(@"%@", [personArray valueForKey:@"name"]);
    }
}

and the output:

KVCExample[79283:507] (
    "obj 1",
    "obj 2",
    "obj 3",
    "obj 4",
    "obj 5",
    "obj 6",
    "obj 7",
    "obj 8",
    "obj 9",
    "obj 10",
    "obj 11",
    "obj 12",
    "obj 13",
    "obj 14",
    "obj 15",
    "obj 16",
    "obj 17",
    "obj 18",
    "obj 19",
    "obj 20"
)

Back in June, at WWDC 13, Apple announced some new frameworks and hardware for game developers: Sprite Kit, Game Controllers and the MFI Game Controller spec.

The MFI Game Controller spec provided a specification for 3rd party hardware manufacturers to use when creating a game controller designed for iOS that Apple would be able to approve, allowing them to guarantee quality and compatibility to their customers.

The two companies to be making the first controllers were MOGA and Logitech, with an expected release timeframe to coincide with iOS 7. That fell short though and the controllers weren't available to purchase until late November.

The Controllers

The spec outlines two types of controllers:

Form-FittingControllers: Form-fitting controllers wrap around the device, much like a case and allow a variety of control methods to be combined, for example physical buttons on the controller combined with motion and touch control on the device. Since the controller is form fitting it will only fit a particular device, e.g. an iPhone. However, both MOGA and Logitech provide adaptors to fit iPods for their products.

Wireless GamePads: Wireless gamepads follow the more traditional Xbox / Playstation style controller. These controllers connect via bluetooth and will work with iPhones, iPod Touches, iPads and Macs. Since they are designed to be used from a distance, they don't combine physical controls with touch or motion.

There are also two controller profiles available for manufacturers to implement. a Controller Profile outlines the types of controls on the device:

Standard Profile: The standard profile provides a directional pad, four face buttons (A, B, X, Y) and two shoulder buttons.

Extended Profile: The extended profile has all of the controls of the standard profile while adding two triggers on the shoulders and two analogue thumb-stick controls.

Each button on the controller is designed to be analogue, meaning they are all pressure sensitive. And finally, every controller has a pause button and a set of 4 LED indicators to show which player is assigned to a controller.

MOGA Ace Power

MOGA were first on the scene with the Ace Power, a form-fitting controller with the extended profile and a built-in 1800mAh battery. The battery allows you to charge your iPhone while you play, allowing you extra time with that battery-killing 3D shooter that was previously impossible to play with touch controls.

One of the few criticisms I have of the Ace Power is that it's USB port doesn't pass through to the iPhone's Lightning Port, meaning debugging with it is impossible (unless Apple decides to bring back wireless debugging again). At one point I was reduced to adding a text view to the screen and logging to it in order to have an idea of what values I was getting from the controls.

Sonic The Hedgehog running in Provenance with improvised debugging enabled

Next, whatever firmware is running inside the controller tends to crash now and again. When this happens you'll have to reset the controller using the recessed reset button on the back using a paper clip (or an iPhone SIM tool). So far it has only happened to me 3 times in many hours of use, so it's hopefully not a big issue.

And my final criticism involves the nature of the analogue buttons. Even though it feels like the button is pressed, sometimes it needs a little more pressure before the game registers it as being pressed. This could possibly be Apple's fault as the documentation states that a button's pressed state will be YES for analogue values in excess of 0.25. Equally, it could be MOGA's fault for making the button feel like its pressed when its value only reads around 0.1.

I worked around that final criticism in my own games by reading the value of a button directly, as opposed to using the 'digital' pressed property. While this skirts around the issue of missing some button presses it also bypasses the hysteresis that Apple applies in order to filter out accidental or incidental button presses. However, I think for some games that responsive buttons are more important.

Game Controller Framework

Apple's Game Controller Framework receives a lot of praise from me for being simple, easy to understand and easy to implement.

Connection/Discovery

Detecting physically connected controllers is extremely easy. Once they're connected the framework posts the GCControllerDidConnect notification, and the GCControllerDidDisconnect notification when it's disconnected. There is the controllers class method on GCController that returns an array of already connected/paired controllers.

Pairing wireless controllers is more involved. If a controller is not already paired, then you must initiate the pairing process using

startWirelessControllerDiscovery
WithCompletionHandler:  

The completion handler will be called when the discovery process finishes or is cancelled.

Apple provides no UI for pairing controllers, as, in theory, it should just work, however, the documentation recommends creating your own UI if you want to allow the user to select which controller to use if multiple controllers are connected.

Thankfully, once a controller is paired with a device it will be remembered and will automatically connect when it is powered on, meaning that once the initial pairing is done, you should only need to listen for the notifications to tell when they're connected or disconnected.

Once a controller is connected you can set its playerIndex which will illuminate the corresponding LED on the controller if the index is between 0 and 3. You can unset the playerIndex by passing GCControllerPlayerIndexUnset, which will turn off any lit LEDs.

iPhone 5s inside the MOGA Ace Power

Reading Inputs

As I said previously, all the buttons are analogue, but some can be treated digitally by accessing the pressed property. Again, pressed returns YES if a button's analogue value is in excess of 0.25.

You can read a button's analogue value directly using its value property. This is a normalised value between 0.0 and 1.0 for buttons and -1.0 and 1.0 for axes such as the directional pad and thumb-sticks. This means you don't have to worry about calibration or deadzone calculations (particularly for thumb-sticks and directional pads). Apple manages the deadzone calculations for you and if a control is within its deadzone, it's value will be 0.0.

In addition to accessing the inputs directly, which is common for games that poll the controller, you can also set block handlers for controls that will be executed when a control's value changes. You can set block handlers on individual controls, groups of controls or even the entire controller.

The pause button is the only button on the controller that cannot be polled, and thus you must set the controllerPausedHandler property, where you will implement whatever logic you need to pause your game. Users will expect a quick and easy way pause games and so Apple highly encourages this behaviour to be implemented.

It is important to be aware of which profile the connected controller is using, which can be determined by the gamepad and extendedGamepad properties. If the controller doesn't support a given profile then it will return nil. Technically, all controllers support the gamepad profile, so it should only be the extendedGamepad profile that you need to test for.

And that's pretty much all there is to it. You should be able to get Game Controller up and running in your game very quickly and easily, so there's almost no excuse not to if you're a game dev (hint hint).

Things To Remember

There are a few things to remember with game controllers:

  • Apple won't allow you to require a game controller in order to play your game. You must still implement another control system like touch or motion.
  • The user may connect/disconnect a controller at any time while you game is still running
    • If a controller is connected while the game is running, pause the game and hide any onscreen controls.
    • If a controller is disconnected, pause the game and revert to whatever control system you would use when a controller is not present (touch or motion).
  • Always implement the pause handler.
    • Apple's documentation says that the pause handler should toggle between paused and running states. Even if your game is paused for another reason (modal alert, or backgrounding etc), then pressing the pause button should resume play. Your UI must also indicate that the game is paused and explain how to resume.
  • Not all game controllers will be physically attached to the device.
    • There is an attachedToDevice property that will inform you whether or not the controller is physically connected to the device, like a form-fitting controller would be. You can use this property to determine whether or not you can combine touch or motion controls with the game controller to enhance the gameplay.
    • You should also use it to know when a controller is not attached to the device so that you can hide touch controls or provide other means of controlling your game's UI using the controller. (Just think when Apple finally allow 3rd party apps on the AppleTV, no touch screen there ;) but I digress).
  • While Apple won't let you require a game controller for your app, you can require a particular profile for your game controller support.
    • For example, if you are making a shooter that requires both analogue controls in order to maneuver the player you can require the extended profile.
    • In the case where the connected controller doesn't fit the required profile for your game, Apple states that it is more appropriate to ignore the controller than provide a sub-standard experience and to continue using whatever control scheme you would use without a controller.
  • If your game doesn't do it already, remember to disable the idle timer so that the screen doesn't dim/lock while playing.
    • The controller inputs aren't detected as user interaction by the OS, so the screen will lock after the timeout if you don't disable the idle timer.

While playing with Sprite Kit recently I ran into an odd crasher when backgrounding the app that threw me for a loop.

The stack trace was showing gpus_ReturnNotPermittedKillClient: as the offending method. Of course this isn't in my code anywhere.

After some trial and error with the code I tracked the crash down to sounds being played. Even if a sound had been played and was now finished it would still crash. A little further investigation led me to find out that this crash was related to AVAudioSession  when being backgrounded. Sprite Kit uses AVFoundation under the hood to make it easy for you to play your sounds and music within your game.

But AVAudioSession apparently cannot be active while in the background (it causes the crash if it is)... The fix was simple: deactivate the audio session when the app enters the background and reactivate it when it returns.

//
//  SSAppDelegate.m
//  Space Ship
//
//  Created by James Addyman on 18/12/2013.
//  Copyright (c) 2013 James Addyman. All rights reserved.
//

#import "SSAppDelegate.h"

@import AVFoundation;

@implementation SSAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{   
    return YES;
}

- (void)applicationWillResignActive:(UIApplication *)application
{
    [[AVAudioSession sharedInstance] setActive:NO error:nil];
}

- (void)applicationDidEnterBackground:(UIApplication *)application
{
    [[AVAudioSession sharedInstance] setActive:NO error:nil];
}

- (void)applicationWillEnterForeground:(UIApplication *)application
{
    [[AVAudioSession sharedInstance] setActive:YES error:nil];
}

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [[AVAudioSession sharedInstance] setActive:YES error:nil];
}

- (void)applicationWillTerminate:(UIApplication *)application
{
}

@end

Since Sprite Kit sets up the audio session for you within the framework, I would expect this to be handled by the framework and not crash your app in this way. I will be filing a bug report with Apple and I suggest everyone else does the same so that they fix it as soon as possible. I'll update this post when I get a radar number so it can be used to dupe the issue.