Introduction

The LayeredTileMap object is the runtime type for the TMX file format (the native file format for Tiled). Whenever a TMX file is added to FlatRedBall, it will (by default) be loaded into a LayeredTileMap at runtime. The LayeredTileMap represents a collection of MapDrawableBatches. It contains one MapDrawableBatch per layer in the source TMX file. The LayeredTileMap class inherits from FlatRedBall.PositionedObject so it can be moved and attached to other PositionedObjects. Each MapDrawableBatch is attached to its parent LayeredTileMap, and can be moved independently by changing its RelativePosition.

Common Usage

The easiest way to use a TMX file is to create a standard GameScreen and Level. This can be accomplished using one of the following methods:

1. Run the Wizard when creating a new project - this will automatically add TMX files to your project.

   Existing (empty) projects can also run the wizard through the Quick Actions tab.
2. Create a GameScreen and Level screens and check the options for creating TMX files.

Manually Adding a MapDrawableBatch From TMX to a Screen

If you are not using the GameScreen/Level pattern, you can add your own TMX files to Screens manually. To add a LayeredTileMap from an existing TMX:

1. Create a TMX file in Tiled

2. Save the TMX file in a location relative to your game's content folder. Be sure that all PNG files and TSX files (tileset files) are also relative to the game content folder

3. Create a game screen

4. Drag+drop the TMX file into your Screen's Files folder

No additional code is necessary - your map will now show up in the screen.

Creating Entities From a TMX

If using the GameScreen/Level pattern, FlatRedBall will automatically set up a Map object which can be used to create entities. If you are creating your own map object manually and you would like to create entities from this map, a small amount of extra work is needed.

Creating a Map object for Entity Creation in Glue

Once you have a TMX file in your screen's Files folder, you can create a Map object by drag+dropping the TMX onto the Screen's Objects folder.

Once the Map object has been created, its Create Entities From Tiles property can be checked.

LayeredTileMap as a list of MapDrawableBatches

The LayeredTileMap is mostly a List of MapDrawableBatches. For example, you can print out information about a MapDrawableBatch as follows:

string information = "This map has " + TestLevel.MapLayers.Count + " layers\n";

foreach (var layer in TestLevel.MapLayers)
{
    information += "Number of verts: " + layer.Vertices.Length + "\n";

}

Introduction

Destroy method fully removes the LayeredTileMap from the engine. Specifically this method performs the following:

• Removes the LayeredTileMap from the engine's DrawableBatch list (removes it from being rendered)

• Removes all TileShapeCollections that have been created when the LayeredTileMap was loaded

• Removes any ShapeCollections created by shapes included in the LayeredTileMap

• Removes this object from being managed by the engine (if the map uses velocity, acceleration, or other every-frame variables)

This method is automatically called if the LayeredTileMap is loaded from a TMX in generated code, but must be called manually if the map is created manually in custom code.

Code Example

The following code destroys the calling LayeredTileMap:

LayeredTileMapInstance.Destroy();

The Collisions object is a List<TileShapeCollection>. When a LayeredTileMap is created (usually from TMX), each tile layer is checked for tiles with shapes. If any tiles on a layer contain shapes (defined in the Tileset), then a TileShapeCollection will be created for that layer. If tiles have shapes defined, but do not have a Type defined, then the name of the TileShapeCollection matches the name of the layer. If a tile defines a type, then the TileShapeCollection will be named after the Type.

Note that this is populated from the shapes added to tiles in the tileset, as opposed to the ShapeCollections object which is populated based on shapes added to object layers.

Introduction

FromTiledMapSave loads a TMX file into a LayeredTileMap. This method populates all internal properties including the LayeredTileMap's Layers and Collisions properties. Internally this method loads necessary PNG files using the argument contentManager.

Typically this method is called in generated code by adding a TMX file to a Level screen in the FlatRedBall Editor.

Tile Layer Format

TMX files can be converted to LayeredTileMaps if they are using any of the following Tile Layer Formats:

• Base64 (uncompressed)

• Base64 (gzip compressed)

• Base64 (Zstandard compressed)

• CSV

Note that Base64 zlib compressed can be used, but to do this you must:

1. Add a reference to the Ionic.Zlib.Core nuget package

2. Add SUPPORTS_ZLIB to your precompile directives

Using an unsupported compression format will result in a runtime error:

Does not support zlib, try using GZIP compression or csv format

Introduction

The Z value of a LayeredTileMap controls the order that it is drawn relative to other objects such as FlatRedBall Entities. Each layer (MapDrawableBatch) on the LayeredTileMap is drawn at one Z value greater than the layer under. For example, consider a map with layers shown in the following image:

Assuming the map's Z value is set to 0, then the layers will have the following Z values:

• GameplayLayer Z = 0

• AboveLayer1 Z = 1

• AboveLayer2 Z = 2

Shift Map to Move Gameplay Layer to Z0

The Map object (the default LayeredTileMap when using a wizard setup) provides the option to shift the map's Z value so the GameplayLayer's Z is at 0. If this option is checked, then any layer above GameplayLayer has a positive Z value and draws on top of entities at Z = 0. Similarly, if this option is checked then any layer below GameplayLayer has a negative Z value and draws under entities at Z = 0.