Tutorial 21 - Integrating Game Center (Part 3)

21.1 On the Shoulders of Giants...

Juan Belón (@juaxix over on the Codea Forums) has already done a lot of the hard work required to get Game Center up and running on your Codea App. If all you need is to submit scores to a single leaderboard then just follow Juan's instructions at this post. Juan has also provided the ability to play and stop mp3's from a Codea App.

We want to be able to submit scores to multiple leaderboards (Easy, Medium and Hard) and incorporate achievements so we need to add to the code that Juan has generously contributed. To this end we will fork his Game Center class on GitHub.

We will start by updating the Codea Runtime Objective C code.

21.2 Modifications to LuaState

In Xcode, make sure that you are showing the Project Navigator (top left button on the tool bar). Open up the Frameworks group, then Codea -> Backend. In Backend, click on the LuaState.m file. Within this file you will see a method called - (void)create{ }. To this method add the following:

//  Game Center Functions:

    LuaRegFunc(aGameCenter_start);

    LuaRegFunc(aGameCenter_isGameCenterAvailable);

    LuaRegFunc(aGameCenter_showEasyLeaderboard);

    LuaRegFunc(aGameCenter_showMediumLeaderboard);

    LuaRegFunc(aGameCenter_showHardLeaderboard);

    LuaRegFunc(aGameCenter_reportEasyScore);

    LuaRegFunc(aGameCenter_reportMediumScore);

    LuaRegFunc(aGameCenter_reportHardScore);

    LuaRegFunc(aGameCenter_reportAchievementIdentifier);

    LuaRegFunc(aGameCenter_showAchievements);

    LuaRegFunc(aGameCenter_resetAchievements);

//  Play Music

    LuaRegFunc(playMusic);

    LuaRegFunc(stopMusic);

21.3 Modifications to OSCommands

In the same directory as LuaState you will see OSCommands.h and OSCommands.m, click on the header file OSCommands.h and after int alert(struct lua_State *L) add the following:

//  Game Center:

    int aGameCenter_start(struct lua_State *state);

    int aGameCenter_isGameCenterAvailable(struct lua_State *state);

    int aGameCenter_showEasyLeaderboard(struct lua_State *state);

    int aGameCenter_showMediumLeaderboard(struct lua_State *state);

    int aGameCenter_showHardLeaderboard(struct lua_State *state);

    int aGameCenter_reportEasyScore(struct lua_State *state);

    int aGameCenter_reportMediumScore(struct lua_State *state);

    int aGameCenter_reportHardScore(struct lua_State *state);

    int aGameCenter_reportAchievementIdentifier(struct lua_State *state);

    int aGameCenter_showAchievements(struct lua_State *state);

    int aGameCenter_resetAchievements(struct lua_State *state);

  //  Play Music

    int playMusic(struct lua_State *L);

    int stopMusic(struct lua_State *L);

Then in the implementation file, OSCommands.m add the following:

static aGameCenter_Codea *CodeaGameCenter;

int aGameCenter_start(struct lua_State *state){

    NSLog(@"Starting Game Center");

    if (CodeaGameCenter==nil){

        CodeaGameCenter = [[[aGameCenter_Codea alloc] init] autorelease];

    }

    [CodeaGameCenter start];

    return 0;

}

int aGameCenter_isGameCenterAvailable(struct lua_State *state){

    return [CodeaGameCenter isGameCenterAvailable];

}

int aGameCenter_showLeaderboard(struct lua_State *state) {

    [CodeaGameCenter showLeaderboard];

    return 0;

}

int aGameCenter_reportEasyScore(struct lua_State *state) {

    [CodeaGameCenter reportEasyScore:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_reportMediumScore(struct lua_State *state) {

    [CodeaGameCenter reportMediumScore:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_reportHardScore(struct lua_State *state) {

    [CodeaGameCenter reportHardScore:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_reportAchievementIdentifier(struct lua_State *state) {

    [CodeaGameCenter reportAchievementIdentifier:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_showAchievements(struct lua_State *state) {

    [CodeaGameCenter showAchievements];

    return 0;

}

int aGameCenter_resetAchievements(struct lua_State *state) {

    [CodeaGameCenter resetAchievements];

    return 0;

}

int playMusic(struct lua_State *L){

    [CodeaGameCenter playMusic:lua_tonumber(L,1)];

    return 0;

}

int stopMusic(struct lua_State *L){

    [CodeaGameCenter stopMusic];

    return 0;

}

21.4 Modifications to the aGameCenter_Codea Class

The final change in Xcode is to add the updated version of the aGameCenter_Codea class. You can download the forked version of Juan's code here. Add these two files to the Supporting Files group in the runtime.

21.5 Modifications to your Codea App

  

Once you start adding the Game Center functionality you wont be able to compile and run your App in Codea anymore (since these functions are only defined in the runtime). Consequently, debug all of your code apart from the Game Center specific parts before you make the following modifications. 

After you are in Xcode and using the runtime, you can still update your Lua code but you need to force the runtime to reload the Lua files into the documents directory. You can do this by changing the version number in the Lua info.plist which can be found in Project.codea. 

This number just needs to be different (not necessarily larger) to what it was the last time you compiled, to force an upload. Alternatively, if you get sick of doing this each run-test cycle (like we did), you can go into the CodifyAppDelegate.m file, find the - (BOOL) migrateProjectAtPath:(NSString*)path toPath:(NSString*)destPath method and comment out the following code as shown below.
  

// NSString* oldVersion = [self versionForProjectAtPath:destPath];

// NSString* newVersion = [self versionForProjectAtPath:path];

// if ([oldVersion isEqualToString:newVersion]) 

//    {

//        return YES;

//    }

Should you need to add sprites, you can save these directly into the dropbox folders in the runtime but you may need to do a clean build (select Product from the menu bar and then Clean) before Xcode will see them.

As part of the Game Center update of MineSweeper (v1.5) we took the opportunity to tweak the code based on feedback from the Codea Forum. In particular:

1. There is a new MineSweeper logo on the Menu screen courtesy of @derhannes (you can see their web site at: http://www.boba-soft.com).
2. The falling mines on the Menu Screen now start dropping from above the screen which makes the animation look smoother. Thanks to @Fred for this suggestion.
3. The textBox used to enter the players name, if a new high score is achieved, now handles a changing orientation (e.g. Portrait to Landscape). Thanks to @West for finding this bug.

Once you have added all the code above, the actual Game Center implementation in Lua is very simple. In the Setup() function in Main add the following code:

-- Initialise Game Center if it is available (requires a device running iOS 4.1
-- or later and the App needs to be running within the Codea run time).
    
    aGameCenter_start()
    if aGameCenter_isGameCenterAvailable() then
        print("Game Center Started.")
    else
        print("Game Center not available")
    end

Then you just need to report your scores and achievements as they happen. For example in MineSweeper when the game is won we do the following achievement checks:

-- Check if any Achievements were completed once game
-- has been won.
        
        if gameDifficulty == stateEasy then
            if readLocalData("easyWinner") == nil then
                saveLocalData("easyWinner", "YES")
                aGameCenter_reportAchievementIdentifier(1)
                print("Easy Winner Achievement.")
            end
        end
        
        if gameDifficulty == stateMedium then
            if readLocalData("mediumWinner") == nil then
                saveLocalData("mediumWinner", "YES")
                aGameCenter_reportAchievementIdentifier(2)
                print("Medium Winner Achievement.")
            end
        end
        
        if gameDifficulty == stateHard then
            if readLocalData("hardWinner") == nil then
                saveLocalData("hardWinner", "YES")
                aGameCenter_reportAchievementIdentifier(3)
                print("Hard Winner Achievement.")
            end
        end
        
        if readLocalData("gamesPlayed") == nil then
            gamesPlayed = 0
        else
            gamesPlayed = readLocalData("gamesPlayed")
        end
        
        gamesPlayed = gamesPlayed + 1
        saveLocalData("gamesPlayed", gamesPlayed)
        if gamesPlayed == 10 then
            if readLocalData("decathlon") == nil then
                saveLocalData("decathlon", "YES")
                aGameCenter_reportAchievementIdentifier(6)
                print("Decathlon Achievement.")
            end
        end
        
        if gamesPlayed == 100 then
            if readLocalData("centurion") == nil then
                saveLocalData("centurion", "YES")
                aGameCenter_reportAchievementIdentifier(7)
                print("Centurion Achievement.")
            end
        end

To save high scores onto the relevant leader board we updated the saveHighScore function as shown below.

function saveHighScore(d)
    
    -- Build the high score data into a string which is saved
    -- using saveLocalData(key, value). Also save gameTime as
    -- the score on Game Center for the appropriate leader board
    -- (easy, medium or hard).
    --
    -- n = playerName
    -- t = gameTime
    -- d = os.date() [current date] not used in this version
    
    playerName = textBox.text
    print("New High Score by: "..playerName)
    
    local hsDataString = string.format("return {\"%s\", %d}", playerName, gameTime)
    
    if gameDifficulty == stateEasy then
        saveLocalData("easyHighScore", hsDataString)
        aGameCenter_reportEasyScore(gameTime)
    elseif gameDifficulty == stateMedium then
        saveLocalData("mediumHighScore", hsDataString)
        aGameCenter_reportMediumScore(gameTime)
    elseif gameDifficulty == stateHard then
        saveLocalData("hardHighScore", hsDataString)
        aGameCenter_reportHardScore(gameTime)
    end
    
    hideKeyboard()
    highScoreSaved = true
    
end

Tutorial 20 - Integrating Game Centre (Part 2)

20.1 Scores and Achievements

Before getting too much further we need to decide what scores and achievements that you want to have for your game. For MineSweeper we will keep things fairly simple. We will set up a leader board for each game difficulty (easy, medium and hard) and keep track of the following achievements:

• Easy Winner (25 points) - Won an Easy Difficulty Game;
• Medium Winner (50 points) - Won a Medium Difficulty Game;
• Hard Winner (100 points) - Won a Hard Difficulty Game;
• Boom (25 points) - tapped a mine;
• Bad Luck (50 points) - tapped a mine on your first move;
• Decathlon (50 points) - play 10 games of any difficulty; and
• Centurion (100 points) - play 100 games of any difficulty.

20.2 iTunes Connect - Leaderboards

To set up the metadata for your App, log into your iOS developer account and go to iTunes Connect. We are assuming that you have already set up your App ID and provisioning profiles. If you haven't, look at Tutorials 12 and 13. 

Click on the Manage your Applications link and then click on the App icon that you want to set up for Game Center. On the App Information screen you will see a button in the top right called Manage Game Center. Click on this and then enable your game (as either a single game or part of a group of games which shares scores and achievements). For MineSweeper we will just enable it as a single game, you can always change it to a group game later if you wish.

From the Game Center screen you can add leader boards and achievements. Remember that Leader boards which are live for any app version cannot be removed. This is true for achievements as well.

Click on the Add Leaderboard Button and then select add Single Leaderboard (You cannot create a combined leaderboard until you have two or more single leaderboards with the same score format type and sort order).

Figure 1. Add Language Screen.

Fill out the information for your leader board. The leaderboard reference name is an internal name that you must provide for each leaderboard. It is the name you should use if you search for the leaderboard within iTunes Connect. We used "Easy Difficulty" for our first leaderboard reference name.

The Leaderboard ID is a unique alphanumeric identifier that you create for this leaderboard. It can contain periods and underscores. We used the reverse URL style for ours (e.g. au.com.reefwing.minesweeper.easyDifficulty).

Then choose the score format for this app leaderboard and choose "High to Low" if you want highest scores displayed first or choose "Low to High" if you want the lowest scores displayed first. We select "Low to High" because a lowering your time to solve the grid is the objective.

Optionally, you can define the score range using 64-bit signed integers. The values must be between the long min (-2^63) and long max (2^63 - 1). Any scores outside of this range will be deleted. We don't define a score range for MineSweeper.

You must add at least one language for your leader board. For each language, you will have to provide a score format and a leaderboard name. Click on the Add Language button to bring up the screen to do this (see Figure 1).

The score format suffix will be added to the end of scores displayed on your leaderboard. Use this field to specify a singular suffix. This is optional, and is useful for clarifying the type of score your app uses. Examples include "point", "coin", or "hit".

Finally, you can assign an image to your leaderboard. The image must be a .jpeg, .jpg, .tif, .tiff, or .png file that is 512x512 or 1024x1024 pixels, at least 72 DPI, and in the RGB color space. Click the Save button and you are done.

Figure 2. Add an Achievement.

20.3 iTunes Connect - Achievements

Creating achievements is very similar to leaderboards. Click on the "Add Achievement" button to get started (Figure 2).

The Achievement Reference Name is an internal name that you must provide for each achievement. It is the name you should use if you search for the achievement within iTunes Connect (e.g. Easy Winner).

The Achievement ID is a unique alphanumeric identifier that you create for this achievement. It can contain periods and underscores. Once again we used the reverse URL style for ours (e.g. au.com.reefwing.minesweeper.easyWinner).

Point Value is the amount of points your achievement is worth. There is a maximum of 100 points per achievement and 1000 points for all achievements combined. The points we assigned to each achievement are shown in section 20.1. You will see that we have left lots of spare points in case we want to add additional achievements in the future.

Achievements marked as Hidden will remain hidden on Game Center until a player has achieved them. We wont hide any of our achievements.

For the "Achievable More Than Once" field, If you select Yes, users can accept Game Center challenges for achievements they have already earned.

Once you have filled out the above metadata for your App you need to add at least one language. For each language you need to add:

• Title: The localized title of this achievement as you would like it to appear in Game Center (e.g. Easy Winner).
• Pre-earned Description: The description of your achievement as it will appear to a Game Center user before they have earned it (e.g. Win at least one Mine Sweeper game on Easy Difficulty).
• Earned Description: The description of your achievement as it will appear to a Game Center user after they have earned it (e.g. Won at least one Mine Sweeper game on Easy Difficulty).
• An image for your achievement. The image must be a .jpeg, .jpg, .tif, .tiff, or .png file that is 512x512 or 1024x1024 pixels, at least 72 DPI, and in the RGB color space.

Click the Save Button and you are finished. Rinse and repeat for each one of your achievements.

In part 3 of the tutorial we will detail the code required in Lua and Objective C to tie these leaderboards and achievements to your game.

Tutorial 19 - Integrating Game Centre (Part 1)

19.1 Game Center

   
Game Center is Apple’s social gaming network. Integrating Game Center functionality into your Codea App has to be done in Xcode. There are three main areas that we need to concern ourself with to implement Game Center:

1. Players;
2. Scores; and
3. Achievements.

All of your metadata for Game Center functionality is set up and managed in iTunes Connect, allowing you to test your Game Center features before submitting your app to the App Store. You use iTunes Connect to enable your app for Game Center testing, and set up your leaderboards and achievements. Then use the Game Kit framework in your app to add Game Center functionality.

   

Apple suggests that you should consider scores and achievements as part of your initial game design (as opposed to tacking it on at the end). This is a legitimate observation in most cases, for example passing other players in DoodleJump is arguably why it is so popular.

  

Be aware that once your Game Center assets are published to the live servers, some assets become more difficult to change because they are already in use by players and on live versions of your game. For example, leaderboard scores are formatted using the leaderboard assets you created. If you change your scoring mechanism and change your leaderboard assets to match, older scores would still be posted on Game Center and would be inconsistent with the newer scores. For this reason, some assets you create cannot be modified after the game ships.

    

19.2 Why Bother?

   

Many iOS games use Game Center, but not all of them use every feature. Apps can choose to include any or all of the following features supported by Game Center:

• Leader-boards – compares scores with the player's friends and with other players from around the world
• Achievements – shows goals that can be accomplished by the player and also allows the player to compare with friends' achievements
• Multiplayer – the game can host matches in real time, either between the player's friends or by "auto-matching" with random players from around the world.

Some of the reasons that you may want to include Game Centre are:

1. Improve the longevity and replayability of your game by adding challenges (aka Achievements) or multiplayer capability.
2. Being able to see usage of your Apps via leaderboard activity.
3. Improve the discoverability of your Apps through players challenging their friends and the new facebook "like" button.
4. Allows players to rate your App from Game Center (if your App is rubbish this may not be a good thing).

To setup Game Centre there is code that we need to add to the App and then metadata which we need to add to iTunes Connect for the App. This tutorial will deal with the App side changes.

      

19.3 Step 1 - Authenticate the Player

     

To demonstrate the implementation of Game Center, we will use the MineSweeper App developed in previous tutorials. We are assuming that you are familiar with the Codea runtime and have got your App running in Xcode. If you haven't then read Tutorials 12 and 13 first. 

     

    

To start, open up your App in Xcode. The first thing we need to do is to link the GameKit framework. In the navigator area of Xcode 4, select the project name in the top left, it should be “CodeaTemplate”. Next, select the current target (“MineSweeper” in our case), and then select the “Build Phases” tab. Expand the “Link Binary With Libraries” option, and then click the “+” button to add a new framework. Type “g″ into the search box, and select the GameKit.framework framework that appears in the list. Click “Add” to link this framework to  your project. So far so good.

Once again in the Project Navigator pane, Under Classes -> Supporting Files, click on the CodifyAppDelegate.h file and add:

  

#import <GameKit/GameKit.h>

  

Your App will now recognise the Game Center methods and variables. If we weren't using Codea, setting up Game Center is pretty simple, to illustrate:
 
Click on CodifyAppDelegate.m and add the following to the end of the didFinishLaunchingWithOptions method:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

{

    // Existing code here...

    // Authenticate Player with Game Center

    

    GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

    

    // Handle the call back from Game Center Authentication

    

    [localPlayer authenticateWithCompletionHandler:^(NSError *error)

    {

        if (localPlayer.isAuthenticated)

        {

            // Player was successfully authenticated.

            // Perform additional tasks for the authenticated player.

        }

        else if (error != nil)

        {

            NSLog(@"error : %@", [error description]);

        }

    }];

    // ...and back to the existing code.

    Return YES;

 

}

This is the code for pre-iOS 6 (since I have an iPad 1) devices. If you are developing for iOS 6, note that authenticateWithCompletionHandler is deprecated (use localPlayer.authenticateHandler instead).

  

Running this code in the Xcode simulator should present you with the pop up shown in Figure 1. Log in with your usual App ID to test.

  

Figure 1. Game Center Sign In.

  

If you haven't enabled your game for Game Center, once you log in you will get the error shown in Figure 2.

  

Figure 2. Game Center not enabled Error.

The problem is that we need to be able to submit scores and achievements from within our Codea App and Codea doesn't know about Game Center. However, one of the gun coders, @juaxix over on the Codea Forums has built a bridge between Objective C and Lua. We will extend this and use it to enable Game Center for MineSweeper. So delete the authentication code above if you added it to your App and we will show you the correct way to bring Game Center functionality to your Codea App.

In the next tutorial we will show you how to add leader boards and achievements in iTunes Connect. We will need these before we can make the changes required to our Lua and Objective C code.

Tutorial 18 - Saving and Loading Complicated Tables

18.1 Recap

   
Tutorial 18 brings together elements from a number of the previous Tutorials. It is an example of where asking the right question makes finding the answer much simpler. Our aim is to be able to load and save level data from our Tower Defence level generator. Most of the data we need is stored in a table. The tricky part is that Codea only allows us to save data as strings at the moment (some smart folks over at the Codea Forum have worked out how to jam data into image files and save those).
  
Tutorial 16 examined a technique for saving simple table structures like a one dimensional array. Initially we thought that saving a more complicated table wouldn't be that tough. All we needed was one of the existing Lua table to string parsers like Pickle / UnPickle. WRONG!
    

18.2 Limitations of Table Serialisation Parsers

  
We discussed Lua tables in Interlude 6. They are simple in concept but capable of representing very complicated structures. Tables can contain all the simple Lua types (booleans, strings, nil, and number), functions, other tables, closures, etc. The most complete table to string parser that we could find was Data Dumper. But even Data Dumper can not handle tables that contain:

• Both light and full userdata
• Coroutines
• C functions

And of course our level data contains userdata (e.g. vec2 is represented using userdata). So where to from here?

    

18.3 The Modified Cell Class

   

This is where asking the right question makes all the difference. Looking at which data we actually need to save, it becomes apparent that we don't need to save the entire table (including functions) as this can all be reconstituted. All we really need from the Grid table is what is contained in each cell. So rather than trying to convert a two dimensional array of cell objects (which contain userdata) into a string, we extend the cell class to provides its contents (state) as a string. We also provide the inverse function which sets the cell state from a string so we can load the level back in. The extended cell class is shown below.

  

  

Once we can get the grid cell contents out as a string it is easy to write a function to create a simple two dimensional table holding each of these strings. Data Dumper makes short work of converting this table to a string which we can save to global data. Even better, Data Dumper saves the table in a format that loadstring can use to rebuild the original table. The updated Main class for dGenerator details these save and load functions.

  

We updated the File Manager class from Tutorial 17 to allow us to select the file to be loaded. As part of this update we got rid of the submenus because we didn't need them and they meant that the user had to do an extra tap to load. In addition, Delete was right next to Load which is poor design. One slip of the finger would be potentially disastrous (particularly because there is no confirmation for delete and no undo). The other improvement to this version of File Manager is we truncate keys and values which are larger than the ListScroll widths. You can see the upgraded version in the screenshot below. The About menu item doesn't do anything at this stage.

     

18.4 Loading & Saving Data

   

Tapping the Save button on the main screen of dGenerator will call the saveLevel() function in Main(). The function starts off by saving the simplified table data in saveGrid. It then generates the key which contains a header "dGen" (to indicate when loading if it is the right data type), the game name and level number, a boolean indicating if the start cell has been selected and its co-ordinates and then a boolean indicating if the end cell has been selected and its co-ordinates. Finally we use Data Dumper to convert saveGrid to a string and save the key and value to global data.

  

Loading a level is the reverse. Tapping the Load button on the dGenerator main screen will call the loadLevel() function in Main. This prints out some debug data but its only compulsory action is to set the App state to stateFileManager. This will draw the File Manager instead of the main screen and handle its touches.

  

Once the user has navigated to global data and selected an appropriate key containing level data, tapping load on the File Manager menu bar will call the loadFile() function in Main. This function splits the key back into its component parts using the explode() helper function and then uses loadstring() to create a function which rebuilds the data table. The createGrid() function was updated so that it can be loaded using this data table.

  

And that is all there is to it. You can use this link to download the entire code including the updated classes.

  

Next up we will look at adding creeps to your levels in a number of waves.

Tutorial 17 - A Simple File Manager for Codea

17.1 The Main Class

         
Tutorial 16 explained the various ways that data can be stored using Codea. In order to facilitate the loading and storing of data for our level generator we created a simple file management class.
    
This version handles Local Data, Project Data, Project Information and Global Data. Remember that all of this data is stored in string format using a pList which is accessed by a unique string called the key.
    
The File Manager is constructed using two ListScroll objects (a class written by sanit over on the Codea Forum), a text box showing the value of the selected key and a MenuBar object (a class written by dave1707 also from the Codea Forum).
   
The Main class is used to load some test data into the four data stores and then instantiate the FileManager class. We have provided stubs for the functions called when the MenuBar items are tapped. The only menu item which has been implemented is delete file. WARNING - file deletion can NOT be undone and there is no confirmation required to delete a file so back up your data and use this class with care (or delete this functionality). Feel free to delete the test data which is loaded in setup(), this will be recreated every time you run the App.
  
The data you need to take particular care with is Global Data as this may have been stored by another Codea App. For example, if you have used Spritely (the sprite creation example program which comes with Codea) then any sprites that you have created will be stored in global data.

The delete function has not been implemented for Project Info because there is no way to determine what keys are in there (i.e. there is no listProjectInfo function).

To delete a file we just assign the value of the selected key to nil. We will provide examples of the load and save function when we incorporate FileManager into our Tower Defence Level Generator (dGenerator).
   
The line FileManager:init() will setup your FileManager class and prefetch the keys for each persistent data store.
       
The class handles both portrait and landscape orientation. The orientationChanged() function adjusts the FileManager position when the iPad is rotated. It works but not very well as ListScroll wasn't designed to handle this. You may have to drag the ListScroll box to show the contents. We haven't had a chance to modify this.
      

17.2 The FileManager Class

             
Most of the hard work is done in this class. We start off by defining variables to represent the four supported Directory Types to make the code easier to read. The init() function creates the two ListScrolls (one for the list of Directories called directoryList and one for the keys it contains called dataKeyList).
     
We then pre-load the keys for Project Data, Local Data and Global Data (we already know the Project Info keys since we loaded them). We set the current directory to Project Info and set the current key to the first one. There is a variable called valueString which we use to contain the value of the selected string. Only the first 150 characters of the saved value are displayed. The last thing we do in init() is setup the MenuBar.
     
One of the modifications we had to make to the MenuBar class was to prevent touches on the ListScroll when a sub menu is displayed (otherwise you could accidentally delete the wrong file).
       

17.3 Download the Code

          
You can download all of the code for this program using the following links:

1. FileManager Complete Code v1.1 - All of the code in one file.
2. Main.lua - The Main tab class only.
3. FileManager.lua - The FileManager v1.1 class only.
4. ListScroll.lua - The ListScroll class from sanit.
5. TextItem.lua - The TextItem class used in ListScroll from sanit.
6. MenuBar.lua - The MenuBar class v1.1 from dave1707 (modified) .

Next up we will incorporate FileManager into our Tower Defence Level Generator.

Interlude 12 - MineSweeper "Sales"

It has been ten days since MineSweeper was released into the wilds of the App Store so I thought I would provide an update on how downloads are going. In summary, downloads are better than I expected, given it is a clone and there are a bunch of established clones already in the store. Figure 1 shows downloads per day (you will probably have to click on the image to see a version big enough to read). 
  

Figure 1. MineSweeper Downloads By Day.

   
It shows the usual trend with a large hump on the day after release followed by a rapid fall over the next four days. You then enter a gentle oscillating phase which will gradually decline if you do nothing else. The small bump on the far right is the weekend kick which I see on most of my App sales. There is many a developer who saw their second day sales, multiplied this by their App price and then by 365 and thought they were on the road to retirement. Alas, my experience is that the post ten day average is a better indicator of long term sales.
   

Figure 2. MineSweeper Download Detail.

    
My guess is that sales will settle down around 50-100 per day, which if I was making any money from them would be fantastic. It does suggest that it would be worth adding iAds to try and extract some return from the effort of writing the App (apart from the educational benefit of course).
  

Figure 3. Early Ranking Data.

  
Looking at how the App ranks is very interesting and illustrates the mysterious Apple ranking algorithm at work. You can see that rank roughly follows downloads (with a slight lag). However, if we look over the ten day period we see a curious result.
  

Figure 4. Ranking Data at the end of the 10 day period.

      
Figure 4 shows that even though sales are not as high as day 2, the rank has continued to climb suggesting that there is some sort of cumulative effect. There is definitely a feedback mechanism whereby the higher you rank, the higher your downloads, which means the higher you rank, etc. The other observation is that it is easy to make progress when you are ranking between 200-300. Getting sub 100 is tougher and top 10 is virtually impossible (unless you call your App Angry Birds).
    

Figure 5. Downloads by Country.

   
Downloads by country contain a couple of surprises. I always expect to do best in America given it is the biggest English speaking market and the UK at number 3 and Australia at number 5 are equally predictable. Germany at number 2 is unexpected and Russia at number 4 is also a pleasant surprise. So thank you to all the German and Russian downloaders. France and China are normally up there and I don't tend to have a lot of luck with the Canadians. Where this sort of information is useful is in deciding what countries to localise your App for. There isn't a lot of text in MineSweeper so localisation would be a fairly simple matter. I have read that localisation can have a dramatic effect on downloads in that market but I havent tried it myself.
    

Figure 6. Reefwing Software Downloads by Product.

     
Figure 6 graphs downloads by product for all of my Apps over a one month period. You can see that the free Apps (MIneSweeper, Personality, LifeAudit, and Number Converter) dominate downloads, however the majority of my revenue comes from LifeGoals. Note that MineSweeper has only been available for 10 days of the month reported on in Figure 6. I will give another update after MineSweeper has been out for a month.
   

Figure 7. Early MineSweeper Reviews.

    
A factor in driving sales is review comments and the number of stars people rate your App at. Trying to bootstrap these by getting your Mum to write a review is always a strategy but in reality unless you have a LOT of friends in MANY countries, real reviews and ratings will swamp any attempt to game the system. BTW - thanks to all the folks from the Codea forum for their positive reviews!
  

Figure 8. Reefwing Software iAds Revenue.

     
The next step in this grand experiment will be to attempt to convert the MineSweeper downloads into cash. Theoretically, iAds should be a fairly good mechanism for this. However, looking at Figure 8 you will see that my current revenue from iAds in the Personality App can only be called pathetic. 
       
Let's see what MineSweeper can do...