Tutorial 14 - SpaceWar! & Extended Ship Class

   

14.1 The Extended Ship Class

    
In Interlude 11 we introduced a ship class. We will use this to explore some new concepts in game design. In particular we will look at:

1. Using a mesh to represent our ship image;
2. Simple path finding for our ship;
3. The use of polar co-ordinates to determine the angle and distance to a destination point; and
4. Simple collision detection by testing for the intersection of two bounding rectangles.

The updated ship class is shown below. This class will automatically move your selected ship to a point that you tap on the screen. The init() function sets up the following variables:

   

x, y -  Are the screen co-ordinates of the ship. Depending on the mode variable, these will refer to either the bottom left of the bounding rectangle (CORNER) or the centre (CENTER). If x and y aren't specified in the constructor then (0,0) is assigned because nil evaluates to false and hence the second parameter in the "or" construct is assigned. We use this trick for all of the specified init() parameters to provide default values.

  

enemy - is a boolean. If true the ship will be drawn in red and wont be selectable.

  

heading - is the bearing in degrees that the ship will point towards. 0 (the default) positions the ship facing right. A value of 180 degrees will face the ship left.

    

speed - determines how far the ship will move each frame (if it is moving which is determined by the boolean shipMoving).

   

width and height - refer to the rectangle which bounds the ship. Changing these will alter the dimensions of your ship.

    

selected - a boolean which indicates whether the ship has been selected. You can select one of your ships by tapping it. A selected ship will be indicated by a rectangle drawn around it. Tapping the same ship again will deselect it.

  

imageMesh - is a mesh containing the representation of your ship. It is built up using two overlapping triangles.

  

destination - this variable is a vec2 which contains the (x, y) co-ordinates of the point you want to move the ship to. If the boolean shipMoving is true then this class will automatically move its ship object towards this point every frame. Initially this variable is nil.
  

      

The Ship class currently contains three functions to provide the appropriate ship behaviours. We will look at each of these in turn.

  

Ship:updatePosition() - if the ship is moving, this function provides a simple path finding algorithm to move the ship towards the destination co-ordinates. In addition, it will automatically point your ship in the right direction. It does this by working out the polar co-ordinates of the destination using the current ship position as the origin. The two variables returned by math.polar (found in the Math tab of the project) are the distance from the ship to the destination and the angle (or heading). We use the distance to determine when to stop moving the ship. When the distance is less than the width of the bounding box we are roughly where we want to be. If we try to get much closer the angle starts getting a bit wonky. The angle is assigned to the heading class variable and is used to rotate the ship in the right direction when we draw it.

Ship:draw() - is responsible for drawing your ship each frame. If the ship is moving (shipMoving is true) then we first call the Ship:updatePosition() function to calculate the new ship position (x, y). We then translate to the new ship position and rotate the ship to the current heading. If the ship is selected a green rectangle will be drawn around the ship. The last thing we do is draw() the mesh (imageMesh) which represents the ship.

  

Ship:touched(touch) - This function does the touch handling. We only use this function for our own ships not enemy ships. Tapping your ship will toggle its selection. If there is a tap on another part of the screen when a ship is selected, it will start moving towards that point. This is achieved by setting shipMoving to true and assigning the destination co-ordinates. The pointInRect() function (found in the Math tab) determines whether the current tap was on the ship.

    

14.2 The Main Class

       

The Main class is very simple. We create two ships in init() and our twinkling star background using the old favourite Twinkle class. In the touched(touch) function we pass on the touches to both ships and in draw() we draw the twinkling stars and the two ships by calling their associated draw() functions.

The only other point of interest is the simple collision detection provided by the intersectRects() function (found in the Math tab). At the moment, if there is a collision between ships we just print out "BANG!!!" This will be enhanced in later versions of the program.

        

14.3 Download the Source Code

       

As usual, the source code for this tutorial may be downloaded from dropbox using the following links.

   

1. Main Class - described in section 14.2;

2. Ship Class - described in section 14.3;

3. Math File - which contains a number of helper & collision detection functions;

4. Colors File - which defines some standard colours; and

5. Twinkle Class - which provides our background star field.

        

14.4 Problems with this Design

      

This code is functional but it has some issues. In no particular order these include:

1. Our ship speed is dependant on our frame rate. In a later tutorial we will look at methods we can use to move our ship at a constant speed regardless of the frame rate.
2. The path finding algorithm is rudimentary at best. It doesn't handle obstacles, different "terrain" or take account of enemy positions. Our next tutorial will develop the A* path finding technique which is much more sophisticated.
3. Collision detection is very rough. As with the other issues we will evolve our collision detection in subsequent tutorials.
4. The selection methodology when there are multiple own ships is a bit flakey.
5. Portrait orientation is not handled properly.

All of these issues will be addressed in subsequent tutorials.

Tutorial 13 - Submitting to the App Store Part 2

    

13.1 Some Runtime Things to Watch

Further to part 1 of this tutorial, there are a couple of things, which if you are not aware of them, can cause problems with running your Codea App in the runtime.

13.1.1 Using Version in the pList

The runtime expects your version variable to be a string. So if you set a version number in Codea using something like saveProjectInfo("Version", version), where version is a number then you will get an error when you try to compile your project.
  
The solution is to either delete this line in your code or to modify a line in the runtime objective C code. If you want to take the second option then in the CodifyAppDelegate class go to the - (NSString) versionForProjectAtPath:(NSString)path method and change the line:
   
NSString* version = [infoPlist objectForKey:@"Version"];
   
To:
   
NSString* version = [[infoPlist objectForKey:@"Version"] description];
   

If you are using a float to represent your version (e.g. 1.4) then it is likely that within the info.plist file (which is found in the Project.codea folder) that this wont be the number you  are expecting (e.g. you get 1.39999999999234 instead of 1.4). This is due to the size of the memory allocated to store numbers in Codea. Anyway, just edit this in your pList file in Xcode back to what it should be. Note that there are two info.plist files, one for your App (found in classes -> Supporting Files) and one for your Codea project.

    

13.1.2 Supporting Orientations

Another trick for young players is that the function orientationChanged(newOrientation) is called before the setup() function in Main. So if you use global variables which are defined in setup() in the orientationChanged() function you will get a runtime error because they haven't been defined yet.

If you are in this situation, the solution is a three step process:

1. In Main, add the following line before anything else:

setupHasRun = false

-- Other global stuff

2. Then in your setup() function, once your setup is done set the variable to true:

  

function setup()
    
    -- setup stuff
  
  setupHasRun = true
      

end

 
3. Finally in the orientationChanged() function:

function orientationChanged(newOrientation)

    if setupHasRun then
        -- Your existing orientation code
    end

end

And that should sort out the problem. Thanks very much to Simeon from Two Lives Left for tracking this solution down.
     

13.2 Customising the Runtime

     

Before submitting your App to iTunes, there are a few things that you will probably want to change in the runtime. We will look at the simple things in this tutorial, a subsequent tutorial will explore how to add things like iAds and Game Centre support.

   

  Figure 1. Changing your Icon & Launch Images in Xcode.

    

13.2.1 App Icons and Launch Images

      

The runtime comes with some default icons and launch images. The easiest way to replace these with your own is to use Xcode.

     

1. Select the Project Navigator (top left button in the tool bar) and click on the top most item in the left pane, called Codea Template.
2. If you then select the summary tab in the right hand (or middle pane depending on how you have Xcode configured) you should see something like Figure 1.
3. Right click (control click) on any of these images and chose "Select File" to change them to your custom versions.
4. There is a plethora of app icon and launch image sizes required, but you can get away with just having these six plus the App store image (which we will get to shortly). The iOS Custom Icon and Image Creation Guidelines lists exactly what dimensions are required and the naming conventions for these images.

           

13.2.2 Hiding the Status Bar

        

Note that you should take into account whether you will be showing the status bar when creating your launch images. Xcode will warn you if the dimensions of your selected images are incorrect. You can hide the status bar by setting the "Status bar is initially hidden" to YES in the info.plist file for your App (found in classes -> Supporting Files).

      

Figure 2. iOS Dev Centre Web Site.

          

13.3 The iOS Dev Centre

            

13.3.1 Provisioning Portal

      

For this next step we are assuming that you already have set up a paid developer account with Apple. The good news is that the App provisioning and certification process has gotten much easier than it was, but it is still a bit tricky so we will step you through the correct order in which things need to happen.

       

Figure 3. iOS Provisioning Portal.

                

1. Open up you favourite browser and go the iOS Dev Centre site (Figure 2). Log in using the Apple ID associated with your Developer Account.
2. Once you are logged in, at the top right of the iOS Dev Centre page is a set of links grouped as "iOS Developer Program". Click on the link which says iOS Provisioning Profile.
3. You should already have a development and distribution certificate. If you haven't, the easiest way to do this is to use the Development Provisioning Assistant. You can start this off by clicking on the button which says "Launch Assistant", it is located in the middle bottom of the page (Figure 3).
4. After you are certified we need to create a new App ID for our App. In the left hand pane of the iOS Provisioning Profile page, click on the link called "App IDs". On the App ID page you will be able to read more than you ever wanted to know about the care and feeding of App ID's. You will also be able to see the status of any App ID's that you currently have in place. Before your eyes glaze over there is one important paragraph buried in there. It starts with "The Bundle Identifier portion of an App ID can be substituted with a wild-card character (asterisk '*') so that a single App ID may be used to build and install multiple applications." We suggest that you don't do this, as wild-card App IDs cannot be used with Push Notifications or for In-App Purchase. 
5. Click on the "New App ID" button in the top right of the screen, and this will take you to the Create a New App ID page shown in Figure 4. Here you have to answer just three questions but the first time you see this, it can be a bit confusing as to what to do. 
6. For description we used "MinesweeperAppID". The description is not important, it is just to remind you which App this ID is for. The next question is important. It is to set the "Bundle Seed ID (App ID Prefix)". We suggest using the default "Use Team ID" as the prefix. As mentioned previously don't use a wildcard "*" for the prefix. The last question is used to set the "Bundle Identifier (App ID Suffix)". This needs to be unique for every App and the usual practice is to use a reverse domain name string. In our case we used "au.com.reefwing.Minesweeper". So what if you don't have a domain? It doesn't matter you just need to use something unique - you could perhaps base it on your name (e.g. "davidsuch.YourAppName"). Click on submit and you will be taken back to the previous App ID status screen where you should now be able to see your shiny new App ID.
7. The last step in this stage is creating our Provisioning Distribution Profile. In the left hand navigation pane click on the "Provisioning" link and then on the Distribution tab. This will show a list of existing Distribution Profiles. Click on the "New Profile" button in the top right. Fill in the details. Distribution method is "App Store", choose an appropriate profile name (we used Minesweeper Distribution Profile), and select the App ID that you just created. Click on "Submit" and you are done.
8. In the top right you will see a link which says "Go to iOS Dev Centre". Click on that and we will be ready for the next stage.

                

Figure 4. Creating a New App ID.

               

13.3.2 iTunes Connect

             

Figure 5. ITunes Connect.

             

Back at the iOS Dev Centre we now want to prepare our App for upload to Apple for review. We do this by using the link below the Provisioning Portal called iTunes Connect. Click on this now. You will probably be asked to sign in again at this stage. 

            

1. On the iTunes Connect page (Figure 5) you will see a link to "Manage Your Applications" at the top of the right hand column. Click on this and then click on the "Add new App" button (top left).
2. You will be asked to select your App type (iOS or Mac OS X). Click on iOS.
3. Enter your App information. This is pretty self explanatory. For SKU we usually use the date (SKU = stock keeping unit, businesses use them to identify a unique product) and make sure that for Bundle ID you select the App ID created in section 13.3.1 above. The App name that you select will also need to be unique - in our case Minesweeper was taken so we went with iMinesweeper instead. When done click "Continue".
4. Next select the availability date and price tier. Use the current (default) date if you want your App released as soon as it is approved by Apple. Select some future date if you want to control the release date. This can be handy if you are co-ordinating a massive marketing effort to drive up demand for your App and its first day sales. Selecting anything else but FREE for the price will bring up a matrix showing the price for that tier in different countries. Click "Continue".
5. Fill out the version information and the age rating survey to determine its rating in the App store (e.g. Minesweeper comes out at a 4+ rating, the lowest possible). Clicking Frequent/Intense for some of these questions will mean that your App can't be sold in selected countries or in some instances at all. Next fill out your App's Metadata, this information will appear in the iTunes App store. The keywords are important because this is how customers will discover your App using the search functionality in iTunes. You are probably okay to go with the standard End User Licence Agreement (EULA), so the last step is to upload the images displayed in the App Store. The large App Icon needs to be 1024x1024 pixels in size. For the iPad screenshots, the easiest way to get these is using Organiser in Xcode (select your iPad from the left hand navigation panel and then screenshots. Run the App on your iPad using Xcode and then click the new screenshot button to take the images you want. You can then export these to a handy folder for upload to iTunes Connect). You can have up to 5 screenshots, drag and drop to change the order. Click "Save" when you are done.
6. After saving your App data you will be brought to the App summary screen. Check that all the details are correct. The status at this stage should be a yellow "Prepare for Upload". Click the "View Details" button below your App icon, then in the top right hand corner, click on "Ready to upload binary".
7. Answer the question about cryptography then click "Save" and then "Continue". Your App status will now be a yellow "Waiting for Upload". Click on App Summary and Done and you should see something like Figure 6, and we need to head back to Xcode for the next step.

            

Figure 6. iTunes Connect - Manage Your Apps.

       

13.3.3 Uploading Your Binary

         

In Xcode, we need to associate our App with the bundle ID that we set up in iTunes Connect. 

1. Before proceeding, we need to download the distribution provisioning profile. In the Organiser window, click on Devices and then Provisioning Profiles in the left hand navigation pane. Click on the Refresh button (bottom left corner) and your new profile will be downloaded.
2. Select the Project Navigator (top left button in the tool bar) and click on the top most item in the left pane, called Codea Template.
3. If you then select the summary tab in the right hand (or middle pane depending on how you have Xcode configured) you should see something like Figure 1. Scroll up to the top of the Summary tab. The Bundle Identifier will currently have: com.twolivesleft.Minesweeper. This needs to be changed to the bundle ID that we established in the steps above. In our case we changed it to au.com.reefwing.Minesweeper. Check that the correct version number is listed while you are here.
4. While we are here we will sign our code with the appropriate distribution profile. Select the "Build Settings" tab and scroll down to the Code Signing section. Under Code Signing Identity -> Release -> Any iOS SDK, select the distribution profile that you just downloaded.
5. Before uploading we need to recompile the binary with all this good stuff included. Select Product -> Archive from the menu bar. After compiling you should see Archive Succeeded in Xcode and the Organiser window will automatically be presented showing your App Archive (Figure 7).
6. In Archives (Figure 7), click on the Validate button (top right) and your archive will be validated prior to upload to Apple. At this stage, you may get an error - "No identities are available for signing." If you do, choose the Connect to iOS Dev Centre, "Download Identities" button. You should now be validated, click on "Finish"
7. Click on Distribute, select submit to the iOS App Store, click "Next" three times and you will see a message "Your application is being uploaded".
8. If all goes well you will get a "Submission Succeeded" message (Figure 8).

          

  Figure 7. Your App Archive in the Organiser Window.

    
Well done if you made it to this point. Believe it or not, Apple have actually streamlined and automated a number of steps in this process which used to be much more cryptic (especially for your first attempt at it).

  
If you want, you can go back into iTunes connect and validate that your App status has changed to orange and "Waiting for Review". In fact, we would recommend that you do this. There have been instances where people have uploaded their binary but for some reason it never moves on to "Waiting for Review." If this happens you can try rejecting the binary and re-uploading it. It will take about a week for the App to work its way up the review queue. Watch this space for updates...

     

Figure 8. Success! You App has been submitted for Review.

Interlude 11 - Classes in Lua and Codea

   

Interlude 11.1 What is a Class?

In Object Oriented Programming (OOP) a class is a coding construct used to define and create an object. Our original training was in the days of Procedural Programming, so we have some sympathy for those grappling with classes and other OOP paradigms for the first time. One way to think of a class is that it is the blueprint for an object.
  
When you create a new object using a class it is called an instance of that class. A class normally consists of data and functions which are associated with the object, this concept is called encapsulation. The class functions (sometimes called methods) act on the data variables to modify the behaviour of the object or provide information about its state. The purist approach is that only an objects functions can modify its variables. 

There are many benefits to using classes (code reuse, maintainability, modularity, inheritance etc.) but for us, the best thing about them is the mapping of a physical object or concept to a virtual object in your code. This makes it easier to conceptualise, write and understand complicated applications.
   
To be balanced we should point out that there is a camp of OOP haters (this rant by Linus Torvalds against C++ is quite amusing), it can make your code larger than necessary and arguably harder to maintain. Like most things in life moderation is the key. Abstraction for its own sake is pointless.
     

Interlude 11.2 Classes in Lua

   
As the comic at the start of the Interlude suggests, there is no class type in Lua. If that is the case then why the hell are we doing a tutorial on classes? Well it is possible to emulate a class in Lua using tables and because they are so useful the good folk at Two Lives Left have done it for you and it is included in Codea implementation of Lua. If you are really interested in how this is done then you can read the description on the Codea Wiki.
  

Interlude 11.2 Classes in Codea

    
The usual tutorial examples for classes are cars, employee data or animals. Whilst not wishing to anger the coding gods, we thought we would do something a bit more relevant to our next tutorial in the series (our interpretation of the classic SpaceWar! game). For this game we want to have a reusable ship class. The first step is to think about what sort of attributes a ship has which are relevant for us to model. Let's start with its position, speed and screen representation.
   
As mentioned above, Codea comes with a built-in global function called logically enough - class(). You can declare a class just about anywhere (with the usual caveat that if it refers to another class or function then this must have been defined before it in the tab order), but it is usually best to use the "+" tab at the top right of the screen when you are in a project to create your class. Tapping the "+" will bring up a popover with the "Create New Class" button at the top. Tapping this button allows you to enter the name of your new class and when "Done" is then tapped, Codea will create a new tab with your class template code. By convention class names start with a capital and class instances start with a lower case letter. This helps with the readability of your code, as you can immediately tell if you are referring to the class or its instance.
    

Interlude 11.3 The Ship Class

    
OK let's give it a go. Create a new project called SpaceWar! then tap the "+" tab and create a new class called Ship. You should end up with something that looks like Figure 1.
  

Figure 1. Default Class Template in Codea.

   
Codea automatically adds three functions to your class which you will usually need. The init(x) function is often called a constructor in OOP terminology. Whenever you create an instance of a new class this function will be called to set it up. Notice the x? When you create a new class you can pass in parameters to be used in the initialisation. The line self.x = x is assigning the parameter that you pass in (x) to the class variable (self.x). You don't have to do this, in which case your function would look like Ship:init() and you would also delete the line self.x = x in the body of the function. 

The draw() function you would be familiar with from earlier tutorials. Within a class we use it to handle the drawing of your object (if required). As the embedded comment says, Codea won't automatically call this function, you need to explicitly call it from the draw() function in Main. We will show you how to do this shortly.
    
Similarly, the touched() function looks after how your object handles touches. As for draw(), Codea won't call the class touch function automatically, so you need to do it in the Main touch() function. We won't be using touch until later.
   
So we have a ship class but it isn't much use at the moment. To keep track of our ship we want to use screen co-ordinates (x,y), assign a speed and allocate an image to represent the ship. The following code will achieve these objectives. 
      
Ship = class()
   
function Ship:init(x, y)
    -- you can accept and set parameters here
    self.x = x
    self.y = y
    self.speed = 5
    self.image = readImage("Tyrian Remastered:Boss D")
end
    
function Ship:draw()
    -- Codea does not automatically call this method
    -- Draw the ship
   
    sprite(self.image, self.x, self.y)
   
end
   
function Ship:touched(touch)
    -- Codea does not automatically call this method
end
        
We want to initialise our ship located in the middle of the screen so in the setup() function of your Main class you would have:
    
myShip = Ship(WIDTH/2, HEIGHT/2)
  
And then to draw you ship, in the Main draw() function, after the line background(40, 40, 50) add the line:
   
myShip:draw()
  
It is as simple as that. In subsequent tutorials we will look at the concept of inheritance and ways of moving your ship (the earlier Move Ship code in Tutorial 8 illustrates one method).

Tutorial 12 - Submitting to the App Store Part 1

Webcomic Courtesy of Ethanol & Entropy

12.1 The App Store Journey

For many people the whole point of writing applications is to see them published in the App store and available for download from iTunes. Before you quit your job and go out and buy matching Porsche 911's you would be wise to get a few months of sales data under your belt. Like most endeavours, there is a bell curve of App sales. Everyone hears about Angry Birds developers making $70m, but there is a lot less media coverage at the other end of the bell curve. 

In a recent survey of more than 1,500 developers in 83 countries, it was found that the average per-app revenue is roughly $1,200 to $3,900 depending on the platform. Additionally, the survey noted that an app has roughly a 35% chance of generating between $1 to $500. This obviously means that most developers cannot rely on app development as their main source of income. However, it does mean that if you put the effort in you can make enough to fund your development habit. 

Our own experience is that you can never tell which Apps are going to be regular sellers (LifeGoals) and which will sink like a stone (LifeMovie). The Reefwing stable of Apps currently nets us around AUD$10k per annum, which is sufficient to purchase a MacBook Air, a new iPad, external development costs (Apple Developers Licence, App Sales Analytics, web-site and forum costs, etc.) plus a bit of change for the highly caffeinated beverages which programmers run on. We only work on this the odd night and weekend so with more application we imagine the rewards would be better. The thing that we are no where near recovering is the time spent developing. The average App takes us about 3 months from start to finish and while the proceeds roll in for some years to come, it isn't really passive income because sales quickly decline if you aren't frequently updating your App. 

However, lets face it - we would code if we didn't get paid anything so anything we do get is a very pleasant upside. There is also something addictive about tracking the daily "sales" of you App (even if it is free).

The other thing that most developers don't realise, is that the Apps which are successful in the App store, have as much time and money spent on marketing their Apps as they do on developing them. There is the odd exception but these are an exemption. Books have been written on this subject and we will provide our thoughts on the best approaches to marketing in a later tutorial.

But for now, let's have a look at how we go about getting our Minesweeper game submitted for approval.

Figure 1. Xcode in the Mac App Store.

12.2 What do I need and how much will it cost?

The process of getting your App approved is fairly straight forward but there is a fair bit of assumed knowledge which we will attempt to clarify. Sometimes we may miss a step due to our familiarity with the process and software, so don't hesitate to drop us a comment if you get stuck. This will help not only yourself but future readers.

To get your App in iTunes there is a bit of an investment. Presumably if you are reading this you already have an iPad and Codea, so we will assume that they are a sunk cost. All of the costs below are in Aussie Dollars unless stated otherwise. In addition to Codea on your iPad, you are going to need:

• Some variety of Mac which will run Xcode (there are virtual machine solutions for those who want to do it the hard way or save money (e.g. for Windows or the Mac In the Cloud solution), but that is outside the scope of this tutorial). Any recent Mac will do the job so the cheapest new solution at the time of writing would be a Mac mini from $699 if you already have a monitor and keyboard.
• A paid App Developer Licence. These come in a variety of flavours but the cheapest will cost you $99 per year. We have a company licence for tax reasons but individual is fine (and simpler to apply for). There is a bit more effort required if you want to sell apps (as opposed to making them free) but it doesn't cost any more, apart from the 30% cut of every sale that Apple keeps. You can register for free developer licence but this doesn't allow you to upload an App on iTunes. This process used to take a bit of time so apply before you need the licence. 
• A copy of the Apple Xcode 4 Integrated Developer Environment (IDE), which is available as a free download on the Mac App Store (that also includes the OS X. and iOS  Software Development Kits - see Figure 1) to registered members of Apple’s iOS and Mac Developer Programs. This tutorial is based on version 4.4 of Xcode which runs on the Lion and Mountain Lion variants of OS X.
• A copy of iExplorer from Macroplant so that you can extract your Codea project from your iPad and load it into Xcode. This costs $31.04 (US$31.49). We are using version 3.0.1.2 for this tutorial. There is also a free program for linux users called libimobiledevice which I understand comes in Windows and OS X variants but we haven't used it (thanks to Andrew Stacey for pointing it out). Another FREE option is iFunBox (thanks to Keebo for this suggestion).
• The Codea Runtime Library - Which we will discuss in some detail in the next section. It is available free, courtesy of Two Lives Left. Version 1.4.3 was the version we used for the tutorial, it appears to still be a Beta version but works fine apart from some warnings when you compile.
• And finally an internet connection is required, so that you can upload your App to iTunes Connect.

12.3 Step 1 - Download and Extract the Codea Runtime

    
[UPDATE: An assumption here is that you have already developed your App in Codea and it is operating without any obvious run time bugs. Don't bother submitting buggy code to Apple it will just be rejected and if by some chance it gets through the approval process, you will get a reputation for developing poor quality software. 

One of the issues with the App store process is that if you delete an App from your device it prompts you to rate it and provide a comment. Obviously, if a user is deleting an App it is likely that they are not going to rate it very highly. Since most happy users of you App wont bother to rate it (unless asked to), this can lead to a negative bias in ratings and comments which will dramatically effect your downloads and sales. 

To offset this bias it is good practise to prompt your users to rate and comment on your App just after something positive has occurred (e.g. a level in a game was completed) or if they have been using the App for some period of time. Under these circumstances you are much more likely to get a positive review. Like most things, moderation is the key, badgering your users for positive reviews will likely produce the opposite effect to what you were intending.

IMPORTANT: The latest version of Codea (v1.4.3) supports dependencies. These are a great tool for re-using code but unfortunately the current runtime (also v1.4.3) doesn't know how to handle them. So don't use dependencies if you plan on submitting your code to the App store.]

In order to submit your App you first have to get it working in the simulator on your Mac. We will also use this opportunity to add a touch more polish. The native language of iOS is Objective C so getting your Lua Codea App to run in Xcode requires the Codea Runtime Library. 

Figure 2. Git repository of the Codea Runtime Library.

Clicking on any of the Codea Runtime Library links in this tutorial will take you to the Git repository for the code (Figure 2). From here you can read a short description of the library, the current version, licence information (Apache License v2.0), requirements and setup. Have a read of all of this and then click on the zip button in the top left of the page to download a zipped copy of the Library and a script (make_project.sh), to your Mac development machine. We use chrome as our browser and in this you can right click (control click) on the downloaded file and select "Show in Finder" to take you to the file. Whatever you are using, locate the downloaded zipped file which is probably in the Downloads folder (depending on your preferences) and called something like "TwoLivesLeft-Codea-Runtime-1.4.3-0-g1539e18.zip", and then double click on it to decompress the archive.

This will create a folder called "TwoLivesLeft-Codea-Runtime-1539e18" or similar which contains a Codea Template folder, a copy of the licence, the readme file and the make_project script. To save on typing in the next step we renamed the folder "TwoLivesLeft-Codea-Runtime-1539e18" to "Codea" - but this is optional.

The next step requires us to get our hacker hat on and use Terminal. This is where the setup instructions in the Codea Runtime library assume a bit of knowledge, but don't worry we will take it slowly.

12.4 Step 2 - Enter the Terminal

    
Terminal is a program included with all versions of Mac OS X. It is located in the Utilities folder within the Applications folder. When launched, it provides a command line interface to control the UNIX based operating system. The default UNIX shell in Mac OS X Panther (10.3) or later is called Bash.

Figure 3a. The Terminal Application.

Go ahead and launch Terminal, you will see a window like that shown in Figure 3a. You should be in the root directory at this point. Type "ls" (don't include the double quotes) and you will see a list of files and directories which are in the current directory. You need to navigate to the directory which contains the files you just downloaded and extracted. In our case we first change directories to Downloads by typing "cd Downloads", you should see the  Terminal prompt change to something equivalent to:

DS-MacBook-Air:Downloads dsuch$ 

Type "ls" again if you have forgotten what the extracted zip folder is called, we changed the name to "Codea" so that we could remember, thus at the prompt we now type "cd Codea". 

Okay you should now be where we need to be. Type "ls" to check, hopefully you see:

DS-MacBook-Air:Codea dsuch$ ls
CodeaTemplate README.md
LICENSE-Codea.txt make_project.sh
DS-MacBook-Air:Codea dsuch$ 

This next step will create an Xcode template for your Codea project with the same name as your App. At the command line prompt, type "./make_project.sh yourAppName" where "yourAppName" should be replaced with the name of your App. Don't miss the full stop "." at the start of the script, this means run a command script in the current shell.

Note: if you plan to release your game on the iOS App Store please do not use the word "Codea" in the title of your game. (You may, however, mention Codea in the description and keywords for your game. Or in the game itself.)

There will be a brief pause when you execute the script and then the command prompt will return. Do another "ls" to see the newly created Xcode folder. Remember our App is called Minesweeper so the results look like:

DS-MacBook-Air:Codea dsuch$ ./make_project.sh Minesweeper
DS-MacBook-Air:Codea dsuch$ ls
CodeaTemplate Minesweeper make_project.sh
LICENSE-Codea.txt README.md
DS-MacBook-Air:Codea dsuch$

Notice the new directory called Minesweeper? That's what we need. We won't go into the detail of the bash script used but those really interested can work it out themselves by looking at the list of bash commands and the contents of the script.
      

You can now close down Terminal (command w will close the window), but remember where your new Xcode folder is located.

Figure 3b. The custom Dropbox.spritepack folder on the iPad

 
[Update: If you use custom sprites in your project then you need to copy across your Dropbox.spritepack folder (using iExplorer it is in Apps -> Codea -> Documents - see Figure 3b) and place it in the SpritePacks folder in the project created by running the script. In our example, the destination folder is Minesweeper -> SpritePacks. You will see the other standard sprite packs in the same location. To save space you could delete the images you don't use in this App from the copy of your Dropbox.spritepack folder.

If you haven't used iExplorer before then read section 12.6 below to get it set up. To copy from your iPad to the Mac, navigate to the location of the Dropbox.spritepack folder and right click on it, then select "Export to Folder" from the pop up menu.]

The next bit is optional but we think it is good practise. All of our Xcode projects are kept in a directory imaginatively called "Xcode Projects". Locate your newly created Xcode folder (in Downloads\Codea: for us) using Finder and copy or drag across to the directory where you will store your projects (Figure 4). 

Figure 4. Codea Runtime Xcode Template in Finder

In Figure 4. you will see a file in the Minesweeper directory called CodeaTemplate.xcodeproj, you can double click on this to load the project into Xcode, or follow the instructions in the next step.

12.5 Step 3 - Opening up the Codea template in Xcode

Stage 1 is almost complete. Open up the Xcode App, click on file, open in the menu bar and navigate to your new Xcode directory described in the previous section. Single click on the directory name and then click on the open button in the bottom right of the open file dialog. This will load the CodeaTemplate project into Xcode. 

[UPDATE: DO NOT run and compile the default runtime until your project is loaded and has replaced the Dungeon Roller project (see the next section). When the runtime is executed it copies the Lua files from the Project.codea folder into the iPad's document folder for this App. If you do this with the default folder it will copy across all the Dungeon Roller files and leave them there. At worst you may have Lua files with the same name which will cause very odd behaviour and will probably cause the App to crash. At best you are taking up unnecessary space on your iPad.]

If you do want to just see the default runtime project in operation, then in the top left of the Xcode screen you will see a play button, click on that to compile and run the loaded project code (Figure 5). As the project compiles you may see a bunch of warnings, don't worry about those. Eventually the iPad simulator will launch with the default Codea App "Dungeon Roller", one of the example Apps provided with Codea.

Figure 5. Xcode 4 and the iPad Simulator.

It is all very well to have an operating Codea Template project, but how do we inject our App so that it is playing in the simulator not "Dungeon Roller"? This is where iExplorer comes into play. Leave Xcode open as you do the next step.

12.6 Step 4 - Extracting your Codea project from the iPad

Connect your development iPad to your Mac using the USB cable and then launch iExplorer. All going well, iExplorer should look like Figure 6.

Figure 6. iExplorer connected to iPad

Using the left hand pane, navigate to Apps -> Codea -> Documents (Figure 7) and find your App folder (Minesweeper.codea in our case), right click (control click) on this and select "Export to Folder" from the pop up menu. It doesn't matter too much where you save this folder, we put it in Downloads.

Figure 7. Find your App in iExplorer and Export it to your Mac.

Back in Xcode, open up the classes folder using the left hand navigation panel (if you can't see the folders and files then click on "show the project navigator button" in the top left hand corner - it looks like a grey folder). Delete the existing Project.codea folder by right clicking (control click) on it and choosing delete from the pop up menu, select "Move to Trash" in the subsequent dialog box.

Open up Finder on your Mac, locate the yourAppName.codea directory and rename it "Project.codea". Drag your Project.codea folder into Xcode (just below the classes folder) and when you release the mouse button you will see Figure 8.

Figure 8. Import your Project.codea directory into Xcode

Check the "Copy items into destination folder's group (if needed)", Select "Create folder references for any added folders" and make sure your app's target is selected, then Click Finish.
 
You should now be able to compile and run your application in the Xcode iPad simulator. 
   
[Update: An alternative approach to that described in the Codea runtime (which we have described above) would be to: 
 

1. Close Xcode.
2. In iExplorer navigate to your Apps folder within Codea (e.g. Apps -> Codea -> Documents -> Minesweeper.codea).
3. Right click on this folder and select "Export to Folder"
4. Navigate into the folder created by step 2 (section 12.4). In our case it is called Minesweeper. Within this folder you will see a folder called CodeaTemplate.
5. Within CodeaTemplate you will see the Project.codea folder. Export your project file (e.g. Minesweeper.codea) into this location.
6. Right click on the default Project.codea folder and select "Move to Trash" from the popup menu.
7. Rename your file to Project.codea
8. Open Xcode and from the Menu -> File -> Open: select CodeaTemplate.xcodeproj from the folder created in step 2. ]