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 :) 

Comments

[Montreal iOS Game Developer]

Absolutely superb! Thanks... Looking forward to updates you think are as valuable.

[c0ppo]

Link to corona autocompletion for sublime text 2 isn't working any more :(