How to convert a PNG into a Tilemap using CSV (png to tmx): The worst possible way

Guide
1

So! You made a color coded png to be used as a tilemap. However! The scripts used to convert said png into a tilemap have since been depreciated and nothing else seems to work, you can import it as a picture but that serves no functional purpose. Should you just give in and remake your map file in Tiled? I mean probably, but now there is another way!

We are going to take that map file (It needs to have the same dimension as the map you are importing to, the colors need to directly match up to your tile types, and you should convert it into a png [make sure the colors don’t get aliased, compressed, or otherwise changed whatsoever, looking at you jpg), convert it’s individual pixel values into a csv file, convert those big-ass pixel values into beautiful tile values, and add commas to the end of each line of the csv for good measure.

Step one! Get your tilemap png mistake! Find the dimensions, then download this old and frankly creepy software from this site I found https://www.avekt.com/en-us/Software/ImageCSV. Make absolutely sure that the colors are 1:1 with your planned tilesheet, if you aren’t sure use a photo editor like GIMP and bucket / color tool to make sure the colors are solid, and make corrections as needed.

Step two! Open A-VEKT Image CSV Converter, in that open your tilemap png, save as on said file, and under file type save as .csv.

Step three! Open this .csv in any application that has a find/replace function, use your context clues, go through and change every huge pixel value into a corresponding value for your tile map. The value for your tile map goes from left to right, then up to down, like words in a book. Refer to your tilemap, how it appears in tiled, or even a sample tilemap made in tiled with every tile in your tileset in order, preferably in the same dimensions as your original PNG (hint hint). Once every value has been replaced, add a comma to every single line except the last one. Save your csv and you are almost done!

Step four! After completing the previous step, create a new tilesheet in tiled with the same dimensions and tileset as corresponding to your png tilemap, edit this new tmx file in notepad or notepad++, and carefully replace the block of csv numbers in that file with the ones you created from the png using the converter. Make sure that the only thing that changes is the actual tile numbers, not the spacing, comma placement, or newlines or the file will read as corrupted in tiled and won’t load.

If your png tilemap shows up in tiled, success! Save it and go about editing it and tweaking it to your liking!

I really don’t expect this to get much traction but if I can help one poor soul who was in my situation it will be worth it, let me know if you want a tutorial in video form because like my methodology, this guide is the worst.

P.S. Please consider adding image to tile-map functionality to Tiled I saw it was something on your radar at some-point it would be pretty nice.

2

Some time ago, I wrote a Tiled script that reads in an image and converts it to tiles based on colour: tileID mappings.
Detailed instructions are in the comment at the top of the script, but the gist is you make a map with the tileset you want to use, add a custom property that lists which tile each colour in the image maps to and another one to tell the script which source image to use, and then run the script. There are some additional custom properties you can use to further control how the script works, detailed in the comment.

The script does fuzzy colour matching, so the colours don’t need to be 1:1, as long as they’re distinct enough from each other.

ImageToMap.js (9.2 KB)

3

Oooo I’m gonna try that out because ngl that sounds way better and from what I can see, it looks like it works with the current version of Tiled, thank you for sharing

4

This is perhaps not the brightest reply ever but how do you run custom scripts with Tiled? Can you please guide me. As per the JS script instruction, i added the user comment metadata of mapImage, but how do I run the JS script with tiled?

5

You need to put the JS script in either your project’s extensions directory, or into the global extensions directory, you can see more on that in the docs.

After the script loads, you can access the “Populate Map from Image” action via the Map menu.

6

Thanks a lot!

7

Look…Super stoked for this, but I read the instructions in the script and I’m lost. It mentions something about the extensions folder in the project but my projects in tiled are always files not folders, and the tiled install folder has a plugins folder not “extensions”. Would you mind providing a sort of ELI5 step by step? Certainly I’m missing some fundamental thing that is just assumed.

8

The Project folder is the folder where your Project file is located. Create an externsions folder in there and put the script there.

Alternatively, go to the global extensions location appropriate to your OS. It is not in the Tiled install directory. You can find the locations for each OS in the documentation: Scripting — Tiled 1.10.2 documentation

10

I was able to run the script. Thanks. I can stop banging my head against this wall and continue to use Tilesetter > Tiled > Godot as my workflow.

11

If you’re using Tilesetter, why do you need this script at all? This script is intended for situations where you have a colour-coded schematic map that you want to convert to some arbitrary tileset to polish further in Tiled. If your starting image is already made of tiles, there are better tools for this. Tilesetter itself can export to Godot, and if you need to do further editing in Tiled, Tilesetter’s JSON format sounds simple enough to write a Tiled custom format for. If that’s not an option for you, you can use a tileset extractor tool that can output to a Tiled format, such as this one.

12

Yeah…so…I figured this out the hard way. I kept running into issues exporting from Tilesetter to Godot only to find out on their discord that Godot 4 is not supported yet. My Godot freezes when trying to import exports from Tilesetter. I learned that I can just output a PNG and its not a big deal (for me) to manually add things like collisions and defining the tilesets further there. I was so confused about the issues I was having that I didn’t know what the issue was and I was obviously asking the wrong questions. I did however get your script to work only to find out it wasnt the solution I needed but I really appreciate you helping and joining me on this wild goose chase.

TL;DR You’re right.

1 Like