# TileMapDual: a Godot plugin that autotiles across square, isometric and hex grids

> TileMapDual is a Godot editor plugin that turns a TileMapLayer into a dual-grid autotiler, cutting the tiles you need to draw from 47 to 15 and redrawing the corner pieces as you paint, with support for isometric and hex layouts.

**pablogila/TileMapDual** — An automatic, real-time dual-grid tileset system for Godot

- Repository: https://github.com/pablogila/TileMapDual
- Stars: 1,305 · Forks: 60
- Language: GDScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/pablogila-tilemapdual

## The dual-grid idea, and the tile count it saves

TileMapDual is an automatic custom TileMapLayer node for Godot that provides a real-time, in-editor and in-game dual-grid tileset system for all kinds of grids, square, isometric and hex.

The dual-grid system, as explained by Oskar Stålberg, reduces the number of tiles required from 47 to just 15. That is the entire pitch and it is a big one, because the 47-tile count is what a conventional autotile needs to cover every combination of edges and corners that can meet.

The advantage comes from splitting the drawing into two layers. One grid holds the terrain shape, the other holds the visual, and the plugin recombines them. The listed benefits follow from that split. Only 15 tiles are required for autotiling instead of 47. The tiles can have perfectly rounded corners, because the corner rounding is a property of the visual layer rather than something the shape layer has to encode. And the tiles align to the world grid, which matters when the shape layer is what gameplay code queries.

There is a further reduction available. If your tiles are symmetrical, you can get away with drawing only 6 tiles and then generate the 15-tile tilesets used by TileMapDual, thanks to tools like Wang Tile Set Creator. Six tiles is a genuinely small amount of artwork for a terrain system that covers rounded corners and every edge combination.

The plugin is MIT licensed, the default branch is main, the last push was on 2026-09-03, and there are no published GitHub releases, so the version you get is the tip of the branch. It is written in GDScript, and the repository root has the addons directory, a docs directory, an examples directory, a project.godot for the plugin's own test project, and an assets directory.

## Installing it as a Godot plugin

There is no package manager step. TileMapDual is installed as a regular Godot plugin: copy the addons/TileMapDual folder to your Godot project, and enable it on Project, Project settings..., Plugins.

That is the whole install, and it is worth noting what it implies. There is no version pinning through a package manager, so the copy is the version you get, and an upgrade is another copy. For a plugin that the project itself describes as having been fully rewritten in v5, that is a detail worth keeping in mind.

The plugin ships with its own project file and an examples directory, so you can open the repository in Godot and see the plugin working before you install it into anything of your own. The example scenes cover the range of what the plugin does: AllShapes.tscn, CustomDrawingSprites.tscn, Hexagonal.tscn, Isometric.tscn, Jess.tscn, MultipleAtlases.tscn, MultipleLayers.tscn, Random.tscn and Shaders.tscn, plus a rotating_light.gd script.

That scene list is a good map of the feature set. MultipleAtlases and MultipleLayers are about how the plugin composes its two layers from different sources. CustomDrawingSprites is about the visual layer not being a plain tileset. Shaders and Random are about the plugin working with unusual rendering. And Jess is presumably named after the person whose terrain art the demo uses.

The documentation is largely in the form of videos and images linked from the README, with the first video in the FAQ and troubleshoot section being the one the hex grid section points you at for configuration. The docs directory at the root holds the images and the icon, so the visual reference material is in the repository rather than on a separate site.

## Drawing a level, and what updates in real time

The node is loaded the same way as a regular TileMapLayer node, so nothing changes in your scene tree conventions. You create a TileMapDual node with your own tileset, and set it up with the appropriate tile shape and orientation.

Then you sketch. You start with the fully-filled tile, and you can also sketch with the empty tile in the bottom-left corner, or erase tiles as usual. The dual grid updates in real time as you draw, which is the part that makes the plugin pleasant rather than merely correct. The demo GIF in the README shows exactly this, a level being painted and the corner pieces rearranging as you go.

The erasing case is the one that catches people out with conventional autotiling, and it is worth knowing how the plugin handles it. A conventional autotiler recomputes the neighbourhood of a cell when you erase, but the neighbouring cells around the erased one may also need to change, and the ordering of those updates is a classic source of flicker. Because the plugin recomputes the whole dual grid rather than a single cell, that class of bug does not apply.

The reference images in the docs directory show the standard square tileset template, the isometric variant, and the dual-grid reference diagram that explains how the two grids correspond. The standard template is a 15-tile layout, and the isometric version is an isometric-ed version of that same template, which is what makes the isometric case work without a separate art pipeline.

For the isometric case the project suggests two routes. You can draw the isometric tileset by hand, or you can use TileCropper, a Godot plugin by the same author that lets you draw the tiles in one continuous image and then separates them afterwards. The second route is the practical one for anyone who does not want to work tile by tile.

## Two layers for more terrains, and two spritesheets for collisions

Two of the configuration decisions in the README are workarounds for the limits of a two-layer design, and knowing them upfront saves a lot of confusion.

The first is terrain count. To use more than two terrain types, it is highly encouraged to use multiple TileMapDual layers. So the dual grid handles exactly two layers, one for one terrain and one for another, and a third terrain means a third node. The MultipleLayers.tscn example scene is there to show it working. The cost is that each additional layer is a separate node whose tilesets have to be kept in sync, and the benefit of the single-layer design, that everything composites in one pass, is lost as the layer count grows.

The second is collision and gameplay data. To include extra data like collisions and pathing to your TileSet, it is recommended to use 2 separate spritesheets: one for displaying the tiles, the display tiles, and one for program logic, the world tiles. The reasoning is that the display layer needs the visual treatment, with the rounded corners and the variant art, while the logic layer needs a stable, regular grid for queries, and a single spritesheet cannot serve both cleanly.

Once set up that way, you can put hitboxes on the display tiles and logic such as pathing on the logical tiles. That separation is what makes the two-layer model pay off in a real project, because gameplay code reads the logical grid and never has to reason about a variant that happens to be drawn in the corner.

The FAQ section adds the practical detail about shapes and offsets. The plugin supports all the different tile shapes, layouts and offset axes, and the README walks through them with common mistakes and their corresponding fixes. If your spritesheet does not follow the standard preset layout, you can set the terrains manually, and there is a walkthrough for a Hexagonal Vertical tileset. You can also safely switch to a different tileset if you need to, which is a separate walkthrough in the same section.

## The v5 rewrite and the legacy node

TileMapDual v5 was fully rewritten from the ground up, and the project ships a bridge for people caught mid-transition.

If you encounter issues, the instruction is to report them on GitHub, and to make the transition from v4 to v5 smoother, a custom TileMapDualLegacy node is available within the v5 version, containing the stable version from v4.0.3. The limit on that fallback is explicit: the legacy version only supports square and isometric grids.

So the hex support, which the announcement highlights as one of the headline features of v5, is not available in the legacy node. If your project is on v4 with a hex grid, you have to move to v5 rather than wait.

The v5 discussion issue on GitHub is where the details live, and the README points at it both for the announcement and for how v5 works under the hood. The announcement also asks for contributions, noting the current issues and inviting pull requests.

The maintenance picture is straightforward. The repository is not archived, the last push was on 2026-09-03, and there are no published GitHub releases, so version tracking is by branch. The plugin is managed by pablogila as the first developer and raffimolero since v5, and the README credits code contributors and issue contributors, with a note that the plugin would not be the same without its users.

For an adopter, the practical sequence is to read the v5 discussion, then try the plugin in a scratch project using the example scenes, then port your existing tileset. The last step is the one where the tileset layout matters, since a non-standard spritesheet can be set up manually with the terrains set by hand, but the standard templates are the path of least resistance.

## Conclusion

TileMapDual fits a Godot developer who is hand painting tile-based levels and wants the corner pieces to sort themselves out, and it fits one who supports more than one grid projection in the same project, since the same plugin handles square, isometric and hex. It is a poor fit if you need more than two terrain types on one layer, since the recommended answer is a second layer rather than a feature, and a poor fit if you need collision data baked into the same tileset, since the documented approach splits display and logic spritesheets. Before adopting, check the shape and orientation settings for your grid in the FAQ video and the example scenes, and read the v5 discussion issue, because v5 was a full rewrite.

## FAQ

### What is TileMapDual and what does it do in Godot?

TileMapDual is a custom TileMapLayer node for Godot that provides a real-time, in-editor and in-game dual-grid tileset system for square, isometric and hex grids. It reduces the tiles needed for autotiling from 47 to 15 by splitting the terrain shape and the visual into two layers.

### How do I install TileMapDual in a Godot project?

Copy the addons/TileMapDual folder to your Godot project and enable it under Project, Project settings..., Plugins. There is no package manager step, so the copy is the version you get, and an upgrade means copying again.

### How do I use more than two terrain types with TileMapDual?

The project recommends multiple TileMapDual layers, since the dual grid handles two. Each additional terrain means another layer node whose tilesets have to be kept in sync, and the MultipleLayers.tscn example scene shows the arrangement.

### How do I add collisions and pathing to a TileMapDual tileset?

Use two separate spritesheets, one for displaying the tiles and one for program logic, then put hitboxes on the display tiles and pathing logic on the logical tiles. The plugin supports all the different tile shapes, layouts and offset axes, and terrains can be set manually if your spritesheet does not follow the standard preset layout.

### What is the TileMapDualLegacy node for?

TileMapDual v5 was rewritten from the ground up, and a TileMapDualLegacy node is included in the v5 version containing the stable v4.0.3 code to smooth the transition. The legacy node only supports square and isometric grids, so hex grids have to move to v5.

## Sources

- [Issues](https://github.com/pablogila/TileMapDual/issues)
- [License: MIT](https://github.com/pablogila/TileMapDual/blob/main/LICENSE)
- [pablogila/TileMapDual on GitHub](https://github.com/pablogila/TileMapDual)
- [README](https://github.com/pablogila/TileMapDual/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pablogila-tilemapdual