Introduction

This is a quick start guide to get you up and running with Corona. It discusses how you edit your programs in Corona and writing your first program. It ends with a list of references to help you learn more about using Corona.

You only need two things to get started with Corona:

1. A copy of Corona
2. Any text editor

Corona doesn't come with a built-in program editor so you will need to provide your own. Many people already have a favorite text editor, but if you don't, for Mac we recommend starting with TextWrangler, which is free and can be downloaded here. For Windows users we recommend starting with Notepad++, which is free and can be downloaded here.

You could also use the TextEdit utility that's included with your Mac, or Notepad which is included with Windows, but you'll find that it's easier to work with a text editor designed for programming.

To just check out the Corona Simulator you don't need to install Apple's developer kit (Xcode) or the Android SDK. Later on if you want to build and test your code on a iOS device (iPhone, iPod Touch, iPad), you will need to sign up as an Apple Developer and create and download provisioning certificates. For Android, you don't need to download the Android SDK unless you want to use the ADB tool to help with installing builds and viewing debug messages.

The trial version of Corona Simulator allows building Adhoc (for iOS) and Debug builds (Android) for testing on your own devices. The builds will contain a "Trial User" message box when the app runs on the device. You will need to purchase a Corona Subscription if you want to build for Apple's App store or Android's Marketplace. Corona Subscribers also get the benefit of subscriber-only features such as access to Daily Builds and subscribers areas on the Corona Forums.

Installing Corona

If you haven't done so already, you should also install Corona. See these installation instructions for Mac OS X and for Microsoft Windows.

Your First Corona Program

Corona ships with lots of code samples that demonstrate basic Corona features, including examples for accessing the camera, GPS, accelerometer, compass, and so on. A number of the samples show off the Physics library that can be used for creating great interactive games. You will also find more code samples (submitted by users) in Corona's Code Exchange.

The samples are divided into several categories, organized by folders. In the "GettingStarted" folder, you'll find a project called "HelloWorld".

A "Hello World" program is a traditional way to begin any new programming language. In our Corona example above, we try to make it a bit more interesting by adding some graphics. But to keep things simple, let's start with the most basic version.

Open your favorite editor and type the following lines:

myText = display.newText( "Hello, World!", 20, 40, native.systemFont, 36 )
myText:setTextColor( 255,0,0 )

Next, create a folder named "Hello World", and save the above text as a file named "main.lua".

Now start Corona. On Mac OS X, locate the Corona folder in your Applications directory. Double-click on "Corona Terminal". (Note: "Corona Simulator" only opens the simulator. "Corona Terminal" opens the simulator and terminal, which displays simulator errors/warnings and any "print" messages from your program.)

On Microsoft Windows, select Corona from the list of Programs in your Start menu or double click the Corona icon on the desktop. (The simulator and terminal are always opened together in the Windows simulator.)

When Corona opens, you'll be greeted with a welcome screen:

Corona Welcome Screen on Mac OS X

Corona Welcome Screen on Microsoft Windows

Click the second button, "Simulator".

Finally, navigate to the "Hello World" folder you just created. You should see your "main.lua" file in this folder.

On Mac, click the "Open" button. On Windows, select the "main.lua" file and click the "Open" button. You'll see your new program running in the Corona Simulator:

Believe it or not, this two-line program is a complete iPhone application. Better yet, it's also a complete iPad or Android application!

Using Corona, you could ship this app to either the iTunes App Store or the Android Marketplace. In real life, you would obviously want your app to do more than print some text, but you've now seen the basic Corona workflow.

Modifying Your First Program

Before moving on to more advanced game development examples, let's make some simple changes to your program.

As you may have guessed, the second line of this program sets the color of the text that you created in the first line:

myText:setTextColor( 255,0,0 )

The color is specified by three numbers, indicating red, green and blue, with values ranging from 0 to 255. On this scale, the color black would be ( 0,0,0 ), white would be ( 255,255,255 ), and our current code specifies pure red ( 255,0,0 ).

Go back to your file in the editor, and change the second line to read as follows:

myText:setTextColor( 150,25,180 )

Now switch back to the Corona Simulator, and choose "File > Relaunch". Your text should now be a deep purple:

Feel free to try other color values to see what happens.

To test your changes quickly, you can press Command+R on the Mac keyboard, or Ctrl+R on the Windows keyboard, to relaunch Corona instantly, rather than using the "Relaunch" menu item.

Now let's look at the first line, which has a more complicated function:

myText = display.newText( "Hello, World!", 20, 40, native.systemFont, 36 )

This line creates a new piece of text and gives it the name "myText", a name that is then used by the line below.

Within the text creation function, the first item controls what the text should say, which in this case is "Hello, World!"

The next two numbers control the horizontal and vertical position of the text on the screen.

The next item specifies the font. In this case we've used the name native.systemFont, which automatically refers to whichever font is standard on the current device. For example, the iPhone's default font is Helvetica.

The final number is the font size. Note that many Corona functions you'll learn in the future will have optional values, but in this case, all five values must be specified.

Instead of the standard font, you can specify any font you have available. Try changing the first line to the following:

myText = display.newText( "Hello, World!", 20, 40, "Zapfino", 36 )

Press Command+R/Ctrl+R in the Corona Simulator to see the new font:

Finally, add the following two lines at the bottom of your program:

myText.yScale = 3.0
myText.rotation = 45

Press Command+R/Ctrl+R in the Corona Simulator to see the changes:

As you can see, the text has now been stretched to three times its original height, and also rotated to 45 degrees.

What is a Corona Project?

At minimum, a Corona project is just a folder containing a text file named "main.lua". You'll notice that all the Corona sample code follows this pattern, although most of the samples contain other files in addition to main.lua.

This special filename "main.lua" is required to tell Corona where to start. This main file may in turn load other code files, or other program resources such as sounds or graphics. The file extension ".lua" indicates that the file is written in Lua, which is the language you'll use to create apps in Corona.

Lua is a simple yet very powerful scripting language. Even if you have little or no coding experience, you'll find that Lua is quite easy to get started with.

Look inside the "HelloWorld" folder in the "GettingStarted" directory, You'll see that there are four files in the project:

• config.lua - a configuration file for different screen sizes
• Icon.png - the project's iPhone icon
• main.lua - a slightly different version of the "Hello World" code you wrote above
• world.png - a large image of the Earth

You can open this project in the Corona Simulator to see the fancy version of "Hello World":

Also, you can preview the project on different devices using the Simulator. For example, choose "Window > View As > NexusOne" or "Window > View As > iPad" to see the following:

If you open this version of main.lua in your text editor, you'll notice a new function that puts an image on the screen using just a single line of code:

background = display.newImage( "world.png" )

In most of the Corona samples, you'll notice that the word "local" appears before variables and objects. This is a good practice in Lua to save memory and resources, but in simple programs it doesn't make any difference, and so you can omit the "local" keyword if you're just starting out.

Further Resources

• Other Corona documentation
• API Reference
• User submitted sample code in Code Exchange
• Troubleshooting Guide
• Corona Videos
• Corona Forums

Also, check out Dr. Brian Burton, a Texas educator and consultant, has created this useful tutorial for getting started with Corona.