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 API scene management library.

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

Note

At this time, Composer is only available for Mac 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 Corona SDK daily build and, if you're not familiar with the process, follow the Installing Corona SDK guide.

  3. Open the Corona Simulator

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 the main.lua file in your preferred text/code editor.

  2. Copy and paste the following code on the line after local composer = require "composer". This code enables and starts the physics engine which is required for the sample app game mechanics.

lua local physics = require "physics" physics.start()
  1. Save and close this main.lua file.

  2. Now 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.

  3. 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 (Command-O). 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 all ready added to the canvas.

  4. Click on the 'Asset Library' and drag the road image to the canvas. Locate this asset in Asset Library, drag it onto the canvas, and position it near the bottom.

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

    — 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.

  6. 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.

  7. 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 you save your scene from the editor.

  8. Notice: You won't see the structure if you have built it to the far right of the background image because this is off the screen for now. We will be adding a camera perspective library to to pan the view so don't worry too much.

Adding Interactivity

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

  1. Drag a flying saucer 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. In the upper-left corner of the Composer GUI window, with the saucer selected, locate the Name field. Click this field and replace the default name with ufo. This is an important step, since you'll eventually need to reference its name to add interactivity.

  3. Save the project (Command-S). 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 you save your scene from 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  ball, using a visible force vector
    function shootPlasma( event )

        local t = event.target
        local phase = event.phase
        local startRotation -- fwd decl

        if "began" == phase then
            display.getCurrentStage():setFocus( t )
            t.isFocus = true

            target.x = t.x
            target.y = t.y

            startRotation = function()
                target.rotation = target.rotation + 4
            end

            Runtime:addEventListener( "enterFrame", startRotation )

            local showTarget = transition.to( target, { alpha=0.4, xScale=0.4, yScale=0.4, time=200 } )
            myLine = nil

        elseif t.isFocus then

            if "moved" == phase then

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

            elseif "ended" == phase or "cancelled" == phase then

                display.getCurrentStage():setFocus( nil )
                t.isFocus = false

                local stopRotation = function()
                    Runtime:removeEventListener( "enterFrame", startRotation )
                end

                local hideTarget = transition.to( target, { alpha=0, xScale=1.0, yScale=1.0, time=200, onComplete=stopRotation } )

                if ( myLine ) then
                    myLine.parent:remove( myLine )
                end

                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 -- A bit more fluid tracking

                -- Only start the camera tracking when the penguin has moved pasted the center of the view port
                local function trackPlasma( event )
                    if plasma.x > 600 then
                        camera:setFocus(plasma) -- Set the focus to the penguin so it tracks it
                    end
                end

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

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

    local ufo = self:getObjectByTag( "ufo" )

    ufo:addEventListener( "touch", shootPlasma )

    ------------------------------------------------------------
    -- Camera code

    camera:setParallax(1,.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 plasma ball 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!