Animations API

Spawn Pixscape sprite animations from Java, switch animations and clips, and control playback in a LibGDX game.

api.animations() is the Java entry point for spawning registered Pixscape animations and controlling animated entities.

AnimationsAPI animations = api.animations();

Spawn and play an animation

Spawn by registered animation name:

AnimationRef hero = api.animations().spawn("hero-run", 120f, 64f)
        .play("run")
        .loop(true);

You can also spawn by the registered animation’s asset ID:

AnimationRef hero = api.animations().spawn(42, 120f, 64f);

The animation must be a registered Pixscape animation definition. A plain atlas image with the same name or ID is not enough.

AnimationRef provides the common spawn-time controls. It also exposes entity(), transform(), sprite(), animation(), and shader() when you need the complete facades.

Control an existing entity

Get the animation facade from an EntityRef:

EntityRef player = api.entities().requireTag("player");

player.animation()
        .play("run")
        .setLoop(true);

api.animations().get(player) returns the same facade.

Playback

AnimationFacade animation = api.animations().get(player);

animation.pause();
animation.restart();
animation.setFps(18f);
animation.setStateTime(0.5f);

Use play(), pause(), stop(), and restart() for playback. setLoop(...), setFps(...), and setStateTime(...) adjust its current state. A frame rate of 0 is allowed and does not advance the animation.

Clip selection

setClip(name) selects a clip and resets its frame and playback time without starting playback. play(name) selects the clip, resets it, and starts playback.

Playback queries

Use clip(), hasClip(...), frame(), stateTime(), and fps() to inspect the current animation. Playback state is available through isPlaying(), isLooping(), and isFinished():

AnimationFacade animation = player.animation();

if (!animation.isLooping() && animation.isFinished()) {
    animation.play("idle");
}

isFinished() becomes true when a non-looping clip has completed. Looping clips do not report finished.

Change animation

An authored entity can own more than one animation. Switch among those animations by ID or name:

player.animation().setAnimation("hero-attack");
player.animation().play("hero-attack", "heavy");

setAnimation(...) restores the selected animation’s authored default clip and FPS. It preserves whether playback was running and whether it was looping. play(animation, clip) switches to the requested animation and starts that clip.

The target animation must be registered, available for the scene, and owned by the entity. If an animation or clip is invalid, the call throws IllegalArgumentException and leaves the previous animation state unchanged.

Inspect animation metadata

Use definition(...) to inspect a registered animation without spawning it:

AnimationDefinition heroRun = api.animations().definition("hero-run");

float authoredFps = heroRun.fps();
int frameCount = heroRun.frameCount();
boolean hasRun = heroRun.hasClip("run");

The definition also provides assetId(), name(), currentClip(), and clipCount(). Resolve definitions again after loading another project.

Make animations available

Animations created or selected by gameplay must be registered and their visual assets must be available for the current scene. Add animations used only from code to Runtime Availability before export.

spawn(...) does not create a definition from an atlas asset and does not load missing resources during gameplay.

See Animations in Studio for visually authoring animations and named clips before export.