Sunday, April 7, 2013

Tutorial 27 - Codea v1.5.2: Export to Xcode

Figure 1. Tap & Hold the Project Icon.

27.1 Exporting to Xcode is Simple

The team at Two Lives Left continue to innovate. The latest version of Codea includes an export to Xcode function which is so simple to use that you can now submit to the App store without knowing any Objective C at all. Previously, incorporating your Lua code into the Codea runtime was something of an arcane art (see our earlier tutorial on submitting an app to the Apple App Store). Now, it is a matter of a few taps. This latest addition really rounds out Codea as the only development environment that you need.

Figure 2. Check the Export Settings

Loading your Codea apps into Xcode is useful for a couple of reasons:
  1. To submit apps to the App Store, this is a necessary interim step;
  2. To add additional functionality which isn't currently available in Codea (e.g. iAds, Game Center, creating a universal app - albeit most of this can be done in Codea, audio support, or hooking into some other Objective C methods). We will discuss this in the next tutorial.
Figure 3. Add a Custom Icon

Figure 4. Select an icon from your Photo Library

Figure 5. Tap on the selected icon

Once you are ready to export an app to Xcode, follow the following steps:
  1. If you want to use a custom icon for your app, you can either attach this as part of the export process or do it later in Xcode. Assuming you want to include it in the export package, you will need to have it completed and stored in your iPad photo library before you start exporting. Codea will create four icons from the one that you include. Their dimensions are 57 x 57 pixels, 114 x 114 pixels, 72 x 72 pixels and 144 x 144 pixels. This is for the standard and retina versions of the iPhone and iPad icons. I suggest attaching an icon with a resolution of at least 144 x 144 pixels to ensure the best quality. If you are submitting to the app store you will need a version with 1024 x 1024 pixel resolution.
  2. In Codea, tap and hold the icon of the project that you wish to export (Figure 1). This will bring up the pop up menu shown. Tap on Export.
  3. Check that the Project settings are correct (Figure 2). Taking these one by one: 
  • The first item is the app name which is taken from the name of your project (not the "Description" meta tag for your project created using saveProjectInfo). 
  • The second item is the developer/author name which is derived from the "Author" meta tag and assigned using saveProjectInfo(). For example, saveProjectInfo("Author", "Reefwing Software"). 
  • The third item, "Company Name" is optional. Note that the bundle ID will use a "short form" of the author or company name you include (it will prefer the company name if specified). A short version of a name simply removes any spaces or special characters in the name. So "Two Lives Left" becomes "twolivesleft", and the bundle ID then becomes com.twolivesleft.projectShortName. The bundle ID is important, as it connects your app in Xcode with your app submission in iTunes Connect. I always use a bundle ID of the form, so I will need to tweak this in Xcode regardless.
  • The next item determines whether your app will display the status bar or not (the black bar right at the top of your iPad which shows your wireless connection strength, network provider, time, battery level, etc). This is an option in your applications pList, so if you change your mind later you can change it in Xcode.
  • The final item in Project Settings is Icon. If you are happy with the default Codea icon for your app then you need do nothing. Most people will want to assign a custom icon however, and tapping the arrow to the right of "Icon" will allow you to do this (Figure 3). Tap on the "+" in the "Choose Icon" dialog to bring up your photo library and select the icon (Figure 4). If you created the icon on your Mac then importing it into iPhoto will add the image to your Photo Stream (if enabled) which is then available on your iPad to select.
  • The "Included Assets" section allows you to include specific sprite images and shaders in the export bundle. Codea normally does a good job of finding these for you but it will have problems if you are procedurally generating the sprite/shader names in your code. If you find assets are being left out then they can be added here.
  • Once you have confirmed all of the Project Settings, tap the Export Button in the top right hand corner of the navigation bar. Codea will chug away (Figure 6) and create your Xcode bundle. When complete (Figure 7), you are given the option to save your exported project bundle somewhere. You need to get this file onto your Mac, so the simplest method is to use Dropbox. If you haven't already signed up for this then I recommend that you do - it is free - and then install the Dropbox app on your iPad. This makes the file movement very simple.

Figure 6. Exporting your Project...

Figure 7. Exported and ready to save.

  • Assuming you are using Dropbox, tap the "Open With" button shown in Figure 7, and you will be given the option to select Dropbox (Figure 8). Select this and then save the zipped bundle when prompted (Figure 9). You will then have the bundle saved in your Dropbox repository (Figure 10) which you can unzip and access from your Mac.
Figure 8. Select Export Bundle to Dropbox.

Figure 9. Save the zipped Project Bundle.

Figure 10. Bundle Saved in Dropbox.

27.2 Importing your Bundle into Xcode

  1. Open up Finder on your Mac and navigate to the Dropbox folder containing your exported project bundle. Double click on this to unzip the folder (Figure 11).
  2. Open up Xcode and select your unzipped project to open (Figure 12). Optionally you may want to save this folder locally first.
  3. And that's it! You should now be able to run your imported project on the iPad or iPhone simulator.
Figure 11. Unzip your project bundle on the Mac.

Figure 12. Open the Project with Xcode.

Figure 13. Configure your Project in Xcode.

27.3 Pre-App Submission Tweaks

If you are going to submit your app to the Apple App Store for approval and listing on iTunes, then there are a few things you still need to do. Have a read of our previous tutorial on this for the full story but in short:
  1. Click on the project (top left of the project navigator) to bring up the project configuration (Figure 13).
  2. Check that the bundle identifier is the same as that entered in iTunes Connect.
  3. Determine whether you want to distribute a universal app (works on iPad and iPhone) or target a specific device. The default is universal.
  4. Check the supported orientations.
  5. You may want to add your own default load images. The default ones say "made with Codea".
  6. When adding your App to iTunes Connect you will need a version of your icon which is 1024 x 1024 pixels in size.
As shown above, the process is now much simpler than it used to be. Good luck with your submissions!


  1. Hi David,

    Thanks for the mention, but there is just one issue:
    How do I get Codea 1.5.2? I currently have 1.5.1, but there is no update available at the App Store. On top of that, if I google "codea 1.5.2", the first (and most relevant) result is a forum where someone posts suggestions for the next Codea version. Simeon said he was working on it, but nothing else. So how and where did you get it?

    1. Hi laytonblogger,

      Ahh yes - v1.5.2 is in Beta at the moment. It hasn't been released to the App store yet. I did this tute as part of the testing process, to allow the other Beta testers a chance to review the tute and to make sure that it was available when 1.5.2 comes out. This latest version breaks the way that I was hooking into Objective C for things like Game Center and iAds. Simeon has developed a new API to do this and it helps (me) if I document the process as I test new features.

      My apologies for the confusion.