The Aseprite tilemap mode I wish I had learned in year one

I built the entire first version of Quiet Frame without ever using Aseprite's tilemap mode. I drew every tile as a single sprite, exported it as a separate PNG, and stitched them together inside Godot. It worked, but it was 90 minutes of fiddly export busywork every time I revised a tileset.

Then Aseprite v1.3 shipped tilemap mode and I ignored it for nine months because the documentation made it look like a niche feature for terrain auto-tiling. It is not a niche feature. Once I understood what it actually does, it became the single most valuable feature in the program for level work.

This is the post I wish I had read in year one.

The mental model

In normal Aseprite, a layer is a grid of pixels.

In tilemap mode, a layer is a grid of tile references, each of which points into a tileset stored on the side. When you paint on a tilemap layer, you are not painting pixels — you are placing tile-IDs into a grid.

Two consequences fall out of this:

1. If you edit a single tile in the tileset, every instance of that tile across every map updates automatically. No re-export, no Godot reimport, no nothing.
2. If two map cells happen to contain the same visual content, they refer to the same tile-ID. You never accidentally end up with three subtly-different versions of "grass with a rock".

If you have used a level editor like Tiled or LDtk, this is the same model — except now your map editor and your sprite editor are the same program. The round-trip is gone.

The four kinds of tilemap layer

Aseprite distinguishes four tileset-painting modes:

• Manual. You explicitly pick a tile from the tileset palette and place it. Best for set-piece details, signs, doors.
• Auto. Painting on the canvas creates new tiles in the tileset on demand. Best when you are still designing the tileset and want to throw pixels at the canvas without thinking about indices.
• Stack. Like Auto, but if you paint a tile that's visually identical to an existing tile, Aseprite re-uses the existing tile-ID instead of creating a new one. This is the mode you almost always want.
• Pixel-perfect / Manual + brush. A combination mode for retouching tiles in place without changing their tile-IDs.

Stack mode is the default in v1.3 and it should be. It gives you the visual freedom of "just paint" with the storage efficiency of "tile IDs are reused when content matches".

The tagging system that changed how I work

In v1.3.4, Aseprite added user-defined tags on tiles. A tile can carry an arbitrary string like solid, water, slope_left_45, breakable. When you export the tileset, the tags come out as JSON.

This means my levels in Aseprite contain everything Godot needs to build the physics for them. No separate "collision mask" PNG, no per-tile config in Godot, no spreadsheet of which tile-IDs are solid. The Godot importer reads the JSON and assigns collision shapes based on the tags. The whole feedback loop is: paint a tile in Aseprite, tag it solid, save, switch to Godot, the wall is now solid.

I tag using a tiny convention I've settled on:

• solid — a full collision box
• slope_NN where NN is the angle (slope_45, slope_22r for 22.5° rising-right)
• oneway — you can jump up through it but not fall through
• water — trigger the swim state
• ladder — trigger the climb state
• damage_NN — touching it deals NN damage
• noted_NN — my own bookmark for tiles I want to come back and refine

This vocabulary is small enough that I can keep it in my head and large enough that I have not needed to extend it in the eighteen months I've been using it.

The 600-tile environment problem

For Quiet Frame's second area I built an environment with around 600 distinct tiles. At that size, a flat tileset palette becomes unusable — you spend more time scrolling for the right tile than placing it.

Aseprite handles this with multiple tilesets per file, one per tilemap layer. My pattern:

   Layer name                Tileset           Tiles
   ─────────────────────────────────────────────────
   bg_sky                    sky               18
   bg_mountains              mountains         42
   midground_buildings       buildings         156
   foreground_terrain        terrain           204
   foreground_props          props             89
   foreground_details        details           91

Each layer's painting palette only shows its own tileset, so when I'm placing windows on buildings I see 156 building tiles, not the 600-tile soup. Switching layers is one keystroke.

The smart-tile feature is where it gets uncanny

Smart-tile mode is Aseprite's auto-tiling. You define a small set of "edge" tiles (eg, "this tile is a grass-to-dirt transition on its right edge") and Aseprite figures out which transition tile to place when you draw adjacent grass and dirt.

I will not pretend smart-tile mode is easy to set up. The first time you do it, expect to spend an evening on the Wang-tile rules you need to express. But once it's set up for a terrain, painting massive areas of varied terrain becomes the click-and-drag experience that you remember from Warcraft II's map editor. It is genuinely magical.

For my Quiet Frame terrain I have smart-tile rules for grass/dirt, dirt/stone, stone/water, water/sand, and sand/grass. That's five rule sets covering five terrain pairs and they handle every reasonable transition the game will ever need.

What still doesn't quite work

Multi-layer smart-tiles. Smart-tile rules operate within a single layer. If you want a piece of grass on the foreground layer to auto-tile against a piece of stone on the midground layer, you cannot. You have to either flatten the two layers (and lose the parallax) or define manual transition tiles.

Sharing tilesets across files. You can import a tileset from another .aseprite file, but it's a copy — subsequent changes don't sync. For a shared "props" tileset used across ten levels, this is annoying. I work around it by keeping the props in a single canonical file and re-importing when they change, but a proper "linked tileset" feature would be welcome.

Performance with very large maps. A 200×200-tile map starts to feel a touch sluggish in v1.3.4 on my M2 Air. Aseprite is not Tiled and never claimed to be; for huge maps I still drop into a dedicated tool. But for the 80×80 areas that make up most platformers, performance is fine.

Where to start

If you have never used tilemap mode and your project has any kind of tile-based environment, do this:

1. Make a new Aseprite file with the canvas size of one full screen of your game (eg, 320×180).
2. Layer → New Tilemap Layer. Tile size: 16×16 (or whatever your sprite scale is).
3. Painting mode: Stack.
4. Just paint a level. Don't worry about the tileset palette — it'll fill itself as you go.

Twenty minutes in, you'll have built a level and an organically-sized tileset, and the answer to "should I be using tilemap mode?" will be obvious.

If you want sample files to learn from, I've put a couple of the Quiet Frame tilemaps on GitHub for anyone who wants to poke at them. The forest_03.aseprite file in particular has a fairly complete smart-tile setup that's worth reverse-engineering.