In RPG-style games, using a simple Image as background quickly becomes insufficient. While SpriteCache offers performance benefits, developers familiar with tile-based design can leverage LibGDX's support for TiledMap through classes located in com.badlogic.gdx.graphics.g2d.tiled: TiledMap, TileAtlas, and TileMapRenderer.

Preparing a TiledMap Asset

Use Tiled Map Editor to design the map. Create a grid of 50×30 tiles with each tile sized at 32×32 pixels. Import tileset graphics, ensuring correct margin and spacing values—here, both set to 1 pixel according to source asset layout. Design the world layout visually, then save as a .tmx file. Process the file with gdx-tiled-preprocessor, which generates three additional files replacing older ones.

Loading and Rendering the Map

Iintialize components for rendering:

TiledMap levelMap = TiledLoader.createMap(Gdx.files.internal("assets/level.tmx"));
TileAtlas tileAtlas = new TileAtlas(levelMap, Gdx.files.internal("assets/"));
TileMapRenderer mapDrawer = new TileMapRenderer(levelMap, tileAtlas, 10, 10);

The last two arguments define how many tiles are cached horizontally and vertically; tune based on performance needs. Render via:

mapDrawer.render(camera);

Combining TiledMap with Scene2D Stage

Scene2D stages can coexist with tiled maps. Acquire the stage’s camera for map rnedering, update actors, then draw stage contents.

Core loop example:

Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
OrthographicCamera cam = (OrthographicCamera) stage.getCamera();
((Label) stage.getRoot().findActor("infoLabel")).setText("FPS: " + Gdx.graphics.getFramesPerSecond());
stage.act(Gdx.graphics.getDeltaTime());
mapDrawer.render(cam);
stage.draw();

Full implementation sketch:

public class GameApp implements ApplicationListener {
    private Stage uiStage;
    private TiledMap levelMap;
    private TileAtlas tileAtlas;
    private TileMapRenderer mapDrawer;

    @Override
    public void create() {
        levelMap = TiledLoader.createMap(Gdx.files.internal("assets/level.tmx"));
        tileAtlas = new TileAtlas(levelMap, Gdx.files.internal("assets/"));
        mapDrawer = new TileMapRenderer(levelMap, tileAtlas, 10, 10);

        float w = Gdx.graphics.getWidth();
        float h = Gdx.graphics.getHeight();
        uiStage = new Stage(w, h, true);

        Label info = new Label("FPS:", new LabelStyle(
            new BitmapFont(Gdx.files.internal("fonts/ui.fnt"), 
                          Gdx.files.internal("fonts/ui.png"), false),
            Color.BLACK), "infoLabel");
        uiStage.addActor(info);
        Gdx.input.setInputProcessor(uiStage);
    }

    @Override
    public void render() {
        Gdx.gl.glClear(GL10.GL_COLOR_BUFFER_BIT);
        OrthographicCamera cam = (OrthographicCamera) uiStage.getCamera();
        ((Label) uiStage.getRoot().findActor("infoLabel"))
            .setText("FPS: " + Gdx.graphics.getFramesPerSecond());
        uiStage.act(Gdx.graphics.getDeltaTime());
        mapDrawer.render(cam);
        uiStage.draw();
    }

    @Override
    public void dispose() { /* cleanup */ }
    @Override
    public void pause() {}
    @Override
    public void resume() {}
    @Override
    public void resize(int width, int height) {}
}

When integrating Stage with TiledMap, invoke stage drawing after map rendering to ensure proper layering. Camera movement within Stage will shift the visible portion of the map, simulating character mosion, but actor positions must be updated accordingly.

Before use, always preprocess .tmx files with TiledMapPacker, not TexturePacker, to produce compatible assets.