libgdx-tiled-maps

libGDX Tiled Maps

Quick reference for libGDX Tiled map integration (com.badlogic.gdx.maps.*). Covers loading, TiledMap structure, renderers, unit scale, object layers, properties, animated tiles, and collision extraction.

Loading

TmxMapLoader (synchronous)

// Direct loading (uses InternalFileHandleResolver by default)
TiledMap map = new TmxMapLoader().load("maps/level1.tmx");

// With parameters
TmxMapLoader.Parameters params = new TmxMapLoader.Parameters(); // 1.12.x
// BaseTiledMapLoader.Parameters params = new BaseTiledMapLoader.Parameters(); // 1.13.1+
params.textureMinFilter = Texture.TextureFilter.Linear;
params.textureMagFilter = Texture.TextureFilter.Linear;
TiledMap map = new TmxMapLoader().load("maps/level1.tmx", params);

AssetManager Loading (preferred)

assetManager.setLoader(TiledMap.class, new TmxMapLoader(new InternalFileHandleResolver()));
assetManager.load("maps/level1.tmx", TiledMap.class);
// ... assetManager.update() in render loop ...
TiledMap map = assetManager.get("maps/level1.tmx", TiledMap.class);

When using AssetManager, disposal is handled by assetManager.unload("maps/level1.tmx").

AtlasTmxMapLoader

Loads tiles from a TextureAtlas instead of separate tileset images. Reduces draw calls.

Requirements:

• TMX file must have a map-level property named atlas with the path to the .atlas file
• Atlas regions must be named after tilesets with indexes local to the tileset (not global tile IDs)
• Atlas must NOT use strip-whitespace or rotation

// Direct
TiledMap map = new AtlasTmxMapLoader().load("maps/level1.tmx");

// Via AssetManager
assetManager.setLoader(TiledMap.class, new AtlasTmxMapLoader(new InternalFileHandleResolver()));

Gotcha: Throws GdxRuntimeException("The map is missing the 'atlas' property") if the TMX lacks the atlas map property.

Parameters

Field	Type	Default	Purpose
flipY	boolean	true	Converts Tiled y-down to libGDX y-up
convertObjectToTileSpace	boolean	false	Divides object coords by tile dimensions
generateMipMaps	boolean	false	Generate mipmaps for tileset textures
textureMinFilter	TextureFilter	Nearest	Min filter for tileset textures
textureMagFilter	TextureFilter	Nearest	Mag filter for tileset textures