Friday, 22 January 2016

How to build TMX Map loader for SFML

Soo.. the usual opening apology for lack of content - sorry! (Happy new year by the way!). Although I have a wealth of ideas I'd like to write about it actually becomes very hard to find the time to write about them when I'm busy implementing them. Long story short I've been working on tidying up the framework I use for building SFML games called xygine. Technically this post is not about that though, (and the project itself is far from finished) so if you're curious as to what my take on an Entity Component System for SFML might look like you can find the repositiory here. Hopefully one day you'll start to see some posts detailing some of the features.

To the crux of the matter: I get repeatedly asked about building the TMX map loader as, for some reason, it seems to be my most popular project. To be honest I'm a little disappointed with myself for not making this post much, much sooner but finally here it is. I've added a page to the map loader wiki which explains how to build it on various platforms and compilers, complete with an explanation for building the required zlib library on Windows. You can find the page here. Hopefully this will get enough exposure that anyone looking for it will be able to find it and build the map loader successfully. There may be a mistake here or there but, as the page is hosted on the Github wiki, anyone with a Github account will be able to contribute fixes and corrections. From now on this will be the official source of build information and I will forward  any queries to this link :)

Wednesday, 26 August 2015

Updates, updates...

... updates. I've not been toiling over any huge projects recently, but there has been a speight of update activity. First off I've pushed a few updates to the SFML TMX loader to the github repo. There's no new full release, but the updates do fix a couple of bugs, including polygonal objects losing their point data when properties are added. I've also added support for 'Collection of images' tile sets, which is more of a feature than a bug fix. If this is something you were waiting for then now is the time to pull down the latest revision.

I've also updated Pseuthe, fixing a bug where the score timer continued to run when the main window lost focus, as well as adding a colour blind mode for people who find distinguishing between red and green difficult. I've also updated the help menu. This brings Pseuthe to 1.0.3, the Windows and Linux binaries for which you can download from, or, if you prefer, the source from Github. Thanks to kind community donations there is also now an OSX binary in the works, which should appear on itch within the next few days.

Monday, 3 August 2015

TMX Map Loader for SFML version 1.1.0

I've recently published version 1.1.0 of the Tiled map loader on Github. This release includes the changes from the previous update, as well as bug fixes, and the ability to load tmx maps from xml strings stored in memory.
   I was asked recently over on the SFML IRC channel about the possibilities of obfuscation of tmx maps. It was pointed out that any end user of a game can easily cheat by loading the game's map files into Tiled and editing them to make them easy to complete. I guess this is technically true of any game, whatever the map format, although with varying degrees of determination needed to make it happen. With tmx map files, however, it is incredibly easy. I guess you could argue of someone wants to cheat to make the game easier, then it's their loss anyway, but I saw no harm in offering a bit of flexibility to devs who want to obfuscate their map files. The idea is that tmx files output by Tiled can be run through an obfuscator of choice, making them immediately difficult to load directly into Tiled - although it's not of course bullet proof. The game using the maps would then need to internally unobfuscate the map data before passing it to the map loader - hence the new ability to load files directly from xml strings. I've not implemented and obfusation routines myself, and it's not part of the map loader. Offering such things as open source would probably undermine their use anyway. Hopefully this will find some use with developers. In the future I'm also planning to support other formats such as json, and possibly even binary tmx files - so watch this space.

Tuesday, 30 June 2015

A new game - Pseuthe

UPDATE: You can now download the latest binaries for Windows and Linux from !

So I've been busy beavering away behind the scenes (and neglecting this blog) working on a casual game written using everyone's favourite C++ library; SFML. Pseuthe (pronounced 'soothe') started out as an experiment in Newtonian physics, but I was soon elbow deep adding the prettiest graphics I could muster, as well as some semblance of gameplay. You take on the role of a deepwater plankton, feeding on all the happy microbes you can find before your being winks out of existence. Last as long as you can, and don't eat any of the bad microbes (highlighted by their red markings). Here's a video to give you some idea of what it's all about:

I'm still tweaking things here and there, so there are no binaries available, but it is open source so you can compile it yourself. The repository contains a Visual Studio 2013 solution to get you started on Windows, and I've tested the CMake / make files with gcc on linux (mainly Ubuntu and Arch). It should compile on OSX too, but I don't have a machine to test it on. If anyone wants to contribute OSX support to the CMake file, I'll gratefully accept any pull requests ;)

Tuesday, 21 April 2015

Tmx loader for SFML - an update!

It's been a while since I last updated my first and, apparently, most popular project but I've finally found some time to sit down and tackle the ever increasing list of issues. I've not fixed everything, but have made some significant improvements, so here they are in brief:

New debug levels. It was brought to my attention that the loader doesn't need to be so verbose all the time, so I've made debug output more flexible. Firstly the output of debug messages can be decided with three defines:


These allow messages to directed to either the console, a log file on disk, or both. Logging is skipped altogether if none of these are defined. This allows flexible logging between different builds, such as Debug and Release for example. The log class also has a function which allows setting a series of flags to define the level of logging, with Information, Warning and Error levels available. These are set via

Logger::SetLogLevel(Logger::Warning | Logger::Error);

and can be set at any point in code.

Texture fixes. There was a small but rather daft error which meant adding new textures to a loaded map would invalidate existing texture references. This has now been fixed.

Rendering optimisation. Large maps which contained a lot of TileQuad data would run abhorrently, due to the fact the renderer would check *every* TileQuad each frame for any updates. This was a silly mistake, and I've improved performance twenty-fold in some cases by listing dirty quads and only updating those. This means maps with a lot of moving tiles, such as map objects with attached textures, will suffer performance drops proportionally to the number of moving objects. In extreme cases it's probably better to handle such game entities outside of the map loader inside a scene graph or physics world for example (consider that all tiles will be updated, even when off screen. This would be much better optimised if handled elsewhere). Maps which are mostly static will draw much faster now, however. Vertex arrays which cover only a small portion of a map are also culled if not visible on screen. This gives a small performance boost, particularly to maps with a lot of layers or tile set textures.

The updates are all available via the source on Github, and the Readme contains more information on using the debugger output.

Wednesday, 18 February 2015

Crush! Breakdown Part 2 - Collision World

In part one of the Crush! breakdown I outlined the scene graph used to transform and render game entities, as well as some of the controller classes used to manipulate nodes within the scene. Entities are created by attaching a combination of components to a node, one of which is the collision component - used to make the nodes react to external forces and resolve collisions between the bodies. My instinct for this kind of thing is usually to reach for a library such as chipmunk or box2d, but experience has taught me that this is often overkill for a small project, and will probably not yield great results if the game isn't inherently physics based (such as Angry Birds for example). On top of this I'm always willing to investigate new areas of programming, so giving the subject of physics and collision handling some serious study was an idea which appealed to me. To prevent presenting myself with a daunting scope I tried to reduce the amount of complexity as much as possible by looking carefully at what would actually be needed. After some cogitation I decided that all I needed were rectangular bodies with no rotation which reduced the scope dramatically when considering what would be needed for collision detection. Normally I would give body properties mass so that each body's acceleration could be calculated by the current force acting upon it, using Newton's second law of motion: force = mass * acceleration. Even this could be reduced so that a collision body only needed a velocity vector, a position, and a bounding box.

struct CollisionBody
    vector2 m_velocity;
    vector2 m_position;
    floatRect m_boundingBox;

Each frame the body's position is updated by adding the current velocity to it. The velocity is adjusted by either applying an external force (by adding another vector to the velocity), or as a result of a collision. Collision bodies exist within a CollisionWorld class, which is responsible for creating bodies, detecting collisions between them, and applying any resulting forces. The CollisionWorld class also acts as one of the controller classes, and so the instance lives alongside the other controllers in the GameState class. Apart from the factory functions of the CollisionWorld class, the beef of the code exists inside:

CollisionWorld::update(float dt)
    //test which bodies intersect and mark as collision pair
    for(const auto& bodyA : m_bodies)
         for(const auto& bodyB : m_bodies)
            if(bodyA.get() != bodyB.get())
                    m_collisions.insert(std::minmax(bodyA.get(), bodyB.get()));


    //for each collision pair calculate manifold and resolve collision
    for(const auto& pair : m_collisions)
        auto manifold = getManifold(pair);
        manifold.z -= manifold.z;

    //apply gravity to each body and perform a physics step
    for(auto& body : m_bodies)

The update function is performed in to three main steps. First each body is tested against the others for intersection using its bounding box. If there is an intersection the pair of bodies are inserted into a std::set using std::minmax() which makes sure that each pair is inserted only once. Potentially this step could be optimised with some kind of spatial partitioning to make sure bodies are only tested against other nearby bodies, but for a small game it wasn't needed, and I omitted it for the sake of simplicity.
    The second step is to calculate the collision manifold of each intersecting pair. The manifold contains a normalised vector perpendicular to the intersected surface, and a value stating the depth of intersection. This is usually the minimum it takes to resolve a collision between two objects - and in rectangular-only collision is vastly simplified by the fact that there can only be one of four possible normal vectors for each side of the rectangle, reducing the complexity of manifold calculation dramatically. In my calculation function I took advantage of the fact SFML's rectangle class returns the intersection area as a new rectangle, and you can see the full implementation here. Handily I could fit the two component normal vector along with the penetration depth into a single sf::Vector3, which made it an easy value to pass around. If you're interested in manifold generation for more complex interactions, there is an interesting article here which I found worth reading. The last step of the CollisionWorld update function applies a pre-defined gravity force to each body (the gravity value is passed to the CollisionWorld constructor), and executes each body's step() function.

Each body has two important functions, resolve() and step(). The resolve() function is used to decide how the body should react to the collision manifold data. As each body type needs to react slightly differently this is where behaviour customisation is applied. Each body has a currently active state defining its behaviour at that point in time. I took this idea from the state pattern (again from Game Programming Patterns), and created a BodyBehaviour class from which body type specialisations are inherited. This allows collisions to resolve themselves in specific ways, such as water being absorbent, or the ground being solid - as well as giving bodies the opportunity to raise body specific events. When a player body is destroyed then a PlayerDied event can be raised and so on. Physics values such as gravity and friction can also be intercepted by the active behaviour and modified if necessary, velocity vectors reflected about the manifold normal data or penetration values negated.
    The body step() function then applies any changes made by the resolve() function by integrating the current time step with the body's velocity, and then moving the body. It also does some simple bounds checking and moves any bodies which may have tunneled out of the play area to a reasonable place at the top of the world. If the body is attached to a node in the scene graph then that node's position is then updated in the scene. Here is a video of the initial physics setup:

The red blocks are solid bodies, green are enemies, and blue is the player.

This is a very simplified overview of the collision system in Crush!, admittedly, but it's very difficult to go very far into detail in a single post. Crush! is open source, however, and the full collision code can be seen here.

Tuesday, 17 February 2015

Crush! Breakdown Part 1 - Scene setup

After spending any amount of time on a project I like to look back over what I did and break it down in a kind of postmortem. I find some retrospect helps me to consider what it is I've done wrong so that I can learn from the experience before moving on. The starting point for this particular project was creating a scene and getting it rendering in a modular and extensible way. I'm actually pretty pleased with what I did, although I do wish I had considered networking support early on in design, as it really needs to be baked in from the start (and hence will probably never be added to Crush!).
    I started with the concept of a scene graph - a series of parented nodes which allow draw calls and transformations to be passed across siblings and down through children. Scene graphs are well documented and there are resources all over the internet for learning about them, so I'll not go too far into detail here. There is even an example in the SFML book, which I used as a starting point as I was using SFML as the main library. The scene graph in Crush! varies from the book's implementation, however, in that instead of relying on inheritance for distinguishing node types it tries to take a component based approach. The scene graph exists to maintain the transformations of each scene node, and allows rendering of the scene in as compact way as possible. The actual drawing of node representations and the behaviour of nodes (including how they are transformed in the scene) is left to those components, so each node can behave independently, depending on the collection of components which are attached to it. The entire node graph is kept inside a class which represents a scene. This class is essentially the root node of the graph, with a few key differences to implement ownership semantics. As well as the graph the Scene class owns any lights which may exist, as well as cameras used for rendering the scene. This means the Scene class can properly set up any views and perform lighting calculations each frame, before moving down the graph and rendering any drawables attached to the nodes. Internally the Scene's draw function looks a bit like this (in pseudo code):

Scene::draw(RenderTarget rt, States states)
    states.shader = m_lightingShader;
    for(const auto& l : m_lights)

    m_sceneGraph.draw(rt, states);

I'll cover the actual lighting and camera set up in another post. For now it's enough to know that the scene is responsible for the lights and cameras which have been created (and attached to nodes as part of the component strategy) which it then uses to update the shader system each frame, before drawing the scene graph.This also nicely encapsulates much of the rendering, so that externally the entire scene can be drawn at once. The overall structure of the game uses a state stack, and the current scene is a member of 'GameState' (other states being PauseState, MenuState and so on), so when the GameState is created a new scene is built from information loaded from a map file, and drawn with

m_scene.draw(m_renderWindow, states);

With little else to do to the scene the code in GameState can be kept relatively clean and easy to read, with all the implementation details tucked away inside the Scene class.

Using a component based approach with the scene nodes also helps with this, as each component can belong to a parent class where its details are relevant, without cluttering up the Node class itself. I already stated that cameras and lights are components, the Camera class being not much more than a wrapper around sf::View, and Light a small struct which contains colour and falloff values. These can be attached to nodes so that they take on any transformations as the node moves around the scene, without having to keep their own transform specific data. Lights and cameras both only exist within the scene so it makes sense that the Scene class should own all the instances, and pass out references to them should they need to be modified. For example:

auto& light = m_scene.createLight(colour, falloff);
Node::Ptr node;
//do other stuff to node

The same goes for cameras. Internally the Scene class creates the light (or camera), providing that certain criteria are met, and returns a reference to it so that it can be modified if necessary, and then attached to a node. Node::Ptr is a typedef for std::unique_ptr<Node> as nodes will usually need to be dynamically added and removed from the scene as game play progresses. Adding the node to the scene allows the Scene class (and, internally, the scene graph) to take ownership of the node, which is why I use a unique_ptr as opposed to a shared_ptr.
    The other main components used in the game are drawables - classes which inherit sf::Drawable, and collision bodies. I used sf::Drawable as the class type for rendering nodes rather than sf::Sprite, as most of the drawables I used were custom classes, such as the water effect or animated sprites. Collision bodies represent a very basic physics engine which only supports rectangular collision detection with no rotation. For this game it was enough, and using a full blown system such as Box2D seemed overkill. It also meant that I didn't have to worry about unit conversion and could keep all values within a single domain. Collision bodies all belong to a 'CollisionWorld' class which takes care of all the physics simulation, collision detection and collision resolution. Bodies can be requested from the CollisionWorld in a similar way to how lights/cameras are requested from the Scene class. The returned bodies remain owned by the collision world, and references are attached to the nodes as needed, so that the nodes can be transformed and updated as bodies move around the world and interact with each other. I'll go into full detail of the CollisionWorld class in another post.

This was enough to create a renderable scene, and make the scene nodes interactive whilst remaining reasonably decoupled from the other classes. It sat in my mind as having a set of playing pieces laid out on a game board, ready for the player to command. To be able to manipulate these playing pieces without directly hooking up too much code, I turned to the observer pattern, as described in Game Programming Patterns by Robert Nystrom (although he's far from the first to write about it of course). Here is, perhaps, where I would make a slight change in hindsight. While the pattern worked very well it did become a little spaghetti-like in places, and it isn't always obvious which classes are observing which - in future I would perhaps replace this pattern with a message bus. In this instance, though, I followed through with the idea of the scene nodes being 'observable', watched by a set of 'controller' classes with the ability to manipulate the playing pieces, each responsible for their own part of the game. Controller classes include the player, the scoreboard, the audio system, the physics world and a controller responsible for map data loaded from an external file. This also provided handy encapsulation for drawable objects, such as the player controller looking after an animated sprite and making sure the correct animations are played, or the map controller being responsible for creating the world geometry which makes up the scenery. Each of these controllers can then provide a reference to drawable items which are attached to the corresponding nodes in the scene graph. The scene graph needs to know nothing of the internal implementation of these drawables, only how to draw them. The controllers need to know little if nothing of each other either, they just watch the scene and wait for events to be raised via the observer pattern. If an event is pertinent to a particular controller, then that controller will act on it. For example if a PlayerDied event is raised then the audio controller will play a specific sound, the scoreboard controller will reduce the number of lives and points, and the player controller will reset the player's position.
    Finally, to enable the controller classes to manipulate the scene, I used a command queue which is more or less identical to that found in the SFML Game Development book. Each controller class keeps a reference to the command stack, so that when it needs to update the scene it can create a command targeted at a specific node or set of nodes, and place it on the stack. At the beginning of each frame the entire command stack is executed so that the scene is updated. After which the collision / physics world is updated and collisions resolved, the controllers respond to any events raised by the updated state, before the entire scene is then drawn. The flow within the GameState class then looks like this:






m_scene.draw(m_renderWindow, states);

Crush! is open source, so if you want to take a look at the final implementation, or just have a play you can get it from the Github page.

Part 2: Collision