Now that our Angry Bots break is over, and the basics of building and running a Unity iOS project have been covered, it’s time to resume our work on the bowling game and get it working on iOS!

From this point on, I will generally assume you’re testing by building and running on a device, but in many cases you can test in the Editor with the Unity Remote or test in the iOS Simulator.

This chapter focuses on making the game look right on an iOS device. This includes making sure the game shows up in the correct orientation and all the game elements show up at an appropriate resolution on the screen, which is a precursor to making the game playable (it’s hard to start playing when you can’t read or tap the Play button).

Furthermore, besides providing required attributes such as the app name and icon, we’ll add some polish by including a splash screen and the familiar iOS activity indicator to indicate the game is loading.

Some of these presentation details might seem to be cosmetic and easy enough to implement that they could be deferred until the end of a project (and typically they are), but easy work could and should be done early. Tasks that can be accomplished quickly help you get into a development groove. And when you’re working crunch-time hours trying to finish your game, the last thing you want to see is unfinished work you could have gotten out of the way early.

Besides, packaging is important. In fact, when I’m creating desktop software, I like to start with the installer, because that is the first customer experience. For iOS apps, the customer first sees the app icon and name and then the splash screen while launching the app. This will form the customer’s first impression of whether the app is polished or amateurish. And you’re the first customer of your app. You’ll feel better about your project and have a clearer idea of what you want your app to be if it’s packaged like a finished product from the very beginning. And you never know when you’ll need to demo it!

The corresponding Unity project is available online at http://learnunity4.com/, and, as usual, I recommend typing in the scripts rather than copying them from the online project. But there are some textures in the project files that will be used for the icon and splash screen, so, from the online project for Chapter 12, copy the additional files in the Textures folder to the Textures folder into the Textures folder of your bowling project (remember, you can drag the files into the Project View). You should have three Fugu Games splash textures of different resolutions, one splash screen displaying a book cover (of this book), and an icon texture (Figure 12-1).

Bowling for iOS

In the Unity Editor, bring up the Project Wizard (Open Project in the File menu), and select the bowling project as you last left it in Chapter 9, before we switched to Angry Bots. You should now be familiar with the process of switching build targets.

Bring up the Build Settings window (select Build Settings in the File menu), select iOS as the build target, and click the Switch Platform button.

If you have the Necromancer GUI installed from Chapter 9, some script errors will appear in the Console View after switching the build target to iOS, because a test script in that package wasn’t written with #pragma strict and is missing some type declarations. This can be resolved quickly by just removing GUITestScript.js from the Project View or wrapping #if !UNITY_IPHONE around all its contents (bonus points for going in and fixing the code by appending :int to the function parameters). Removing the script will disable the Necromancer GUI test scene but otherwise the GUISkin is still usable in your pause menu. All of the changes introduced by this chapter will work with or without the Necromancer GUI (but the screenshots show the Necromancer GUI because it’s prettier).

Once the asset reimport is complete, go to the Edit menu, and under Settings, select Player to bring up the Player Settings in the Inspector View. In the Cross-Platform Settings, fill in your Company Name and Product Name (the app name). Select the iOS tab to display the iOS Player Settings and fill in the bundle ID of the app (Figure 12-2).

Both the original and iOS versions of HyperBowl are portrait-mode games (and it turns out that portrait mode is best for the swipe-to-roll control that will be implemented in the next chapter), so let’s restrict this game to portrait mode (and portrait upside down, because that kind of symmetry is required on the iPad).

Therefore, set the Orientation property in the Player Settings to Auto Rotation, with only the Portrait and Portrait Upside Down options selected (Figure 12-3).

Scale the GUI

We now have enough set up to build and run, and the initial screen of our game looks fine, if we run it on a low-resolution iOS device (i.e., the iPhone 3GS), which has a 320 × 480 pixel screen. But on any of the newer devices, all of which have at least double the screen resolution, the pause menu looks really small, to the point where it’s difficult to read or even tap an individual button. For example, Figure 12-4 shows the pause menu on the 640 × 960 screen of an iPhone 4.

To scale the GUI, you first need to figure out the scaling factor you want to use, which is the current screen width divided by the screen width you were originally targeting. The GUI looks alright on the iPhone 3GS, at 320 × 480 pixels, so let’s say the base screen width we’re targeting is 320. So if we’re actually running on an iPhone 4, for example, at 640 × 960 pixels, we’ll have to scale up the GUI by a factor of two.

The next step is to apply the scaling factor. This can be done in UnityGUI by setting the static variable GUI.matrix, which is a transformation matrix. In computer graphics, a transformation matrix encompasses and applies a translation (change of position), rotation, and scale.

In fact, the local position, rotation and scale of a Transform Component corresponds to a 4 × 4 transformation matrix for that GameObject. And the world position, rotation and scale are calculated by combining (multiplying) all the transformation matrices of a GameObject’s parent GameObjects. In the good old days, you had to include this linear algebra code when programming in computer graphics. Now you can let the game engine hide this from you, but you’re getting a little taste of it here.

var baseScreenWidth:float = 320.0;

function OnGUI() {
#if UNITY_IPHONE
        var guiScale:float = Screen.width/baseScreenWidth;
        GUI.matrix = Matrix4x4.TRS (Vector3.zero, Quaternion.identity, Vector3(guiScale, guiScale, 1));
#endif

var baseScreenWidth:float = 320.0;

function OnGUI () {
        if (IsGamePaused()) {
                 #if UNITY_IPHONE
                 var guiScale:float = Screen.width/baseScreenWidth;
                 GUI.matrix = Matrix4x4.TRS (Vector3.zero, Quaternion.identity, Vector3(guiScale, guiScale, 1));
                 #endif
                 if (skin != null) {
                         GUI.skin = skin;
                 } else {
                         GUI.color = hudColor;
                 }
                 switch (currentPage) {
                         case Page.Main: ShowPauseMenu(); break;
                         case Page.Options: ShowOptions(); break;
                         case Page.Credits: ShowCredits(); break;
                 }
        }
}

function BeginPage(width:int,height:int) {
#if !UNITY_IPHONE
         GUILayout.BeginArea(Rect((screenWidth-width)/2,menutop,width,height));
#else
         GUILayout.BeginArea(Rect((baseScreenWidth-width)/2,menutop,width,height));
#endif
}

function ShowPauseMenu() {
        BeginPage(150,300);
        if (GUILayout.Button ("Play")) {
                 UnPauseGame();
        }
        if (GUILayout.Button ("Options")) {
                 currentPage = Page.Options;
        }
        if (GUILayout.Button ("Credits")) {
                 currentPage = Page.Credits;
        }
#if !UNITY_IPHONE && !UNITY_WEBPLAYER
        if (GUILayout.Button ("Quit")) {
                 Application.Quit();
        }
#endif
        EndPage();
}

Set the Icon

By default, the icon for your app will be the Unity logo. Figure 12-6 shows the icons for several demo apps published by Unity Technologies on the App Store. Aside from Angry Bots, they all have the default Unity icon, albeit an older one because they were built with Unity 3 (and at the time of this writing haven’t been updated).

Figure 12-6 also shows the icon for our Fugu Bowl app if we were to build it right now. It looks a bit different because it’s published with Unity 4 and also has the gloss that is automatically applied by Apple, since we didn’t select Prerendered Icon in the iOS Player Settings.

To customize the icon, you can drag any texture into the Default Icon field of the Player Settings. Let’s use the Icon1024 texture in the Textures folder, copied from the project for this chapter at http://learnunity4.com/. I often indicate the original texture size in the file name (a 1024x1024 texture in this case), which saves a lot of time in assigning icon and splash screen textures.

Since you’re using the texture as an icon, you should adjust the import settings appropriately.

Select the Icon1024 texture in the Project View, and then in the Inspector view, set the Texture Type to GUI instead of Texture (Figure 12-7). This will prevent Unity from applying settings that are suitable for textures with 3D models but not for GUI display. For example, textures used with models should have dimensions that are powers of 2, such as 256 × 256 or 512 × 512, because that’s what graphics hardware likes to operates with, and the textures are stretched around models, anyway. But, generally, GUI textures should stay at their original resolution, since they’re usually sized according to their intended display (which is usually not at a power of 2 resolution).You can switch the Texture Type to Advanced to compare the underlying settings of the Texture and GUI preset texture types, i.e., select Texture then switch to Advanced, then select GUI and switch to Advanced. And within Advanced, you can override any of the preset values for more control over the import settings.

Below the Texture Type area is where texture maximum size and compression level is specified. Unity will generate a warning at build time if you have used a compressed texture as an icon, pointing out correctly that compressed textures may not look good as icons. So select the Default tab so these settings apply to all platforms unless overridden, set the Max Size as 1024 to avoid scaling the texture, and set Format to TrueColor for full color resolution and no compression. Click Apply to reimport the texture with the adjusted settings, and the Preview at the bottom will reflect the new format, size, and memory usage.

Now drag the icon texture into the Default Icon field of the Player Settings in the Cross Platform area. Examine the Icon foldout of the iOS Settings (Figure 12-8). As long as the Override for iPhone check box is not selected, automatically scaled versions of the Default Icon will appear for all the other icon sizes (Figure 12-8).

The various icon sizes correspond to the screen resolutions of the various iOS devices:

• 57 × 57: Any iPhone or iPod touch preceding the fourth generation (the iPhone 3GS or the third-generation iPod touch)
• 114 × 114: Fourth generation and later iPod touch and iPhone
• 72 × 72: The original iPad, iPad 2, and iPad Mini
• 144 × 144: The “new” iPad (or as I like to call it, the iPad 3)

Ideally, there would be an icon tailored for each size, in which case you would check mark the Override box, and then drag the various versions of your icon to each appropriate box. Any box that you leave unfilled with use the Default Icon. But Unity does a good job of scaling textures down (it is far preferable to scale down then up), so I often reuse the same 1024 × 1024 texture that I upload for the iTunes Connect app description.

I recommend you always select the Prerendered Icon option to avoid the gloss that otherwise would be automatically added by Apple.

Besides the optional shine, the portion of the build executed from Xcode also automatically rounds the corners of the icon and adds a drop shadow. So don’t do that yourself! Just keep it square with sharp corners and no special borders.

Set the Splash Screen (Pro)

All iOS apps display a static “splash” screen on startup. Like the default app icon, the default splash screen in a Unity-built app shows the Unity logo (Figure 12-9).

If you’re using Unity iOS Basic, you’re stuck with the default splash screen. But if you’re using Unity iOS Pro, you can supply your own splash screen in a manner similar to the way you customized the app icon.

The Splash Image foldout is located beneath the Icon foldout in the iOS Settings, and, as with the icon selection, it has slots for multiple resolutions appropriate for the various iOS screens and also for both portrait and landscape orientations (Figure 12-10):

• Mobile splash screen: 320 × 480 for any iPod touch or iPhone preceding the fourth generation (i.e., the iPhone 4)
• iPhone 3.5”/Retina: 640 × 960 for the Retina display of the iPhone 4, iPhone 4S, and fourth generation iPod touches
• iPhone 4”/Retina: 640 × 1136 for the iPhone 5 and fifth-generation iPod touch
• iPad Portrait: 768 × 1024 for the original iPad and the iPad 2
• iPad Landscape: 1004 × 768 for the original iPad and the iPad 2
• High-Res. iPad Portrait: For the Retina display of the new iPad (the iPad 3)
• High-Res. iPad Landscape: For the Retina display of the new iPad (the iPad 3)

There is no single default splash screen that Unity will automatically resize for all the splash resolutions, so you have to populate the splash screen boxes for the resolutions and orientations that your game will use. Since only Portrait and Portrait Upside Down orientations (along with Auto Rotation) are selected in the Resolution and Presentation settings, only the portrait splash screens need to be assigned. Like icons, the splash screens can be any textures, and Unity will scale them as needed, but you’ll get the best results with textures that are already the target size. You’ll want to use something appropriate for your company and game.

Drag each splash screen texture from the Textures folder into the matching Splash screen box in the Player Settings (Figure 12-10): Fugu320x480 into Mobile Splash Screen, Fugu640x960 into iPhone 3.5”/Retina, and Fugu1536x2048 into High Res. iPad Portrait. The iPhone 4”/Retina needs a texture, so drag the closest match, Fugu640x960 into it. And Fugu1536x2048 can be used for iPad Portrait.

A Second Splash Screen

Although you can’t change the splash screen in Unity iOS Basic, you can make a splash screen that appears right after the built-in one. You just need to make a scene that displays the splash texture on the screen for a few seconds and then loads the first game scene. This can also be useful with Unity iOS Pro if you want to have more than one splash screen. For example, in HyperBowl I have some HyperBowl artwork displayed by the built-in splash screen and then my Fugu Games logo in the second splash screen.

var waitTime:float=2; // in seconds
var level:String;     // scene name to load

function Start() {
        yield WaitForSeconds(waitTime);
        Application.LoadLevel(level);
}

function WaitForSeconds(waitTime:float) {
        var startTime:float = Time.time;
        while (waitTime > Time.time-startTime) {
                 yield;
        }
}

function WaitForSecondsRealtime(waitTime:float) {
        var startTime:float = Time.realtimeSinceStartup;
        while (waitTime > Time.realtimeSinceStartup-startTime) {
                 yield;
        }
}

Display the Activity Indicator

When something is taking a while, it’s nice to have some kind of loading indicator. For the initial scene load, there’s a convenient way to display the iOS spinner that you often see in apps as an activity indicator. You can enable this by choosing one of the activity indicator styles for Show Loading Indicator at the bottom of the Resolution and Presentation foldout in the Player Settings (Figure 12-17). Given the splash screen is providing a mostly white background, Gray is the best style (the other styles are white).

Now when you run the game in an iOS build, you’ll see the Gray activity indicator spinning on the built-in splash screen.

Script the Activity Indicator

It would be nice to use the activity indicator elsewhere, especially when loading other levels. Fortunately, Unity has a scripting interface for the activity indicator, in the form of static functions in the Handheld class. We just need a script that calls those functions to start and stop the activity indicator. Create a new JavaScript called FuguSpinner and add the contents of Listing 12-8 to the script.

Listing 12-8.  Starting and Stopping an Activity Indicator in FuguSpinner.js

#pragma strict

#if UNITY_IPHONE
function Start() {
        DontDestroyOnLoad(this.gameObject);
        Handheld.SetActivityIndicatorStyle(iOSActivityIndicatorStyle.WhiteLarge);
        Handheld.StartActivityIndicator();
}

function OnLevelWasLoaded() {
        Handheld.StopActivityIndicator();
        Destroy(gameObject);
}
#endif

In the Start callback, the call to Handheld.SetActivityIndicatorStyle specifies the appearance of the activity indicator. The available options, represented by the iOSActivityIndicatorStyle enum, match the Loading Indicator options available in the Player Settings. We’ll choose iOSActivityIndicatorStyle.WhiteLarge, since we know the secondary splash screen has a mostly black background.

The call to Handheld.StartActivityIndicator makes the activity indicator visible in the center of the screen. The Unity Scripting Reference documentation for Handheld.StartActivityIndicator says that the activity indicator will be activated after the current frame, so you need to yield at least a frame before calling Application.LoadLevel. Otherwise, the indicator won’t appear until after the new level is loaded, which defeats the purpose of activating the indicator in the first place. We don’t have to worry about that, here, because we know the FuguSplash script is yielding for some number of seconds before loading the next scene.

However, the activity indicator will keeps going even after the new scene is loaded by FuguSplash. To stop the activity indicator after the scene has finished loading, this script has to survive the scene load, which is why DontDestroyOnLoad is called at the beginning of the Start function, passing it the GameObject this script is attached to. This ensures the GameObject, and thus this script, survives when the next scene is loaded.

Because the GameObject survives the scene load, we can be assured the MonoBehaviour callback OnLevelWasLoaded is called after the new scene has finished loading. This is a perfect place to turn off the activity indicator with a call to Handheld.StopActivityIndicator. At this point, the script and the GameObject it’s attached to aren’t needed, anymore, so Destroy is called on the GameObject.

Note that DontDestroyOnLoad and Destroy are both static functions in the Object class, so just as we called Instantiate in Chapter 7, instead of calling Object.Destroy, for example (or UnityEngine.Object.Destroy to avoid the name clash with System.Object class in .NET), here you’re implicitly calling this.Destroy, which works because this is an Object.

Attach the FuguSpinner script to a new GameObject in the scene, called Spinner. Now when you Build and Run on a device, the activity indicator appears in the center of the splash image and disappears after the next scene has loaded (Figure 12-18).

Explore Further

Now our bowling game for iOS looks like a real app! It has an icon, a splash screen (or two), an activity indicator spinning away on the splash screen, it runs in portrait orientation, and the graphics scale to fit the screen including the UnityGUI scoreboard and pause menu. The menu is even automatically functional in iOS, with its buttons responding to taps on the screen. We can’t quite say that about the actual gameplay, but we’ll implement touchscreen game controls in the next chapter.