3. Your First Project

Pick a folder where you wish to store the project files related to this book. This could be in your user folder or on a development drive.

Create a new folder titled "3-your-first-project" and inside of it create a new empty text file (.txt) and then rename it to game.project with .project as its filename. You may need to turn on file extensions to be able to do this.

Open the Defold editor. On the first Dialog, click the "From Disk" button. Navigate to your "3-your-first-project" folder and double click the empty game.project file. This will open the blank project. This book will not be explaining every area of the Defold editor all at once, and only explain details of areas which you'll need to know about in order to follow along so look to other resources if you wish for in depth details about each area of the editor.

From Assets panel, double click the game.project file. This will open this file in its native editor.

You can also edit this file directly with a text editor (right click in Assets and click Open As ... text - most files can be inspected in plain text this way, but mostly you should use their built in editors). When you open it its native editor you will see the default values a blank game.project will have no matter that it is an empty file. Edit the Title text area so that it says "3. Your First Project" and then save. You may need to click to another text input box before you save for the editor to recognize there were changes made in the text area you are editing.

You may notice too that there is a builtins option in the Assets panel. These files are default files which are bundled with every single Defold project as built in default versions of certain files for convenience. The copies of the files in the builtins folder are read only. If you wish you can copy and paste them into your main directory and then edit them. You'll then need to update your game.project file to point to the new versions.

In the Assets panel, right click on the 3-your-first-project folder and create a new collection with the name of main. In the future, this book will just say to create new files in folders and not give the exact steps over and over.

Your main collection is the first collection that is loaded when your Defold app runs. You specify this file within your game.project file. Go to game.project and click the ... next to the Main Collection under Bootstrap and select your newly created collection.

Next create a new Input Binding file with the name of input. Then in your game.project file scroll down to the input area and click the ... next to Game Binding to select this newly created file.

At this point, you can run your new Defold project. Go to Project -> Build and your nearly empty project will be ran. You may be asked to allow Defold to use firewall permissions which you should allow. The Defold editor and the Defold game engine need to be able to communicate with each other to work while you develop your games. You can run copies of the Defold game engine on different targets, and push updated game versions directly to them while you work. You can even hot reload scrips while the game is running, which can incredibly speed up development time.

When you make test builds you will notice that a new folder called build is added to your project folder. This folder includes temporary versions of project files which are processed and sent to the running copy of the Defold engine. If you use version control such as git you should add this folder as an ignored folder as it is only temporary files.

Your first project is only a black screen for now.

Save a copy of the below file into your 3-your-first-project folder:

You can save this as logo.png or any file you like. You can also use any image you want if you would rather.

Create a new Atlas file and name it logo. Open this logo.atlas file and right click Atlas under the Outline area of the editor. Click Add Images... and select the logo.png file.

Once added, you may need to scroll your mouse wheel out inside of the center viewport area of the editor to see the added logo.png texture. Atlas files are a way of optimizing texture space for maximum performance. Defold gives you options such as defining the amount of compression you want to apply to specific atlas files when bundling for Android projects (or any target) - these kinds of features are what make Defold so good for productivity.

Open your main.collection and click click on Collection under Outline. Click Add Game Object. This will create a new GO. Right click on the "go" and under Add Component... click Sprite.

Left click the new sprite to select it, and look at the Properties panel below the Outline. Click the ... next to Image and select logo.atlas to set this atlas as the Image the sprite picks its animation from. Every texture you add to an atlas counts as its own animation. You can change the selected animation while your game is running from any animation within an atlas. It's possible to define sets of textures to be a single animation so that they play a looping animation.

Your main.collection should now look something like this:

With the go selected in the Outline, you can pick from the three tools at the top right of the viewport: translate, rotate, scale. Make sure the first option, translate, is selected, and then click and drag any of the four visible controls to move the go more to the up and right. You can use the mouse wheel to zoom, and click and drag the middle mouse button to pan around the viewport.

On the Properties panel, with the go selected, you can also specify its exact position. Try to zoom/pan the viewport, and move the go to the approximate position of the image above. It doesn't have to be exact. Try building your project about with Project -> Build.

You should see the Defold logo on your first project's running game screen. Do not worry that it's not perfectly centered for now - we will fix that with a script in a moment to illustrate its use.

Create a new Script and name it logo. In Defold, scripts are kinds of Lua files which you attach as components to Game Objects. They are somewhat special, and have built in features which help you with productivity. New script files have a set of functions and comments already inside of them. These functions are automatically called during the lifecycle of whatever you associate the script to. The init function, for example, is called when what the script is associated with is initialized.

In your main.collection file, right click on the go and click Add Component File and then select the logo.script file. This will associate the logo.script file with the "go" game object so that whatever logic you have in the logo.script will be able to be applied to the go in a relative way. You can have multiple scripts, or other kinds of components associated with a single go.

Edit the game.project file so that its width and height are 800x600 and make sure to save.

In the logo.script file, edit its init function so that it reads as:

function init(self)
    local center_width = sys.get_config("display.width")/2
    local center_height = sys.get_config("display.height")/2
    local position = vmath.vector3(center_width,center_height,0)
    print(center_width)
    print(center_height)
    pprint(position)
    go.set_position(position)
end

Do not copy and paste. Always type source examples by hand so that you practice in order to learn more quickly. If your project doesn't run correctly make sure you typed everything exactly. Only copy and paste as a last resort to catch any repeated typos! And if you notice any typos in this text please contact the author.

sys.get_config() can fetch various values you have set in your game.project file. If you open your game.project file now in a text editor it should look something like this:

Take care to know that display.width and display.height only refer to whatever value you set in the game.project file as a default "virtual resolution" and not the actual device resolution of your game as it runs on a device or has its window resized.

Build the project again and you should see the logo is now centered in the now 800x600 window. Important - leave this window running for the time being while you continue below.

In the Defold editor, you can see that some information was printed to the console as well. You can use print to print basic data and pprint to print table data to the console for debugging purposes.

If you closed the Defold engine window be sure to build it again and leave it running while you continue below.

Edit the update function of your logo.script to the following (with the "local angle = 0" above the update function).

local angle = 0

function update(self, dt)
    angle = angle + 1
    go.set(".","euler.z",angle)
end

Save, and then click File -> Hot Reload. This should update the script in the currently targeted engine instance. (If it doesn't work - don't worry too much for now, just rebuild the project like normal. Target discovery is a bit wonky in Editor 2 at the moment.)

You'll now see the Defold logo is animated with a rotation over time. This is an example of both one way to animate things, and of hot code reloading. You can increase the value of the "magic number" 1 to increase rotation speed, or make it negative to rotate in the opposite direction. If you were to use go.set_rotation() instead of setting the euler.z property you would be working with quaternions instead of euler angles - which you probably don't want to work with for now!

Open the input.input_bindings file you created before. Click the + next to Mouse Triggers. Select "mouse-button-left" from the Input drop down and set the Action label to "click" then save. Make sure you click off the Action input before saving - for extra paranoia close the file and reopen to make sure it is saved correctly.

Edit the logo.script's init function so that it reflects the code below:

function init(self)
    msg.post(".", "acquire_input_focus")

    local center_width = sys.get_config("display.width")/2
    local center_height = sys.get_config("display.height")/2
    local position = vmath.vector3(center_width,center_height,0)
end

msg.post is used to send messages to various systems or components within a running Defold game. In this case, when the script has its init function ran it sends a message to itself "." telling to to begin to get information about user device input. We only defined mouse left click so far so that will be the only input that is being tracked.

The on_input function is where input information is sent as tracked device input occurs. Edit the logo.script on_input function to the code below:

function on_input(self, action_id, action)
    pprint(action_id)
    pprint(action)
end

Build your game again and then move your mouse around and click a few times. Close the game, and then inspect the Console. You'll notice that whenever you move the mouse there is action information related to the mouse position that is being tracked. When this information is reported the action_id is shown to be nil instead of being defined.

DEBUG:SCRIPT: nil
DEBUG:SCRIPT: 
{
  screen_dy = 0,
  x = 739.5,
  screen_x = 739,
  dx = 4,
  y = 597.5,
  screen_y = 598,
  screen_dx = 4,
  dy = 0,
}

Look through the console to find an example of you clicking and you should see something like this:

DEBUG:SCRIPT: hash: [click]
DEBUG:SCRIPT: 
{
  x = 536.5,
  pressed = false,
  y = 203.5,
  screen_y = 204,
  screen_dy = 0,
  screen_dx = 0,
  screen_x = 536,
  dx = 0,
  value = 1,
  repeated = false,
  released = false,
  dy = 0,
}

You can see that the "click" action is reported when you left click your mouse. Additional information is also reported within the action table.

Update the on_input function to the code below so that it only cares about input actions when they are the "click" action.

function on_input(self, action_id, action)
    if action_id == hash("click") then
        pprint(action_id)
        pprint(action)
    end
end

Move your mouse around and click while also paying attention to the console output. Resize the console panel / move the window around to allow you to see both. You can see that , for example, action.value is set to 1 when you click or hold down the left mouse button. You'll notice that the bottom left area of the screen is is 0,0 and going up increases the y value while going right increases the x value. Defold's viewport is like a math graph -- the viewport is also called a scene graph.

Update the on_input function once more to the code below:

function on_input(self, action_id, action)
    if action_id == hash("click") and action.released then
        go.cancel_animations(".", "scale")
        go.set(".", "scale",vmath.vector3(1,1,1))
        go.animate(".","scale",go.PLAYBACK_ONCE_PINGPONG,2,go.EASING_INOUTELASTIC,2)
    end
end

Build and you'll see that when you click the logo animates to 200% of its scale in an elastic style easing with the animation taking 2 seconds to complete in total. The code above also cancels any existing animations for the scale property and resets the logo's scale back to 100% if you click again before the animation completes. You can use go.animate() to animation many kinds of effects in a convenient way, and even call functions when animations complete automatically. There are several types of easing functions to choose from which can be found in the Defold API documentation. Many properties of a game object can be animated with this function not just the scale. The delay and function arguments are optional and were not used in the code above.

go.animate(url,property,playback,to,easing,duration,[delay],[function])

Take some time to explore the Defold editor further on your own, create different files and see what they look like. As you continue through this book, a majority of the features will be covered one by one as you build the example game projects.

Try creating a new particlefx file. Add this as a component to the go, and then add the following code to the logo.script init:

particlefx.play("#particlefx")

The # is a way to identify a component. Writing the name of the component like this means it is intending to be addressed relative to its parent game object. Build and you should see something like this:

Play with the particlefx file settings and see what kinds of effects you can come up with on your own. Notice that when the logo scales when there is a click the new particles which are created are scaled up too due to the parenting of the child particlefx component and its game object parent.

If you close Defold and then open it again you'll be able to quickly open your recent projects directly without navigating to their directory.

You can download a copy of this chapter's completed project (minus particlefx addition) from the following link (right click -> open in new tab to download): 3-your-first-project.zip

(Currently if you bundle this project it will error due to logo.png being in the same folder at logo.atlas - this is most likely an Editor 2 bug, can be sidestepped by moving logo.png to anther sub folder.)