Unity Iphone Newbie Guide - Lesson1

Learning Unity IPhone Lesson 1: Getting Started

Gregory Pierce May 16, 2009

Sojourner Mobile

Getting Started, Page 1

Introduction

Welcome to your new home! The purpose of this document is to get you started with a visual run through all of the steps to getting Unity iPhone up and running and publishing your first application. This application is the first in a series of tutorials that will take you from getting your first “blank screen” up to having an application running that has all the bells and whistles that Unity iPhone has to offer.

Sojourner Mobile

Getting Started, Page 2

Start the IDE

Step 1: Start the Unity iPhone environment. The icon for Unity iPhone looks somewhat similar to that of Unity except for the iPhone sitting next to it. You should have installed Unity first before installing Unity iPhone (because the Unity environment will remove or replace some demos if you do it in the other order). If you installed them in a different order, you can simply reinstall Unity iPhone and get back all of the demos that you may be missing. Once you have done that you will have the Unity IDE as shown above. Note that you can NOT develop Unity iPhone applications in the ‘regular’ Unity Indie/Pro IDEs - they are not capable of producing iPhone applications.

Sojourner Mobile

Getting Started, Page 3

The Basics Step 1: Start the Unity iPhone environment. The icon for Unity iPhone looks somewhat similar to that of Unity except for the iPhone sitting next to it. You should have installed Unity first before installing Unity iPhone (because the Unity environment will remove or replace some demos if you do it in the other order). If you installed them in a different order, you can simply reinstall Unity iPhone and get back all of the demos that you may be missing. Once you have done that you will have the Unity IDE as shown above. Note that you can NOT develop Unity iPhone applications in the ‘regular’ Unity Indie/Pro IDEs - they are not capable of producing iPhone applications. Step 2: The next thing we need to do is to create a Unity Project. A Unity Project contains all the scripts, resources, assets, etc. that will be used in the game and deployed to the device. If you have assets and they aren’t a part of the project, Unity will not deploy them to the target device (it can’t read minds as much as we’d like it to). Step 3:

Sojourner Mobile

Getting Started, Page 4

To create a new project, go to the File menu and tell Unity that you want a New Project. New Scenes and such will come a little later.

Step 4: The project Wizard will appear and ask you for the location of your new project. Give it a location on disk where you’d like the project files to be stored. Note that in this case a directory (Lesson1) will be created and the project will be stored here. This is the root directory for the project. Step 5: Unity Applications require some credentials be created on the Apple Developer portal. I am assuming that you already have a certificate on the developer site. If you don’t, Apple has a handy video under Portal Resources that will help you get your certificate created and Sojourner Mobile

Getting Started, Page 5

installed on both Apple’s end as well as on your development machine. Follow the steps in that video to get your certificate setup. Step 6: The Next step is to create an Application ID specifically for your Unity iPhone application. To do this properly it should NOT be an application ID that is a wildcard ID (i.e. it should NOT end with a *). There are a number of nonUnity reasons to not do this (including Store Kit as well as Notifications) so just take it as law that you want a new application ID for each one of your Unity applications (well, you won’t have a choice anyway). In this example I create one for an application called unitylessons - which is the application we will be building throughout this series. Note the App ID (com.sojournermobile.lessons) is not a wildcard ID.

Sojourner Mobile

Getting Started, Page 6

Step 7: Now that you’ve created your App ID you can create your provisioning profile. This is what Unity will use when it builds your application to make sure that it is signed and gets installed on your device (and any test devices that you’re going to be deploying to). In the first box you will give a descriptive name to the profile. Next you will check off the certificate that will be used for signing the application (in this case I only have one - and you probably will too). In the drop down you will select the appropriate app id for this provisioning profile. Remember ours was giving the descriptive name of unitylessons and as such we select that in the drop down. Finally we will select all of the devices which this application will be able to deploy on (for development purposes - we will come to production deployment later in the series). In my case I want all of my testers and friends to be able to run this application on their phones so I have selected them all. If you are looking for how devices are added here, there is a good video of this in the Apple developer portal.

Sojourner Mobile

Getting Started, Page 7

Step 8: The portal will take a few minutes to create the mobileprovision file. This is the file that will allow Unity and XCode to build and sign your project properly. Many deployment issues come from getting this next set of steps incorrect so if you are brand new to iPhone development you may want to pay close attention to these next few steps. In the portal, click on the download button and the mobileprovision will go to your machine keep track of where it went for now because you need it. Step 9: Plug your iPhone/iPod Touch into your development machine (important step). Start XCode. Next, go to the Window menu and start an application called the Organizer. The screenshot you see here is from the iPhone SDK 3.0 software. Your version may look different if you are running an older version. Now you can either double click on the mobile provision file, drag it into the organizer, or click on the plus next to provisioning and find the mobileprovision file on the file system. Utilizing any of these approaches should result in your Sojourner Mobile

Getting Started, Page 8

provisioning profile showing up in the organizer in the provisioning area. If this doesn’t happen something has gone wrong. Try restarting XCode and trying again or trying using one of the other approaches listed above as you may be plagued by some weird bug in an earlier version of XCode. Step 10: To confirm that you have your profile installed properly, you can click on Provisioning Profiles (note this is SDK3) and you should see it and any other profiles that are installed as well as any warnings that would denote an improperly installed certificate or similar. If you have ANY warnings here, read them and remedy them as your build will NOT work. Your screen should be as warning free as mine is here. Step 11: We’re almost done. Go back into Unity and tell it to build and run your project (Command-B or AppleB depending on how dated you are). You will get a very interesting error about the iPhoneBundleIdentifier. Sojourner Mobile

Getting Started, Page 9

What Unity is telling you is that it needs to know which provisioning profile it should be using to build. Note that if you look in step 10 it gives you everything you need to know in the app identifier. Note that its (a bunch of random stuff).com.sojournermobile.lessons. The only part that Unity cares about is the “com.sojournermobile.lessons” part. You will also notice that Unity has taken you to the PlayerSettings in the IDE - guiding us to where we need to fix the problem (so nice of them). Step 11: The very first setting is the iPhone Bundle Identifier that the IDE is complaining about. Note that if something changes with Unity where this isn’t surfaced, you can find the player settings in Edit>Project Settings>Player. So just click on the text where the old bundle identifier is, type in the new one “com.sojournermobile.lessons”.

Sojourner Mobile

Getting Started, Page 10

Step 12: When finished, your player settings should look like mine. Now as far as Unity is concerned, you’ve given it all that it needs to know in order to create and build your project. When Unity builds your project you should note that it is creating a project in XCode, putting a lot of information in it (something we’ll exploit later) and then it is having XCode do a build on that project. There are some special scripts that are in that build that result in your project being endowed everything Objective-C and iPhone-like and deployed to the phone. So lets go ahead and do that - press Command-B/Apple-B. Step 13: Its probably the humor of the universe that this step is step 13. If you’ve done anything wrong - this is where you’ll pay the price. Some reminders before we move on Unity is expecting to deploy to a device, make sure its plugged Sojourner Mobile

Getting Started, Page 11

in. Unity is also expecting that all your certificates are installed so that when it tells XCode to run certain targets that things don’t explode. If things blow up here you probably missed something. In any event this entire step is fairly well automated so the final thing that you should see at the bottom of your XCode IDE (Unity has passed control over to XCode at this point) is:

This is the most joyous thing you will see as it means that your app is fine and its on its way to the phone. One final note is that if you have some autolock on your phone, XCode may be able to build your app but not install it. When building, make sure that the device is accessible.

Running for the 1st time The first thing you’ll see when the application runs is the traditional Made With Unity splash screen. We’ll replace this in the next lesson (if you have Pro. If you have Indie - your app will deploy displaying this splash screen or one similar). What you should see is a slightly blue and empty world. For whatever reason I was unable to capture an image of that from the device for you to see but that’s all your application will do at this point. Your environment is now confirmed to be set up properly Sojourner Mobile

Getting Started, Page 12

and you’re ready to do some basic housekeeping tasks like changing the application icon and the splash screen.

Congratulations!!! See you next lesson.

Sojourner Mobile

Getting Started, Page 13