by Ter13
Fast, simple, abstract 47-state autojoining library
AutotileLib has been fully rewritten. This new version takes advantage of advances in the engine to provide more flexible joining that is easier to configure, and gives developers the power to choose when tiles will have their join flags updated. This is a full breaking change, so prepare to adapt your codebase to a new method of doing autotiles.

Autotile Properties:

turf.tile_id: tile_id is a text string that identifies the tile type. tile_ids are used to determine matches in autotile join rules.

turf.tile_joins: tile_joins contains the raw join state for this tile. 0 means no neighbors match, and 255 means that all 8 neighbors match.

turf.autotile: autotile can be null, causing this tile to not check for join matches with its neighbors. When set to a json array of tile_ids, any neighboring tile with a matching tile_id from this array will set a tile_join for that neighbor.

turf/autotile = @{"["grass","dirt","world"]"}

The above code snippet will cause the turf to tile with any turfs matching tile_id "grass", and "dirt". the "world" argument is special, allowing tiles to join with the edge of the world map. Do not set these values to a list(). AutotileLib will handle conversion of these values into lists automatically for you, and all tiles with the same autotile json will share the same autotile match list. This is much easier to set up than the global list in the old version, and much more flexible.

turf.autotile_type: the autotile_type will determine which autotile algorithm will be used for the tile's icon_state after its tile_joins are updated.
  • AT_256: Raw 256-state autotile joining
  • AT_47: Uses diagonal join reduction common to RPGMaker's autotile format.
  • AT_16: Disallows diagonal joins.
  • AT_WALL: Disallows diagonal or vertical joins.
  • AT_PILLAR: Diallows diagonal or horizontal joins.

Helper functions:

    turf/loc - where to place the new tile
    type - The turf type to place at the tile
    the turf that was created

This function will create a new tile of the specified type at the specified location, and then update the autotile joins of the created turf, and its 8 neighbors.

    x1, y1, z1 - the near corner of the block to retile.
    x2, y2, z2 - the far corner of the block to retile.
    fill_rate - how many tiles the function must retile before sleeping (defaults to AUTOTILE_FILL_RATE)
    cpu_limit - allows this function to take up this much of the world's cpu budget maximum before sleeping. (defaults to AUTOTILE_CPU_LIMIT)

This function will attempt to retile an entire block of tiles. This is useful for situations where you've loaded a chunk of the map and need to update the whole thing's autotile state, or to be called when the world first starts. The function tries to not throw the world into overtime and block ticks.


This function is called when the autotile_flags of a turf are updated in place_tile() or autotile_block(). It will perform the autotile type reduction algorithm and set the icon_state of the tile. You don't need to call this yourself, but it may be useful in some special cases to hook and extend its behavior.


Autotile join flags:
  • AT_NORTH (1)
  • AT_SOUTH (2)
  • AT_EAST (4)
  • AT_WEST (8)
  • AT_NORTHWEST (128)

Autotile join flags are used to determine which neighbor tiles create a join with this icon. You can override these values before importing autotilelib to change the join flag values globally.

Autotile type enum:
  • AT_256 (1)
  • AT_47 (2)
  • AT_16 (3)
  • AT_WALL (4)
  • AT_PILLAR (5)

Autotile types are used to do join state reduction on tiles to help determine the final icon state used by the tile. If a tile doesn't have an autotile_type, it will not change its icon_state due to join state updates.

Fill rate:

The fill rate definitions allow you to customize how fast autotilelib tries to fill in blocks of tiles. The fill rate determines the minimum number of tiles the autotile_block() function will attempt to join per tick, and the cpu_limit will determine how far into a tick the autotile_block() function can be until it begins to wait until the next frame to continue autotiling.


You can define this to change how the world's autotile initialization is done.

If this define is not set before autotile_lib is included, it will include the following code in your project:


If you need to load maps at world startup, or want to change how autotile initialization is handled, you'd just define AUTOTILE_INITIALIZE in your project to prevent this from happening.

Generating autotiles:

Autotile blanks must be in a DMI, and must be in this format:

This is a standard RPGMaker XP autotile format that's widely used across the web. The top-left tile is state 0, where nothing joins this tile. The top-right tile is all four join corners (state 15). The bottom group of 9 tiles are the outer edge states, the center of which is state 255.

This DMI can be animated using the DMI editor. The converter will preserve that animation in each individual tile.

Include the autotile library in your project and then compile and run the project in DEBUG mode.

The client verb GenAutotile() can be called from the command line. It will ask you to supply an icon to cut into the autotile47 format. It will perform the conversion and then ask you to save the resulting autotile icon somewhere on your hard drive. You can then use this icon file in your project.

Please note that this autotile library doesn't care about the tile size, so if you want to generate an autotile for a specific icon size, the icon must be exactly 3x4 tiles for that final icon size. You can cut up icons taller than your target autotile to create 3/4ths projection cubes too, but the formatting for that can be somewhat difficult to get right.

Supported formats:

AT_256 stores 256 unique states per autotile icon. This format will be used rarely.

(Image not available)

AT_47 stores 47 unique states per autotile icon.

AT_16 stores 16 unique states per autotile icon.

AT_WALL and AT_PILLAR both support 4 unique states per autotile icon.