tilemap_set_mask

This function sets the Tile Map Bit Mask for a single tile map.

You give the tile map element ID (which you get when you create a tile map element using layer_tilemap_create or when you use the function layer_tilemap_get_id), and then the mask value. If you have, for example, a pretty small tile set of 16 x 16 tiles then you have a total of 256 different tiles in your tile set. You only need 8 bits of the  to index these tiles (from an available 19 bits of data). These bits can be "masked" and then the rest of the tile data can be used to store additional values. See Calculating the Mask Bits.

Tile map bit masking is an advanced feature and allows you to use bits of the tile data "blob" for your own use. For example, you could reserve a bit to mean "solid" in the tile data that can then be checked for fast collisions. Basically, the bit mask is "and"-ed against the tile data when the tile map is drawn (so it doesn't affect any of the other functionality), meaning that bits which aren't in the mask are ignored, but can still be read and written to by the user for their own purposes.

Syntax:

tilemap_set_mask(tilemap_element_id, mask);

Returns:

N/A

Example 1: Using 8 bits for the tile index

var _lay_id = layer_get_id("Tiles_sky");
var _map_id = layer_tilemap_get_id(_lay_id);
var _mask = tile_mirror | tile_flip | tile_rotate | 255;
tilemap_set_mask(_map_id, _mask);

The above code gets the tile map ID from the given layer and then sets the tile map bit mask to 8bits (a value of 255 or 0b11111111), preserving the flip, mirror, and rotate values for each tile in the map.

Example 2: Resetting to the default mask

var _lay_id = layer_get_id("Tiles_sky");
var _map_id = layer_tilemap_get_id(_lay_id);
var _mask = tile_mirror | tile_flip | tile_rotate | tile_index_mask;
tilemap_set_mask(_map_id, _mask);

The above code sets the tile bit mask to the value needed for GameMaker to draw tiles correctly by combining all tile mask constants using bitwise OR. The full 19 bits are used for the tile index and the mirror, flip and rotate bits are preserved.

Example 3: Writing and reading back custom data

Create Event

randomise();

var _lay_id = layer_get_id("Tiles_1");
var _map_id = layer_tilemap_get_id(_lay_id);
var _mask = tile_mirror | tile_flip | tile_rotate | 255;
tilemap_set_mask(_map_id, _mask);
for(var _x = 0;_x < tilemap_get_width(_map_id);_x++)
{
    for(var _y = 0;_y < tilemap_get_height(_map_id);_y++)
    {
        var _tdata = tilemap_get(_map_id, _x, _y);
        var _random_value = irandom(255);
        var _random_value_shifted = _random_value << 8;
        _tdata |= _random_value_shifted;
        tilemap_set(_map_id, _tdata, _x, _y);
    }
}

Step Event

var _tdata = tilemap_get_at_pixel(map_id, mouse_x, mouse_y);
random_value_under_cursor = (_tdata >> 8) & 255;

Draw GUI Event

draw_text(5, 5, $"Value: {random_value_under_cursor}");

The above code shows how to store some custom data in the cells of a tile map and read them back.

In the Create event the bit mask is set to be the 8 lowest bits plus the mirror, flip and rotate bits. A random integer value from 0 to 255 is then written to bit 8 to 15 of each tile. This is done as follows: the bits of _random_value are first shifted left by 8 bits, for example a value of 0b0000000011001111 (207) becomes 0b1111111100000000 (52992). This result is stored in _random_value_shifted. This value is then bitwise "or"-ed | with the tile data, which will result in a 1 bit whenever a bit is set in either the tile data or in the random value. The tile data is then written back to the same tile map call using tilemap_set.

In the Step event the tile data under the mouse is looked up using tilemap_get_at_pixel. To get the random value back out, the bits are first shifted right by 8 bits, which moves the 8 bits of the random value back to bit positions 0 to 7 (the index bits are also shifted right and so are lost at this point). This new value is then bitwise "and"-ed & with 255 to only keep the lower 8 bits that hold the random value (any of the mirror, flip or rotate bits may be set which, without "and"-ing would give a much higher value). The result is assigned to random_value_under_cursor.

The random value stored in the tile under the mouse position is displayed in the Draw GUI event.