Tiled Animation API

Inspect exported Tiled animation definitions and control animated tile playback per cell from a LibGDX game.

Pixscape Runtime controls animated tiles exported with a scene from Java. Tiled animations have two parts:

• A global definition describes which frames make up an animated tile and how long each frame lasts.
• Per-cell playback describes what one particular map cell is doing now.

Cells using the same definition can pause, loop, play once, or finish independently.

Inspect global definitions

Global definitions are available through:

TiledAnimationsAPI animations = api.tiled().animations();

Look up an exported definition by name:

TileAnimationDefView def = animations.get("door_open");

if (def != null) {
    int id = def.id();
    int frameCount = def.frameCount();
    int firstFrameAssetId = def.frameAssetId(0);
    int firstFrameDurationMs = def.frameDurationMs(0);
}

get(...) accepts an animation name or asset ID and returns null when no definition exists. Use contains(...) when you only need an availability check.

To resolve a known name to its animation ID:

int animationId = animations.animationId("door_open");

animationId(...) throws IllegalArgumentException when the name is blank or unknown.

TileAnimationDefView is a short-lived view, not a permanent snapshot. Read the values you need and do not retain it across later API calls.

Register a definition at Runtime

Animations exported by Studio are already registered. Use put(...) only when game code needs to define or replace one at Runtime:

api.tiled().animations().put(
        100,
        new int[]{101, 102, 103},
        new int[]{100, 100, 100}
);

The first value is the animated tile asset ID. The arrays contain its ordered frame asset IDs and their durations in milliseconds.

The animated tile and every frame asset must be available for the scene. Add dynamically used resources to Runtime Availability before loading it.

Definitions can be removed by ID with remove(id). clear() removes all global definitions; there are no name-based put(...) or remove(...) overloads.

Control one animated cell

Resolve the Tiled Map by entity ID or stable ID, then use tileAnimations() for the playback state of one cell.

playOnce(x, y) starts at frame 0 and holds the last frame when complete. playOnce(x, y, holdLastFrame) lets you choose whether completion holds the last frame or returns to the same visual frame as stop(...).

Playback controls

• play(...) starts normal looping playback.
• playOnce(...) starts one-shot playback from frame 0.
• pause(...) keeps the current frame visible.
• stop(...) stops playback without removing the tile.
• restart(...) restarts the cell’s current playback mode from frame 0.

Queries and manual state

Use isAnimated(...), isPlaying(...), isPaused(...), and isFinished(...) to query playback. currentFrame(...) and elapsedMs(...) expose the current per-cell position.

For manual visual control, setFrame(...) selects a frame and setElapsedMs(...) changes elapsed time within it. Playback operations on a non-animated cell do nothing.

Keep gameplay state in game code

Tiled animation playback is intended for visual map state. Keep important gameplay timers and rules in your game code.

Use a normal entity or Game Object when something needs substantial behavior such as collision changes, locks and keys, sound timing, persistent/save-game state, complex interaction, or a changing Spatial footprint. A tiled animation can still provide its visual state.

See Tiled Animations in Studio for creating and editing the animated tile assets used here.

Code examples

Open a door from gameplay

Start the visual door animation on an application event, then observe completion from later game-loop frames.

private boolean doorOpening;

void requestDoorOpen() {
    TiledMapRef doors =
            api.tiled().requireStableId(doorsMapStableId);

    // The visual tile is authored in Tiled/Studio.
    doors.tiles().setAnimated(12, 8, "door_open");
    doors.tileAnimations().playOnce(12, 8, true);
    doorOpening = true;
}

void updateDoor() {
    TiledMapRef doors =
            api.tiled().requireStableId(doorsMapStableId);

    // This runs on a later frame after the one-shot has progressed.
    if (doorOpening && doors.tileAnimations().isFinished(12, 8)) {
        doorOpening = false;
        doorController.markOpen();
    }
}

doorController and doorOpening are application state. The one-shot holds its final frame; collision, keys, sounds, and persistent state stay in gameplay code.