Corona in 5 Minutes

The best way to learn Corona is by writing sample apps. To do this, you write programs in a language called Lua. If you're new to the language, please read the Introduction to Lua.

In keeping with tradition, you'll write some Lua code that prints "Hello World!" to the Corona Simulator Console window. Then you'll display that text to the screen, change its color, and create basic tap interactivity to change its color randomly. After that, you'll learn how to implement physics in Corona with just a few lines of code.

Printing "Hello World!"

With the Corona Simulator open, select New Project... from the File menu. In the Project Name input field, type HelloWorld and ensure that the Blank template option is selected. Leave the other settings at default and click Next. On the next screen, navigate to where the project should be saved — in general, each project should be contained within its own directory on your system. Click Create and then, when prompted, click Open in Editor... to open the core project file in your chosen text editor (see recommendations for OS X and Windows).

Project Structure

Glance at the project folder you just created. Inside are several image files which will be used for the app's icon on varying devices. However, the most important file is main.lua, the project's core file. You will eventually design more complex apps using additional files/modules, but every Lua project must contain a main.lua file at its core.

Back in the text editor, for the main.lua file, type the following on a new line:

print( "Hello World!" )

In Lua, the humble print() command can be used to output messages to the Corona Simulator Console. Save the file and, in the Corona Simulator, relaunch the project with ⌘-R (Command-R). Notice that nothing appears in the Corona Simulator window, but don't panic! Look at the Corona Simulator Console window and you'll see the text Hello World! displayed there:

About Parameters

The print() command accepts only one parameter. If you are new to programming, a parameter is a numerical value, text string, variable, or similar piece of information that is passed to and used by the command or function. In the above example, the parameter passed to the print() function is simply "Hello World!". This parameter is a text string and thus it is enclosed in quotes. As you can see in the Corona Simulator Console view, the quotes are not displayed in the printed result; they simply indicate that the parameter is a string value (text), not a variable or numerical value.

Displaying "Hello World!"

To display Hello World! on the Simulator screen, you need to use a different API (Application Programming Interface) included in Corona's display library. A library in Corona is a collection of functions and commands that provide useful, related functionality.

To show Hello World! in the Simulator, add the following line to your text file:

local myTextObject = display.newText( "Hello World!", 160, 240, "Arial", 60 )

If you're new to scripting or programming, this might look complicated, but in fact it's relatively simple. Let's examine each element in order:

local myTextObject

This is the basic method to declare a variable in Lua. Unlike most other languages, Lua is a dynamically typed language. This means that you don't need to explicitly define the variable as a number, string, etc. Variables can, and sometimes will, change types as you work with them. As you study further, you'll realize that this is a very convenient feature of Lua.

In this case, local defines the scope of the variable in Lua's memory system. Scoping is a very important aspect of Lua which you can read about here.

myTextObject is the variable name and can be whatever you wish. However, variable names must be unique (not previously declared elsewhere in your code) and non-reserved — you cannot name your variables the same as a command/API reserved by Lua or Corona.

display.newText( ... )

As mentioned above, Corona includes many libraries, including the display library which contains APIs related to displaying and managing screen content like text, vector objects, images, and animated sprites.

About "Dot" Notation

To access an item from a library, use this notation consistently:

[library].[API]

This tells Corona that you wish to "access" the chosen library then "use" the chosen API. You must always specify the library first, then a dot (period), then the API. This is known as a property relationship.

display.newText( ... )  --CORRECT!
newText( ... )          --INCORRECT

The newText API is self-explanatory: display a new text object to the screen! It requires five core parameters as explained below. Note that parameters are always separated by commas — do not separate them solely with spaces!

display.newText( string, x, y, font, size )

Now that you understand each parameter, inspect the newText command in your code. You are telling Corona to display the string "Hello World!" to the screen. The text will be positioned with its horizontal axis at 160 pixels from the left side of the screen and its vertical axis at 240 pixels from the top. The text will be shown in the common "Arial" font face. Finally, the text will be shown at a size of 60.

Let's check the result of your new code using the Corona Simulator. Simply "relaunch" it using ⌘-R (Command-R) and you will see your text displayed on the screen.

Setting Text Color

Now let's discuss how to modify the color of your text. Notice that the newText API does not include parameters to set the color directly. To accomplish this, you will need to use another command:

[object]:setFillColor( r, g, b )

If you use this command directly after you display the text — on the next line — it effectively occurs at the same time in your app and the new color will be reflected immediately.

Let's try the command in your app. Add this code to your text document on the line directly following the display.newText() command:

myTextObject:setFillColor( 1, 0, 0 )

Notice that you begin with myTextObject, the same variable name that you assigned above. Directly following that, you put a colon, and following that you write the command.

About "Colon" Notation

In addition to the dot notation explained above, let's examine the colon notation.

[object]:[command]

This notation is called an object method. Typically this method modifies the variable/object before the colon. In this tutorial, setFillColor(), following the colon, tells Corona that you want to change the color of myTextObject, specified before the colon.

As you can see, this API requires 3 core parameters: r (red), g (green), and b (blue). Each parameter is a color "channel" and the value must be a number between 0 and 1. The higher the value, the more of that color will be "mixed" into the final result. If you set all three values to 1, the result will be solid white; if you set all three values to 0, the result will be solid black. In the above line of code, only the red value is mixed into the result. Relaunch the Simulator with ⌘-R (Command-R) and notice that the text color has changed to pure, bright red.

Basic Interactivity

Now let's add some basic interactivity that will change the color of the text randomly. Add the following lines to the end of your project:

function screenTap()
    local r = math.random( 0, 100 )
    local g = math.random( 0, 100 )
    local b = math.random( 0, 100 )
    myTextObject:setFillColor( r/100, g/100, b/100 )
end

This code creates a new function, a core element of programming. A function is a block of code — a routine or set of commands — that is "called" (executed) by another command or process.

This specific function is named screenTap, the name you'll use to reference it. Since this is a custom function you've written, you can name it whatever seems logical; note that many programmers adhere to a short descriptive "sentence" with the first word lowercase and successive words capitalized for legibility.

Inside the function, you write four lines. The first three lines create variables for the red, green, and blue values that you'll use to set the text color. These three values are randomly determined by the math.random() command, part of Corona's math library. In this example, you tell Corona to choose a random number between 0 and 100.

The fourth line simply uses those random values, divided by 100, to set the text color, using the same method you practiced with already.

Event Listener

Next, you need to add a Corona event listener to create interactivity. Add this line to your project on the line after the function's end line:

display.currentStage:addEventListener( "tap", screenTap )

Event listeners can take various forms which you'll learn as you progress further. This one adds a "tap" listener to display.currentStage. For more information on the stage, please read the Group Programming Guide.

Note that the object method is used to create an event listener. The object is the Corona stage, accessed by the command display.currentStage. The method is the addition of an event listener with two parameters:

  • "tap" — this tells Corona that you wish to "listen" for a quick screen tap, meaning a quick touch and release on a specific point.
  • screenTap — this is the reference to the function you just wrote; it will be executed when the tap occurs.

That's it! Relaunch the Simulator and now "tap" (click) on the screen. The text should change to a random color on each click. This is an extremely basic example of what you can do using a tap listener, but it exhibits how easy it is to add basic interactivity to a Corona object.

Rapid Physics

In line with Corona's rapid prototyping, you can implement physics with just a few lines of code. Corona includes the popular Box2D physics engine which features multiple body types, collision detection, joints, raycasting, and more.

To follow along with this project in the Simulator, please locate the source code and assets in your local Corona application folder:

/SampleCode/Physics/HelloPhysics

Physics Library

When using physics, the first task is to require() the physics library. Don't worry about what this does internally — just realize that it opens up access to the physics APIs and functions. In addition, the physics engine is started via physics.start(), which must always be done before calling any other physics functions.

local physics = require( "physics" )
physics.start()

Visual Objects

Next, some visual content is added to the screen, starting with the sky background and a grassy piece of ground. More details about images are described in the Display Objects guide, but at this time, observe the simple use of display.newImage():

local sky = display.newImage( "bkg_clouds.png" )
sky.x = 160; sky.y = 195

local ground = display.newImage( "ground.png" )
ground.x = 160; ground.y = 445

This basic code displays two images on the screen: "bkg_clouds.png" for the sky background and "ground.png" for the ground image. After the images are placed, the position(s) are adjusted to specific x/y coordinates on the screen: 160,195 for the sky and 160,445 for the grass.

Physics Bodies

Now the fun part: creating a physics body! When a standard display object is made into a physics body, it immediately becomes a functioning element of the physics engine and it will adhere to basic Box2D physics behavior.

physics.addBody( ground, "static", { friction=0.5, bounce=0.3 } )

This line is simple. The first parameter, ground, is the name of the display object to convert to a physics body. The second parameter, "static", tells Corona that this object is a solid, non-moving object that will be effectively locked in place and immune to physical forces like gravity. As you might guess, this is a perfect body type for the solid ground. The third parameter is a Lua table/array {} which contains various settings and properties for the physics body. In this case, the friction is set to 0.5 (50%) and the bounce to 0.3 (30%).

If you view the Simulator, the ground object won't look any different because, by default, objects which are physical bodies do not appear any different than normal objects. Don't concern yourself with this now — just be aware that the ground is a physical body that will interact with other physical bodies in the scene.

Next, an additional object is added:

local crate = display.newImage( "crate.png" )
crate.x = 180
crate.y = -50
crate.rotation = 5

This adds a wooden crate to the scene, far above the ground and off the screen. At this point in the code, it will just float in space because it's not yet a physical body. Thus, it must be converted to a physical body in the same manner as the ground:

physics.addBody( crate, { density=3.0, friction=0.5, bounce=0.3 } )

Notice that in this case, the second parameter which defines the body type — "static" in the case of the ground object — has been omitted. This makes the crate into a dynamic physics object, the default body type in Corona. Dynamic objects will be affected by all forces such as gravity, impulses, and collisions with other physical objects.

Reload the project in the Simulator and watch how the crate falls from the sky, collides with the ground, bounces, and comes to a rest. Implementing basic physics in Corona is that easy!

To continue your exploration of the physics engine, please refer to the Physics Setup guide.

Project Customization

Once you're comfortable with the topics presented in this tutorial, please continue to the Project Configuration guide. This will walk you through the essential setup of a Corona project, including how to manage multiple screen resolutions, work with the screen display area, and more.