Unity 4.2.2 brings iOS Game Controller support

October 11, 2013 in Technology

Like most mobile games developers, we’ve been closely following what important additions and changes the recently released iOS 7 update has made. One of the biggest and most exciting of Apple’s initiatives is the standardization of game controllers for iOS-based platforms. So we’re happy to tell you that, in addition to several important bug fixes for Xcode 5 / iOS 7 (Build&Run, WebCamTexture and status bar), Apple Controller support is included with 4.2.2! This blog post aims to answer most common questions this addition will raise and serve as a short tutorial on how to add support for iOS Game Controllers to your game.

Lets start with the questions you probably have:

  • Q: Will there be a separate iOS-specific API for iOS Game Controllers in Unity?
    A: iOS Game Controller support plugs directly into the standard Unity Input API.
  • Q: The Game Controller API is part of iOS 7, does that imply that games supporting this API will only run on iOS 7 and later?
    A: No, Unity takes care of it. The Game Controller framework is loaded dynamically by Unity iOS runtime only if it is available. For older iOS versions it will just return an empty list of controllers.
  • Q: Can I release my game with a controller-only input scheme?
    A: No, Apple documentation explicitly states that controller input must be optional and your game should be playable without them.
  • Q: Where can I read more about Game Controllers and the Unity Input API?
    A: The Unity Input manual is available from our manual page and Apple Game Controller documentation is here.

Ok, now it’s probably time to write some code ;)

The first thing you probably want to do is detect whether a controller is connected and, if so, what type of controller it is. Call Input.GetJoystickNames() to enumerate attached controller names. If the list is empty, there are no controllers attached. It’s worth checking it every several seconds to detect if controllers have been attached/detached. Here’s an example in C#:

    private bool connected = false;
    IEnumerator CheckForControllers()
    {
        while(true)
        {
            var controllers = Input.GetJoystickNames();
            if (!connected && controllers.Length > 0)
            {
                connected = true;
                Debug.Log("Connected");
            }
            else if (connected && controllers.Length == 0)
            {
                connected = false;
                Debug.Log("Disconnected");
            }
            yield return new WaitForSeconds(1f);
        }
    }
    void Awake()
    {
        StartCoroutine(CheckForControllers());
    }

When controllers are detected you can either hide on-screen touch controls or amend them to supplement controller input. The next task is to check for Game Controller input. Your actual input scheme is highly dependent on the type of game you are developing. Lets take a look at the upcoming Unity 2D tutorial as a simple example:

bean

The player controls the bean character, which can move right or left, jump and fire at the bad guys. By default, the Unity Input “Horizontal” axis is mapped to basic profile game controller dpad and the left analog stick on extended profile controllers. So the code used to move the character back and forth is pretty simple:

    float h = Input.GetAxis("Horizontal");
    if(h * rigidbody2D.velocity.x < maxSpeed)
        rigidbody2D.AddForce(Vector2.right * h * moveForce);

You can set up jump and fire actions in Unity’s Input Manager. Access it from the Unity editor menu as follows: Edit > Project Settings > Input. Lets pick joystick button “A” for the “Jump” action and “X” for “Fire”. Open the following actions in the Unity Input Manager and specify “joystick button 14″ for “Jump”  and “joystick button 15″ for “Fire”.

JumpAndFire

The code handling them looks like this:

    if(Input.GetButtonDown("Jump") && grounded)
    {    
        rigidbody2D.AddForce(new Vector2(0f, jumpForce));
    }
    if(Input.GetButtonDown("Fire"))
    {
        Rigidbody2D bulletInstance = Instantiate(rocket, transform.position, Quaternion.Euler(new Vector3(0,0,0))) as Rigidbody2D;
        bulletInstance.velocity = new Vector2(speed, 0);
    }

The following cheatsheet should help you map controller input in the Unity Input Manager:

Name KeyCode Axis
A joystick button 14 N/A
B joystick button 13 N/A
X joystick button 15 N/A
Y joystick button 12 N/A
Left Stick N/A Axis 1 (X) – Horizontal, Axis 2 (Y) – Vertical
Right Stick N/A Axis 3 – Horizontal, Axis 4 – Vertical
Dpad joystick button 4 .. joystick button 7 Basic profile only: Axis 1 (X) – Horizontal, Axis 2 (Y) – Vertical
Pause joystick button 0 N/A
L1/R1 joystick button 8/joystick button 9 N/A
L2/R2 joystick button 10/joystick button 11 N/A

That’s all you need to start adding iOS Game Controller support to your games!

Comments (24)

Subscribe to comments
  1. Android Application Development

    January 6, 2014 at 8:14 am / 

    It Is Free For iPhone Application Or Not???????

  2. meroip

    December 24, 2013 at 7:56 am / 

    thanks for sharing

  3. Stefan

    December 12, 2013 at 7:55 pm / 

    Is this Feature available in the Free Version of iOS ?

  4. Mantas Puida

    November 20, 2013 at 10:47 am / 

    Controller type is embedded into reported joystick’s name. You can do check like this:
    var sticks = Input.GetJoystickNames();
    if (sticks.Length > 0)
    {
    bool isBasic = sticks[0].StartsWith(“[basic,”); // Extended controller names start with “[extended,”
    }

  5. Scott Berfield

    November 18, 2013 at 8:36 pm / 

    Also, what is the correct method to use to determine whether or not the extended profile is available? There are two types, one has triggers and sticks and one does not.

  6. Scott Berfield

    November 18, 2013 at 8:33 pm / 

    All the controls on an MFI controller are analog. It would be very useful to have access to the actual values returned (0-1). While most of the time, analog is not useful for buttons, it might be, and it is clearly Apple’s expectation.

  7. CodGhostsSeasonPass

    October 28, 2013 at 10:50 am / 

    What about the unity web player for mac / linux?

  8. Draven2222

    October 22, 2013 at 10:11 am / 

    Just to make clear, iOs7 has built in framework for the new controllers,This is to standardize game controller support on Apple devices, as to what controller is supported the answer is any Game Controller that declares itself as an “MFi Game Controller”, this is the key wording that tells us it is officially supported by Apple and will work with iOs7. keep a lookout for Logictech & Moga MFi Controllers.

  9. Rasel

    October 20, 2013 at 4:18 pm / 

    Very helpful and useful article to get the latest technological news. So it will be more reliable to get the free online software and so on.
    Thanks and wishing the success.

  10. Rubel

    October 20, 2013 at 12:02 pm / 

    Which controller will support for this?

  11. Mantas Puida

    October 17, 2013 at 1:52 pm / 

    @Cascho, all controllers released with Apple MFI blessing should work.

  12. Tulai Paul

    October 17, 2013 at 1:48 pm / 

    It seems that Unity 4.2.2 is of great utility, though we have not experienced it at the personal level. Such codes and guidance have made the jobs of mobile apps and games developers much easier, who have been fulfilling the need of newer games and apps for tapjoy, adcolony, admob, revmob, appnext, chartboost

  13. Cascho

    October 16, 2013 at 11:47 am / 

    What controllers are supported?
    Bluetooth controllers?

  14. Bari

    October 15, 2013 at 10:53 am / 

    Thanks for the additional info.

  15. Mantas Puida

    October 14, 2013 at 6:22 pm / 

    1. You can get controller type out of reported controller names. They will follow this pattern: “[$profile_type,$connection_type] joystick $number by $model”. $profile_type might be either “basic” or “extended”, $connection_type is either “wired” or “wireless”.
    2/3. If you want to use dpad exclusively on both joystick profiles just use it as buttons “joystick button 4″ .. “joystick button 7″.

    Check iPhone_Sensors.mm on Xcode project for implementation details. You can tweak it there if needed.

  16. Bari

    October 14, 2013 at 5:52 pm / 

    I have a few questions about this:
    1. How do we detect if it is Basic or Extended Profile.
    2. If you din’t give us a clear way to detect it at least you shouldn’t have mixed the inputs between the 2 types (Axis 1 = Left Stick = Dpad).
    3. Why is dpad separatly maped for Basic And Extended profile? (this makes implementing controller suport for Basic and Extended in the same proiect a nightmare!!!)

    Thanks for including this into Unity, But please rethink the mapping + detection
    Thanks,
    Bari

  17. Wahooney

    October 14, 2013 at 12:45 pm / 

    Could this be used as a catalyst to start updating the Input API to be able to modify buttons and axes at Runtime?

    http://feedback.unity3d.com/suggestions/scripting-expose-input-manager-

  18. Wesley Bastos

    October 11, 2013 at 8:20 pm / 

    Please also update the Social API, to work with Google Play Games, Windows Phone Games Hub and the Game Center new api.

  19. q4a

    October 11, 2013 at 6:50 pm / 

    What about Unity web player for Linux?

  20. U3DXT

    October 11, 2013 at 5:39 pm / 

    It’s great that Unity is including this as part of there Input class.

    But if you want complete control. Our IOS SDK Pro plugin supports analog buttons. You don’t need to poll to get controllers, we will send you an event. You can get the inputs as part of your game loop or register events. Basically, we expose all the IOS APIs for Game Controller. The documentation and API is available at http://www.u3dxt.com

  21. Mantas Puida

    October 11, 2013 at 4:13 pm / 

    Currently it’s not yet that clear which button’s pressure sensitivity would be most useful. It is quite probable that more buttons are going additionally exposed as axes with next Unity releases. At the moment all the relevant game controller implementation lives in Xcode trampoline iPhone_Sensors.mm. So if you have urgent need to receive some button pressure measurement as axis, you can tweak code and add your mapping there.

  22. Aaron Sullivan

    October 11, 2013 at 3:54 pm / 

    Am I right that there is no support for the pressure sensitive buttons that the Apple API supports? I’m not sure if all controllers are required to have pressure sensitive buttons but the Apple documentation clearly states that you can get a number between 0 and 1 inclusive for reading how much pressure is applied to any button.

    Hope this comes soon if it’s not already implemented and I’m missing something. Please let me know if I’m missing something! :)

  23. Jessy

    October 11, 2013 at 3:37 pm / 

    I’m not sure that anything is “worth checking every several seconds”. Unity should relay events for this purpose.

  24. Adams Immersive

    October 11, 2013 at 3:23 pm / 

    Great! Thanks.

    Supposedly, MFi controllers will also work with Macs via Mavericks. Will coding iOS controllers as above also provide the same functionality to Mac builds? Hope so! (And I hope we see these mythical controllers at Apple’s event this month.)

Comments are closed.