Tilemap script interface

The ITilemapInstance interface derives from IWorldInstance to add APIs specific to the Tilemap plugin.

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 script interface exposes the following flags and masks which can be used to manipulate tile numbers:

ITilemapInstance.TILE_FLIPPED_HORIZONTAL = -0x80000000;
ITilemapInstance.TILE_FLIPPED_VERTICAL = 0x40000000;
ITilemapInstance.TILE_FLIPPED_DIAGONAL = 0x20000000;
ITilemapInstance.TILE_FLAGS_MASK = 0xE0000000;
ITilemapInstance.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 | ITilemapInstance.TILE_FLIPPED_HORIZONTAL. Similarly you can test if the bit is set using tile & ITilemapInstance.TILE_FLIPPED_HORIZONTAL.

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

Tilemap APIs

The size of the tilemap, in tiles (read-only).
The displayed size of the tilemap, in tiles (read-only).
The size of a tile in pixels (read-only).
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.
Construct 3 Manual 2021-08-24