Project Summary

I’ve been really looking forward to putting this game tutorial together. My grandchildren just love to play these simple games where you see how many balloons you can pop before too many of those balloons escape. The catch, of course, is that the balloons start to come faster and faster, the more you pop. So…I thought this would be a great introductory game to highlight use of the Defold engine within a ‘real’ game (well, close to a real game). I’ll be demonstrating the use of several key features, to include: (a) use of multiple Atlases, (b) use of several Lua Modules, such as timer, hash_utils and animationFunctions, (c) many lessons learned in using multiple collections to represent the levels of the game and (d) multiple Graphic User Interfaces (GUI) supporting main menu, level controls, information panel and exit menu. I hope you enjoy the tutorial.

Introduction: GAME OVERVIEW

Balloon Pop! is a fun game – primarily targeted at younger children. The game objective is pretty simple — try to ‘pop’ as many moving balloons as you can before three of them escape off the screen. The balloons are spawned at random times, with random locations to make it a little more challenging — leveraging parameter driven speed and inter-spawning times. Additionally, as you increase from Level 1 to Level2 – the speeds and inter-spawning times get even quicker. My goal was to introduce a relatively simple game that uses the basic components we introduced in the Enhanced Defold Game Template (prior tutorial). You’ll find the following features closely parallel the work accomplished in the Enhanced Template Tutorial:

  • Incorporates Animated Logos and Buttons – using the same animateFunctions Lua Module
  • Uses the basic Main-Menu Structure – including re-skinned GUI Nodes and gui_scripts
  • Custom Rendering and Custom Font techniques are also similar to those conducted within the template.
  • OnScreen Debug Messaging has been retained in this project — but can easily be removed for a final production version.
  • Here’s what the final Balloon Pop Game looks like:

    • RANDOMIZATION FEATURES – Balloon Game Objects invoke randomly selected sprite images and are spawned at random x-positions across the bottom of the screen; spawn times and traverse speeds are also randomly invoked.
    • CURSOR BASED COLLISIONS – A cursor Game Object (unique to each level) is used to trigger user clicks on a Balloon Game Object.
    • SCORE KEEPING – The project includes flag variables which display how many balloons have escaped, and how many have been popped.
    • USE OF LUA MODULES FOR UTILITY CODE – This project incorporates three common Lua Modules: (a) animationFunctions, supporting button, popup and GUI node animations, (b) hash_utils, part of Defold’s DefTable assets, providing manipulation of hash-like tables, and (c) timer, pulled from Britzl’s GitHubGist, which is used to get a callback when a certain amount of time has elapsed.
    • GAME LEVEL MENU – The project presents the user with a main menu, enabling the selection of a specific game level, or exiting from the game. I’ve only included two game levels, but Level 2 increases difficulty, due to increased speed and spawning frequency.
    • MULTIPLE CROSS-COLLECTION GUIs – Several GUI components are included (main_menu, level_controls, info_panel and exit_menu).
    • BALLOON POP! USES MANY ENHANCED TEMPLATE FEATURES – The game includes many of the key features highlighted in the previous tutorial (Enhanced Defold Game Template), to include: (a) a Popup Help Panel, (b) animated splashscreen logos, (c) a custom render script, and (d) custom fonts. Additionally, a canvas resizing function has been added to the index.html file created during the Defold HTML5 Build process — to enable dynamic resizing of the game world when embedded within an iFrame.

    High-Level Design Description

    For this Balloon Pop! game, I’ll be using a design structure very similar to our Enhanced Template — though, there are some differences which I’ll highlight as the tutorial proceeds. The project hierarchy is designed to conform with three distinct collections:

  • main.collection — this level is invoked immediately upon starting the game — it displays both a Studio and Game Logo as SplashScreens, then presents the game main menu. This collection also includes the components for each of the Graphic User Interfaces (GUI).
  • level1.collection — this level includes all the game components needed to play the initial level of the game
  • level2.collection — this level includes all the game commponents needed to play the second level of the game.
  • For a real game, we’d obviously want to have more then simply two levels – but, I thought this would suffice for a simple game tutorial. At the highest degree of abstraction — the overall game design is as follows:


    Please note, that I’ve tried to minimize the use of Global Variables — relying heavily on inter-collection/inter-component messaging for the exchange of parameter related information. This approach emphasizes unit integrity within each of the collections and scripts, aka, the project is designed in increase code cohesion and focuses on loose coupling between scripts/levels.

    A more detailed project hierarchy is provided in the following tables which delineate which game objects and their components belong to each of the following three collections.

    Collection Components


    I’ve structured this game such that the main.collection is initiated upon game start (setup in the bootstrap section of the Defold game.project file). The main.collection initiates a set of animated images depicting the developer and the game logos, followed by display of the main menu. Please note that there are two collection proxies included within the controller Game Object — these will enable us to load those respective game levels based on menu selection by the user. Each of the GUI’s are included within this collection, under a separate Game Object for each.


    The level1.collection contains each of the components needed to play this initial game level. At random times and positions, the factory invokes the balloon Prototype as the means for generating balloons to be popped. When a balloon is popped, the other factory creates an animated explosion effect. All these features are controlled by the level1_main.script.


    The level2.collection is essentially the same as that for level1 — except that there are slight variations within the sprites and script files to reflect increased difficulty and a separate set of background sprites.


    Game.Project Setup

    Within the Defold game.project file, several parameters are changed for this project:

  • Title: Change the title to reflect the current project. I’ve used ‘TactxStudios – Balloon Pop!
  • Version: Change to 1.0.
  • Render: This template will be using a custom rendering script which will be described later in the tutorial.
  • Display Width: 2224 Display Height: 1668 — these parameters reflect an Apple iPad Pro 10.5 which is one of my target mobile platforms (though all Apple tablets have the same aspect ratio, which simplifies our rendering issues).
  • Dynamic Orientation: Checked — this will ensure that the application is viewed properly on a mobile device if the user rotates the screen
  • Project Atlases

    This project uses multiple atlases to accommodate the full set of .png images within the game. The images used within this Balloon Pop! game can be downloaded within a single zipfile by clicking the following button – placing them within the images folder within the Project Explorer.

    Attribution: These images are all free assets provided by the following sources: (1) balloon image is from; (2) the level1 background image is from, (3) the level3 background image is from, (4) the main menu balloon background is from, (5) the restart icon is from the free icon library and (6) the exit icon is from

    The allocation of images to Atlases is displayed within the following table.

    This table shows which images are included within each of the four atlases in this Defold Game Project. Static images are imported to the respective atlases as shown. Flipbook animations are included as Animation Groups — the name of the Animation Group, followed by the component images in parentheses.

    You can create each of these Atlases and align both the static images and animation groups into them — consistent with the process described in the previous tutorial.

    Helpful Hint Many older mobile devices only allow you to use an Atlas which is limited to 2024 x 2024 pixels in size. Therefore, to provide the full set of graphic resources needed for this project and to comply with these size limitations — we’ve created four distinct Atlases for this Balloon Pop! game.

    Custom Fonts

    We’ll add a set of custom fonts to this project — as a means to match the tone & style desired for the game. Download this set of custom font files by clicking the following button and place them within a new folder (‘fonts’) within the Project Explorer.


    Using the files now added to your ‘fonts’ folder, create the *.fnt files to your project.

    Technique Reference I’ve leveraged the same Custom Fonts as we used in designing the Enhanced Defold Template. You can review how to add fonts to a Defold Project within Game Tutorial A.

    Custom Render Script

    Bjorn Ritzl of the Defold team has created a custom render script which I’ve found to be very useful — it’s located on Britzl’s github site. This custom script enables you to select either (a) centering content with a maintained aspect ratio, (b) centered content and fitting the content to the screen with a maintained aspect ratio, or (c) stretching the content to fill the entire screen. For this template — I’ve selected the option to stretch the content to fit the screen — but you now have the flexibility (depending upon the type of game being developed) to switch between these options.

    This custom rendering script can be downloaded by clicking the following button. Place the two files within a new folder (‘render’) within your Project Explorer.


    At this point, you can now add this render script to the project.

    Technique Reference I’ve leveraged the same custom Render Script as we used in designing the Enhanced Defold Template. You can review how to add that to a Defold Project within Game Tutorial A.


    The last step in the initial project setup is configuring the input bindings — we’ll keep it simple, only a ‘touch’ input associated with ‘mouse-button-1’, aka, the left mouse button (or touch on a mobile device).

    II: collection level/proxies

    As highlighted within the High Level Design Description — the structure of this Balloon Pop! game is organized around three collections (main, level1 and level2). This enables us to easily switch between the two active game levels, as well as switching between an active level and the front-end GUI. Defold uses message passing as the mechanism for controlling the switching between collections.

    In this game, a collection proxy is established for the level1 and a second proxy is defined for the level2 collection — the load/unload procedures are controlled using statements, for example:, “load”) or, “unload”). The status of these collection processes are also based on messages, to include: message_id == hash(“proxy_loaded”) or message_id == hash(“proxy_unloaded”). These message interactions are explained as detailed comments within the source code.

    The following subsections identify the Game Objects and Component Elements within each of these three collections:

    main.collection outline

    Within Balloon Pop! — the main.collection is structured around five Defold Game Objects:

  • background — which is the container for the background sprite image
  • controller — which contains both the level1/level2 proxies and the main_menu Graphic User Interface (GUI)
  • exit_controller — containing the exit_menu GUI
  • info_controller — containing the info_panel GUI
  • levelController — containing the level_controls GUI
  • The following image depicts the full outline of the main.collection, to include each of the component elements.

    Technique Reference Please note — for this project, I’ve leveraged the same Button Template as we used in designing the Enhanced Defold Template. You can review that button template within Game Tutorial A.

    level1.collection outline

    The level1.collection is structured around five Defold Game Objects:

  • board — containing the background sprite
  • createBalloon — which includes the factory for producing balloon Game Objects
  • createExplosion — which includes the factory for producing explosion Game Objects
  • cursor — which contains the collision object and the script file for the cursor Game Object
  • game_level1 — which holds the script for this game level
  • The following image depicts the full outline of the level1.collection, to include each of the component elements.


    level2.collection outline

    The level2.collection is very similar to the level1.collection structure, focused on the same five Defold Game Objects, however, it includes a different board sprite, and different balloon characteristics than level1. The following image depicts the full outline of the level2.collection, to include each of the component elements.


    Helpful Hints - Defold Collections

    Helpful Hint I (re)learned the hard way that within Defold, each top level collection is a separate physical world. As highlighted within the Defold Manual: “All physics interactions between game objects, (collisions, triggers, etc) only happen between objects belonging to the same collection. The Defold Game Engine does not recognize any physics interactions between objects which belong to different top level collections.” For this game, it was important to have an active cursor Game Object within each level — in order to enable the user to use the cursor to point to and click on a balloon as the means for ‘popping’ it.
    Helpful Hint As described within the Defold Manual — the physics engine within Defold allows you to identify a set of Game Objects as members of a collision group. Defold allows you to have up to 16 separate collision groups within an application. Within each collision object you can create two properties which control how the object collides with other objects: (a) Group – the name of the collision group the object should belong to; and (b) Mask – the other groups which this object can collide with. This group/mask process is incorporated within the Balloon Pop! program structure.

    III: gui structure

    Within Defold, Graphical User Interfaces (GUI) consist of several standard components: (1) Nodes, (2) Textures, (3) Fonts, (4) Layers, (5) Layouts, and (6) Spine Scenes. For the example within this tutorial, we’ll be using a total of four GUI sets to represent the menu buttons, information panels, popup notices and flag variable status. Those four GUI sets are:

  • main_menu
  • level_controls
  • info_panel
  • exit_menu
  • The following illustrations highlight the various GUI nodes which are included within each of these sets:


    The main_menu.gui controls the introductory logo splashscreens for both the designer and the game logos. It also animates the button elements within the game’s main menu – enabling a user to select Level1, Level2 or Exit the Game. The GUI node ID’s are indicated on the adjacent screenshot.

    The level_controls.gui provides the interface which a user sees within each of the game levels — including the means for accessing a helpscreen, a return back to the main menu and the current status of both number of balloons popped and flags for the number of balloons that have escaped. The GUI node ID’s are indicated on the adjacent screenshot.


    The info_panel.gui controls the helpscreen user interface — containing the specific informational text and a button for returning back to the current game level. The GUI node ID’s are indicated on the adjacent screenshot.

    Finally, the exit_menu.gui controls the user entries once they’ve selected ‘Exit the Game’ from the main menu — the buttons here enable a user to change their mind and return to the game, or alternative, it confirms that they want to exit the game. The GUI node ID’s are indicated on the adjacent screenshot.


    IV: utility lua modules

    For this Balloon Pop! project, I’ve included three Lua Modules – facilitating reuse of these functions across other projects. The three Lua Modules are:

  • timer
  • hash_utils
  • animationFunctions
  • The timer and hash_utils modules are derived from the Defold community assets available at the following Defold Website. The animationFunctions module was developed as a component of the Enhanced Defold Template, introduced in the previous tutorial.

    The source code for each of these is provided below. Please note that I’ve set a 500 pixel limit on the display window for each of these, so you’ll need to scroll them to see the full extent of lua code.

    Source Code for animationFunctions.lua

    Source Code for hash_utils.lua

    Source Code for timer.lua

    V: script walkthroughs

    The following script files are components of the BalloonPop! game — and control the actions related to level1 gameplay, to include:

  • level1_main.script
  • cursor.script
  • balloonScript.script
  • balloonExplosion.script
  • The specific game functions provided and the manner in which they are implemented are described within comments throughout the source code.

    Please note that I’ve only included the level1 game scripts in this section. There is a parallel set of scripts for level2 within the project file. If levels are very similar in terms of functionality, the developer could combine them into another set of lua modules similar to the manner in which animationFunctions.lua has been treated. I have not done that here to highlight how the game developer can structure differing game levels.

    Source Code for level1_main.script

    Source Code for cursor.script

    Source Code for balloonScript.script

    Source Code for balloonExplosion.script

    VI: GUI Script Walkthroughs

    Each of the Graphic User Interface components has a script associated with it – to include:

  • main_menu.gui_script
  • level_controls.gui_script
  • info_panel.gui_script
  • exit_menu.gui_script
  • The Lua Source Code for each is provided below — with the features and implementation techniques highlighted within the embedded comments.

    Source Code for main_menu.gui_script

    Source Code for level_controls.gui_script

    Source Code for info_panel.gui_script

    Source Code for exit_menu.gui_script


    I hope the overall sequence of build events has been helpful. I’ve tried to condense the length of these tutorials — but still describe the key build steps and the manner in which overall logic is incorporated into this project. At this point our Balloon Pop! Game is complete — and I have included the full project within a zipfile which can be downloaded by pressing the following button

    All the best - Dave


    Send me a note. Your feedback is important!