Tiled Maps

Access exported Tiled layers from LibGDX, convert map coordinates, and read or edit tiles through Pixscape Runtime.

Use api.tiled() from Java to access and edit Tiled layers exported with the current Pixscape scene. Runtime works with converted Pixscape data rather than loading the source TMX directly.

To bring a Tiled map into the project first, follow the Tiled TMX and TSX import guide.

Get a Tiled layer

The normal lookup uses the numerical layer index exported with the scene:

TiledLayerRef ground = api.tiled().requireLayerIndex(2);

The layer index is not an Artemis entity ID or a Studio display name. Studio display names are not Runtime layer identity.

When your game already stores another exported identity, you can use:

TiledLayerRef byEntity = api.tiled().requireEntityId(layerEntityId);
TiledLayerRef byStableId = api.tiled().requireStableId(layerStableId);

The require... methods expect a valid Tiled layer and throw if it is missing. The corresponding tolerant lookups—ofLayerIndex(...), ofEntityId(...), and ofStableId(...)—return a TiledLayerRef whose exists() can safely be false:

TiledLayerRef optional = api.tiled().ofLayerIndex(5);

if (optional.exists()) {
    // Use the layer.
}

layer(int) remains a strict compatibility convenience. Prefer requireLayerIndex(...) in new code.

A TiledLayerRef is the handle for one Runtime Tiled layer. It exposes map(), tiles(), spatial(), and tileAnimations(), plus its entity ID, stable ID, and existence state.

Inspect and control the map

The map facade provides dimensions and common layer controls:

int mapWidth = ground.map().width();
int mapHeight = ground.map().height();
int tileWidth = ground.map().tileWidth();
int tileHeight = ground.map().tileHeight();

ground.map()
        .setOrigin(0f, 0f)
        .setVisible(true)
        .setCollisionEnabled(true);

You can also inspect chunkSize(), chunksX(), chunksY(), projection(), and atlasTag(). setAtlasTag(...) changes the layer’s atlas tag; a blank tag selects main.

Convert world and tile coordinates

Use the two-coordinate overloads for code that works with either orthogonal or isometric maps:

int gx = ground.map().worldToTileX(worldX, worldY);
int gy = ground.map().worldToTileY(worldX, worldY);

if (ground.map().isInside(gx, gy)) {
    float wx = ground.map().tileToWorldX(gx, gy);
    float wy = ground.map().tileToWorldY(gx, gy);
}

isInside(...) also distinguishes a valid empty cell from coordinates outside the map.

Read and change tiles

Use tiles() for logical cell editing:

int currentAssetId = ground.tiles().get(10, 4);

ground.tiles().set(10, 4, grassAssetId);
ground.tiles().fillRect(20, 8, 6, 2, stoneAssetId);
ground.tiles().clear(15, 4);

For larger shapes, the facade also provides clearRect(...), hLine(...), and vLine(...). Out-of-bounds writes do nothing. Check map().isInside(...) when invalid coordinates should be handled explicitly.

Tile transform flags

Cells can store horizontal, vertical, and diagonal flip flags:

import games.pixscape.runtime.tiled.TileTransformFlags;

ground.tiles().set(
        5,
        5,
        grassAssetId,
        (byte) (TileTransformFlags.FLIP_H | TileTransformFlags.FLIP_V)
);

byte flags = ground.tiles().getFlags(5, 5);

The available constants are FLIP_H, FLIP_V, and FLIP_D. Pixscape handles their stored representation.

Place an animated tile

If an animated tile definition was exported or registered, place it by animation name:

ground.tiles().setAnimated(12, 8, "water_flow");

See Tiled Animation API for global definitions and per-cell playback controls.

Resize a map

ground.map().resize(200, 120);

Resizing is relatively expensive because it rebuilds the map’s Runtime chunks. Cells that remain inside the new bounds are preserved. Tile size, chunk size, and projection do not change.

Spatial altitude and height for a Tiled layer or individual cells are documented in Spatial API.