Composer GUI Tutorial

This tutorial will guide you through the basics of the Composer GUI, the official visual editor tool which allows you to quickly and easily create scenes and levels in Corona SDK. The Composer GUI also integrates seamlessly with the Composer scene management library.

In this tutorial, we'll create a simple Angry Birds™ clone, Aliens vs. Mutant Mice, in less than 15 minutes.


At this time, Composer is only available for OS X builds of the Corona Simulator.

Setup and Installation

  1. Download the Aliens vs. Mutant Mice sample app from GitHub. Unzip and place the files in a convenient working directory.

  2. Download the most recent version of Corona SDK.

  3. Open the Corona Simulator.

Video Introduction

Project Files

Let's inspect the files that you downloaded in the Aliens vs. Mutant Mice sample app. In the Finder, navigate to the folder where you copied these files. You'll notice some core files which are common to all Corona projects, including main.lua, build.settings, config.lua, and the default app icons.

There are also some scene files. Scene files consist of a .ccscene file and a corresponding .lua file with the same name. These .ccscene files are JSON-formatted settings files which are generated by the Composer GUI scene editor. The corresponding .lua file is the scene template which connects to its .ccscene file.

Initially, there is one scene named scene1.lua. If you want to add more scenes, follow the outlined structure and name the .lua file the same as the .ccscene file. Please do not change the name of any core existing files at this time.

Image Assets

Composer will recognize image assets that you place within the project folder and/or subfolders within it. Simply copy these assets over and they should appear within the Asset Library when you restart Composer.

Editing the Code

Once you're comfortable with the basic project structure, proceed through the following steps:

  1. Open scene1.lua in the text/code editor. This file is structured around a typical Composer scene. If you're not familiar with scenes and scene templates, please refer to the Composer API guide.

  2. Close or minimize this scene1.lua file, but remember where it is since we'll be adding some additional code shortly.

Opening the Project

Now let's open the sample project. From the Corona Simulator Welcome Window, click Open, or alternatively select FileOpen. From the menu, navigate to the folder where you put the Aliens vs. Mutant Mice files, then click Open to load the project in the Corona Simulator. It should look similar to this:

Next, we'll open the project for editing within the Composer GUI scene editor. If it's not already open, select WindowCorona Composer or press Command-2 on the keyboard. The Composer GUI should start and automatically load the scene1.ccscene file. This scene should mimic what you see in the Simulator.

Basic Scene Construction

With the Composer GUI open, let's start building the game!

  1. The existing scene objects consist of a red rectangle and a text object. You can select an object by either clicking its name in the Timeline Inspector below the main scene window or by clicking on the actual object within the scene window.

  2. Delete each object by selecting it, pressing delete/backspace, and confirming the action.

  3. The demo project will have the background already added to the canvas.

  4. Create a new Group by clicking on the +GROUP button above the timeline object inspector. Click on the newly created group in the timeline object inspector.

  5. With this group still selected, locate the Name field in the upper-left corner of the Composer GUI window. Click this field and replace the default name with gameGroup. This is an important step as the group is necessary for the camera feature. Put all objects except the 'background' in the gameGroup.

  6. Click on the Asset Library, drag the "road" image onto the canvas, and position it near the bottom.

  7. To add the "road" image to our gameGroup, find the gameGroup in the timeline object inspector and click the arrow to the left. It should go from pointing right, to pointing downward. Now find your "road" image in the timeline object inspector (named Object by default). Click and drag it immediately below the gameGroup. Repeat this process for every other object.

  8. Now, add physics to the road object so that it acts as a stationary ground object.

    — In the upper-right corner, select the Object Inspector tab.
    — Expand the Physics sub-menu by clicking on it.
    — Select the road object in the scene.
    — Check the Physics Enabled checkbox.
    — Click on Body Type and choose Static from the popup dialog.
    — For more natural-looking behavior, click on Edit Physics Body and pull both upper handles down to the road's horizontal middle.

  9. Now, build a hideout for the mutant mice by using beams and other structural assets from the Asset Library. As before, simply drag them onto the scene canvas, then enable physics for each object. For these objects, keep the default dynamic body type so that they will respond to physical forces and collide with other physical objects. Optionally, adjust the Density of these objects to make some more heavy (stone) or less heavy (wood). These values can be adjusted later to fine-tune the physics behavior.

  10. Save the project (Command-S). If you've set the Corona Simulator to relaunch the project every time the code is modified, you'll notice that the Simulator view automatically refreshes when saving the scene in the editor.

  11. Note that you won't see the structure if you have built it to the far right of the background image because this is currently off the screen. However, we will soon add a camera perspective library to pan the view.

Adding Interactivity

Before finishing the hideout, let's add a way to knock it down. Enter the aliens!

  1. Drag a "flying saucer" image from the Asset Library to the canvas. Place it near the bottom-left and slightly above the road so it looks like it's floating. You don't need to enable physics for this object.

  2. With the saucer selected, go to the Name field as you did with the gameGroup and name it ufo. We'll eventually need to reference its name to add interactivity, so this is also important.

  3. Save the project. Again, if you've set the Corona Simulator to relaunch the project every time the code is modified, you'll notice that the Simulator view automatically refreshes when saveing the scene in the editor.

Enhancing the Code

Now for some action! Assuming that you correctly named the saucer (ufo), add the following code to the scene1.lua file, within the scene:show() function under phase did. If you're not familiar with the Composer API scene management library, please consult the guide for a clearer understanding of scenes, scene events, and phases.

-- Build Camera
local perspective = require( "perspective" )  -- Code Exchange library to manage camera view
local camera = perspective.createView(3)

local target = display.newImage( "640x1136/target.png" )
target:scale( 0.25, 0.25 )

-- Shoot the object using a visible force vector
function shootObject( event )

    local t =
    local phase = event.phase
    local startRotation  --forward declaration

    if ( phase == "began" ) then

        display.getCurrentStage():setFocus( t )
        t.isFocus = true

        target.x = t.x
        target.y = t.y
        startRotation = function()
            target.rotation = target.rotation + 4
        Runtime:addEventListener( "enterFrame", startRotation )
            local showTarget = target, { alpha=0.4, xScale=0.4, yScale=0.4, time=200 } )
            myLine = nil

    elseif ( t.isFocus ) then
        if ( phase == "moved" ) then
                if ( myLine ) then
                    myLine.parent:remove( myLine )  --erase previous line, if any
                myLine = display.newLine( t.x,t.y, event.x,event.y )
                myLine:setStrokeColor( 1, 1, 1, 50/255 )
                myLine.strokeWidth = 15

        elseif ( phase == "ended" or phase == "cancelled" ) then
            display.getCurrentStage():setFocus( nil )
            t.isFocus = false
            local stopRotation = function()
                Runtime:removeEventListener( "enterFrame", startRotation )
            local hideTarget = target, { alpha=0, xScale=1.0, yScale=1.0, time=200, onComplete=stopRotation } )
            if ( myLine ) then
                myLine.parent:remove( myLine )
            local plasma = display.newImage( "640x1136/AlienHead.png" )
            plasma.width = 80
            plasma.height = 80
            plasma.x = t.x
            plasma.y = t.y
            physics.addBody( plasma, { density=3, friction=1.0, bounce=.2, radius=40 } )
            plasma:applyForce( 70*(t.x - event.x), 70*(t.y - event.y), t.x, t.y ) 
            camera:add( plasma, 1 )
            camera.damping = 10  --more fluid tracking

            local function trackPlasma( event )
                if ( plasma.x > 600 ) then
                    camera:setFocus( plasma )

            Runtime:addEventListener( 'enterFrame', trackPlasma )
    return true  --stop further propagation of touch event

local background = self:getObjectByName( "background" )
local gameGroup = self:getObjectByName( "gameGroup" )

local ufo = self:getObjectByName( "ufo" )

ufo:addEventListener( "touch", shootObject )
-- Camera code

camera:setParallax( 1, 0.6 )
camera:add( background, 2 ) 
camera:add( gameGroup, 1 )
camera:setBounds( 0, 1480, 320, 320 ) --used to keep our view from going outside the background
-- print( camera:layerCount() )

Save the scene1.lua file and relaunch the Corona Simulator. The additional code has added interactivity to the project — now, when you pull back on the ufo, the alien head will launch across the screen!

Further Enhancements

As you can imagine, this project could be enhanced in numerous ways. You could add more saucers, more levels, animation, sound, and much more. With the Composer GUI for visual layout and configuration, paired with the thousands of APIs built into Corona SDK, the sky is the limit!