Search this manual

Tilemap APIs

Addon SDK v1 retirement

The built-in Tilemap plugin exposes the following APIs allowing manipulation of the tiles in the tilemap.

Tile numbers

Tiles in the tilemap are represented as a single 32-bit integer number and can be rotated and flipped. To support this they consist of two parts using a bitmask:

  • The tile ID in the lower 29 bits - this is the number of the tile as shown in the Tilemap Bar when hovering the tile
  • Tile flags in the upper 3 bits

There is also a special tile number -1 indicating an empty tile.

Tile flags

The Tilemap plugin exposes the following flags and masks which can be used to manipulate tile numbers:

C3.Plugins.Tilemap.TILE_FLIPPED_HORIZONTAL = -0x80000000;
C3.Plugins.Tilemap.TILE_FLIPPED_VERTICAL = 0x40000000;
C3.Plugins.Tilemap.TILE_FLIPPED_DIAGONAL = 0x20000000;
C3.Plugins.Tilemap.TILE_FLAGS_MASK = 0xE0000000;
C3.Plugins.Tilemap.TILE_ID_MASK = 0x1FFFFFFF;

For example, to flip tile ID 2 horizontally, you would use bitwise OR combining the tile ID and the flag, e.g. 2 | C3.Plugins.Tilemap.TILE_FLIPPED_HORIZONTAL. Similarly you can test if the bit is set using tile & C3.Plugins.Tilemap.TILE_FLIPPED_HORIZONTAL.

You can also use the masks to extract each component of the tile number. For example tile & C3.Plugins.Tilemap.TILE_ID_MASK will return just the tile ID, since it removes all the flag bits.

Tilemap instance APIs

GetTileWidth()
GetTileHeight()
Get the size of a tile in pixels.
GetMapWidth()
GetMapHeight()
Get the size of the tilemap in tiles.
GetTileAt(x, y)
Get the tile at a given position in tiles (i.e. (0, 0) is the top-left tile of the tilemap, regardless of the tilemap's position or the tile size). Returns -1 for empty tiles or tiles outside the tilemap; otherwise use bit operations to determine tile ID or flags separately.
SetTileAt(x, y, tile)
Set the tile at a given position in tiles. Use -1 to set a tile empty; otherwise use bit operations to combine the tile ID and flags.
Addon SDK Manual 2024-05-20