Tile map

A Tile Map is a component that allows you to assemble, or paint, tiles from a Tile Source onto a large grid area. Tile maps are commonly used to build game level environments. You can also use the Collision Shapes from the tile source in your maps for collision detection and physics simulation (example).

Before you can create a tile map you need to create a Tile Source. Refer to the Tile Source manual to learn how to create a Tile Source.

Creating a tile map

To create a new tile map:

  • Right click a location in the Assets browser, then select New... ▸ Tile Map).
  • Name the file.
  • The new tile map automatically opens in the tile map editor.

    new tilemap

  • Set the Tile Source property to a tile source file that you have prepared.

To paint tiles on your tile map:

  1. Select or create a Layer to paint on in the Outline view.
  2. Select a tile to use as brush (press Space to show the tile palette)


  3. Paint with the selected brush. To erase a tile, either pick an empty tile and use it as brush, or select the eraser (Edit ▸ Select Eraser).

    Painting tiles

You can pick tiles directly from a layer and use the selection as a brush. Hold Shift and click a tile to pick it up as the current brush. While holding Shift you can also click and drag to select a block of tiles to use as a larger brush.

For clockwise brush rotation, use Z. Use X for horizontal flipping and Y for vertical flipping of the brush.

Picking tiles

Adding a tile map to your game

To add a tile map to your game:

  1. Create a game object to hold the tile map component. The game object can be in a file or created directly in a collection.
  2. Right-click the root of the game object and select Add Component File.
  3. Select the tile map file.

Use tile map

Runtime manipulation

You can manipulate tilemaps in runtime through a number of different functions and properties (refer to the API docs for usage).

Changing tiles from script

You can read and write the content of a tile map dynamically while your game is running. To do so, use the tilemap.get_tile() and tilemap.set_tile() functions:

local tile = tilemap.get_tile("/level#map", "ground", x, y)

if tile == 2 then
    -- Replace grass-tile (2) with dangerous hole tile (number 4).
    tilemap.set_tile("/level#map", "ground", x, y, 4)

Tilemap properties

Apart from the properties Id, Position, Rotation and Scale the following component specific properties exist:

Tile Source
The tilesource resource to use for the tilemap.
The material to use for rendering the tilemap.
Blend Mode
The blend mode to use when rendering the tilemap.

Blend modes

The Blend Mode property defines how the component graphics should be blended with the graphics behind it. These are the available blend modes and how they are calculated:

Normal blending: src.a * src.rgb + (1 - src.a) * dst.rgb
Brighten the background with the color values of the corresponding pixels of the component: src.rgb + dst.rgb
Darken the background with values of the corresponding pixels of the component: src.rgb * dst.rgb
Opposite of Multiply. Brighten background and values of the corresponding pixels of the component: src.rgb - dst.rgb * dst.rgb

Changing properties

A tilemap has a number of different properties that can be manipulated using go.get() and go.set():

The tile map tile source (hash). You can change this using a tile source resource property and go.set(). Refer to the API reference for an example.
The tile map material (hash). You can change this using a material resource property and go.set(). Refer to the API reference for an example.

Material constants

The default tilemap material has the following constants that can be changed using go.set() or go.animate() (refer to the Material manual for more details). Examples:

go.set("#tilemap", "tint", vmath.vector4(1,0,0,1))
go.animate("#tilemap", "tint", go.PLAYBACK_LOOP_PINGPONG, vmath.vector4(1,0,0,1), go.EASING_LINEAR, 2)
The color tint of the tile map (vector4). The vector4 is used to represent the tint with x, y, z, and w corresponding to the red, green, blue and alpha tint.

Project configuration

The game.project file has a few project settings related to tilemaps.