Tiled Maps API

Access Tiled Map entities from LibGDX, convert coordinates, and read or edit map cells through Pixscape Runtime.

A Tiled Map is a first-class scene entity. It lives in a normal Universal Layer alongside sprites, animations, lights, Game Objects, and other scene entities.

The owning Universal Layer provides general composition behavior such as Layer placement, visibility where applicable, parallax, and optional Spatial actor participation. Tiled-specific configuration belongs to the Map itself; parallax is not a Tiled Map property.

Runtime uses the converted Pixscape scene data rather than loading the source TMX directly. See the Tiled import guide for authoring and import.

Get a Tiled Map

Resolve a Map by its persistent stable ID when gameplay needs to find it again:

TiledMapRef map =
        api.tiled().requireStableId(mapStableId);

Use requireEntityId(...) when integrating with a known runtime ECS entity ID. The tolerant counterparts return a reference whose exists() can be false:

TiledMapRef optional = api.tiled().ofStableId(mapStableId);

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

The current lookup surface is:

api.tiled().ofEntityId(entityId);
api.tiled().ofStableId(stableId);
api.tiled().requireEntityId(entityId);
api.tiled().requireStableId(stableId);

A Layer index is not Map identity: one Universal Layer can contain several Maps. TiledMapRef exposes entityId(), stableId(), exists(), and four focused facades:

map()            Map properties and coordinate conversion
tiles()          Logical cell editing
spatial()        Map Spatial Depth and cell volumes
tileAnimations() Per-cell animation playback

References remain bound to the captured Map entity and become inert if it is removed or the Runtime World is replaced. See Entities and EntityRef for the shared identity model.

Inspect and control Map properties

map() owns Tiled-specific configuration and dimensions:

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

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

The facade also exposes chunk dimensions, projection, atlas tag, coordinate conversion, and resizing. setAtlasTag(...) selects the Map’s atlas tag; a blank tag resolves to main.

Collision enablement is Map-local. Disabling it removes that Map’s native Box2D body and fixtures while preserving authored Physics data and identities. Enabling it lets normal synchronization rebuild native state, and fails when the active scene explicitly has Physics disabled. It does not enable scene Physics or affect another Map.

Convert world and tile coordinates

Use the two-coordinate overloads for code that can work with orthogonal or isometric Maps:

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

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

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

Read and change cells

Use tiles() for logical cell editing:

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

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

The facade also provides clearRect(...), hLine(...), and vLine(...). Out-of-bounds writes do nothing; check map().isInside(...) when invalid coordinates need explicit handling.

Tile transform flags

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

import games.pixscape.runtime.tiled.TileTransformFlags;

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

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

Animated cells

Place a registered animated tile by name:

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

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

Resize a Map

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

Resizing rebuilds Runtime chunks. Cells that remain within the new bounds are preserved; tile size, chunk size, and projection do not change. Width and height must be positive.

Map Spatial Depth, default tile volume, and per-cell overrides are documented in Spatial API.

Imported Tiled Object Layers

Objects imported from a source Tiled Object Layer become ordinary Pixscape entities in a Universal Layer. Use api.entities() for their tags, custom properties, authored geometry, transforms, and animation:

EntityRef enemy = api.entities().requireTag("Enemy");

int health = enemy.properties().getInt("health", 100);
float speed = enemy.properties().getFloat("speed", 80f);

Object references are converted to stable entity IDs, and supported nested Tiled Class properties remain structured values. See Entities and EntityRef for the property API and the Studio import guide for supported source-TMX scopes.

Open a passage

Resolve the authored Map by stable identity, then clear its cells:

TiledMapRef walls =
        api.tiled().requireStableId(wallsMapStableId);

walls.tiles().clear(18, 7);
walls.tiles().clear(19, 7);

Collision and progression rules remain application gameplay responsibilities.