How to write a custom Text File importer for Tiled Map Editor

Guide
1

Using the reference we will be writing a JavaScript extension for importing our tile-map in TextFile format.

Please read the Introduction in the reference for script writing and study the reference if you have an interest in what is going on here! https://doc.mapeditor.org/en/stable/reference/scripting/

Firstly you need your .txt file of columns and rows. This should be made of 0 and 1 characters, like this tiny and quick diagram of a Text File’s contents:

11111111
10100001
10101111
10000001
11100001
10001111
10100001
11111111

Note the width and height of this, as these are property values you will need later. This quick guide, for simplicity’s sake, is for a target TiledMap of a single layer and a Tileset consisting of 1 tile. You will need to change things to accomodate any other type of tilemap.

So prepare a .tsx file in Tiled Map Editor with at least 1 tile and note the filename with full path. Also note the height and width (in pixels) of tile.

Next we will start writing the JavaScript file for an extension. Extensions are loaded when the editor is started up. If you have any errors in your extension it will show up in the Tiled console, so fear not!

The code sections below are executed when you open your source TextFile or .txt, which is only possible because of the first part.

(I am practically splitting code sections, though it allows me to describe and comment to make this an effective guide.)

    var customMapFormat = {
        name = "Custom Text format",
        extension = "txt",

We are writing a custom map format definition, to be called later. The above section of code is describing to Tiled what file extension it should accept. This ensures when loading your map, the Load dialogue can switch to .txt and enables it to open your source TextFile.

    read: function(fileName) {
        var file = new TextFile(fileName, TextFile.ReadOnly);
        var map = new TileMap();
        map.setSize(<width>, <height>);
        map.setTileSize(<tileWidth>, <tileHeight>);
        map.orientation = TileMap.Orthogonal;

Here is the part that reads in the source TextFile by filename. It establishes a TileMap, along with it’s properties. You have those values already as per earlier, so replace them in the code. These are hard-coded in with our example just for brevity. You don’t actually need to add the orientation style, though be aware it defaults to orthogonal.

        var tileset = tiled.open(<tilesetFilenameWithPath>);
        if(tileset && tileset.isTileset) {
            map.addTileset(tileset);

This handy Tiled function opens your prepared tileset file and assigns it to the map.

Note: You might want to use inherent Tiled FileInfo functions so that you can use the fileName variable from the previous code section to point to the same directory, provided the tileset is in the same directory as your source TextFile. See reference https://doc.mapeditor.org/en/stable/reference/scripting/#fileinfo

            var layer = new TileLayer();
            layer.width = map.width;
            layer.height = map.height;
            layer.name = "Import";
            var layerEdit = layer.edit();

Inside the script we add a much needed layer. I’ve called it “Import” but you may want something different. The last line is creating an object for a function that will edit the layer.

            for (var y = 0; y < map.height; ++y) {
                var line = file.readLine();
                for (var x = 0; x < map.width; ++x) {
                    var tileID = parseInt(line.charAt(x), 10) - 1;
                    if(tileID >= 0) layerEdit.setTile( x, y, tileset.tile(tileID) );
                }
            }
            layerEdit.apply();
            map.addLayer(layer);
        }
        file.close();
        return map;
    }
}

Essentially, the for loops are parsing the 0 and 1 characters to the map, character by line - as tile number values by x,y coordinates. Though note how we subtract 1 from the parsed value. This means we are either grabbing a tile object using tileset.tile(tileID) with 0, being the first ID value in every Tileset, or leaving a blank space in the layer when parsing a -1.

After applying, the layer is added to the map. Very importantly, the source TextFile is closed. Then the map data is returned.

tiled.registerMapFormat("Custom Text", customMapFormat);

Add the above line to the script. This concludes the extension. Now save the file as .js in the “extensions” folder of Tiled. This is found in the following (default) location - C:\Users<User>\AppData\Local\Tiled\extensions

When you open Tiled, providing the script is valid, there should be no errors in the console readout and you will be able to open your source TextFile as a TileMap.

(Don’t forget your Tileset filename and path should be provided in the script.)

Exciting huh?

Credits for the code goes to @eishiya.