Subscribe to GameFromScratch on YouTube Support GameFromScratch on Patreon
24. August 2016

 

Welcome back to the ongoing Defold Game Engine tutorial series looking at all aspects of game development using the Defold game engine.  In this tutorial we are going to look at the process of playing sound and music in Defold.

 

There is an HD video version of this tutorial available here.

 

Playing sound in the Defold engine is simple, which is a double edged sword.  It’s extremely easy to add and play a sound file.  On the other hand the functionality provided is also quite simple.  Many things you may want to accomplish ( callback on sound end, fast forwarding/rewinding a playing audio file, positional audio, etc. ) simply aren’t supported.

Let’s start by adding some audio files to the project.  In my case I added a folder named audio and dragged in an ogg file and a wav file from Windows Explorer to Defold.  These are the two file formats supported.  The ogg file is an Ogg Vorbis file, a compressed streamed format similar to mp3 format but not patent encumbered.  Wav files are almost entirely uncompressed but require less processing power.  In a nutshell for longer form audio files, such as music, use an ogg.  For sound effects, use wav.  The end result should look something like:

image

 

Next we go ahead and create a sound component for our game.  You could parent your sound components to whatever game object you wish.  If it makes sense to create a music player game object and attach all the sounds to it, you could.  Or if you want your game objects (for example, the player) to own their own sound components, that’s alright too.  Select whatever game object you want to add the sound to, right click and select Add Component.

image

 

Next select Sound from the component list.

image

 

Here I am creating one for the music file first:

image

 

Hit the … button beside Sound and select the ogg file you dropped in earlier.  Notice in this case I changed the Group to music.  I repeat the same process for the wav file, instead named sfx. 

 

Now playing the sound effect using code is extremely easy and once again uses messages like so:

msg.post("#music","play_sound")

 

Simply post the play_sound message to the music component of our current game object.  Playing the sound effect file is the exact same process but instead post the message to the #sfx component like so:

msg.post("#sfx","play_sound")

 

We can also control the volume of the sound component, like so:

msg.post("#music","set_gain", { gain = volume })

 

Volume is a value from 0.0 to 1.0, where 0.0 is no volume, while 1.0 represents full volume.  Remember earlier when I changed the group for our music file from “master” to “music”.   Groups enable you to control several sound effects at once, for example muting all the playing songs or sound effects.  For example, we could mute all the sounds in the group music with the following call:

sound.set_group_gain(hash("music"), 0.0)

 

Here is the full source for this example:

-- Local variable for volume. 0 is none, 1 is full
local volume = 1.0

function init(self)
  msg.post(".","acquire_input_focus")
  -- start playing the background music
  msg.post("#music","play_sound")
end

function on_input(self, action_id, action)
  if(action_id == hash("SPACE_PRESSED") and action.pressed == true) then
    -- if user hits the spacebar play the soundfx file. 
    -- multiple presses will play multiple instances.
    msg.post("#sfx","play_sound")
  elseif(action_id == hash("ESC") and action.pressed == true) then
    -- on ESC mute the entire group "music"
    sound.set_group_gain(hash("music"), 0.0)
  elseif(action_id == hash("DOWN_ARROW") and action.pressed == true) then
    if volume >= 0 then
      volume = volume - 0.1
    end
    -- lower the volume of our music
    msg.post("#music","set_gain", { gain = volume })
  elseif(action_id == hash("UP_ARROW") and action.pressed == true) then
    if volume <= 1 then
      volume = volume + 0.1
    end
    -- increase the volume of our music
    msg.post("#music","set_gain", { gain = volume })    
  end
end

 

The Video

Programming


15. August 2016

 

Welcome back to the ongoing Defold Game Engine tutorial series, today we are going to build on the Sprites and Animation tutorial and look at three critical aspects of Defold game programming, scripting and messages.  Defold is programmed using the Lua scripting language which is beyond the scope of what we will be covering in this tutorial.  However we have already completed a Lua programming course for beginners available here.  If you are unfamiliar with Lua, it will teach you everything you need to know to get started with the language.

As with all tutorials in this series, there is an HD video version available here.

 

Setting up Input

 

If you created a default project, you will see a folder named Input, like so:

image

If for some reason you don’t have this input_binding file, you can create one by right clicking, selecting New->Input Binding File

image

The Input Binding File is a special file that maps various input devices to a text string that identifies the action to perform when that input occurs.  Double click the game.input_binding file and it will open in the editor:

image

You will notice there is a category for keys, mouse, gamepad, touch and text.  Right click the category you want to add an input control for and select the Add ___ trigger option.

image

 

This will create a new entry.  In the input value, drop it down and select the key/button/action you want to bind.  In the value name it.  In this example I’ve mapped KEY_SPACE to the event toggle_move.

image

 

The cool thing about this approach is you can map multiple input devices to the same action, like so:

image

 

Now the spacebar and left mouse button with both fire off the toggle_move action.  You will see how this works in just a split second.

 

Scripting

 

Now that we have some input firing, lets set up a script to handle it.  Building on the project we made in the last tutorial, add a script file to your game.  In my case it looks like:

image

 

We already covered the basics of creating a script in this earlier tutorial if you need to details on how to proceed creating a script.  In the previous tutorial we created an animation called walk.  Create another one called “Idle” using the same process, but add just a single frame of animation, so it looks like this:

image

 

We are now going to add the code to toggle between the two animation states.  In your freshly created .script file, add the following code:

local currentAnimation = 0

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

function on_input(self, action_id, action)
    if action_id == hash("toggle_move") and action.pressed == true then
      print("ACTION")
      if self.currentAnimation == 1 then
        msg.post("#sprite","play_animation", {id = hash("walk")})
        self.currentAnimation = 0
      else
        msg.post("#sprite","play_animation", {id = hash("idle")})
        self.currentAnimation = 1
      end
      
      return true -- input handled.
    end
end

 

There are a couple key things here… first you notice the local variable currentAnimation.  This is simply going to track which animation is playing so we can switch between them.

 

Next we have the init() callback function.  This function is called ONCE by the Defold game engine, when the game object this script is attached to is created.  This is where you would do your various initialization and setup logic.  In this case we are telling Defold that we want to have input sent to this game object.  That way when you hit the keyboard or press a mouse for example, this scripts on_input() function will be called.  This is done by sending a message, message passing is very important and we will cover it shortly.  For now know that the first parameter in the post() call is where to send the message.  “.” is shortcode for “to the object this script is attached”.  Meanwhile ‘#’ is shorthand for “to this script itself”.  Dont worry, we will cover this in more detail in a moment.  The second parameter is the message we want to send.   In this case we are sending the message “acquire_input”, which is a predefined message type in GameObject.

 

Now that we’ve told Defold we respond to input, we not implement the on_input() callback function.  First we check to see what the action id is, but this value will be encoded, so simply pass it into the hash() function.  Basically we test to see if our toggle_move action that we defined earlier has been fired.  Remember, this is wired to the left mouse button or spacebar being hit.  We also check to make sure it’s a pressed event (as opposed to a release).  Next we toggle our input, if our currentAnimation value is 0 we are currently walking so now we want to change to the idle animation, and vice versa.  Notice that we change the animation once again by using a message.  In this case we are passing the message “play_animation” to the object “#sprite”.  This refers to a fragment, part of an underlying message url… dont worry, it’ll make sense in a moment.  For now just think of #sprite as saying, send this message to the sprite component of this object. 

image

 

If you look at the documentation for any given class… such as Sprite, you will see the various messages it will respond to.

image

 

Sending and receiving messages is the core of how objects in Defold communicate.  It’s a way of having different objects able to communicate and share data or respond to actions or events, while remaining loosely coupled.

 

Now if you run this code, it will start with the player walking.  Hitting space bar or left clicking will fire off the toggle_move event, and the animation should now switch.  Let’s look a bit closer at how you can send messages between objects.

What I did is created a new folder named other, inside of which I created a game object named other and attached a script to it, named inventively enough other.script, like so:

image

 

In your main.collection, add an instance of other, like so:

image

 

Other does absolutely nothing, but is going to illustrate how two game objects can communicate with … um… each other.  Ugh.

In other.script, add the following code:

function update(self, dt)
  msg.post("main:/character", "marco", { msg = "You out there?", meaningOfLife = 42 })
end

 

The update() function is the callback called by the Defold engine every single pass through your game loop.  In this case we are simple sending a message to our character game object in the main folder.  The message is called “marco” (for marco/polo).  You will notice we also pass a table with some pretty useful data in it…  msg and meaningOfLife, the first a string the second a number.  The data you fill in this table is completely optional… in fact you dont need to pass data at all.

 

The important part to understand is the URL we are using to post the message to.  It’s a lot like the URL you use to go to a website.  The first part (in this case) is referring to the collection the target is in, the second part is the name itself.  It doesn’t work exactly like what you might expect though, as here is the structure:

image

The folder name has ZERO importance in this scenario… it’s just there as a handy way for you to organize things.  The root of the url (main:/) refers entirely to the name of the collection, then the remainder of the URL, refer to values within that collection.

So we are sending this message to the character game object inside main.collection:

image

 

If we had instead wanted to send the message directly to the sprite attached to the character, we could have sent the message to main:/character#sprite

 

Now we can modify our code inside main to listen for this message:

function on_message(self, message_id, message, sender)
  pprint(message)
    if(message_id == hash("marco")) then
      print("Polo")
  end
end

 

The on_message() function is called when the object your script is attached to receives a message.  In this case we check to see if the message was “marco”.  Again we encode it using the hash() function.  If you run this code you will see Polo written over and over in the console.  You will also see the data that was sent in the message, remember that table we encoded earlier.   Note the use of pprint().  This is a handy function that performs a pretty print of a table you pass in.  Basically it prints the table out in a nice easily read form.

 

There are a couple special message targets available as well.  @physics, @render and @system.  These actually send messages to the Defold game engine itself, the physics, rendering and system sub systems respectively.  For example, we can see that the render subsystem responds to the following messages:

image

 

So we could easily change the background color sending a message valued clear_color to @render like so:

msg.post("@render:","clear_color", { color = vmath.vector4(0,0,1,1) })

In this case our data is a Vector4 with the value (0,0,1,1).  This is an RGBA color value, basically saying no red, no green, full blue and full opacity.  AKA… blue.  This will cause our background color to be blue instead of black.

 

This messaging system may at first seem very alien, but it quickly becomes intuitive.  You do have to keep the reference handy to see what messages each object responds to.

 

Properties

 

Finally let’s look quickly at the concept of Properties before moving on.  You’ve already dealt with several built in properties.  For example, when you created a game object, it had several built in properties already defined:

image

 

You can also easily create your own properties.  This is a great way to make code reusable, or set it to so that a coder can code, but expose some data to a designer.  The process is simple, in our script file, simply add:

go.property("MyProperty",42)

To the top of the script file.

f you are wondering just where the heck go.property() came from, it’s simply a member of Game Object which you can think of as your base class.

 

You can define a property anywhere, except inside the various different Defold callbacks (such as Init()).  Now you can use this property anywhere just like any other local variable, like so:

print(self.MyProperty)

 

The cool part however is, now if you check in the Editor for that script, you will see the property is exposed and can easily be overriden:

image

 

The Video

Programming


14. July 2016

 

In the previous tutorial we looked at the basics of creating an application using the Defold engine, part of that included the built in Atlas type for displaying a sprite.  In this tutorial we are going to look further into sprites.  In case you are unaware, a sprite is simply a 2D graphic with position and is pretty fundamental to modern 2D games, even if sprites are actually faked in 3D.

 

There is an HD video version of this tutorial here.

 

In the previous tutorial we started with an Atlas created for us.  This time we are going to create one from scratch.  Don’t worry, it’s easy.  So what exactly is an Atlas?  It’s simply a collection of images in a single source.  The Defold engine itself is resposible for determining the ideal layout for the best performance.

 

Creating and Populating an Atlas

 

Creating an Atlas is simple.  In the Project Explorer, right click the folder you want to create the Atlas in and select New->Atlas File

image

 

Next name your Atlas file.  In this case I’m going with walker.  The extension is predictably enough .atlas.  Then click Finish.

image

 

Now we need some Image files to put in our Atlas.  In this case I am using a selection of images I created earlier but you can use whatever images you want.  If you are a Patreon backer, they are available in the Patreon Dropbox in the folder Art\AnimatedCharacter\Spritesheets\Raw\walk.  Whatever images you go with, simply drag and drop them to the images folder inside the main folder.  If you don’t have such a folder, simply right click and create one.

GIF

 

Now make sure Walker.Atlas is open in the editor, then go over to the Outline view, right click Atlas and select Add Animation Group. 

image

 

In the properties window, name the animation walk and set the default playback mode to Loop Forward.

image

 

Now right click the newly created Walk animation group and select Add Images.  In the popup dialog, select all our newly added images.  You can use CTRL or SHIFT to multiselect:

image

 

You will see that Defold automatically arranges all of our frames of animation together into a single atlas:

image

 

Be sure to save your Atlas before continuing.  You can preview the animation by right clicking “walk” in the Outline then choosing Play/Stop Animation.

GIF2

 

Creating a Sprite

Now that we’ve got our populated Atlas and a walk animation, how do we use it?  We create a Sprite.

To do so open up your main level .collection file.  In Outline right click Collection then choose Add Game Object:

image

 

I personally changed the ID of mine to walker.  Now right click the newly created game object and select Add Component.

image

 

In the Add Component dialog, choose Sprite.

image

 

With the sprite selected in Outline, we now need to define some properties, specifically Image and Default animation.

image

 

For Image, it will bring up a dialog box, select our recently created Atlas.  If the Atlas isnt shown, make sure everything has been saved.

image

 

Next select the Walk animation we defined earlier.

 

Now your game object Sprite will show in Collection.

image

 

In this case our sprite is centered about the atlas.  You can move the sprite using the W key.  ( E and R can be used for rotation and scaling as well ).

image

 

Each arrow represents the axis it will be moved along.  Or you can position your mouse inside the square and move freely in any direction.  Position your character then run your game (Ctrl + B) and you should see:

GIF3

 

Creating a Tile Source

You can also use a tile source instead of an Atlas.  A tile source is simply a grid of sprites already arranged into a single image.  To use a tile source instead of selecting Atlas, you select Tile source.  I wont be covering it in detail here ( I will cover tile sources later when we get to tile maps ), but if you want more details check the video where I did cover it.

 

You can also programmatically program the animation, get callbacks when animations complete, etc... but that requires knowledge of message passing... and that’s in the next tutorial!

 

The Video

Programming


5. July 2016

 

In the previous tutorial we covered installing the Defold Engine and creating your first project.  Today we are going to be looking at the overall structure of a Defold game, as it varies slightly from previous game engines.  I assume at this point you’ve followed the previous tutorial, created an empty project and have it open in the Defold editor.

 

There is an HD video of this tutorial available here.

 

The default project should look something like:

image

 

The built-ins folder is exactly that.  It contains several resources and scripts usable in your game, but we will talk about that later.  The more important thing to be aware of here is the main folder and it’s contents.

Inside this folder we find main.collection, logo.atlas and a folder containing an image.  A collection is a very important concept in Defold.  In this particular usage, you can think of a collection as a level.  If we double click main.collection for example it will open up a scene editor, like so:

image

 

A collection isn’t simply a level however...  what it is is a container for game objects or other collections.  We will look at game objects in a second.  So yes, Collections can be used to compose game levels, but they have other purposes.  The also perform the role of “prefabs” in other engines.  For example you might have a prefab for an enemy, that contained the scripts controlling it, the graphics you used to draw it, the sounds it plays, etc.  This collection can then be used to “instance” a version of your prefab one or more times.

 

A moment ago I mentioned Game Objects.  This is another cornerstone to understanding Defold.  With main.collection open in the editor, you should see in the Outliner, the following:

image

 

You can see here that our collection (main.collection) contains a single Game Object named go, which in turn contains a single component sprite.  You’ll notice with sprite selected that the Properties show our sprite comes from /main/logo.atlas and uses the animation or image named logo and renders using the built in material sprite.material. 

If you’ve worked with a component based game engine, such as Unity or Unreal, should be immediately comfortable with this concept.  Basically Game Objects are the entities or items that make up your game.  You will notice with a game object selected, it has very few properties:

image

Basically a Game Object contains positioning information (location, rotation and scale) and an Id, which we will use later.

What makes a Game Object useful is it’s a container for Components.  If you right click a Game Object in the Outliner, you can Add Component (or press I)

image

 

You can then chose a component from the following list:

image

This is how you can attach a Sprite, Collision Object, Sound effect, etc... to your Game Object.

 

So in a nutshell, a Collection is just that, a collection of things.  Generally Game Objects and other Collections.  A Game Object is an entity within your game world.  It has a position and ID and is a container for several components.  Components are the things that make up your game object, sprites, sounds, etc.  Got it?

 

So then... what about code?

 

Well every game engine has a game loop somewhere.  A game loop is a pretty simple concept, it’s a loop that runs over and over again and looks something like this primitive psuedo code:

 

while(gameRunning()){
    updateWorld()
    updatePhysics()
    getInput()
    render()
}

 

The exact contents of the game loop change from engine to engine but if you look at enough engines you will notice they are all very similar in the end.  It’s a loop that runs, checks for input, updates the game world, updates the physics engine if one exists then renders the results.  The actual game loop itself is often hidden away in a game engine and Defold is no exception.  So how then do you program your game?

Well first off you create a script.  A script is just another type of asset that can be added to your project.  To do so, right click the folder you want the asset to be created in (main), then select New->Script File.

image

 

Next you want to name your script.  In Defold scripts have the .script extension. 

image

 

This will create a new script file.  Double click it to bring it up in the editor:

function init(self)
    -- Add initialization code here
    -- Remove this function if not needed
    print("Game Created")
end

function final(self)
    -- Add finalization code here
    -- Remove this function if not needed
end

function update(self, dt)
    -- Add update code here
    -- Remove this function if not needed
end

function on_message(self, message_id, message, sender)
    -- Add message-handling code here
    -- Remove this function if not needed
end

function on_input(self, action_id, action)
    -- Add input-handling code here
    -- Remove this function if not needed
end

function on_reload(self)
    -- Add reload-handling code here
    -- Remove this function if not needed
end

 

I added a simple print() function call in the init() method.  Remember what I was saying about game loops earlier?  Well in Defold, during it’s game loop it makes various callback function calls at different points in the loop.  In this case init() is called when the script is first created, final() is called when it is done.  All the other methods are called each pass through the loop. We will look at each of these methods in detail in the future.

 

So now that we have a script, we actually have to attach it to something to get it to run.  Thankfully we already have a game object in main.collection named go.  Let’s attach the script to it.  Make sure main.collection is being edited, then in the outliner, locate go, right click it and select Add Component From File.

image

 

Select main.script then click OK:

image

 

Now that script will be attached to that game object.

 

This leaves one last question... how does the Defold engine know to create our main.collection to start all of this off in the first place?  Well that’s where game.project comes in.  This file contains several global configuration settings for your game.

image

 

In this particular case however, it’s the bootstrap that we are interested in.

image

 

You can think of main_collection as the entry point of your game.

 

That’s it for this tutorial.  Now that we have a good understanding of what the pieces that go together to make a game, next we will jump in and start getting our fingers dirty.  This tutorial is not going to be covering Lua programming.  If you are new to the Lua language, be sure to check out this tutorial series and you will learn everything you need to know to get up to speed.

 

The Video

GameDev News


1. July 2016

 

There is a new release of Gideros, a cross platform Lua powered mobile focused open source game engine.  Release 2016.6 ( I like this naming convention by the way ) bringstumblr_static_gideros-mobile-small several new features and improvements including:

New features

  • Introduce a threading system allowing to launch tasks in background
  • New Pixel sprite, a simple and fast rectangular coloured sprite 
  • New Particles sprite (alpha), which allows to draw several identical dots or bitmaps with varying colour and orientation
  • Releases now include offline docs
  • New examples
  • Lua 5.1 ‘universal’ bytecode
  • UTF8 string library

Improvements

  • Matrix object promoted to full 4x4 (3D) matrix
  • Matrix has sprite transform functions as well as direct scale/rotate/translate/multiply
  • Pixels can be retrieved from a render target through RenderTarget:getPixels()
  • Win32 target general improvements (fixed autorotation issue and UrlLoader now supported)
  • Shaders constants can now be set on a sprite by sprite basis
  • Viewport can now be used to render 3D scenes with different perspectives
  • Switched to QT 5.6 (fix multi monitor issues with gideros studio)
  • Updated luasockets to 3.0rc1 (for IPv6 access)

Fixes

  • Allow to remove a shader from a Sprite through Sprite:setShader(nil)
  • Fixed concurrency issue in UrlLoader on Android, causing random crashes
  • Fixed Render target clear/clipping
  • Android fixed orientation issue on screen suspend
  • Fixed export complete dialog appears only after export is finished
  • Logical scale now applies to Z axis too
  • HTML5 fix mouse buttons reporting
  • Fixed blur shader example to be GL ES compliant

 

Gideros is available for download here.  You can read the release announcement here.

GameDev News


AppGameKit Studio

See More Tutorials on DevGa.me!

Month List