Let's start with a quick introduction to the Corona SDK. We'll focus just on the essentials without getting stuck in the details. We're not trying to be complete or precise. Rather, we want to get you as quickly as possible to the point where you can start creating cool, useful, or engaging apps.

We'll talk about some basics like variables and functions as well as incorporate animation and interactivity so you get a sense of what's possible. Keep in mind this is just a tutorial, so you won't find a complete explanation of any one feature.

Our aim is to address multiple audiences. Experienced programmers should be able to extrapolate the information in this chapter for their own needs. Beginners can use this as a springboard for writing their own small, simple apps.

Hello World

The best (only) way to learn how to use the Corona SDK is by writing an app. To do that we write programs in a language called Lua. In keeping with tradition, let's write a some Lua code that prints “Hello World”.

The big roadblock, here, is figuring out the details of how to actually use the Corona SDK to do this. Once you've got these details mastered, everything gets a lot easier.

So let's get started! What you'll need is a text editor to write your program in. Later, you'll save that file to a folder so that the Corona Simulator can run and show you the results.

In the text editor, type the following:

print( "Hello World" )

Then save it to a file called main.lua in some folder that's easy to locate. Generally, every program should have its own folder on your system.

To run the program, you need to launch the Corona Simulator. All Corona SDK files should be in the Corona folder in your Applications folder (see Getting Started Guide for more information on how to install the Corona SDK.)

The contents of the SDK will look something like the picture at right. Double-click on the icon for Corona Terminal (the circled icon below).

This will launch a Terminal window and bring up a file dialog. In the dialog, navigate to the folder containing your main.lua file and click the Open button.

At this point, you will see “Hello World” in the Terminal window:

You will also see a blank simulator window (right) that simulates what would display on the actual phone. In this case, the phone screen remains blank because we're told the program to output to the Terminal.

Let's explain how this program worked. The app launches from the file called main.lua. The simulator loads this file and follows the instructions contained inside. Generally, an app consists of statements and variables. Statements provide instructions on what operations and computations need to be done; variables store the values of these computations.

In this program, we use a function called print. A function is just a collection of statements that perform some task. You send inputs into the function called parameters (or arguments). Some functions return results. In the case of print, all it does is output the arguments as strings to the Terminal.

Simulator vs Terminal

So why did “Hello World” only display in the Terminal window and not in the simulator? That's because print is designed to output messages to the Terminal. Its purpose is to output you to send diagnostic messages about what's happening in your program. And in general, the Terminal window gives you the ability to see warning/error messages that the simulator generates or print your own messages.

Hello World on the Simulator

To get things displaying on the simulator screen, we need to use different functions that come from Corona's graphics library. A library is a collection of functions that provides useful, but related functionality. To show “Hello World” in the simulator, you need to add the following two lines:

local textObject = display.newText( "Hello World!", 50, 50, nil, 24 )
textObject:setTextColor( 255,255,255 )

Let's explain what's happening. newText is a function of the display library that returns an object that will represent the text on the screen.

Library functions deserve some more explanation. In this example, you can think of newText as belonging to the display library. This relationship is known as a property relationship. So to access the newTextproperty of display, you have to use a dot. Hence, you write “display.newText” but not “newText” by itself.

The function setTextColor is a special method called an object method. It uses a special colon syntax that means it is related to the text object you created. Typically these methods modify the variable before the colon (i.e. textObject ). In this case, the text object has no color by default, so we need to assign the Red, Green, and Blue color channels. These numbers range from 0-255. So for white, we need 255 for each channel.

Rapid Prototyping

One of the most powerful things about the Corona SDK is the ability to make quick changes and see those changes instantly.

Let's revisit our previous example to see how this works. You can also start with the “HelloWorld” project in the Sample Code. Launch the simulator, navigate to the folder for your program, and click open as you did before.

Now, open up the main.lua file in your text editor and try changing the 3 arguments to setTextColor. For example, you might have done something like:

local textObject = display.newText( "Hello World!", 50, 50, nil, 24 )
textObject:setTextColor( 255, 0, 0 )

Now, save the file and then go back to the simulator. Under the File menu, click the Relaunch submenu item (File > Relaunch) — or use the keyboard shortcut ⌘R (command-R) in the simulator. This reloads your main.lua file without having to restart the simulator. Notice how the color of the text changes immediately. In the version above, the text would appear red.

As you develop your application, you'll find yourself doing this sort of thing very often. You'll load your app in the simulator, make some edits to your main.lua file in text editor, switch back to the simulator and relaunch your code to see the results. This makes it really easy to make edits and see the results, all while avoiding the time and trouble of quitting and restarting the simulator.

Basic Interactivity

Let's add some interactivity by creating a button that will change the color of the text randomly. Starting with your “HelloWorld” project, add the following lines at the end of main.lua to load an image:

local button = display.newImage( "button.png" )
button.x = display.contentWidth / 2
button.y = display.contentHeight - 50

This loads an image called button.png and positions it at the bottom center of the screen. It uses another display library function ( display.newImage ). This function returns an image object that we store in the variable button. We could have called the variable anything, but the name button seemed natural since we are going to turn this image into a button.

The image object that we created has built-in properties that we can modify. These include the x,y positions on the screen which refer to the position of the center of the image relative to the top-left corner of the screen.

To get a position towards the bottom of the screen, we took advantage of the display properties of the screen display.contentWidth and display.contentHeight to help us center the position of the image.

To turn the image into an actual button, we need to make it respond to events. There are various kinds of events. For this example, we will make the image respond to “tap” events (which are similar to single mouse clicks on a desktop computer). When you add the following lines at the end of main.lua, you can click on the image and the text color changes.

function button:tap( event )
        local r = math.random( 0, 255 )
        local g = math.random( 0, 255 )
        local b = math.random( 0, 255 )
 
        textObject:setTextColor( r, g, b )
end
 
button:addEventListener( "tap", button )

Let's see how this works. The code above has two parts. The first part defines an object listener for the image object button. An object listener (usually called a table listener) is an object method whose name matches the name of the event. Object listeners are just another name for object methods where a specific convention is followed: the name of the method is the same as the name of the event we are interested in, so in this case, we call the method tap. The colon is present because that's the syntax for defining object methods.

The second part is where we register this object listener to receive “tap” events. Fortunately, the image object button (like all objects created by the display library) has a built-in object method called addEventListener that allows us to make it interactive. Because it's an object method, the image object variable buttonis to the left of the colon and the object method addEventListener is to the right. The first argument is the name of the event and the second argument is the image object itself.

When the user taps on the image, the system sees that an object listener has been registered. It looks for an object method named tap inside that object and then calls that method. In our implementation of the tap object method, we generate 3 random numbers between 0 and 255 and use those to set the new text color.

The final code for this is available in the “HelloWorld2” folder.

Animation and Sound

Let's animate the text and add some sound every time the user taps the button. Start with the “HelloWorld2” project and add the following lines at the end of main.lua so that the text will move vertically down by 100 pixels:

transition.to( textObject, { time=1000, y=textObject.y+100 } )

Here, we are using the transition library which does a lot of the heavy lifting on our behalf (see Animation).

We can add some sound by adding one line to the tap object method:

function button:tap( event )
        local r = math.random( 0, 255 )
        local g = math.random( 0, 255 )
        local b = math.random( 0, 255 )
 
        textObject:setTextColor( r, g, b )
        media.playEventSound( "beep.caf" )
end
 
button:addEventListener( "tap", button )

Here we are using the media library which provides multimedia support.

You're All Set

So that’s it for the quick tour of Corona. There's plenty more to explore like using the accelerometer to create novel user interactions, getting GPS information to enable location-based functionality, storing data in a database, and much much more.

Hopefully, you've gotten a taste for how easy Corona makes it to create cool apps and games. If you want to learn more, head over to our Overview page.

Or, if you’d really like to dig into a book, check the book list for titles available for sale online or at your local bookseller.