Getting Started with Corona SDK Development

1. Introduction

Corona SDK is a powerful platform for cross-platform mobile game development.  As of this writing it currently supports iOS & Android.

I’ve been playing Corona for a while and really digging it.  In sprite of the fairly decent official documentations,  beginners can still get confused with topics such as setup, which editor to use, etc.  The goal of this article is to minimize the initial hurdles you may run into and let you be productive with the tool as soon possible.

2. Environment Setup

2.1 Corona SDK Installation

The installation of Corona SDK is really simple, you can download it from its website. You will have to register in order to either download or use the SDK later.

2.2 Text Editors

A great text editor will no doubt make your life a lot easier. I’ve tried several editors but my recommended editors are TextMate and Sublime Text 2.

2.2.1 TextMate

After a brief period of hiatus, TextMate released their 2.0 Alpha version last December. TextMate remains one of the best editors for Mac OSX and it supports Lua very well.

To maximize your productivity, download a Corona SDK bundle to give you some hints or snippets:

1. Download from GitHub.

2. Unzip the archive.

3. Rename it to whateveryoulike.tmbundle. In my case I went with "CoronaSDK.tmbundle".

4. Copy it to ~/Library/ApplicationSupport/TextMate/Bundles

5. LaunchTextMate and you are good to go.

From now on, if you create a new *.lua file, TextMate will automatically recognize it and perform syntax highlighting. While editing, press ESC to activate code completion and TAB to fill a code snippet.

For instance, if you type in “dis” and press “ESC”, it will automatically complete it and show “display”. When you want to create a new function, you can simple type function and press TAB, and you will see below:

function functon_name (...)

-- Body

end

Continue pressing TAB to cycle through function_name, args, and body placeholders one by one.

Oh one thing worth mentioning - with the newly installed bundle settings, you can run your Corona simulator directly from TextMate. Simply press Command + R and it will launch automatically. Neat!

2.2.2 Sublime Text 2 (ST2)

I started using ST2 weeks ago and fell in love with it immediately. If you have never heard ST2 before, check out these posts: 9 reasons you must install Sublime Text 2 and Sublime Text 2 Tips and Tricks

It’s very similar to TextMate but it’s better. ST2 is compatible with all TextMate Bundles but in my experimentation, it's not working perfectly yet.  Thanks to @lano78, we now have a Corona SDK package in ST2 and get the code completion feature you get in TextMate and more.

You can get the Sublime Text2 CoronaSDK Autocomplete here. Just download it and follow the detailed installation guide.

After you have installed it, you can create a new .lua file and set it to use the CoronaSDK package by pressing shift + cmd + P during editing as shown below.

 After this, the code complete feature works as expected.  You can now choose from a list showing all possible alternatives. Yowza!

Next let me tell you my favorite features of ST2.

cmd + P

Command + P takes you anywhere (similar to Open Quickly in Xcode). While editing, press cmd + P and enter part of the file name you want to navigate to.  Cool eh?

Editor Layout Customization

This is extremely useful if you have a big screen. Combining this with fullscreen mode can significantly increase your productivity. By click option + cmd + 1/2/3/4 you are able to split it into multi-columns and shift + option + cmd + 1/2/3 makes it multi-rows.

Build With Corona

You can build your project from ST2 directly by pressing cmd + B.

Usually when you build and run your app using the standard Corona simulator, it will open another terminal window to output runtime/debug information.  ST2 integrates the console into the editor, which makes me (and I am sure you too) mucho happy. 

Multi-Selection

Multi-selection is similar to your typical Replace feature except that it provides a more direct and visual way of changing the same text in your file (In Xcode, the closest thing to this in Edit in Scope). To use multi-selection, put your cursor in the word you want to choose, and press control + cmd + G. You will now see cursors appearing under the same words.  Change the word under your current cursor and everything changes.  I feel like a ninja!

Sublime Text 2 may be downloaded and evaluated for free, however a license must be purchased for continued use. There is currently no enforced time limit for the evaluation.

3. Code Libraries

Now that we have got the editor portion taken care of.  Let's head over to the next thing that makes your life easy - code libraries.  Code libraries wrap around all the commonly-performed tasks in your game development into a reusable chunk, allowing us to focus on things that are specific to the particular game you are working on. They are made possible by people generously contributing their code into the community.  I strongly advice you do the same so we can all learn and benefit frome each other's journey.

Below are some of the common code libraries I use during development.

3.1 Director Class

One of the things that frequently takes place in a game is scene or level switching. Even though Corona provides a lot of useful API, it doesn't have an official function to manage scenes. Director Class handles this perfectly. It’s easy to use and contains a lot of fancy transition effects for your scene switching needs.

You can download it here and there is a great tutorial for using this.

The sample code and in-class guides should provide all the info you need to get started. I just add one thing rarely mentioned:

Between the code

local localGroup = display.newGroup()

--Your code here

return localGroup

is our functions and objects. You will have to insert all display objects into localGroup in order to use Director Class. These objects will be cleaned automatically after switching to a new scene.

But wait, what about all these events, tables, and sounds used in your scene? They are not inserted into localGroups. Do we hear "memory leaks"?

A quick peruse of Director Class’s source code should provide the hint. Before you return localGroup, simply add a clean function like this:

local localGroup = display.newGroup()

-- Your fancy game logic

-- Clean function

clean = function ()

--Clean all your tiemrs, unfinished transitions, and useless tables

end

return localGroup

Make sure not to mark local since it will be called externally by Director Class. Now no matter how often you switch your screen, you memory bucket is safe and sound.

3.2 Ice

Ice allows you to save and load data easily. You no longer have to deal with local files when you just want to store some game scores.  It uses SQLite and JSON decoder to store and retrieve data which is very fast. It can be download here and it has a sample app demonstrating its use.  I use Ice frequently for loading and storing settings and game data in our games.

3.3 Pausable timers and transitions with speed adjustments

This library is useful if you want to pause your transition, something not possible with the current Corona API. You can download the code here.

The usage is almost the same with the official one.

Before:

local test = transition.to(obj, params)

transition.cancel(test)

Now:

local tnt = require(“awesome_timers_and_transitions_manager.lua”)

local test = tnt:newTransition(obj, params)

test:pause()

test:resume()

test:cancel()

Besides the pausable feature, it will also collect all the timers and transitions you created using newTransition/newTimers. Combining this with the director class clean function, you can clear out all your transitions in a single line when you switch scene.

tnt:cleanTimersAndTransitions()

Life is good. :)

3.4 SpriteGrabber

SpriteGrabber is a helper module that automatically reads a SpriteSheet’s images by name. It will help you write significantly less code compared to directly calling the SDK functions.

It can be download here.

Let’s say you have a sprite_hero.lua and sprite_hero.png which has 50 frames and the animation time is 200ms.

This is what you have to to without SpriteGrabber:

local newSprite = require(“sprite_hero”)

local spriteData = newSprite.getSpriteSheetData()

local spriteSheet = sprite.newSpriteSheetFromData(“sprite_hero.png”, spriteData)

local spriteSet1 = sprite.newSpriteSet(spriteSheet, 1, 50)

sprite.add(spriteSet1, “fly”, 1, 25, 200, 1)

sprite.add(spriteSet1, “jump”, 26, 50, 200, 1)

local heroInstance = sprite.newSprite(spriteSet1)

hero:prepare(“heroAnimation”)

hero:play()

With SpriteGrabber:

local grabber = require(“SpriteGrabber.lua”)

local heroes = grabber.grabSheet(“myHeroes”)

local heroInstance = heroes:grabSprite(“superman”, true, {

fly = {1, 25, 200, 1},

jump = {26, 50, 200, 1},

}

heroInstance:playClip(“fly”)

The only drawback is you have to name the sprite.lua file and its images using the same name and put them both on the root folder. Some developers (myself included) prefers to put images in a subfolder. You can get around this by editing the library code yourself.

3.5 Enhanced UI Library (ui.lua)

This library allows you to create button and label in a significantly clear and easy way. The latest version can be found here.

If your button or label animation is relatively simple, say if it has only two states (normal and pressed) - then this module is designed for you.

Let’s see how ui.lua helps us.

Create a button.

local ui = require(“ui.lua”) !

local testBtn

local testBtnTouch = function (event) !!

-- Define your touch event here

end

testBtn = ui.newButtn {

defaultSrc = "testBtn.png", -- Path for pics

defaultX = 100, -- Width

defaultY = 100, -- Height

overSrc = "testBtn-Over.png", -- Pic when touched

overX = 100, -- New Width

onEvent  = testBtnTouch, -- Touch Event

id = "testBtn", -- id

text = "TEST", -- text

font = "Helvectia" -- Font, optional

textColor = {255, 255, 255, 255} -- Color, optional

size = 16, -- Size, optional

emboss = false, -- emboss, optioanl, default false

}

testBtn:setReferencePotint(display.BottomCenterReferencePoint)

testBtn.x = 240; testBtn.y = 160

Saved a lot of works!

4. End

What you just read is what I consider a list of MUST HAVE when you develop games using Corona SDK. Obviously, there are many more great code libraries out there that are not included here, such as fps which can monitor your memory usage by creating a viewable label in your app and Multiplayer Networking and Push Notifications API.  I will constantly update this article to include what I think is the most essential tools in game development using Corona SDK.

A good editor and some handy code modules do help us a lot, but just like everything else, to master Corona SDK, remember to practice often.

This is our first but definitely not the last post on Corona SDK.  Leave us your thoughts and comments.

And..that’s it. Don’t work too hard, life is beautiful :) 

Beta Testing iOS Apps Made Easy

The success of iOS platform has spurred the creations of third party solutions that make certain aspects of iOS development less painful such as in-app purchase, push notifications and backend integration provided by companies like Urban Airship and Parse.  TestFlight is another such service and a damn awesome one. It was created to help facilitate your beta testing and lets you distribute your beta build over the air - made possible by the wireless app distribution model added in iOS4.

Let's take a quick look at what TestFlight is all about and what they offer.  For a complete overview of the latest and greatest of the service, you should of course sign up and visit the site directly. If you are already using TestFlight for your beta testing, you can also skip this and go straight to the next section.

1) Sign in after registration

2) Check the email on any of your test devices and login:

3) Tap Register Device to send your UDID over to TestFlight.

4) TestFlight sends back the provisioning profile over the air. What are you waiting for, tap Install!

5) Your device is now registered with your TestFlight's database.

 

6) Now that you have registered some devices for testing, let's submit a build to TestFlight.

7) We created the adhoc build in Xcode, saved the ipa file in Organizer, went to the folder where the ipa file is stored and dropped it here. Notice that it's quite a bit of work -- we will discuss how to automate this step without relying on Xcode later in this article, giving you a more pleasant test flight. :)

8) When your ipa file is done uploading, this is what you will see, and it's where most of the power of TestFlight lies. In particular, pay attention to the left pane: History shows you the upload history of each build of the app, along with feedback sent by testers (from within the app), crash reports, test session info (such as what your testers have tested and how long), etc.
(Names and photos have been blurred to protect the innocence)

9) Crashes has got to be the #1 concern when it comees to testing. Be sure to upload your dSYM file so TestFlight can make sense of the crash reports coming from your build.

10) This is an example crash report received from a test run of an app we worked on. Sexy, no?

At this point, assuming we have convinced you enough to start trying out TestFlight, here comes one last goodies. (Names and photos have been blurred to protect the innocence)  

Step (7) and (9) requires that you mess around with doing the build and uploading your ipa file and dSYM file to TestFlight. Wouldn't it be nice if this can somehow be taken care of as well? Well, you have chosen the right profession. All you need is create a shell script to automate this task and to save you time, we have created a script to do precisely that. If you are a gluten for punishment, you can skip the following and continue to use the good old Xcode way.

Quick HOWTO:
1) Save the script above to build.sh
2) chmod +x build-ipa.sh
3) ./build-ipa.sh

Let's take a look at the script to automate the building and submission of our app to TestFlight:

#!/bin/sh
ProjectPath="~/Projects/Test/"
Target="TestApp"
AdHocPath="build/AdHoc-iphoneos/"
AdHocConfigurationName="AdHoc"
DeveloperName="developer name"
ProvisionFile="8490865F-4F60-41BA-98EA-EA2E7B470CF2.mobileprovision"
ipaName="TestApp"
api_token="your test flight api key"
team_token="your test flight team token"
notes="Beta build #1"

// Step (1)
xcodebuild -target "$Target" -configuration ${AdHocConfigurationName}

// Step (2)
xcrun -sdk iphoneos PackageApplication -v "${AdHocPath}${Target}.app" -o ${ProjectPath}${ipaName}.ipa --sign "${DeveloperName}" --embed ${ProvisionFile}

// Step (3)
pushd .
cd ${AdHocPath}
zip -r ${ipaName}.app.dSYM.zip ${Target}.app.dSYM/

// Step (4)
popd
curl -v http://testflightapp.com/api/builds.json \
  -F file=@${ipaName}.ipa \
  -F api_token="${api_token}" \
  -F team_token="${team_token}" \
  -F notes="${notes}"\
  -F notify=True \
  -F replace=False \
  -F dsym=@${AdHocPath}${ipaName}.app.dSYM.zip 

// Step (5)
rm ${AdHocPath}${ipaName}.app.dSYM.zip

Explanations:

Step (1) Here we use the xcodebuild command to build the project of our choice. Configure the target name and the configuration profile in the shell variables above it. In our case we are doing an adhoc build for our TestApp.
Step (2) We then use xcrun to create the ipa file. The command also takes care of embedding the provisioning profile into the ipa.
PackageApplication is a perl file locate at /Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/PackageApplication
The rest should be self-explanatory.

NOTE: In case you wonder, ipa stands for iPhone Application. It's technically a folder and in Unix a folder is essentially a file.

Step (3) After the ipa file is generated, the script proceeds to zip up the dSYM folder. This way when TestFlight receives a crash report from your beta builds, it will be able to make sense of things in the event that you have configured the build setting for the build process to strip the debug symbols out of the build (e.g. to reduce file size).

NOTE: We use the Unix command "pushd ." to save where we are at before traversing into the build folder so we can return later with "popd".

Step (4) We are now at ready to send the build off to TestFlight. Retract back to the project folder and use curl command to do the delivery. The parameters should be self explanatory so we won't get into them.

Step (5) Finally we remove the dSYM zip file to keep things clean. You may choose to skip this step if you wish to keep it around for later use.

With the build uploaded to TestFlight, you can now notify your beta users to start testing it away! Perhaps the next logical step for TestFlight is to automate the finding of beta testers for developers (sorry, we couldn't automate this part with shell script).

"Thanks for flying with TestFlight and we hope you will fly with us again."

Disclaimer: This article is the result of our subject evaluation with TestFlight. We are in no way affiliated with TestFlight and have received no bonus miles in promoting their service.