Getting Started building your first game in Lua with Marmalade Quick Part1/2

Marmalade Quick and Lua are perfect new developers, but for experienced programmers, be prepared to experience a different kind of syntax. For example,


If your a C# developer you will be used to loops looking like this (c# example):

   1: for (int i = 0; i < 50; i++)
   3: {
   5: }
There are no brackets in Lua, and variable types.
   1: for i = 1, 50
   3: do
   5: end

In Lua everything is one type of variable, but it is how you use it that reflects what exactly it is. For more quick information on Lua, see this great blog by Nick Smith from Marmalade here. Some key things (variables, functions, listeners, etc are all still valid).  Lua does however miss objects, but you can add objects can be added.

One of the key advantages of Quick and Lua is you can make some really great things with half the code that you would usually write when using other engines. The fact that box2d as well as the other API’s are already packed into the engine make it pretty extendable for more detailed information, check out our documentation.

Getting Started
You will need to have Marmalade installed you can get it for FREE  from here.
Next, I have prepared a few assets for a quick tutorial. these can be downloaded from

Knowledge of quick and lua is preferred, but not required. I will try to be as detailed as I can. I suggest you make a start with the 101 of development a Hello World Example you can make a Quick Hello world app in 5 minutes by following the guide here.

Creating a Game with Marmalade Quick

Ok, so let’s get building a flappy bird clone!


After clicking Marmalade Quick (that big Q in the middle), you will need to hit ‘Create New Project’ on the bottom left.


You will then be presented with a screen which allows you to add some details to your project,  Press hit ‘Create Project’!





Ok so you have created your first Marmalade Quick project is up and ready .

Using the Hub, you can change your target platform and even edit certain configurations for specific platforms. Let’s deploy it to x86, which uses the Marmalade Simulator on Windows and Mac, and see how it looks in the Platform drop down choose Simulator x86


So you should have a black screen.

This is exactly what we want. The command line is showing the build process as well as a debug message that says ‘This is my app!’, and the simulator is showing nothing. Considering we just created a new project.

You can close the simulator as we know this working we now need to do a bit of preparation before we can get coding.

On the bottom left of the Hub, hit the drop down menu under ‘Action’, and press ‘Open Project Directory’.



You will now be in the Project Directory of your application.

Open the ‘Resources’ folder, and you should be presented with the Lua files and folders.

We now need to add all our assets to this folder structure. downloaded from

So take the of the ‘Assets’ folder  and paste them into the Resources Folders.

Take the files out of ‘quicklua+’:  and put it into your own ‘quicklua’ folder in your project (overwrite if asked).


This is the folder hierarchy which has just been created

· ‘fonts’ folder - allows you to specify alternative fonts

· ‘gfx’ folder - where we will keep our graphics (I have provided some for you already)

· ‘quicklua’ folder - the prebuilt Marmalade Quick APIs that we will be using

· ‘sfx’ folder - includes some sounds we will use in our game

· app.icf - modify certain behaviours at runtime

· class.lua - a prewritten Lua file which allows for object oriented development (see here for more info)

· common.icf - more configuration settings

· development.icf - automatically generated settings file

· game.lua - this is where most of the game code will take place

· main.lua - the entry point to our application

· menu.lua - our main menu!

· object.lua - Allows us to use objects (more on that later...)

-modebug.lua – Allows us to debug the lua code in ZeroBrane

What I need you to do first is edit your app.icf file, and add the following:

   1: [S3E] 
   2: MemMgrMaxAllocWarning=0 
   3: DispFixRot=FixedPortrait 
   5: [GL] 
   6: VirtualWidth=480 
   7: VirtualHeight=800 
   9: [QUICK] 
  10: mainFilename="main.lua" 

Why edit App.icf?

What the above code does is  fixing the orientation to portrait. Why? Well, Flappy Bird is primarily a portrait game, so if the user decides to rotate their phone, we don’t want the game rotating with it so we want to lock the orientation to FixedPortrait

As for our virtual widths and heights, we want our app to run on multiple devices and platforms with all kinds of screen sizes and ratios. Our solution is to build the game at dimensions of 480x800, which means that our game’s display surface will always scale to fit the full device screen with these dimensions in mind. See here for more info.

Setting ZeroBrane as the Default IDE for .lua files

Go back to the directory of your application, right click one of your Lua files, hit ‘Properties’, and next to ‘Opens with:’ press change. Then navigate to your Marmalade install folder, and go to:


Open ‘zbstudio.exe. Zero Brane Studio is an IDE for Lua code which we package into the SDK. You only need to do this once.

And now we can code! First things first, add the following to main.lua:

   1: -- Imports 
   2: dofile("menu.lua") 
   3: --


You need to set the project directory so we can see just our project select Project\Project Directory\ Set from current file


Also you need to set Marmalade Quick as the Lua Interpreter


We will need to to allow debugging of the app and testing of the app within the Marmalade Simulator

Ok next we need to add the menu into the game this will be the first thing the user sees.

The ‘--’ are simply comments, and will not be compiled by Marmalade Quick at run time.

add the following to menu.lua,

   1: -- Creates scene 
   2: menuScene = director:createScene() 
   4: -- Create background: 
   5: local background = director:createSprite(director.displayCenterX, director.displayCenterY, "gfx/background.png") 
   6: background.xAnchor = 0.5 
   7: background.yAnchor = 0.5 

All we are doing here is creating a global variable called MenuScene which holds our menu scene.

As we have not called local before the variable name, it is automatically global and will be accessible from other parts of the application.

Next, we make a new local sprite called background. Here, we place it in the middle of the display, and then load the image we want. We also change the x and y anchor of the sprite which affects the coordinates of the node’s anchor point.

Hit save all within ZeroBrane, and press the run button


The Simulator will load and display a screen with the background for the main menu.

Building the menu

We need a scene changer.

The scene changer  will allow us to change scenes in our app. Go to your menu.lua and add:

   1: -- Switch to specific scene
   3: function switchToScene(scene_name)
   5: end

So what we have done here is create a function called ‘switchToScene’ which takes in one parameter. Specifically, the name of the scene we want to move to. 

We haven’t put local before ‘function’, so it is automatically global and accessible from other lua files.

   1: -- Switch to specific scene
   3: function switchToScene(scene_name)
   5:  if (scene_name == "game") then
   7:     dofile("game.lua")
   9:     director:moveToScene(gameScene)
  11:   end
  13: end

In this code we are comparing the parameter passed into the function.

Specifically, ‘scene_name’. We are saying that if the ‘scene_name’ variable is equal to the string “game”, then we will import our game.lua file, and then move to that scene using the director.

Adding a Start Button to the menu Screen

   1: local playButton = director:createSprite(director.displayCenterX, director.displayCenterY, "gfx/start.png")
   3: playButton.xAnchor = 0.5
   5: playButton.yAnchor = 0.5

Adding a function to call a new game

   1: function newGame(event)
   3: if event.phase == "ended" then
   5: -- Switch to game scene
   7: switchToScene("game")
   9: end
  11: end

We call this function when we want a new game using the ‘switchToScene’ function. 

We are passing the user’s touch into the function, and then checking the state of the touch. In Marmalade Quick, we have 3 states for touch:

  • began - when the user first touches
  • moved - when the user moves their finger
  • ended - when the user takes their finger off the screen

In this case, we are saying, call the function when the user takes their finger off the button. Don’t forget to pass in “game” as the scene switcher parameter, so the app knows which scene to go to.

We have our function that will take the user from the menu to the game scene, but it isn’t connected to the ‘start’ sprite yet. Even at this point, it is still a sprite. We now need to use something called an event listener. Add this under your playButton code:

   1: playButton:addEventListener("touch", newGame)

What this line does is add an event listener to the playButton. This means that it is now waiting for something to happen. When that event does happen, it will react accordingly. In this instance, our event listener is waiting for a ‘touch’, and when the play button is touched, the newGame function will be called.

Making the Game Scene

Go to game.lua and add the following:

   1: gameScene = director:createScene()
   3: local label = director:createLabel(0, 0, 'Hey - welcome to the game scene.\nCome here often?')

Again this scene is global like our menu scene.

We have also created a bit of text using a label and we then display it to the user.

Adding a Game Title to your menu screen

Go to menu.lua file code. Make sure it is after the background code so that the text isn’t drawn underneath it.

The \n after Flappy Bird is an escape character by the way. It allows us to write on different lines). As you can see, we also change the colour of it. As a node, you can do all sorts of things to it. See here:

But yes, the code:

   1: local gameTitle = director:createLabel(0, director.displayCenterY+(director.displayCenterY/2), 'Flappy Bird\n A New Developer")
   3: gameTitle.color =


So now we can create a button in your game scene that once pressed, goes back to the menu scene. All you will need to do is pass in the “menu” string to our global scene switcher function in main.lua.

Ok lets now add some code to game.lua: so delete the text

local label = director:createLabel(0, 0, 'Hey - welcome to the game scene.\nCome here often?')

and add the following

   1: local background = director:createSprite(director.displayCenterX, director.displayCenterY, "gfx/background.png")
   3: background.xAnchor = 0.5
   5: background.yAnchor = 0.5
   7: background.rotation = 180
   1: local player = director:createSprite(director.displayCenterX/2,director.displayCenterY + (director.displayCenterY/2), "gfx/player.png")
   3: player.xAnchor = 0.5
   5: player.yAnchor = 0.5

What is really great about Quick is that it supports Box2d physics engine. So we can simply add physics to the player and world and we can do this by adding this line of code under our player:

   1: physics:addNode(player, {radius = 21})

If you press run, your ball should slowly fall off the screen and increase in speed while doing so.

In Part 2 we will continue with the development of  the game.

For more details on Marmalade see

Windows Developer Offer

Just Apply, Port & Publish! Spreading your game to the Windows Store and Windows Phone Store is super-easy with Marmalade and you could bag up to $1000 of incentives.

To qualify, your game will need to:

  • Have received a 3 star rating or above and/ or your game has at least 5,000 installs (if premium/paid) or 50,000 installs (if free-to-play)

If your game does not meet the above criteria, it can still qualify. Submit it for evaluation and your entry will be evaluated on the following criteria:

  • Whether your game has innovative content and is clearly differentiated from other games in the same genre
  • Developer track record in shipping quality games on mobile or other platforms
  • Overall quality of the user experience and presentation

What’s in it for you?

  • $100 PayPal gift voucher
  • A priority review for Windows Phone Store promotion
  • A developer account token for the Windows Phone Store
  • A license to Windows 8.1 Pro (worth up to $200)
  • A Windows Phone device (at Microsoft’s discretion and subject to availability)
  • A Marmalade Indie license (worth $500)

How to participate

1. Register or login

You need to be logged in to sign up for the offer

2. Sign up for the offer

Once you have submitted your application, someone from Marmalade will be in touch to let you know if you have been accepted onto the program.

3. Get tooled up

Once accepted you’ll receive:

  • a developer account token for the Windows Phone Store
  • a license to Windows 8.1 Pro (worth up to $200)
  • a Windows Phone device (at Microsoft’s discretion and subject to availability)
  • a Marmalade Indie license (worth $500)

4. Develop and Port

Develop or port an innovative, functional app using Marmalade.

  • read the porting guides, which cover everything you need to know about configurations, SDKs, general considerations, and first steps
  • complete your Windows Phone app

5 Publish your app to the Windows Phone Store and Windows Store *

To publish to the Windows Store or Windows Phone Store you will need a developer account. Email us at for a developer token code that you can use to create an account free of charge, if you have not already received one.

*Game must be published between 1st Nov 2014 and 31st March 2015 to qualify.

6 Reap your reward

Once you have published your app to Windows Phone Store and Windows Store don’t forget to let us know to receive extra rewards.

  • $100 Paypal gift voucher
  • priority review for Windows Phone Store promotion

Sign up for the offer

Skip to main content