HaxeFlixel Tutorial – Loading TMX Data

March 21, 2015WY Leong 15 Comments

Edit 2015-04-24: This tutorial has been revised completely to cater for multiple tile/object layers.

So far we have covered how to load CSV data and then parsing the loaded data. However, we assumed there’s only one layer; so if there is a player tile at (10,5), then there cannot be any ground tile behind it. And what if there’s an enemy that spawns on a specific grass tile? We would usually need layers. This is where Tiled Editor and the TMX file come in.

In Tiled, you can create multiple “tile” and “object” layers. You could have a map with the following setup:

tile layer for background (ground, river, etc.)
tile layer for foreground (walls, trees, etc.)
object layer for actors (player, enemies, treasure, etc.)

Before we proceed, let me share some nuggets of knowledge I gained while researching on how to parse TMX data:

What you need to load TMX data
- In order to load TMX data, you only need the TiledMap addon, flixel.addons.editors.tiled.TiledMap .
- The addon is a haxelib which needs to be enabled in the Project.xml file, like this: <haxelib name="flixel-addons" />
TMX layer data format
- Getting the layer data is quite flimsy: if the TMX format is in CSV, then you need to access the data via “csvData” property. If the TMX format is Base64, you need to access the data via “tileArray” property. I couldn’t get XML data from the TMX file, and since FlxTilemap isn’t able to parse XML data anyway, we’re only left with two choices.
Parsing TMX data
- TiledMap only loads the TMX file’s data. You will have to parse the data yourself. TMX data loads two main parts of the file — the tileset list, and the layer list.
- The tileset list contains all the tilesheet images that you used in the TMX map. In Tiled Editor, you can import multiple different spritesheets and use them in one project.
- The layer list (if you saved the layer format as CSV) will contain an array of CSV data for each layer. This is just a more convenient way of saying the TMX file keeps multiple CSV data in one place.
TMX loading/parsing limitations
- This is very important when proceeding with parsing TMX data. I struggled for a long time on figuring out an easy way to do this, until I realised the following limitations.
- HaxeFlixel does not have any function (as far as I know) that supports loading a tile map which uses multiple tilesheets. As such, each layer can only have ONE tilesheet associated with it.
- Layers in the TMX file also do NOT store info on which tilesheet is being used. As a result, you need to add a custom property on each layer to explicitly store the name of the tilesheet you used for that layer.
- In short, TiledMap only extracts most of the important info you need from the TMX file. It’s entirely up to you regarding how you’ll use the data to generate and render the tile map.

With the wisdom above, let us proceed.

Setup

First, let’s create a template HaxeFlixel project with an arbitrary name:

flixel tpl -n "MyTmxLoader"

1	flixel tpl -n "MyTmxLoader"

Next, let’s setup the necessary resources — we need a placeholder tilesheet. Let’s use this excellent sample from Sharm, “tiny 16 basic“. We’ll be using 4 images from there:

basictiles_2.png
characters_1.png
dead_1.png
things_0.png

Put the images in your project’s /assets/images folder.

TMX Data Setup

Now to create the TMX file. Here’s the bare minimum steps you’d usually have to go through to create a layered TMX file:

1) Create a new project.

2) Add the image tilesheets (basictiles_2.png, characters_1.png, dead_1.png and things_0.png) to your project.

3) For the purpose of demonstrating multiple tile and object layers, let’s create two tile layers and two object layers. In my example below, I renamed the layers to match the tilesheet image’s name which I’ll use for each layer.

4) Add a custom property to the tile layers so that when we parse the data in HaxeFlixel later, we can know what tilesheet this layer is using.

5) Do the same for the object layers.

6) Now place the tiles in the tile layer as you like. In my example below, I tried to use all possible tiles from each layer to test if all of them would appear correctly:

7) Do the same for the object layers:

8) When I enable all the layers, I should be able to see all of them, like this:

9) This step is optional. When you have specific object types in the object layer, such as “player”, “enemy”, “door” and “key”, you would normally do this — Select an arbitrary “player” object and add a custom property “type” to it, with the value “player”. We will use this value to parse it in TiledMap later. Without doing this, we won’t know how to identify different unique objects in the layer when we want to parse the data later. Repeat this step for other objects, such as enemies (“type” = “enemy”).

10) Save the file as something easy to remember, e.g. “my-map.tmx” Put the TMX file in the /assets/data folder. You’re now ready to load and parse the map data in HaxeFlixel!

Code

Now let’s get straight to the code:

package;

import flixel.FlxState;
import flixel.FlxG;
import haxe.io.Path;
import flixel.tile.FlxTilemap;
import flixel.addons.editors.tiled.TiledMap;

class MenuState extends FlxState
{
    override public function create():Void
    {
        super.create();

        // Load the TMX data
        var tiledLevel:TiledMap = new TiledMap("assets/data/my-map-2.tmx");

        // Get map variables
        var tileSize = tiledLevel.tileWidth;
        var mapW = tiledLevel.width;
        var mapH = tiledLevel.height;

        // Loop through each tile layer and render tile map
        for (layer in tiledLevel.layers)
        {
            // Remember:
            // TiledMap can only load data of type "String" or an "Array<Int>"
            // types, so there is no need load or parse XML data.

            // There are two ways to load layer data:
            // 1) If the TMX is saved in CSV format, then use this:
            // var layerData:String = layer.csvData;

            // 2) If the TMX is saved in base64, then use this:
            // (we shall assume our TMX is base64 format for now)
            var layerData:Array<Int> = layer.tileArray;

            // IMPORTANT:
            // If you used the wrong method to load the data,
            // the game will crash. :(

            // By default, the tilesheet used for this layer is not included in
            // the layer's data. As such, we had to add a custom property "tilesheet"
            // and include the tilesheet's name manually.
            var tilesheetName:String = layer.properties.get("tilesheet");
            var tilesheetPath:String = "assets/images/" + tilesheetName;

            // Finally, create the FlxTilemap and get ready to render the map.
            var level:FlxTilemap = new FlxTilemap();

            // If we're passing an array of data, the level needs to know
            // how many columns of data to read before it moves to a new row,
            // as noted in the API page:
            // http://api.haxeflixel.com/flixel/tile/FlxTilemap.html#loadMap
            level.widthInTiles = mapW;
            level.heightInTiles = mapH;

            // Note: The tilesheet indices are continuous! This means,
            // if there is more than one tilesheet, the 2nd tilesheet's
            // starting index right after the 1st tilesheet's last index.
            // e.g.
            // - tilesheet 1 has 100 tiles (index = 1-100)
            // - tilesheet 2 has 100 tiles (index = 101-200 instead of 1-100)
            //
            // Note2: that the gid "0" is reserved for empty tiles
            var tileGID:Int = getStartGid(tiledLevel, tilesheetName);

            // Render the map.
            // Note: the StartingIndex is based on the tilesheet's
            // startingGID rather than the default 1.
            level.loadMap(layer.tileArray, tilesheetPath, tileSize, tileSize, FlxTilemap.OFF, tileGID);
            add(level);
        }
    }

    function getStartGid (tiledLevel:TiledMap, tilesheetName:String):Int
    {
        // This function gets the starting GID of a tilesheet

        // Note: "0" is empty tile, so default to a non-empty "1" value.
        var tileGID:Int = 1;

        for (tileset in tiledLevel.tilesets)
        {
            // We need to search the tileset's firstGID -- to do that,
            // we compare the tilesheet paths. If it matches, we
            // extract the firstGID value.
            var tilesheetPath:Path = new Path(tileset.imageSource);
            var thisTilesheetName = tilesheetPath.file + "." + tilesheetPath.ext;
            if (thisTilesheetName == tilesheetName)
            {
                tileGID = tileset.firstGID;
            }
        }

        return tileGID;
    }

    override public function update():Void
    {
        super.update();
    }

    override public function destroy():Void
    {
        super.destroy();
    }
}

100

101

102

103

104

105

106

107

108

package;

import flixel.FlxState;

import flixel.FlxG;

import haxe.io.Path;

import flixel.tile.FlxTilemap;

import flixel.addons.editors.tiled.TiledMap;

class MenuState extends FlxState

{

override public function create():Void

{

super.create();

// Load the TMX data

var tiledLevel:TiledMap = new TiledMap("assets/data/my-map-2.tmx");

// Get map variables

var tileSize = tiledLevel.tileWidth;

var mapW = tiledLevel.width;

var mapH = tiledLevel.height;

// Loop through each tile layer and render tile map

for (layer in tiledLevel.layers)

{

// Remember:

// TiledMap can only load data of type "String" or an "Array<Int>"

// types, so there is no need load or parse XML data.

// There are two ways to load layer data:

// 1) If the TMX is saved in CSV format, then use this:

// var layerData:String = layer.csvData;

// 2) If the TMX is saved in base64, then use this:

// (we shall assume our TMX is base64 format for now)

var layerData:Array<Int> = layer.tileArray;

// IMPORTANT:

// If you used the wrong method to load the data,

// the game will crash. :(

// By default, the tilesheet used for this layer is not included in

// the layer's data. As such, we had to add a custom property "tilesheet"

// and include the tilesheet's name manually.

var tilesheetName:String = layer.properties.get("tilesheet");

var tilesheetPath:String = "assets/images/" + tilesheetName;

// Finally, create the FlxTilemap and get ready to render the map.

var level:FlxTilemap = new FlxTilemap();

// If we're passing an array of data, the level needs to know

// how many columns of data to read before it moves to a new row,

// as noted in the API page:

// http://api.haxeflixel.com/flixel/tile/FlxTilemap.html#loadMap

level.widthInTiles = mapW;

level.heightInTiles = mapH;

// Note: The tilesheet indices are continuous! This means,

// if there is more than one tilesheet, the 2nd tilesheet's

// starting index right after the 1st tilesheet's last index.

// e.g.

// - tilesheet 1 has 100 tiles (index = 1-100)

// - tilesheet 2 has 100 tiles (index = 101-200 instead of 1-100)

// Note2: that the gid "0" is reserved for empty tiles

var tileGID:Int = getStartGid(tiledLevel, tilesheetName);

// Render the map.

// Note: the StartingIndex is based on the tilesheet's

// startingGID rather than the default 1.

level.loadMap(layer.tileArray, tilesheetPath, tileSize, tileSize, FlxTilemap.OFF, tileGID);

add(level);

}

function getStartGid (tiledLevel:TiledMap, tilesheetName:String):Int

{

// This function gets the starting GID of a tilesheet

// Note: "0" is empty tile, so default to a non-empty "1" value.

var tileGID:Int = 1;

for (tileset in tiledLevel.tilesets)

{

// We need to search the tileset's firstGID -- to do that,

// we compare the tilesheet paths. If it matches, we

// extract the firstGID value.

var tilesheetPath:Path = new Path(tileset.imageSource);

var thisTilesheetName = tilesheetPath.file + "." + tilesheetPath.ext;

if (thisTilesheetName == tilesheetName)

{

tileGID = tileset.firstGID;

}

return tileGID;

}

override public function update():Void

{

super.update();

}

override public function destroy():Void

{

super.destroy();

}

Now if you test the game with lime test neko …

Oops, I forgot to set the screen resolution, but let’s assume you fixed that (change the gameWidth and gameHeight values in Main.hx).

Anyway, the game renders the two tile layers correctly! Now you know how to load multiple layers in your tilemap. Now let’s load the game objects:

package;

import flixel.FlxState;
import flixel.FlxG;
import flixel.FlxSprite;
import haxe.io.Path;
import flixel.tile.FlxTilemap;
import flixel.addons.editors.tiled.TiledMap;

class MenuState extends FlxState
{
    override public function create():Void
    {
        super.create();

        // Load the TMX data
        ...

        // Get map variables
        ...

        // Loop through each tile layer and render tile map
        ...

        // Loop through each object layer and spawn the objects.
        for (group in tiledLevel.objectGroups)
        {
            var tilesheetName:String = group.properties.get("tilesheet");
            var tilesheetPath:String = "assets/images/" + tilesheetName;

            trace("group : " + group.name + " , " + tilesheetPath);

            for (object in group.objects)
            {
                var objectType:String = object.custom.get("type");
                var objX:Int = object.x;
                var objY:Int = object.y;

                // NOTE: same as layer note above, regarding tilesheet indices.
                var tileGID:Int = getStartGid(tiledLevel, tilesheetName);

                // Get the current tilesheet's id by subtracting
                // the object's gid from the tilesheet's firstgid value.
                var frameIndex:Int = object.gid - tileGID;

                // For example purposes, all objects are regarded as same type.
                switch(objectType)
                {
                    case "player": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    case "enemy": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    case "door": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    case "key": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    default: createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                }
            }
        }
    }

    function createObject (objX:Float, objY:Float, tilesheetPath:String, tileSize:Int, frameIndex:Int)
    {
        var player:FlxSprite = new FlxSprite(objX, objY);
        player.loadGraphic(tilesheetPath, false, tileSize, tileSize);
        player.animation.frameIndex = frameIndex;
        add(player);
    }

    function getStartGid (tiledLevel:TiledMap, tilesheetName:String):Int
    {
        ...
    }

    ...
}

package;

import flixel.FlxState;

import flixel.FlxG;

import flixel.FlxSprite;

import haxe.io.Path;

import flixel.tile.FlxTilemap;

import flixel.addons.editors.tiled.TiledMap;

class MenuState extends FlxState

{

override public function create():Void

{

super.create();

// Load the TMX data

...

// Get map variables

...

// Loop through each tile layer and render tile map

...

// Loop through each object layer and spawn the objects.

for (group in tiledLevel.objectGroups)

{

var tilesheetName:String = group.properties.get("tilesheet");

var tilesheetPath:String = "assets/images/" + tilesheetName;

trace("group : " + group.name + " , " + tilesheetPath);

for (object in group.objects)

{

var objectType:String = object.custom.get("type");

var objX:Int = object.x;

var objY:Int = object.y;

// NOTE: same as layer note above, regarding tilesheet indices.

var tileGID:Int = getStartGid(tiledLevel, tilesheetName);

// Get the current tilesheet's id by subtracting

// the object's gid from the tilesheet's firstgid value.

var frameIndex:Int = object.gid - tileGID;

// For example purposes, all objects are regarded as same type.

switch(objectType)

{

case "player": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

case "enemy": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

case "door": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

case "key": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

default: createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

}

function createObject (objX:Float, objY:Float, tilesheetPath:String, tileSize:Int, frameIndex:Int)

{

var player:FlxSprite = new FlxSprite(objX, objY);

player.loadGraphic(tilesheetPath, false, tileSize, tileSize);

player.animation.frameIndex = frameIndex;

add(player);

}

function getStartGid (tiledLevel:TiledMap, tilesheetName:String):Int

{

...

}

...

}

EDIT: Thanks to Keith for the info — If you’re familiar with some other languages (C++, C#, etc.), you probably have this habit of ending every switch case with a break , like I do.

However, in Haxe, switch cases do NOT fall through, as stated on the syntax page. In fact, if you add breaks in your switch case, it will end up exiting the while-loop or for-loop outside of the switch block.

… And now, we can see the objects on the map as well:

But wait, we’re not quite done yet — Notice that the placement of the objects in the layer is a little off (the y-position is lower by one tile than it should be). Thanks to Rafael J in the comment for fix:

        // Loop through each object layer and spawn the objects.
        for (group in tiledLevel.objectGroups)
        {
            var tilesheetName:String = group.properties.get("tilesheet");
            var tilesheetPath:String = "assets/images/" + tilesheetName;

            trace("group : " + group.name + " , " + tilesheetPath);

            for (object in group.objects)
            {
                var objectType:String = object.custom.get("type");
                var objX:Int = object.x;
                var objY:Int = object.y;
                
                if (object.gid != -1)
                    objY -= group.map.getGidOwner(object.gid).tileHeight;

                // NOTE: same as layer note above, regarding tilesheet indices.
                var tileGID:Int = getStartGid(tiledLevel, tilesheetName);

                // Get the current tilesheet's id by subtracting
                // the object's gid from the tilesheet's firstgid value.
                var frameIndex:Int = object.gid - tileGID;

                // For example purposes, all objects are regarded as same type.
                switch(objectType)
                {
                    case "player": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    case "enemy": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    case "door": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    case "key": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                    default: createObject(objX, objY, tilesheetPath, tileSize, frameIndex);
                }
            }
        }

// Loop through each object layer and spawn the objects.

for (group in tiledLevel.objectGroups)

{

var tilesheetName:String = group.properties.get("tilesheet");

var tilesheetPath:String = "assets/images/" + tilesheetName;

trace("group : " + group.name + " , " + tilesheetPath);

for (object in group.objects)

{

var objectType:String = object.custom.get("type");

var objX:Int = object.x;

var objY:Int = object.y;

if (object.gid != -1)

objY -= group.map.getGidOwner(object.gid).tileHeight;

// NOTE: same as layer note above, regarding tilesheet indices.

var tileGID:Int = getStartGid(tiledLevel, tilesheetName);

// Get the current tilesheet's id by subtracting

// the object's gid from the tilesheet's firstgid value.

var frameIndex:Int = object.gid - tileGID;

// For example purposes, all objects are regarded as same type.

switch(objectType)

{

case "player": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

case "enemy": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

case "door": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

case "key": createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

default: createObject(objX, objY, tilesheetPath, tileSize, frameIndex);

}

And now the positions are all correct!

The code above isn’t complete — we didn’t cover customising tile property, player/enemy logic, etc.. But anyway this concludes the tutorial. Thank you for reading. 🙂

HaxeFlixel Tutorial – Parsing CSV Map Data

March 14, 2015WY Leong Leave a comment

In the previous post we loaded CSV data to display a tiled map in HaxeFlixel. But I forgot to talk about what to do after loading the data, so let’s run through a quick tutorial on how to parse the loaded map data.

Let’s assume you’ve created a template HaxeFlixel project, and this is how your MenuState.hx looks like:

package;

import flixel.FlxState;
import flixel.FlxG;
import flixel.tile.FlxTilemap;
import openfl.Assets;

class MenuState extends FlxState
{
    var level:FlxTilemap;

    override public function create():Void
    {
        super.create();

        level = new FlxTilemap();
        var mapData:String = Assets.getText("assets/data/tutorial-map.csv");
        var mapTilePath:String = "assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png";
        level.loadMap(mapData, mapTilePath, 16, 16);
        add(level);
    }

    override public function update():Void
    {
        super.update();
    }

    override public function destroy():Void
    {
        super.destroy();
    }
}

package;

import flixel.FlxState;

import flixel.FlxG;

import flixel.tile.FlxTilemap;

import openfl.Assets;

class MenuState extends FlxState

{

var level:FlxTilemap;

override public function create():Void

{

super.create();

level = new FlxTilemap();

var mapData:String = Assets.getText("assets/data/tutorial-map.csv");

var mapTilePath:String = "assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png";

level.loadMap(mapData, mapTilePath, 16, 16);

add(level);

}

override public function update():Void

{

super.update();

}

override public function destroy():Void

{

super.destroy();

}

If you test the game with lime test neko now, you should get this:

A lot of other tutorials would have mentioned this, but in case you didn’t know yet — To change the resolution of the screen, you just need to modify these variables in Main.hx:

	var gameWidth:Int = 320; // Width of the game in pixels (might be less / more in actual pixels depending on your zoom).
	var gameHeight:Int = 240; // Height of the game in pixels (might be less / more in actual pixels depending on your zoom).

1 2	var gameWidth:Int = 320; // Width of the game in pixels (might be less / more in actual pixels depending on your zoom). var gameHeight:Int = 240; // Height of the game in pixels (might be less / more in actual pixels depending on your zoom).

… and now it should look like this:

Even though the map is loaded, it’s just a static image. There’s no player code, or wall data, or anything else. So how do we code from here? Assuming that we’re using the layout above, here’s the CSV data (generated from Tiled, and using Derek Yu’s tilesheet):

21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21
21,-1,-1,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21
21,-1,2,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21
21,-1,-1,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,20,-1,-1,-1,21
21,-1,-1,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21
21,21,21,65,21,21,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,37,37,37,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,37,37,37,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,-1,-1,21
21,-1,-1,-1,-1,10,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,-1,-1,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,32,-1,21
21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,-1,-1,21
21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21

21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21

21,-1,-1,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21

21,-1,2,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21

21,-1,-1,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,20,-1,-1,-1,21

21,-1,-1,-1,-1,-1,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21

21,21,21,65,21,21,21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21

21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21

21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,37,37,37,21

21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,-1,-1,21

21,-1,-1,-1,-1,10,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,-1,-1,21

21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,21

21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,32,-1,21

21,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,37,37,-1,-1,-1,21

21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21,21

If you examine the tilesheet image, the numbers above correspond with the tile index, as noted below:

Let’s start with the player object first. We know that tile 20 is the red player tile, so how do we convert it into a game object?

package;

import flixel.FlxState;
import flixel.FlxG;
import flixel.tile.FlxTilemap;
import openfl.Assets;
import flixel.FlxSprite;
import flixel.util.FlxPoint;

class MenuState extends FlxState
{
    var level:FlxTilemap;
    var player:FlxSprite;

    override public function create():Void
    {
        super.create();

        level = new FlxTilemap();
        var mapData:String = Assets.getText("assets/data/tutorial-map.csv");
        var mapTilePath:String = "assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png";
        level.loadMap(mapData, mapTilePath, 16, 16);
        add(level);

        /*
            For our player spawn code, we do the following:
            
            1) get FlxPoint array of all tiles that are 
               index "20" (the player tile image)

            2) assuming there's only ever one player in
               the game at one time, get the first FlxPoint

            3) use the FlxPoint to create a new FlxSprite at
               the target point
        */
        var playerCoords:Array<FlxPoint> = level.getTileCoords(20, false);
        var playerPosition:FlxPoint = playerCoords[0];
        addPlayer(playerPosition.x, playerPosition.y);

        /*
            Once we spawn the player, we need to remove the map tile with
            the value "20" (the player tile image). Otherwise, you'll see
            a tile image of the player under the actual player object as
            well. You can try commenting the 3 lines of code below to see
            what I mean.
        */
        var playerTiles:Array<Int> = level.getTileInstances(20);
        var playerTile:Int = playerTiles[0];
        level.setTileByIndex(playerTile, -1, true); // remove player map tile
    }

    function addPlayer(X:Float, Y:Float):Void
    {
        player = new FlxSprite(X, Y);
        player.loadGraphic("assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png", false, 16, 16);
        player.animation.add("idle", [20]);
        player.animation.play("idle");
        add(player);
    }

    override public function update():Void
    {
        super.update();
    }

    override public function destroy():Void
    {
        super.destroy();
    }
}

package;

import flixel.FlxState;

import flixel.FlxG;

import flixel.tile.FlxTilemap;

import openfl.Assets;

import flixel.FlxSprite;

import flixel.util.FlxPoint;

class MenuState extends FlxState

{

var level:FlxTilemap;

var player:FlxSprite;

override public function create():Void

{

super.create();

level = new FlxTilemap();

var mapData:String = Assets.getText("assets/data/tutorial-map.csv");

var mapTilePath:String = "assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png";

level.loadMap(mapData, mapTilePath, 16, 16);

add(level);

For our player spawn code, we do the following:

1) get FlxPoint array of all tiles that are

index "20" (the player tile image)

2) assuming there's only ever one player in

the game at one time, get the first FlxPoint

3) use the FlxPoint to create a new FlxSprite at

the target point

var playerCoords:Array<FlxPoint> = level.getTileCoords(20, false);

var playerPosition:FlxPoint = playerCoords[0];

addPlayer(playerPosition.x, playerPosition.y);

Once we spawn the player, we need to remove the map tile with

the value "20" (the player tile image). Otherwise, you'll see

a tile image of the player under the actual player object as

well. You can try commenting the 3 lines of code below to see

what I mean.

var playerTiles:Array<Int> = level.getTileInstances(20);

var playerTile:Int = playerTiles[0];

level.setTileByIndex(playerTile, -1, true); // remove player map tile

}

function addPlayer(X:Float, Y:Float):Void

{

player = new FlxSprite(X, Y);

player.loadGraphic("assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png", false, 16, 16);

player.animation.add("idle", [20]);

player.animation.play("idle");

add(player);

}

override public function update():Void

{

super.update();

}

override public function destroy():Void

{

super.destroy();

}

You can check the FlxTilemap API for more information on the functions used above. If you test the game, it should still look the same. We replaced the player tile with an actual player object, but we can’t control the player yet. So let’s add the code into the update() function, like this:

    override public function update():Void
    {
        // Automatically handle collision on each update
        FlxG.collide(player, level);

        // NOTE: For collisions to work, objects need to be moved
        // using physics, i.e. setting its velocity.

        // Assuming that no key was pressed, the default velocity
        // of the player will be zero on X and Y axis (no movement).
        player.velocity.x = 0;
        player.velocity.y = 0;

        // save key press booleans into variables for easy readability
        var pressLeft = FlxG.keys.anyPressed(["LEFT"]);
        var pressRight = FlxG.keys.anyPressed(["RIGHT"]);
        var pressUp = FlxG.keys.anyPressed(["UP"]);
        var pressDown = FlxG.keys.anyPressed(["DOWN"]);

        // If any of the buttons were pressed, set the velocity
        // accordingly.
        if (pressLeft) {
            player.velocity.x = -100;
        }
        if (pressRight) {
            player.velocity.x = 100;
        }
        if (pressUp) {
            // NOTE: negative velocity is upwards
            player.velocity.y = -100;
        }
        if (pressDown) {
            // NOTE: positive velocity is downwards
            player.velocity.y = 100;
        }

        // NOTE: the collision will NOT work if you update its position
        // directly rather than setting its velocity, such as the code below:
        // player.x += 5;

        super.update();
    }

override public function update():Void

{

// Automatically handle collision on each update

FlxG.collide(player, level);

// NOTE: For collisions to work, objects need to be moved

// using physics, i.e. setting its velocity.

// Assuming that no key was pressed, the default velocity

// of the player will be zero on X and Y axis (no movement).

player.velocity.x = 0;

player.velocity.y = 0;

// save key press booleans into variables for easy readability

var pressLeft = FlxG.keys.anyPressed(["LEFT"]);

var pressRight = FlxG.keys.anyPressed(["RIGHT"]);

var pressUp = FlxG.keys.anyPressed(["UP"]);

var pressDown = FlxG.keys.anyPressed(["DOWN"]);

// If any of the buttons were pressed, set the velocity

// accordingly.

if (pressLeft) {

player.velocity.x = -100;

}

if (pressRight) {

player.velocity.x = 100;

}

if (pressUp) {

// NOTE: negative velocity is upwards

player.velocity.y = -100;

}

if (pressDown) {

// NOTE: positive velocity is downwards

player.velocity.y = 100;

}

// NOTE: the collision will NOT work if you update its position

// directly rather than setting its velocity, such as the code below:

// player.x += 5;

super.update();

}

Great! Now if you test the game, you’ll be able to move the player and collide with the walls… but wait, you’re also colliding with the key, trap, and door. Why? Because all non-empty tiles (values other than -1) are automatically considered solid walls.

Since we already know how to replace the player tile with the player object, you can repeat the code for other objects. Let’s try to apply DRY (don’t repeat yourself) principle and modify our existing code, resulting in below:

package;

import flixel.FlxState;
import flixel.FlxG;
import flixel.tile.FlxTilemap;
import openfl.Assets;
import flixel.FlxSprite;
import flixel.util.FlxPoint;
import flixel.group.FlxGroup;

class MenuState extends FlxState
{
    var level:FlxTilemap;
    var player:FlxSprite;
    var interactables:FlxGroup;

    override public function create():Void
    {
        super.create();

        level = new FlxTilemap();
        var mapData:String = Assets.getText("assets/data/tutorial-map.csv");
        var mapTilePath:String = "assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png";
        level.loadMap(mapData, mapTilePath, 16, 16);
        add(level);

        // Initialise the objects first
        player = new FlxSprite();
        interactables = new FlxGroup();

        // Load the objects
        addObject(20, "player");
        addObject(10, "trap");
        addObject(32, "key");

        // Add the objects to the game scene
        add(interactables);
        add(player);
    }

    function addObject(tileIndex:Int, objectType:String):Void
    {
        // Instead of "addPlayer", we have a generic "addObject" function
        // that can be used to create different game objects accordingly.

        var objectCoords:Array<FlxPoint> = level.getTileCoords(tileIndex, false);
        for (i in 0...objectCoords.length)
        {
            var objectPoint:FlxPoint = objectCoords[i];
            var object = new FlxSprite(objectPoint.x, objectPoint.y);
            object.loadGraphic("assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png", false, 16, 16);
            object.animation.add("idle", [tileIndex]);
            object.animation.play("idle");

            switch (objectType)
            {
                case "player":
                    player = object;
                    break;

                case "trap", "key":
                    interactables.add(object);
                    break;

                default:
                    break;
            }
        }

        var objectTiles:Array<Int> = level.getTileInstances(tileIndex);
        var objectTile:Int = objectTiles[0];
        level.setTileByIndex(objectTile, -1, true); // remove player map tile
    }

    function onTouchItem(player:FlxSprite, item:FlxSprite):Void
    {
        trace("touched :  " + item);
    }

    override public function update():Void
    {
        // Automatically handle collision on each update
        FlxG.collide(player, level);
        FlxG.overlap(player, interactables, onTouchItem);

        // NOTE: For collisions to work, objects need to be moved
        // using physics, i.e. setting its velocity.

        // Assuming that no key was pressed, the default velocity
        // of the player will be zero on X and Y axis (no movement).
        player.velocity.x = 0;
        player.velocity.y = 0;

        // save key press booleans into variables for easy readability
        var pressLeft = FlxG.keys.anyPressed(["LEFT"]);
        var pressRight = FlxG.keys.anyPressed(["RIGHT"]);
        var pressUp = FlxG.keys.anyPressed(["UP"]);
        var pressDown = FlxG.keys.anyPressed(["DOWN"]);

        // If any of the buttons were pressed, set the velocity
        // accordingly.
        if (pressLeft) {
            player.velocity.x = -100;
        }
        if (pressRight) {
            player.velocity.x = 100;
        }
        if (pressUp) {
            // NOTE: negative velocity is upwards
            player.velocity.y = -100;
        }
        if (pressDown) {
            // NOTE: positive velocity is downwards
            player.velocity.y = 100;
        }

        // NOTE: the collision will NOT work if you update its position
        // directly rather than setting its velocity, such as the code below:
        // player.x += 5;

        super.update();
    }

    override public function destroy():Void
    {
        super.destroy();
    }
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

package;

import flixel.FlxState;

import flixel.FlxG;

import flixel.tile.FlxTilemap;

import openfl.Assets;

import flixel.FlxSprite;

import flixel.util.FlxPoint;

import flixel.group.FlxGroup;

class MenuState extends FlxState

{

var level:FlxTilemap;

var player:FlxSprite;

var interactables:FlxGroup;

override public function create():Void

{

super.create();

level = new FlxTilemap();

var mapData:String = Assets.getText("assets/data/tutorial-map.csv");

var mapTilePath:String = "assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png";

level.loadMap(mapData, mapTilePath, 16, 16);

add(level);

// Initialise the objects first

player = new FlxSprite();

interactables = new FlxGroup();

// Load the objects

addObject(20, "player");

addObject(10, "trap");

addObject(32, "key");

// Add the objects to the game scene

add(interactables);

add(player);

}

function addObject(tileIndex:Int, objectType:String):Void

{

// Instead of "addPlayer", we have a generic "addObject" function

// that can be used to create different game objects accordingly.

var objectCoords:Array<FlxPoint> = level.getTileCoords(tileIndex, false);

for (i in 0...objectCoords.length)

{

var objectPoint:FlxPoint = objectCoords[i];

var object = new FlxSprite(objectPoint.x, objectPoint.y);

object.loadGraphic("assets/images/tumblr_mh2mhude3E1qcptgwo1_250.png", false, 16, 16);

object.animation.add("idle", [tileIndex]);

object.animation.play("idle");

switch (objectType)

{

case "player":

player = object;

break;

case "trap", "key":

interactables.add(object);

break;

default:

break;

}

var objectTiles:Array<Int> = level.getTileInstances(tileIndex);

var objectTile:Int = objectTiles[0];

level.setTileByIndex(objectTile, -1, true); // remove player map tile

}

function onTouchItem(player:FlxSprite, item:FlxSprite):Void

{

trace("touched : " + item);

}

override public function update():Void

{

// Automatically handle collision on each update

FlxG.collide(player, level);

FlxG.overlap(player, interactables, onTouchItem);

// NOTE: For collisions to work, objects need to be moved

// using physics, i.e. setting its velocity.

// Assuming that no key was pressed, the default velocity

// of the player will be zero on X and Y axis (no movement).

player.velocity.x = 0;

player.velocity.y = 0;

// save key press booleans into variables for easy readability

var pressLeft = FlxG.keys.anyPressed(["LEFT"]);

var pressRight = FlxG.keys.anyPressed(["RIGHT"]);

var pressUp = FlxG.keys.anyPressed(["UP"]);

var pressDown = FlxG.keys.anyPressed(["DOWN"]);

// If any of the buttons were pressed, set the velocity

// accordingly.

if (pressLeft) {

player.velocity.x = -100;

}

if (pressRight) {

player.velocity.x = 100;

}

if (pressUp) {

// NOTE: negative velocity is upwards

player.velocity.y = -100;

}

if (pressDown) {

// NOTE: positive velocity is downwards

player.velocity.y = 100;

}

// NOTE: the collision will NOT work if you update its position

// directly rather than setting its velocity, such as the code below:

// player.x += 5;

super.update();

}

override public function destroy():Void

{

super.destroy();

}

Oops, I forgot about the door object, but you should get the rough idea by now. The code above isn’t complete, but it shows how we can parse the map objects manually, if you’re loading a single .CSV file.

There’s of course a better way to load map data, assuming you have multiple layers. Perhaps I’ll cover that in a separate tutorial next time.

In the meantime, you can check out HaxeFlixel’s official tutorial (Part 5), for a rundown on how to load OgmoEditor’s data file (which includes layers). StrandedSoft’s SHMUP tutorial (Part 2) also talks about loading TiledEditor’s TMX map data.

HaxeFlixel Tutorial – Loading Tile Map Data

March 8, 2015WY Leong 2 Comments

If you’ve checked out the Tiled Editor sample or the Tilemap sample, you’d know that HaxeFlixel has convenient libraries to parse Tiled map data.

Unfortunately, I couldn’t find any guide that explain how to do that in HaxeFlixel unless you study it, so here’s a post dedicated to that.

Before we proceed, here are some links to other tutorials that mentions about loading Tiled data in HaxeFlixel:

HaxeFlixel RPG Tutorial : Part 2
HaxeFlixel – A Beginner’s Guide (re: Part 3 – Moving Forward)
HaxeFlixel Tutorial: Building your first 2D Shoot-em-up, Part 2

Map Editors

Here is a quick list of possible editors you can use to create tile maps:

Tiled Map Editor – (Windows / OSX / Linux)
OgmoEditor (Windows)
PyxelEdit (Windows / OSX) – requires Adobe Air
DAME Editor (Windows / OSX / Linux) – requires Adobe Air for OSX/Linux

And here is a list of of sprite editors you can use to create tilesheet images:

Aseprite (Windows / OSX)
PyxelEdit (Windows / OSX)
GraphicsGale (Windows)
Pickle (Windows / OSX) – requires Adobe Air

I personally recommend Tiled Map Editor because it’s the most cross-platform, has lots of features, and it’s free.

My second choice is PyxelEdit; It works with Windows and OSX, it is a map editor that can also handle tiled creation and sprite animation. Unfortunately it’s not free, but you can try out its free Alpha version.

DAME Editor also looks like an interesting alternative but I have yet to experiment on it.

Load Map In HaxeFlixel

The easiest way to load tiled map data is from a text file, separated by commas or anything else — or otherwise known as CSV (character-separated values) files.

You can quickly create any simple CSV data file from Tiled Editor and proceed reading below. If you’re unsure of how, refer to the tutorial links above, like this one by StrandedSoft.

Let’s assume you’ve created a new HaxeFlixel template project. I’m going to use the template code from the cheat sheet for the MenuState.hx:

package;

import flixel.FlxState;
import flixel.FlxG;

class MenuState extends FlxState
{
    override public function create():Void
    {
        super.create();
    }

    override public function update():Void
    {
        super.update();
    }

    override public function destroy():Void
    {
        super.destroy();
    }
}

package;

import flixel.FlxState;

import flixel.FlxG;

class MenuState extends FlxState

{

override public function create():Void

{

super.create();

}

override public function update():Void

{

super.update();

}

override public function destroy():Void

{

super.destroy();

}

Now let’s add the following code:

package;

import flixel.FlxState;
import flixel.FlxG;
import flixel.tile.FlxTilemap;
import openfl.Assets;

class MenuState extends FlxState
{
    override public function create():Void
    {
        super.create();

        var tileMap:FlxTilemap = new FlxTilemap();
        var mapData:String = Assets.getText("assets/data/my-map-data.csv");
        var mapTilePath:String = "assets/images/my-map-tilesheet.png";
        tileMap.loadMap(mapData, mapTilePath, 16, 16);
        add(tileMap);
    }

    ...
}

package;

import flixel.FlxState;

import flixel.FlxG;

import flixel.tile.FlxTilemap;

import openfl.Assets;

class MenuState extends FlxState

{

override public function create():Void

{

super.create();

var tileMap:FlxTilemap = new FlxTilemap();

var mapData:String = Assets.getText("assets/data/my-map-data.csv");

var mapTilePath:String = "assets/images/my-map-tilesheet.png";

tileMap.loadMap(mapData, mapTilePath, 16, 16);

add(tileMap);

}

...

}

In order to load the map data, we only need two things: flixel.tile.FlxTilemap to handle the map creation logic, and openfl.Assets to load the .CSV data as string data.

Note: Make sure to put the .CSV file in the /data folder, and the tilesheet image in the /images folder, and the code above should work. You can check the API on how to use loadMap function.

Note 2: If the map data couldn’t be loaded, make sure the end of the data in the .CSV file is NOT an empty line. It happened to me and I spent an hour troubleshooting. 🙁

You can also load more complex data in HaxeFlixel, such as the original TMX file (the Tiled Editor’s project data format), with the help of flixel.addons.editors.tiled library. Unfortunately, the API page does not have much info on how to do that. I’ll try to cover that in a new post next time.

A Programming Devblog

Infrequent updates

Menu

Widgets

Search

map editor

HaxeFlixel Tutorial – Loading TMX Data

Setup

TMX Data Setup

Code

HaxeFlixel Tutorial – Parsing CSV Map Data

HaxeFlixel Tutorial – Loading Tile Map Data

Map Editors

Load Map In HaxeFlixel