Tileset Editing with ImageMagick, jq, fish, CLion, and Pixelmator Pro

Also see Cataclysm-DDA/TILESET.md at 7e9b88943594a24e7ab9b5b6e97e3d4fd61fa49d · CleverRaven/Cataclysm-DDA · GitHub

So I love the HitButton_iso tileset. Probably as a result of being an '80s kid and growing up on Sinclair Spectrum and MS-DOS graphics. As the game progresses, there are some things that need to be added to the tileset.

I’ve attempted to add to it a few times. I’ve usually run out of gumption in the workflow itself. I think I’ve found a decent method now.

First of all, the big tileset image is hard to work with. I like splitting it up into a set of single-tile PNGs with ImageMagick’s convert tool: Cutting and Bordering -- IM v6 Examples

brew install imagemagick # install imagemagick on macOS
mkdir exploded
convert HitButton_iso.png -crop 16x20 exploded/%04d.png

Using a two-number {h}x{w} argument instead of four-number argument for position and size causes -crop to chop everything into tiles … the %04d is to get a four-digit number so it’s a little easier to keep the files sorted. This is what you end up with – images that have the same number as the fg/bg IDs in the tileset:

Now to find something that’s missing a tile. The game can be made to output this info when it loads the game data. Just for fun I just played until I found something that was missing a tile, e’x’amined it, and found its description. Then I use CLion to search through the game JSON to find it’s id, which is what the tileset uses. CLion is not necessary but I find its ergonomics to fit me well. Here we find a railroad station! Let’s do the gravel tile.

Let’s hop over to CLion and to command-shift-F to search through the project. Filter on *.json and search for the description of what you’re looking at. This tile is just described as “gravel”, so I search for "gravel" including the quotation marks. This can be a useful trick to anchor the search and narrow it down. Turns out the entity ID we’re looking for is "t_railroad_rubble". This is what needs to go into tile_config.json.

Are there any similar tiles that would work? Maybe the tiles for rubble and concrete can serve as inspiration. After searching through the JSON data we find those have the IDs f_rubble_rock and t_concrete. We can actually use that to look up the graphical tile IDs - the same as the fg/bg entires and the numbers of the single-tile filenames. I use jq and fish shell for that:

We’re looking for tiles 79 and 66. Let’s open those in Pixelmator Pro with some nice Fish magic: open -a Pixelmator\ Pro exploded/00{79,66}.png

Hmm, how about we trim down the rubble pixels that are higher than ground level? And, say, let’s overlay transparent concrete on top of that to chill the mood. Here we go – passable gravel?:

Now to give it a tile ID. I just do Save and scroll down to find a blank tile PNG, click its filename, and Save. This creates a Pixelmator-native file in the same place and name as the final PNG only with the .pxd extension. If I want to go back and edit. Then I command-E for 'E’xport. Pixelmator brings me to the same directory and export type as last time. Let’s save the tile PNG. We get tile ID 2498.

Here’s our tile file:

Now let’s pop this into the tileset JSON. Open it in CLIon and find a good place to add it. I tend to lose my windows so I like to do command-shift-O for ‘Open file’ and search for the path and filename and Enter to open it:

Select a similar block of JSON and command-D to 'D’uplicate it. Edit it to fit the entity id and tile info.

Now let’s go back in the game and do Reload Tileset. I’ve bound control-R to it.

Let’s reload!! Here we go:

Oh no! The tile is blank!

Ah … I forgot to rebuild the big tileset image. Let’s go back to ImageMagick:

montage -geometry +0+0 (find exploded -iname \*.png -type f | sort -h) -tile 16x160 -background none HitButton_iso.png

Let’s check our big tilemap! open HitButton_iso.png, scroll and zoom down. OK! It’s here:

Let’s teleport over. Hmm! Looks decent! Right? – Maybe a little noisy and pattern-y? Let’s reserve judgement until the train tracks are ready. We might want to add some variant tiles later too.

Let’s commit to Git and make a PR:


Untiled content is in debug.log in config folder.
Launch the game, set button for “Reload Tileset”, press said button, go to cataclysm folder/config/debug.log and scroll to bottom. You gonna see all IDs for untiled contend separated by categories. Then you can use Notepad++ or whatever to search for needed ID in cataclysm data folder.


Takes me back to my commadore 64 days.

1 Like

Thanks for this, this motivated me to get back to making my tileset xD plus now I’ll know how to track what’s done and what’s not!

1 Like

I’d be interested in contributing a bit to getting hitbutton updated too. I wonder if we could create a master list of missing tiles and work together


Hey yeah, great idea! I’ll try SomeDeadGuy’s method to get the missing tile log, and, uh, drop it in a Google doc maybe?

Here’s a Google Sheet with all that’s currently missing: https://docs.google.com/spreadsheets/d/1ktuKLIULaDHY-odEmvBoOJlkgi4npqjUQqacro1hJhE/edit?usp=sharing

Seems to be a lot of individual variants where a bunch of stuff can be represented with one tile.

For future conviniece add “vp_” to all vehicle parts in the list. This is how they should be in tileset_config.

1 Like

* fights … urge … to write … CMS … *

I’ve submitted PRs for long and tall grass tiles, and a sees-player mod. Both make a lot of difference for not a lot of work! Shows how neat the whole system is. The forest comes alive with the graduation of ever wilder grass. The sees-player stuff is a must!!!

What if i’m using windows?

1 Like

There’s probably a very similar workflow available!

I’m fairly sure that ImageMagick exists on Windows. It’s a very old and classic image processing library that’s used all over the place. It’s probably available through the Windows Linux subsystem for instance, or as a native-built Windows program. Chopping up the tiles is probably available in some other utilities too. It might be interesting to actually collect links on tools that can perform each of the steps.

Then CLion is cross-platform too.

I use Pixelmator Pro because it’s acceptable for pixel editing and is available on macOS. And I’m trying to not shell out for Photoshop just yet :slight_smile: I’m fairly sure that something better exists on Windows being as it’s a bigger gaming OS than macOS. Photoshop would imo be close to ideal.

That said, I’m getting a stronger and stronger sense for a viable way to write a little local web-app that captures most of the task of getting things into and out of the game data. There’s plenty of low hanging automation fruit at least. I kind of picture a searchable/live-filterable page that lists all the exploded tiles and what they’re used for. Then you can drag and drop into an image editing program. And drag and drop the finished tile back onto the page. (And then my ADHD-PI starts telling me very insistently that it should of course be inside the game itself rather than an inefficient external application, and that it should also be written in a cutting-edge programming language, and then of course we need to write a IntelliJ plugin to edit that language properly, and so on … So I wrest myself back to reality and doing things pixel-by-pixel.)

Fun: https://github.com/CleverRaven/Cataclysm-DDA/pull/31439

Please add a link to Cataclysm-DDA/TILESET.md at 7e9b88943594a24e7ab9b5b6e97e3d4fd61fa49d · CleverRaven/Cataclysm-DDA · GitHub at the start of the topic