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

Get the layer by its exported layer index, then use tileAnimations():

TiledLayerRef doors = api.tiled().requireLayerIndex(3);

int x = 12;
int y = 8;

doors.tiles().setAnimated(x, y, "door_open");
doors.tileAnimations().playOnce(x, y, true);

if (doors.tileAnimations().isFinished(x, y)) {
    // Opening animation finished.
}

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 actor, entity, or prefab when an object 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 the visual part of that object.

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