08. Accessing Tiled Properties


This walkthrough will show how to directly access tile and object-layer tile properties.

So far we have used properties defined on tiles and object-layer tiles to create collision ( TileShapeCollection ) and entities ( Door ) using functionality provided by the Tiled plugin. While this functionality simplifies common tasks, some games require custom logic using Tiled properties.

Disabling Collision and Entity Creation

Before we access properties from our TMX file, we need to disable the automatic creation of collision and entities. We will disable collision so TileShapeCollection  visualization doesn’t get in the way of verifying that the code we’re about to write works properly. We need to remove code which automatically creates entities because any created entities replace the tiles we may want to access. To do this, comment the calls to create entities and collision from the GameScreen  CustomInitialize  call:

We also need to remove the collision code from CustomActivity  to avoid a NullReferenceException :

If we run the game we should no longer see the collision show up, nor should we see the circle from the Door entity:

Accessing Tiles by Name

Each layer in the the tile map can contain its own list of tiles. For performance reasons each tile is not an individual object. In other words, we can’t simply loop through a list of tile objects to check for certain properties.

Instead, we have to ask each layer for a list of indexes for a given name. Once we’ve obtained these indexes, we can get the tile positions and perform custom logic. For example, we can create green circles wherever we have a tile with the name "Wall" . First we’ll add a method to create the circles to GameScreen :

Next we’ll add a call to CreateCirclesForWallTiles  in our CustomInitialize  method:

If we run the game we will see green circles drawn on top of the wall tiles:

Warning: The purpose of the code above and much of the code in this guide is to show how to interact with tile properties at a low level. A realistic example would require additional code which would significantly increase the length of this tutorial. Keep in mind that the code above suffers from some serious problems. The created circles are not stored in a list so they cannot be used for any purpose aside from displaying on screen. Furthermore, since the circles are not stored in any list, they cannot be cleaned up. Exiting the screen or switching levels at this point would result in an exception.

Reading Custom Properties from Tiles

The Name property is built-in to the Tiled Plugin, but the plugin also supports reading custom properties. For example, we can modify the Wall tile to include a property for coloring the circle:

This property can be read through the level’s Properties . We’ll modify the code to define the color value and default it to Green . It will be set to Yellow  if the CircleColor  property is Yellow :

We obtain the circle color outside of any loops because the properties set on tiles in a tile set apply to the entire map, so the value will be the same regardless of layer or individual tile. For instance-specific properties we need to use objects on an Object Layer, as we’ll show later in this guide.

Now our game displays yellow circles:

Removing Tiles

Tiles can be removed dynamically removed using the RemoveQuads  method. For example, we can remove all of the wall tiles used to create circles:

Accessing Object Layer Properties

Tiles on “Object Layers” can contain instance-specific properties, as were used to create the Door instance in an earlier guide. We can also access these properties similar to how we access properties on tiles. In the case of our door-creating entity, we didn’t assign a Name property:

We have two options of obtaining a name for the tile object:

  1. Assign a name to the object in Tiled
  2. Find the objects by another property, such as the EntityToCreate property

We will use the 2nd method to create a Door entity, similar to how the entity is created when calling TileEntityInstantiator.CreateEntitiesFrom . First, we’ll add a method called ManualDoorCreation  to GameScreen :

Like before, we need to call this method in CustomInitialize :

Now our door tile will be removed and replaced by a Door  instance. Since our code uses the DoorFactory  object, our Door  instance is automatically added to the DoorList in GameScreen :