Thursday, February 27, 2014

Little Game Programming Love (LGPL)

Hello Again,

First off, I was really reluctant while writing this, since I know lots of people take this kind of thing personally. I am an Open Source user, I have contributed to several Open Source projects and I preach open source to whoever I talk to. I also use Open Source operational systems.

Today I come to talk a little about something less technical than usual, but that some of you will certainly find relevant: the LGPL license.

A couple of days after I posted my bookmarks here on the blog, someone asked me if all those engines were free for commercial use; I promptly (and wrongly) replied Yes, without really checking it. In addition, yesterday, I saw someone in a forum saying that the LGPL license seemed to be an irrestrictive license. That is the general picture, LGPL is a confuse license, that seems free for commercial use without further considerations. A really fast google search revealed to me that lots of people use it without knowing what the restriction really is; while other people actually misexplain it on forums all over the web.

As I stated in the other post, there were some stuff there from before I even knew what GPL and LGPL meant. I just knew they were open source and that open source means free! Right? Well, yes... maybe a pinch too much. I decided to remove from my bookmarked engines the following entries: Indielib (LGPL), Mutiny (GPL)¹, Spherical (GPLv2), Fife (LGPL).

I won't go through GPL, since most know that it isn't usable for commercial projects. But how does a license like LGPL affect the developer and the end user?

Around the Internet, I have seen people describe this really differently. Some state that if you don't alter the libraries it won't matter (misleading enough?), while other misquote Ryan Gordon and say SDL2 changed to zlib because "people get nervous" about LGPL, but not due to the license itself. Doesn't seem like a good technical reason to me.

Clearly, none of them had even skimmed the LGPL license before answering.

¹ - It seems like Mutiny has been mistakenly licensed as GPL, while it was probably meant to use a license similar to Maratis-3D (engine is zlib while editor is GPL). I may put it back if that is the case, but will need verification. I sent the creator an e-mail, but am still waiting for the response.

What's LGPL?

The (GNU) Lesser General Public License is a free software license that allows commercial use. The main principle of this license is that it is free to use; and they make it clear in their terms. Still, it is really restrictive and confusing.

But what does free to use mean? Basically, it means that any developer is allowed to use it on their projects. In addition, it also means that the user is given the rights to freely debug, modify and relink your program, given that he does it inside the scope of the library.

This, initially, doesn't seem like that much of a problem. Of course, it raises a red flag on static linking, since it would legally allow anyone to reverse-engineer your software. Still, dynamic linkage seems to solve these problems. And it does, to an extent.

LGPL isn't always bad

When you see a software that uses code from the Qt Project (LGPL), it is usually a simple GUI application, that no one would really care about hacking or cracking. But why the jets does the Qt Project offer a paid commercial license then, if there's a free one? It all comes down to the needs of the software.

You have to study your case and evaluate whether or not your project has some specific needs or limitations.
  • Is your game a hobbyist project ¹?
  • Is it exclusively single player ¹? if not,
    • Does the multiplayer portion rely on a secure server (not hosted by the player) ¹? if not,
    • Would a cheating player ruin the other players' experience ²?
  • Is it free to play ¹? if not,
    • Would you try and take down crack distributions for your game ²?
  • Does your game's distribution mechanisms prevent you from honoring the "free to use" rights ²? (iOS?)
The entries marked with ¹ are indicatives that your project wouldn't suffer from the usage of LGPL licensed code. So, if this is your case, just go ahead and happily use your LGPL licensed code, just like you were using zlib/x11 licensed code.

Still, if you answered yes to one or more questions marked as ², you'd need to rethink your LGPL dependencies.

I'm on the dark side, what now?

The problems that come with the usage of LGPL licensed code all come from the fact that the user can modify the library our game is using. As the used library is certainly available, it is trivial to add custom code to it; and that's exactly what LGPL swears to guarantee, that the user is free to use it as they wish.

But games are special cases and have special needs. General software wouldn't really suffer from LGPL licensed libraries, but some games do. If your game has multiplayer (specially competitive multiplayer) you would want to be able to ban cheaters. The same goes for controlling crack distributions, in the reachable spectrum.


If your game has problems with altering its multiplayer behavior, giving the user legal rights to modify the library (and, consequently, your game) isn't the best idea. Despite of what your TOS stated, you wouldn't be able to ban a player that is hacking your game by adding some custom code to the library, even if that code isn't related to the library's functionality at all.

This brings us to the possible solutions to this problem:
  • Use a secure server where the LGPL dependent client is merely an interface for the game, and altering it wouldn't break anything.
Even if you do this, it would still be legal to distribute modified clients with integrated bots and other features. If the modified part doesn't touch your own files, but only modifies the LGPL dlls and possibly adds some extra files, there's nothing you can do.
  • Separate the server from the LGPL.
Separate the game server application from the LGPL dependent client. It is a possible solution, but usually one that most would avoid, since it makes it necessary for the player to run the server, wait for its initialization and then join its localhost. I lost account of how many people I've seen complaining about how Starbound's server works.


If your game isn't free to play, you'd probably want to take down possible cracks popping here and there around the web. This means that you would need to get in touch with the download websites (such as mediafire or mega) and ask for the files to be removed.

The problem is that you can only ask this if you own the rights; if a crack is actually done inside SDL1.2's dll, for example, you do not own these rights. In other words, it makes the distribution of cracked files perfectly legal. Of course, the distribution being legal doesn't mean your software can be used without a valid license, so it would still be illegal to use if the user doesn't own a license to your game.

Possible solutions:
  • Make your game server dependent even in single player.
And that's the reason I haven't played Diablo 3 yet.
  • DRM.

My personal stance on piracy is quite liberal. I don't monitor it by any means, and ignore it completely. That is not the best solution, it is just the easiest and more convenient. Of course, the fact that I would not try to stop it doesn't mean I would like this distribution to be legal. If someone wants to do this, they are doing something illegal and they should know that. Knowing it is legal on the other hand makes it worse.

Game Engines, Libaries and LGPL

Being unable to use LGPL for some projects limited the usability of several engines and libraries. Some have changed their licenses, like cocos2d and SDL. Others like Qt created paid commercial licenses, to break free from LGPL developer restrictions (or user freedoms, if you prefer). There are also some LGPL licensed libraries that include exceptions for static linking under iOS, as it would be an illegal use and distribution case otherwise. Not even the FSF votes for LGPL.

But in the end, you could use LGPL and ignore the license. Don't distribute the necessary attachments and license files, nor even acknowledge the use. But, in this case, there's not much to discuss. You could use whatever you want, however you want, if you don't care about their licenses. I just hope it is a personal hobbyist project!

For the open source library/engine creators, I always preach zlib, x11 and BSD 2-clause licenses. These are the ones I use in my projects, and also the ones I use to select technologies. I usually ignore LGPL licensed technologies.

Over and Out.

Friday, February 21, 2014

YAML - YAML Ain't a Markup Language

Hello Again, Today I come to talk a little about YAML. YAML is a general use data serialization language. Its most common uses are storing configurations, data persistence and online software messaging. As its name states, YAML is not a markup language, and this allows for more readable code.

Example XML code:

Equivalent YAML code:

Very Brief Introduction to YAML

This is a short, yet objective, introduction. By reading this you should be able to create and edit simple YAML files (it's not that hard btw, but takes some minutes to get the hang of the syntax). If you want a complete overview, go to and look at their specifications, you'll be amazed by how it can be flexible (or inflexible, sometimes).

YAML, a data serialization language, is designed to be easily readable by humans. It can store any type of data (even in binary form, if you so want).

YAML has three basic structures: scalars, sequences and mappings. A document is formed by several nodes (or objects, if you prefer), that can be a scalar node, that holds information, or a map or sequence node, that hold other nodes. In a comparison to graphs, they can be branch or leaf nodes.
  • Scalars: as the name hints out, are simple values, sometimes with an individual identifying name, sometimes without. Can be string, numbers...

  • Sequences: Sequences are simply a list of nodes without any special identifications. They are easily accessible by index.

  • Mappings: also referred to as hashes and dictionaries, is a structure that allows you to relate identifiers and their informations in a more direct way. These identifiers (also referred to as keys) are usually a simple string name and the information in them can be of any type; as in they can be numbers, strings or even other maps and sequences. It is comparable with an std::map or, in some cases, with std::multimap.

Of course, these can be used together to create more and more complex documents that can be used to store any kind of information. Just don't create a password vault with this, it wouldn't be a good idea.

The language itself has some neat features, such as unique key identifiers (marked by a "? ") and variables marked by the '&' and '*' characters. Having GUIDs is a great way to serialize any types of asset or object data, but I personally don't like YAML's syntax for these unique keys ( actually I hate it, but well, them's the breaks). In that example, I use a sequence (denoted by "[]") what allows me to use, for example [sound, zombie1] or [data, zombie1] later, when I want to store different types of data. This unique sequence key feature is extremely useful.

Using reference variables is also very handy, specially when you may need to change a variable on several items. In this example, if I change the folder where I hold my spritesheets, all I need to do is change that one single line, instead of editing every object that reference that variable (or use a global variable in my engine).

The YAML syntax is quite tricky to get, there are lots of gotchas, and your first 10~20 tries will have invalid syntaxes; worry not! Some syntax gotchas!:
  • No tabs allowed. The blocks in YAML are all defined by indentation, and they banned tabs. More info on this here.
  • White Spaces are meaningful when starting a line and are used to identify blocks (through identation).
  • ": " isn't necessarily ":". While "name: Dejaime" means that name is an scalar node and its value is "Dejaime", name:Dejaime means that it is actually called name:Dejaime with type null. This is so we can have colons inside values like in "time_created: 19:03".
For those who want to try yaml, there's an online syntax checker called yamllint. It validates your text and then spits out a version optimized for ruby, what'll be of no use for us. The important part is just checking the syntax validity.

This should be enough for the article, but if you want to go deeper and into the fancy stuff, dive into the official specification.


The library yaml-cpp has two major versions right now, 0.3 and 0.5, both stable enough for use. The version we will be using here is the 0.5 (0.5.1, as of this writing), since it has a new revamped API, one that makes a better use of C++ in my view. It is available under this link:; X11 (MIT) license, so no worries here.

Building yaml-cpp

The compilation is simple, but you'll proably want to use the Boost library. Under linux platforms, to compile boost, you'll only need to run ./ && ./b2 and it will be built. You may want to issue a sudo ./b2 install so boost is installed in your system (under /usr/local). You can also install boost with apt-get or Synaptic, but you'll get a slightly outdated version. Notice that building the entirety of the boost library can take long, but you can build only the ones you're interested in (I personally always build it all).

After you install boost on your system, yaml-cpp is also just as simple, create a Build folder in yaml-cpp root directory and issue cmake .. && make inside it, and it will be built. If you want, a sudo make install will install yaml-cpp in your system. If you didn't want to install boost, you may need to set the correct path in the boost variables of yaml-cpp CMakeLists file (or use ccmake, or even a cmake gui, if you prefer).

If you have problems or questions on this regard, please refer to their official building guides...

Our Example Problem

We want to load sprites and their definitions, including all possible animations, frame duration, spritesheet location, and anything necessary, from a single data file. We'll be using the following (public domain) spritesheet:
duotone SpriteSheet

Available here:

We will assume that all frames of an animation are at the same horizontal level, with no border (just like in the sheet above) and each may have independent durations. We'll also assume an animation has a name, a constant size, but can change between more than one animation (and assume their respective sizes).

All right. Now that we have our definitions and assumptions, we need to define our YAML file structure, so we can store the information necessary for the whole sprite. So let's list the basic informations we need to store:

  • Unique Name
  • Spritesheet ID
  • Animation List
  • Animation Name
    • Initial SpriteSheet Offset
    • Animation Size
    • Frame List
      • Frame Duration
Basically, that is all the information we will want in our YAML file. It is a complex map, so let's break it down into how to list it.

The first information we need is actually the identifying name of the sprite (can be an number if you prefer):Notice how I didn't use Name: Player, but simply inserted Player: directly. This means we have something called Player, and not that we have an string called Name and valued Player.

Now we add the spritesheet reference. This can be a numeric ID, the path to the spritesheet file or something else. I will be using the spritesheet file path, as we won't be using any file loader that would handle UIDs (wenewbies:D [or not {w/e}]). This takes us to our next line.

We now have the basic information for the sprite, and need to detail the animations themselves. As animations each have their own names, let us list these names, in our example:These are the four animations for the player sprite, all added in a sequence called Anim_Names, so we can look them up later.

Now that we know, in advance, the names of our sprite's animations, we can map them using their names with no problem!

These animations also have specific informations: their size and their offset in the spritesheet.

The animations also need to know how many frames they have as well as each of these frame's time duration. We'll do the same we did to list the animations names.We have an animation with six frames where all of them have 80 ms duration.

This is the last information we need to add to the animation, and to the sprite itself. What takes us to our Player sprite configuration:

And to add the remaining sprites:

Now we have a small problem. As the entire file is a map, we'll need to know what are the unique names of our sprites (in this case, Player, Monster and Gem). In addition, there's no way to access them by a numeric index. It won't be a problem when we have some sort of level definition, specifying all of its objects and their respective Sprites by name, referencing our sprite definitions file. But even then, this line won't hurt:[code]Sprites_List: [Player, Monster, Gem][/code]

So, this is our definite Sprites.yaml file:

Parsing the File

As we are getting into the code part, I must put a license on it.

To the extent possible under law, Dejaime Antônio de Oliveira Neto has waived all copyright and related or neighboring rights to YAML-CPP C++ Example Code. This work is published from: Brazil.
The complete header is available here: Now that we have our file, and we understand how it was created, we can go ahead and create our parser. First, we need to define our structure to hold that information inside our code.

Starting with the Sprite itself, this is what I'll use:It has variables to hold the name of the sprite, the filepath to the spritesheet and a vector for the animations. The Sprite::Load(string, string) function takes a name for an animation and a filepath to the .yaml file (not to be confused with the spritesheet). It can be used directly or by calling Sprite::LoadAll (string, vector[Sprite*]), that will create, load and push all sprites in the file into the passed sprite vector.

Our Sprites also depend on different Animations.That are nothing but a fancy struct.

As you can see, all the information necessary for any sprite can be stored in these, if it follows our initial assumptions. If you have special needs, you can just alter it to suit your needs. Maybe moving the spritesheet into the animation to allow the animations to be in independent textures, or even add more information on every frame such as size, to allow an animation to change in size on each frame. Another useful piece of info could be the origin of each frame, like a reference to be used when rendering. You get it, this example is indeed using a minimalist approach.

The Load function

Since we have our basic structure to hold the information, we can now retreive it from the file and store on our objects, in order to use it. The first thing we should do is open our .yaml file. To do this, we need a yaml node, so it can assume the root node of the file. If you don't know what a node is, you can go back to our YAML introduction or look at their specs.

The yaml-cpp library works under the YAML namespace, and has a variable type for an yaml node, the YAML::Node, I guess I didn't really need to say that... Anyway, we need to declare an YAML::Node and assign the root node of our file to it.

Now that we opened the file and have our root node at baseNode, we need to find the node for our sprite. The name of our sprite was passed to us as an argument, and that's what we are going to use. Here is where the library author used C++ operator overload to give us a really nice API, as you'll see:We simply use our string as the index, and it will find the correct node. If it is not found, it will be left as a null node.

So, Sprite found, we can now start to load up our information, starting by the name. Of course, there's no need to look the name up, as we just received it as an argument, but we still need to look the SpriteSheet path.

With the sprite specifics on their place, the next step is to put all animations to the animation vector. Our code will need to know how many animations there are, but that'll be no problem:

Every animation is a node, so we should now retrieve it.

With the animation node retrieved, we can now create the animation and populate it with the information from the file.

The last thing we need to do now is to get the time duration for our animation's frames.

And Voilà! All our animations are now inside our Sprite object!

The most important functions we used here were:

Want to try?

Start by creating a valid yaml file. You can test your syntax at It will probably take some tries, but after you actually learn it, you will mostly get it right in one try. A single entry like your personal info will do just fine. After that, create a simple structure to hold that information and load it manually, inside your main.cpp directly if you prefer. Then, move the loading procedure into a class that can load the information itself and, lastly, make several entries and load them independently. Move on to more complex documents and you'll master it before you know it.

Thanks to jbeder for the yaml-cpp library! It is so convenient I'm getting lazy.

Over and Out.

Monday, February 3, 2014

My GameDev Bookmarks (danger ☠ minefield)

Hello Again,

Long time no post, I've been working more on personal projects than on our little game. A shame, but I will try to give it some more love soon!Today I come to you guys to share something really personal, that is my personal GameDev related bookmarks. As an Open Source enthusiast, I use firefox, even if Google's Chrome is faster; I don't care if it is faster, if it is not mine. So, I'll provide a mozilla firefox json file for anyone interested, here.

It is a relatively big list, some links have been in here for over 5 years. I gone over it deleting most of them, as there were several dead projects and outdated materials. I added a couple more, and included short descriptions for the links.

If you have a good link that I don't have in my bookmarks, please comment and I'll add it!
PS: The Engines folder is on the very end of the post.
Dejaime's GameDev Bookmarks
A link list by several people who have accounts (not my case). Several useful projects.

Create A Repo · GitHub Help
A simple guide to creating a Repo on GitHub.

N Tutorial A - Collision Detection and Response
Some not-that-basic collision detection and response tutorial for 2D environments.
Highscore Vol. 1 - The Video Game Music Pack -
The cheapest and most high quality song set I've seen.
Welcome to the CEGUI homepage | CEGUI
A GUI library that is very promising. Never used it though.
IGDA Scotland Presents: Brian Baglow on Vimeo
A talk on Indie Game Marketing. Very informative. His name is actually Brian Baglow, the title is misspelled as Brain on the video website...
Arcane Dominion: Exporting and Importing Code::Blocks Themes
A tutorial to import color schemes into Code::Blocks. I always forget how to do this.
YAML - Wikipedia, the free encyclopedia
YAML is a serialization format that, differently from XML, isn't a markup language. I personally don't like XML, I prefer YAML.
[a5 rc4] anomalous blending
This is a short discussion regarding pre-multiplied alpha for 2D, and the main reason I stopped whining about it and started using it. Never looked back.
A music website that has lots of CC licensed titles.
How to Start an Indie Game Business (WIP)
A link list on the Indie Game Buz. Goes from IPs, publishers to funding and selling.
Legal Music For Videos - Creative Commons
Another link for music, CC.

Free Development Resources | Free Resources!
A website with some free art resources. Really small library, but I hope it'll grow!
The Function Pointer Tutorials - Callbacks
A link explaining Callbacks for C++. Very informative.

audiere | home
A high level audio API.
Welcome to the Game Programming Wiki!
A wiki specific for game development. Specially good for beginners.
How to create Box2D collision from a Tiled Map | iUridium
A tutorial on how to create the collision data of a world based on a map created with Tiled Map Editor (which, btw, has the link listed below).
Steering Behaviors For Autonomous Characters
A beginners tutorial on simple movement AI.

SDL tutorials, a rather complete set.
Search Art |
A free art website with a good library.
Vídeos enviados - YouTube (Free Soundtrack)
A youtube list of videos from Free Soundtrack.
Link to the International Game Developers Association website.
Tile Studio
This is both, a tile editor and a map editor. I have only used the tile editing feature.
GTK+ Download: Windows (32-bit)
GTK+ is a GUI Toolkit, very flexible.
Tiled Map Editor
The best map editor I know.
The guide to implementing 2D platformers | Higher-Order Fun
A small article on 2D platformers, very informative.
Valgrind Home
A really good open-source dynamic analysis tool, the best I've used.
It runs on Linux, Android and Darwin systems (no windows).

Dr. Memory Memory Debugger for Windows and Linux
An alternative to Valgrind. This one works on Windows systems, what is a huge advantage, but doesn't have Android support.
index - Haxe
A multi-platform programming language. The code once play everywhere type. Very promising, but lacking badly on Game Development tutorials and snippets.
SDL - Some random links on SDL, been here for ages, I update these from time to time.
SDL Maps
SDL Animation
SDL Entities
Box2D - Some links on Box2D.
▶ Box2D Lesson 2.2 -- Everything we did in Chapter 1 in about 6 minutes - YouTube
Todd's Box2D Tutorials!
Box2D tutorials - Testbed structure - iforce2d
Engines - Several game engines, all free and usable. Most of them are C++.
2d game engine – Indielib
A good 2.5D game engine, slightly microsoft dependent (DirectX and VS are their main targets), so I've never used it. Licensed under LGPL (bad idea for commercial games).

Angel 2D
I totally underestimated how Angel2D makes our lives easier and its overall quality. It is a great prototyping tool. It is only lacking documentation and a real tutorial. Permissive license.
LÖVE - Free 2D Game Engine
A Lua game development framework, made for rapid game development of light games. It also has some awesome T-shirts. Licensed under zlib license, suitable for commercial use.
Oxygine | Oxygine is C++ engine and framework for 2D games
A C++ engine for 2D games for Computers and Mobile platforms. The same as Mutiny, it is a starting project that I hope will do very well on the coming years. Never used it. Licensed under the awesome X11 license.
A link for the SDL official website. Just to say, SDL 1.2 is licensed under LGPL, while SDL 2 is under the zlib license (much better).
Maratis is a visual game editing tool, cross-platform and very high quality. The editor is licensed under GPL, but the engine under zlib.
It is a very ambitious concept, but that is yet to make up for the promises. A really bad compiling solution halted me from using it about a year ago. Haven't tried it since. But I keep the link Bookmarked since I know it will be good someday, just need some more contributors! Licensed under the permissive X11 license.
About FIFE
The engine features isometric and top-down maps and has a rather impressive feature list. Unfortunately, only for computers, no mobile platforms here.
This Java game engine is really complete and flexible. Licensed under the Apache v2.0, that is a long, yet permissive, license.
Cocos2D-X is a multilanguage, crossplatform, X11 licensed engine. You can use it with C, C++, as well as mix it up with libraries such as Box2D. I've personally never used it, but surely will.
This is a X11 licensed engine for mobile platforms, really easy to use and for rapid development. Targets iOS out of the box, but you would need to pay (a lot) for a third-party tool in order to target Android. If you want Android and don't mind paying for it I would recommend Unity's Android version over this engine.
Orx - Portable Game Engine
Another 2.5D engine that is really good. It lacks some features when compared to FIFE (pathfinding to name one), but can target mobile platforms as well as computers. Licensed under zlib.

ClanLib Game SDK
A really awesome 2D and 3D game SDK with numerous great features such as OpenCL support, integrated resource manager, physics, SQLite, GUI framework, and much more. Be sure to take a look. C++.
I guess that's it!
Over and Out!