FlixelAnimationController
View sourceclass
org.flixelgdx.animation.FlixelAnimationController
Playback state and clip registration for FlixelSprite animations. Obtain a controller with FlixelSprite.ensureAnimation() (or assign one directly), then call sprite.ensureAnimation().addSparrowAtlas(...), .playAnimation(...), etc. Decouples animation timing from rendering and physics.
Optionally link a FlixelAnimationStateMachine via FlixelAnimationController.setStateMachine(FlixelAnimationStateMachine) so the machine is ticked automatically inside FlixelAnimationController.update(float) - no separate machine update call would be needed in your game loop.
Mixing in a Sparrow atlas
A character can also carry Sparrow XML clips on the same body via FlixelAnimationController.addSparrowFrames(String), allowing a single sprite to contain multiple Sparrow sheets with unique animations.
Constructors
FlixelAnimationController(FlixelSprite)
Creates a new animation controller for the given sprite.
Parameters:
| Name | Description |
|---|---|
owner | The sprite that owns this animation controller. |
Fields
onFrameChanged
Dispatched when the visible keyframe index changes.
onAnimationFinished
Dispatched once when a non-looping clip reaches its end, or when looping is turned off at end.
Methods
getOwner()
The sprite that owns this controller. Package use includes spritemap loading helpers.
loadSpritemapFromJson(String, String, String)
Adobe/CreateJS spritemap plus animation index JSON. See FlixelSpritemapJsonLoader.load(...) for file shapes.
Parameters:
| Name | Description |
|---|---|
textureKey | Asset key of the already-enqueued FlixelGraphic. |
spritemapJsonPath | Path resolved like other assets (internal or classpath). |
animationJsonPath | JSON with an animations object. |
Returns: The owning sprite for chaining.
addSparrowFrames(String)
Loads or merges a Sparrow atlas onto the owning sprite from a single base path, inferring the conventional .png and .xml file names shared by a Sparrow export. For example, passing "shared/images/foo" loads the texture from "shared/images/foo.png" and the atlas data from "shared/images/foo.xml".
When the sprite has no atlas yet, this installs the sheet as the primary atlas, sizes the sprite to the first frame, and clears any previously registered clips. When the sprite already has an atlas (either from a prior call or from an Adobe Animate rig), this appends the new sheet's frames without disturbing the existing ones, so a single sprite can carry clips from multiple sheets.
sprite.ensureAnimation().addSparrowAtlas("shared/images/foo");
sprite.animation.addAnimationByPrefix("idle", "idle", 24, true);
sprite.animation.playAnimation("idle");
Parameters:
| Name | Description |
|---|---|
path | The base path, without a file extension, shared by the PNG and XML pair. |
Returns: The owning sprite for chaining.
See Also: .addSparrowFrames
addSparrowFrames(FileHandle)
Overload of FlixelAnimationController.addSparrowFrames(String) that accepts the base path as a FileHandle.
Parameters:
| Name | Description |
|---|---|
path | The base path handle, without a file extension, shared by the PNG and XML pair. |
Returns: The owning sprite for chaining.
addSparrowFrames(String, String)
Loads or merges a Sparrow atlas onto the owning sprite from an explicit texture key and XML path. See FlixelAnimationController.addSparrowFrames(String) for the full load/merge contract.
Parameters:
| Name | Description |
|---|---|
textureKey | The asset key of the Sparrow PNG. Must not be null. |
xmlPath | The path to the Sparrow XML. Must not be null. |
Returns: The owning sprite for chaining.
Throws:
| Type | Description |
|---|---|
IllegalArgumentException | If either file is missing or malformed. |
addSparrowFrames(String, FileHandle)
Overload of FlixelAnimationController.addSparrowFrames(String, String) that accepts the XML as a FileHandle.
Parameters:
| Name | Description |
|---|---|
textureKey | The asset key of the Sparrow PNG. Must not be null. |
xmlFile | The Sparrow XML file, read as UTF-8. Must not be null. |
Returns: The owning sprite for chaining.
addSparrowFrames(String, Element)
Overload of FlixelAnimationController.addSparrowFrames(String, String) that accepts a pre-parsed XML root.
Parameters:
| Name | Description |
|---|---|
textureKey | The asset key of the Sparrow PNG. Must not be null. |
xmlRoot | The root TextureAtlas element of a Sparrow XML. Must not be null. |
Returns: The owning sprite for chaining.
parseSparrowFrames(Texture, Element)
Parses Sparrow SubTexture entries into a fresh frame list without installing them on any sprite.
This is the shared parsing core used by FlixelAnimationController.addSparrowFrames(String). Keeping it separate lets callers inspect or transform the frame list before passing it to FlixelSprite.applySparrowAtlas(FlixelGraphic, Array<FlixelFrame>) or FlixelSprite.mergeSparrowAtlas(FlixelGraphic, Array<FlixelFrame>).
Parameters:
| Name | Description |
|---|---|
texture | The backing texture the regions are cut from. |
xmlRoot | The root TextureAtlas element of a Sparrow XML. |
Returns: A newly allocated list of frames, one per valid SubTexture.
clear()
Clears all clips, per-animation offsets, and resets playback state.
addOffset(String, float, float)
Registers a per-animation pixel offset, applied to the owning sprite's offset every time that clip starts.
A Sparrow atlas keeps each frame planted within its own untrimmed source box, but different clips are usually authored on differently sized canvases, so their anchors do not line up when you switch between them. Nudge each clip by a hand-tuned amount so they all share a common ground line. The offset is added to the draw position, so positive x moves the graphic right and positive y moves it up (matching FlixelSprite.setOffset(float, float)).
The feature is opt-in. Until the first addOffset call the controller never touches the sprite's offset; afterwards it owns it, and playing a clip with no registered offset resets the offset to (0, 0). Avoid mixing manual FlixelSprite.setOffset(float, float) with this API.
var anim = sprite.ensureAnimation();
anim.addAnimationByPrefix("idle", "BF idle dance", 24, true);
anim.addAnimationByPrefix("singLEFT", "BF NOTE LEFT", 24, false);
anim.addOffset("idle", 0, 0);
anim.addOffset("singLEFT", -12, 6);
anim.playAnimation("idle"); // offset snaps to (0, 0)
Parameters:
| Name | Description |
|---|---|
name | The animation name, as registered with one of the addAnimation* methods. |
x | Horizontal offset in pixels (positive moves the graphic right). |
y | Vertical offset in pixels (positive moves the graphic up). |
removeOffset(String)
Removes a previously registered per-animation offset.
Parameters:
| Name | Description |
|---|---|
name | The animation name to clear the offset for. |
clearOffsets()
Removes every registered per-animation offset without affecting the registered clips.
hasOffset(String)
Parameters:
| Name | Description |
|---|---|
name | The animation name to check. |
Returns: true if a per-animation offset is registered for name.
centerOffsets()
Equivalent to FlixelAnimationController.centerOffsets(boolean) with adjustPosition set to false.
centerOffsets(boolean)
Centers the owning sprite's hitbox within its current frame's untrimmed source box.
This is useful when a trimmed Sparrow frame draws smaller than the hitbox set by FlixelSprite.updateHitbox(float, float) (or vice versa), since the art would otherwise sit off-center inside the box.
This is a one-shot computation from the currently displayed FlixelFrame, independent of the per-animation registry; it does not read or write FlixelAnimationController.animationOffsets. Calling it after a clip with a registered offset will overwrite that offset until the next FlixelAnimationController.playAnimation(String) call reapplies it.
Parameters:
| Name | Description |
|---|---|
adjustPosition | Whether to also shift the sprite's position so its origin stays anchored to the frame's center, matching HaxeFlixel's optional position correction. |
pause()
resume()
isPaused()
getPaused()
Returns whether animation playback is currently paused.
reverse()
Toggles playback direction. Time still advances by FlixelAnimationController.update(float) while not paused.
getPlayDirection()
setPlayDirection(int)
addAnimationByPrefix(String, String, int, boolean)
Adds an animation to the controller by prefixing the frame names.
Parameters:
| Name | Description |
|---|---|
name | The name of the animation. |
prefix | The prefix of the frame names. |
frameRate | The frame rate of the animation. |
loop | Whether the animation should loop. |
addAnimationFromAtlas(String, int[], float, boolean)
Adds a clip from the current atlas list FlixelSprite.getAtlasRegions() using zero-based indices into that list. Used by spritemap JSON and by games that know frame order after a Sparrow or spritemap load.
Parameters:
| Name | Description |
|---|---|
name | Clip name for FlixelAnimationController.playAnimation(String). |
atlasFrameIndices | Indices into the atlas list (out-of-range entries are skipped). |
frameDuration | libGDX frame duration in seconds (reciprocal of FPS). |
loop | Whether the clip loops. |
addAnimation(String, int[], float)
Adds an animation to the controller by specifying the frame indices.
Parameters:
| Name | Description |
|---|---|
name | The name of the animation. |
frameIndices | The indices of the frames to add. |
frameDuration | The duration of each frame. |
playAnimation(String)
Plays the animation with the given name. Loops and restarts the animation by default.
Parameters:
| Name | Description |
|---|---|
name | The name of the animation to play. |
playAnimation(String, boolean)
Plays the animation with the given name. Restarts the animation by default.
Parameters:
| Name | Description |
|---|---|
name | The name of the animation to play. |
loop | Whether the animation should loop. |
playAnimation(String, boolean, boolean)
Plays the animation with the given name.
Parameters:
| Name | Description |
|---|---|
name | The name of the animation to play. |
loop | Whether the animation should loop. |
forceRestart | Whether the animation should restart. |
isAnimationFinished()
getAnimationFinished()
Returns whether the current animation has finished playing (only meaningful for non-looping animations).
update(float)
getAnimations()
getStateTime()
getCurrentAnim()
getCurrentKeyframeIndex()
Zero-based key index in the current clip. Computed from FlixelAnimationController.getStateTime() and the controller's looping flag rather than from the underlying libGDX Animation's PlayMode, so the index always matches what FlixelAnimationController.update(float) actually displays no matter how the clip was registered.
For non-looping playback that has already finished, this returns the last keyframe index (keyframeCount - 1). For looping playback, it returns the wrapped index inside [0, keyframeCount). Useful for multi-part BTA/texture-atlas characters driven outside a single-frame texture (for example FlixelAnimateSprite).
Returns: The current keyframe index. Always >= 0.
isLooping()
getLooping()
Returns whether the current animation is set to loop.
getStateMachine()
Returns: The linked FlixelAnimationStateMachine, or null if none is set.
setStateMachine(FlixelAnimationStateMachine)
Links a FlixelAnimationStateMachine to this controller so it is ticked automatically by FlixelAnimationController.update(float). Pass null to detach a previously linked machine.
This is the recommended way to drive an FSM: link it once and update only the sprite each frame. The machine still works independently if you prefer to call its own FlixelAnimationStateMachine.update(float) by hand - just do not link it here.
var fsm = new FlixelAnimationStateMachine(player);
player.ensureAnimation().setStateMachine(fsm);
// From now on player.update(elapsed) advances both the controller and the FSM.
Parameters:
| Name | Description |
|---|---|
stateMachine | The machine to auto-tick, or null to clear the link. |