FlixelAnimateSprite

View source

class

org.flixelgdx.animation.FlixelAnimateSprite

public class FlixelAnimateSprite extends FlixelSprite

A FlixelSprite that renders Adobe Animate texture-atlas rigs. The three input files (spritemap1.png, spritemap1.json, Animation.json) are loaded through FlixelAnimateSprite.addSpritemapAndAnimation(String). The first call builds a rig with FlixelAnimateRigLoader; further calls merge additional Adobe exports into that rig automatically. Both nested symbol exports (Better Texture Atlas style with E.SI + SD.S) and flat document timelines (direct E.ASI keyframes) use the same API.

Rendering is fully data-driven by the rig: every draw call looks up the clip that the inherited FlixelAnimationController is currently playing, grabs the keyframe at FlixelAnimationController.getCurrentKeyframeIndex(), and walks the keyframe's pre-baked parts back-to-front. Every part carries a fully composed Affine2, so the inner loop is a single Affine2.setToProduct plus one Batch.draw(...) per visible bitmap.

Position, scale, rotation, color tint, flip, origin, offset, antialiasing, scroll factor, and facing all behave like a normal FlixelSprite loaded with a single graphic. The sprite's hitbox matches the anchor clip's bounding box scaled by FlixelAnimateSprite.getScaleX() / FlixelAnimateSprite.getScaleY(), so FlixelSprite.screenCenter() and Flixel.overlap(...) remain consistent with what the player sees.

Example

FlixelAnimateSprite fas = new FlixelAnimateSprite();
fas.addSpritemapAndAnimation(
    "path/to/atlas/spritemap1.png",
    "path/to/atlas/spritemap1.json",
    "path/to/animation/Animation.json");
fas.setScale(0.65f);
fas.setAntialiasing(true);
fas.updateHitbox();
fas.screenCenter();
fas.animation.playAnimation("Animation Name");
add(fas);

// If you group all of your atlas files in individual folders, you can
// also just provide a path to a folder and the paths will be automatically
// loaded for you!
FlixelAnimateSprite.defaultSpritemapFileName = "customSpritemapName";
FlixelAnimateSprite.defaultAnimationFileName = "customAnimationName";

FlixelAnimateSprite fas = new FlixelAnimateSprite();
fas.addSpritemapAndAnimation("path/to/atlas/folder");

Merging multiple atlases

Call FlixelAnimateSprite.addSpritemapAndAnimation(String) again with another export triple. Subsequent loads append frames to the shared atlas, bake clips into the existing anchor space (the body stays pinned when you switch atlases), and register clip names on the same FlixelAnimationController.playAnimation(String) path. Names from a later sheet override earlier registrations on collisions.

Mixing in a Sparrow atlas

A character can also carry Sparrow XML clips on the same body via FlixelAnimationController.addSparrowFrames(String). Rig clips keep rendering from the baked rig; clips registered against the merged Sparrow frames render through the standard frame path, and the sprite picks the right one per clip automatically.

See Also: .addSpritemapAndAnimation, .addSpritemapAndAnimation, FlixelAnimationController.addSparrowFrames, .defaultSpritemapFileName, .defaultAnimationFileName

Constructors

FlixelAnimateSprite()

public FlixelAnimateSprite()

Creates an empty sprite at (0, 0). Call FlixelAnimateSprite.addSpritemapAndAnimation(String) before using BTA rigs.

---

FlixelAnimateSprite(float, float)

public FlixelAnimateSprite(float x, float y)

Creates an empty sprite at the given world position. Call FlixelAnimateSprite.addSpritemapAndAnimation(String) before using it.

Parameters:

Name	Description
x	The x-coordinate of the sprite's position.
y	The y-coordinate of the sprite's position.

---

Fields

defaultSpritemapFileName

public static String defaultSpritemapFileName

The default file name for every spritemap .png / .json loaded with FlixelAnimateSprite.addSpritemapAndAnimation(String). Note that you shouldn't include an extension, as it's already handled for you. Default value is "spritemap1".

---

defaultAnimationFileName

public static String defaultAnimationFileName

The default file name for every animation .json data loaded with FlixelAnimateSprite.addSpritemapAndAnimation(String). When using this, you don't need to include .json at the end, as the loader does it for you. Default value is "Animation".

---

Methods

addSpritemapAndAnimation(String)

public FlixelAnimateSprite addSpritemapAndAnimation(String path)

Adds an Adobe Animate texture atlas from a single provided path.

This method is very useful if you have an exact location where all three core parts of an atlas are stored, and you just want to provide the path to it. Note that you can set the default file names of the default spritemap and animation data if you know what it's going to be every time!

Parameters:

Name	Description
path	The directory where all three core files are stored. Must be a directory.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If the provided path isn't a real directory.
NullPointerException	If either FlixelAnimateSprite.defaultSpritemapFileName or FlixelAnimateSprite.defaultAnimationFileName are null.

See Also: .defaultSpritemapFileName, .defaultAnimationFileName

---

addSpritemapAndAnimation(FileHandle)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle path)

Adds an Adobe Animate texture atlas from a single provided directory handle.

Equivalent to FlixelAnimateSprite.addSpritemapAndAnimation(String), but accepts a libGDX FileHandle for callers that already resolved the directory through a file resolver instead of holding a raw path.

Parameters:

Name	Description
path	The directory handle where all three core files are stored. Must be a directory.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If the provided path isn't a real directory.
NullPointerException	If either FlixelAnimateSprite.defaultSpritemapFileName or FlixelAnimateSprite.defaultAnimationFileName are null.

See Also: .defaultSpritemapFileName, .defaultAnimationFileName

---

addSpritemapAndAnimation(String, String, String)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, String spritemapJsonPath, String animationJsonPath)

Adds an Adobe Animate texture atlas (PNG plus spritemap JSON and Animation.json). If this sprite has no rig yet, FlixelAnimateRigLoader.load builds one and starts the anchor clip. If a rig is already installed, the same triple is merged with FlixelAnimateRigLoader.append. The anchorClipName argument is read only on the first successful load; it is ignored on merges.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, String, String)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, String spritemapJsonPath, String animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts textureKey as a FileHandle instead of a path string.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, FileHandle, String)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, FileHandle spritemapJsonPath, String animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts spritemapJsonPath as a FileHandle instead of a path string.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, String, FileHandle)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, String spritemapJsonPath, FileHandle animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts animationJsonPath as a FileHandle instead of a path string.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, FileHandle, String)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, FileHandle spritemapJsonPath, String animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts textureKey and spritemapJsonPath as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, String, FileHandle)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, String spritemapJsonPath, FileHandle animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts textureKey and animationJsonPath as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, FileHandle, FileHandle)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, FileHandle spritemapJsonPath, FileHandle animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts spritemapJsonPath and animationJsonPath as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, FileHandle, FileHandle)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, FileHandle spritemapJsonPath, FileHandle animationJsonPath)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts all three core parameters as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, String, String, String)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, String spritemapJsonPath, String animationJsonPath, String anchorClipName)

Adds an Adobe Animate texture atlas with an explicit anchor clip on the first load.

When no rig exists yet, anchorClipName selects the clip whose first keyframe defines the hitbox anchor and which autoplays after load; pass null (or a non-matching name) to use the first clip from the timeline (for document exports with no labels, this is the synthesized default clip). When merging into an existing rig, anchorClipName is ignored.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, String, String, String)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, String spritemapJsonPath, String animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts textureKey as a FileHandle instead of a path string.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, FileHandle, String, String)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, FileHandle spritemapJsonPath, String animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts spritemapJsonPath as a FileHandle instead of a path string.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, String, FileHandle, String)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, String spritemapJsonPath, FileHandle animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts animationJsonPath as a FileHandle instead of a path string.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, FileHandle, String, String)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, FileHandle spritemapJsonPath, String animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts textureKey and spritemapJsonPath as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, String, FileHandle, String)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, String spritemapJsonPath, FileHandle animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts textureKey and animationJsonPath as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(String, FileHandle, FileHandle, String)

public FlixelAnimateSprite addSpritemapAndAnimation(String textureKey, FileHandle spritemapJsonPath, FileHandle animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts spritemapJsonPath and animationJsonPath as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

addSpritemapAndAnimation(FileHandle, FileHandle, FileHandle, String)

public FlixelAnimateSprite addSpritemapAndAnimation(FileHandle textureKey, FileHandle spritemapJsonPath, FileHandle animationJsonPath, String anchorClipName)

Overload of FlixelAnimateSprite.addSpritemapAndAnimation(...) that accepts all three core parameters as FileHandles instead of path strings.

Parameters:

Name	Description
textureKey	The asset key of the spritemap PNG, as a file handle. Must not be null.
spritemapJsonPath	The path to the spritemap JSON, as a file handle. Must not be null.
animationJsonPath	The path to the animation JSON, as a file handle. Must not be null.
anchorClipName	Anchor clip name for the initial load only; ignored when appending. May be null.

Returns: this sprite, for chaining.

Throws:

Type	Description
IllegalArgumentException	If any file is missing, malformed, or not a recognized Adobe Animate export.

---

getRig()

public FlixelAnimateRig getRig()

---

setCurrentFrameForAnimation(FlixelFrame)

public void setCurrentFrameForAnimation(FlixelFrame frame)

Routes the controller's per-frame "current keyframe" callback to the right renderer.

When the clip that is playing is rig-backed we render directly from its pre-baked parts and never touch FlixelSprite.currentFrame, so we swallow the callback (and clear any leftover Sparrow frame so switching from a Sparrow clip to a rig clip does not flash stale art). For a Sparrow or simple-atlas clip the callback falls through to the normal FlixelSprite.setCurrentFrameForAnimation(FlixelFrame) path, which is what lets a Sparrow sheet merged with FlixelAnimationController.addSparrowFrames(String) share the same sprite as the rig.

Parameters:

Name	Description
frame	The frame being advanced to by FlixelAnimationController; ignored while a rig clip is playing.

---

updateHitbox()

public FlixelSprite updateHitbox()

Rebuilds the hitbox so it exactly matches the drawn rig. With a rig installed, the hitbox is the anchor bounding box scaled by FlixelAnimateSprite.getScaleX() / FlixelAnimateSprite.getScaleY(), so FlixelSprite.screenCenter() and Flixel.overlap(...) agree with what the player sees. Without a rig the parent behavior is used.

Unlike FlixelSprite.updateHitbox(), this method does not reset FlixelAnimateSprite.setScale(...) back to 1. The rig's part affines are baked at anchor-local size, so the absolute scale must remain on the sprite for the FlixelAnimateSprite.draw(FlixelBatch) matrix chain to size the visible rig correctly. The FlixelAnimateSprite.draw(FlixelBatch) method is fully aware of this and uses FlixelAnimateSprite.getOriginX() / FlixelAnimateSprite.getOriginY() together with |scaleX| / |scaleY| so the visible rig still coincides with the hitbox.

Returns: this sprite, matching FlixelSprite.updateHitbox().

---

setGraphicSize(int, int)

public FlixelSprite setGraphicSize(int width, int height)

Sets how large the rig is drawn on screen (in pixels) without changing the underlying anchor data. With a rig installed this divides the requested dimensions by the rig's anchor bounding box to derive the matching FlixelAnimateSprite.setScale(...), then calls FlixelAnimateSprite.updateHitbox() so the hitbox follows the new visual size. Without a rig, the parent behavior is used so plain atlas usage continues to work.

This is the recommended entry point when game code needs a character to occupy a fixed pixel size regardless of the resolution of the source export, because callers do not have to compute the anchor dimensions themselves or chain setScale + updateHitbox manually.

Parameters:

Name	Description
width	The drawn width in pixels (must be > 0).
height	The drawn height in pixels (must be > 0).

Returns: this sprite for chaining.

---

setAntialiasing(boolean)

public void setAntialiasing(boolean antialiasing)

Toggles texture filtering on the rig's spritemap (or the inherited FlixelSprite.currentFrame's texture when no rig is installed). Without this override, FlixelSprite.setAntialiasing(boolean) would be a no-op on a rig sprite because FlixelSprite.currentFrame is null while the rig is active.

Parameters:

Name	Description
antialiasing	true to use TextureFilter.Linear, false for TextureFilter.Nearest.

---

draw(FlixelBatch)

public void draw(FlixelBatch batch)

Draws the sprite. With a rig installed, walks the current clip's current keyframe and draws each part through the shared FlixelSpriteBatch with a preallocated Affine2. Without a rig (or with a non-sprite Batch), falls back to the inherited FlixelSprite draw path.

The rig draw composes the sprite's world transform once per frame as T(wx-offsetX, wy-offsetY) * T(originX, originY) * R(angle) * S(sx, sy) * T(-originX/|sx|, -originY/|sy|). The asymmetric origin (scaled-world units before the scale, anchor-local units after the scale) is what makes the rig's visible bounding box exactly coincide with the hitbox after FlixelAnimateSprite.updateHitbox() for any non-unit scale, while still pivoting rotations around the visual center. Per-part baked matrices are post-multiplied into this base, so rotation, scale, flip, origin, and offset all behave identically to a regular FlixelSprite.

Parameters:

Name	Description
batch	The active batch.

---

destroy()

public void destroy()

---