FlixelSprite
View sourceclass
org.flixelgdx.FlixelSprite
The core building block of all FlixelGDX games. Extends FlixelObject with graphical capabilities including texture rendering, scaling, rotation, tinting, and flipping.
Frame-based clips, Sparrow/XML atlases, and playback use a FlixelAnimationController that is not allocated by default (saves memory for large sprite counts on the order of thousands of extra sprites before overhead dominates). Call FlixelSprite.ensureAnimation() or assign a controller directly when you need clips, then use sprite.ensureAnimation().addSparrowAtlas(...), .playAnimation(...), etc.
It is common to extend FlixelSprite for your own game's needs; for example, a SpaceShip class may extend FlixelSprite but add additional game-specific fields.
Constructors
FlixelSprite()
Constructs a new FlixelSprite with default values.
FlixelSprite(float, float)
Constructs a new sprite at the given position.
Parameters:
| Name | Description |
|---|---|
x | The X coordinate to place the new sprite at. |
y | The X coordinate to place the new sprite at. |
FlixelSprite(float, float, String)
Constructs a new sprite at the given position with a loaded graphic.
Parameters:
| Name | Description |
|---|---|
x | The X coordinate to place the new sprite at. |
y | The X coordinate to place the new sprite at. |
Fields
graphic
Graphic backing this sprite (shared/cached wrapper around a Texture).
atlasFrames
The atlas frames used in this sprite (used for animations).
secondaryGraphics
Extra FlixelGraphic handles retained when additional spritesheets are merged onto this sprite, so those atlases' textures stay loaded for the sprite's lifetime. The primary graphic is still tracked by the FlixelSprite.graphic field; this list only holds graphics appended after the initial load, for example through FlixelSprite.mergeSparrowAtlas(FlixelGraphic, Array<FlixelFrame>) or an appended Animate rig atlas. Lazily allocated to avoid the per-instance footprint for sprites that only ever load one atlas.
animation
Heavy controller object for handling animations. null until FlixelSprite.ensureAnimation() or assigned directly.
currentFrame
The current frame that this sprite is currently using for drawing.
frames
Where all the image frames are stored. This is also where the main image is stored when using FlixelSprite.loadGraphic(FileHandle).
scaleX
Horizontal scale factor. 1 = normal size.
scaleY
Vertical scale factor. 1 = normal size.
originX
X component of the rotation/scale origin point.
originY
Y component of the rotation/scale origin point.
offsetX
The offset from the sprite's position to its graphic.
offsetY
The offset from the sprite's position to its graphic.
color
The color tint applied when drawing this sprite.
facing
The direction this sprite is facing. Useful for automatic flipping.
antialiasing
Whether this sprite is smoothed when scaled.
flipX
Whether this sprite is flipped horizontally.
flipY
Whether this sprite is flipped vertically.
Methods
ensureAnimation()
Returns the existing controller or creates and assigns a new FlixelAnimationController for this sprite.
update(float)
Updates this sprite.
Parameters:
| Name | Description |
|---|---|
elapsed | The amount of time that has passed since the last frame update. |
setCurrentFrameForAnimation(FlixelFrame)
Called by FlixelAnimationController when the displayed keyframe changes.
Parameters:
| Name | Description |
|---|---|
frame | The frame to draw, or null to leave static graphic unchanged. |
clearAnimationDisplayFrame()
Clears the active Sparrow / atlas / animation display frame. FlixelSprite.draw(FlixelBatch) will draw nothing until a frame is set again (e.g. by FlixelAnimationController or FlixelSprite.applySparrowAtlas(FlixelGraphic, Array<FlixelFrame>)).
loadGraphic(FileHandle)
Load's a texture and automatically resizes the size of this sprite.
Parameters:
| Name | Description |
|---|---|
path | The directory of the .png to load onto this sprite. |
Returns: this sprite for chaining.
loadGraphic(FileHandle, int)
Load's a texture and automatically resizes the size of this sprite.
Parameters:
| Name | Description |
|---|---|
path | The directory of the .png to load onto this sprite. |
frameWidth | How wide the sprite should be. |
Returns: this sprite for chaining.
loadGraphic(FileHandle, int, int)
Load's a texture and automatically resizes the size of this sprite.
Parameters:
| Name | Description |
|---|---|
path | The directory of the .png to load onto this sprite. |
frameWidth | How wide the sprite should be. |
frameHeight | How tall the sprite should be. |
Returns: this sprite for chaining.
loadGraphic(Texture, int, int)
Loads a texture and automatically resizes the size of this sprite.
Parameters:
| Name | Description |
|---|---|
texture | The texture to load onto this sprite (owned by caller). |
frameWidth | How wide the sprite should be. |
frameHeight | How tall the sprite should be. |
Returns: this sprite for chaining.
loadGraphic(String)
Loads a cached graphic by key. Queue the asset with FlixelAssetManager.load(String) in a loading state to avoid synchronous stalls on the first frame.
Parameters:
| Name | Description |
|---|---|
assetKey | The key of the graphic to load. |
Returns: this sprite for chaining.
loadGraphic(String, int)
Loads a cached graphic by key. Queue the asset with FlixelAssetManager.load(String) in a loading state to avoid synchronous stalls on the first frame.
Parameters:
| Name | Description |
|---|---|
assetKey | The key of the graphic to load. |
frameWidth | The width of the graphic. |
Returns: this sprite for chaining.
loadGraphic(String, int, int)
Loads a cached graphic by key. Queue the asset with FlixelAssetManager.load(String) in a loading state to avoid synchronous stalls on the first frame.
Parameters:
| Name | Description |
|---|---|
assetKey | The key of the graphic to load. |
frameWidth | The width of the graphic. |
frameHeight | The height of the graphic. |
Returns: this sprite for chaining.
loadGraphic(FlixelGraphic)
Loads a graphic from a FlixelGraphic.
Parameters:
| Name | Description |
|---|---|
g | The FlixelGraphic to load. |
Returns: this sprite for chaining.
loadGraphic(FlixelGraphic, int)
Loads a graphic from a FlixelGraphic.
Parameters:
| Name | Description |
|---|---|
g | The FlixelGraphic to load. |
frameWidth | The width of the graphic. |
Returns: this sprite for chaining.
loadGraphic(FlixelGraphic, int, int)
Loads a graphic from a FlixelGraphic.
Parameters:
| Name | Description |
|---|---|
g | The FlixelGraphic to load. |
frameWidth | The width of the graphic. |
frameHeight | The height of the graphic. |
Returns: this sprite for chaining.
makeGraphic(int, int, Color)
Creates a solid color rectangular texture on the fly.
Parameters:
| Name | Description |
|---|---|
width | The width of the graphic. |
height | The height of the graphic. |
color | The color of the graphic. |
Returns: this sprite for chaining.
makeGraphic(int, int, FlixelColor)
Creates a solid color rectangular texture on the fly.
Parameters:
| Name | Description |
|---|---|
width | The width of the graphic. |
height | The height of the graphic. |
color | The color of the graphic. |
Returns: this sprite for chaining.
applySparrowAtlas(FlixelGraphic, Array<FlixelFrame>)
Installs a retained FlixelGraphic and parsed Sparrow atlas frames. Called by FlixelAnimationController.addSparrowFrames(String) and FlixelSpritemapJsonLoader.load(...), not a general API for game code.
Parameters:
| Name | Description |
|---|---|
newGraphic | Graphic from Flixel.ensureAssets().get(...) with retain() already called. |
parsedFrames | Frames built from the XML (which may be empty). |
mergeSparrowAtlas(FlixelGraphic, Array<FlixelFrame>)
Merges parsed Sparrow atlas frames onto this sprite's existing atlas instead of replacing it.
Where FlixelSprite.applySparrowAtlas(FlixelGraphic, Array<FlixelFrame>) swaps in a fresh atlas and clears the sprite's clips, this appends parsedFrames to whatever atlas the sprite already has (creating one when it had none) and retains newGraphic as a secondary graphic so its texture stays loaded. That lets a single sprite carry frames from more than one sheet, which is what FlixelAnimationController.addSparrowFrames(String) builds on. The currently displayed frame and the registered clips are left untouched, so a sprite already showing a rig clip or another atlas keeps rendering exactly as before; play one of the newly registered clips to show the merged art.
Parameters:
| Name | Description |
|---|---|
newGraphic | The graphic backing parsedFrames, already retained by its loader. |
parsedFrames | The frames to append, which may be empty. |
retainSecondaryGraphic(FlixelGraphic)
Retains an additional FlixelGraphic so its texture stays loaded until this sprite is destroyed, and propagates the sprite's current antialiasing setting onto the new graphic's texture so an appended atlas matches the visual filter of the original.
The graphic is assumed to have already been retained by the caller (typically via FlixelAssetManager.get(...) followed by retain()), so this method only stores the reference and does not call FlixelGraphic.retain() again. This is an advanced hook used by atlas-merging code such as FlixelAnimationController.addSparrowFrames(String) and the Animate rig loader; most game code never calls it directly.
Parameters:
| Name | Description |
|---|---|
graphic | The graphic to retain for the sprite's lifetime. Must not be null. |
draw(FlixelBatch)
setGraphicSize(int, int)
Sets how large the graphic is drawn on screen (in pixels), without changing which part of the texture is used.
This adjusts FlixelSprite.setScale(float, float) so the full current frame/region maps to the given size. It does not change TextureRegion bounds: TextureRegion#setRegionWidth/setRegionHeight only resize the source rectangle inside the texture (UVs), which crops or re-samples texels; the drawable size in this class comes from FlixelSprite.getWidth()/FlixelSprite.getHeight() and scale in FlixelSprite.draw(FlixelBatch).
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.
updateHitbox()
Sets the hitbox to match the on-screen graphic.
FlixelSprite.draw(FlixelBatch) sizes every frame from FlixelFrame.originalWidth/FlixelFrame.originalHeight and scale separately, so the hitbox is set to the frame's untrimmed source size times |scale| so the box frames the whole drawn artwork (matching HaxeFlixel's frameWidth/frameHeight), not just the trimmed pixels.
updateHitbox(float, float)
Updates the hitbox of this sprite to the size of the given width and height.
Parameters:
| Name | Description |
|---|---|
width | The width of the hitbox. |
height | The height of the hitbox. |
Returns: this sprite for chaining.
screenCenter()
Centers this sprite on the screen.
Returns: this sprite for chaining.
screenCenter(FlixelAxes)
Centers this sprite on the screen.
Parameters:
| Name | Description |
|---|---|
axes | The axes to center on. |
Returns: this sprite for chaining.
destroy()
setShader(FlixelShader)
Assigns a shader that is applied to this sprite individually when it is drawn.
Each unique shader transition in draw order flushes the GPU vertex buffer before the new shader takes over. Consecutive sprites that share the same FlixelShader instance batch together for free. If you mix many different shaders across sprites in a single camera, performance may drop noticeably on weak devices. Giving players the option to disable sprite shaders is strongly recommended.
The shader is NOT owned by this sprite. Call FlixelShader.destroy() yourself when the shader is no longer needed. Pass null to remove the current shader.
If you need a full-scene effect (post-processing applied to everything a camera sees), prefer FlixelCamera.setShader() instead, as it captures the entire scene into a single FBO and applies the shader once, with no per-sprite flush cost.
Parameters:
| Name | Description |
|---|---|
shader | The shader to apply when drawing this sprite, or null to remove it. |
getShader()
Returns the shader currently assigned to this sprite, or null if none is set.
Returns: The active per-sprite FlixelShader, or null.
hasOwnedGraphic()
Whether this sprite holds an owned FlixelGraphic (e.g. from FlixelSprite.makeGraphic(...)), so CPU-side pixmap uploads are allowed without mutating a shared atlas.
getGraphic()
getTexture()
getScaleX()
getScaleY()
setScale(float)
setScale(float, float)
setScaleX(float)
setScaleY(float)
getOriginX()
getOriginY()
setOrigin(float, float)
setOriginCenter()
getOffsetX()
setOffsetX(float)
getOffsetY()
setOffsetY(float)
setOffset(float, float)
isAntialiasing()
getAntialiasing()
Returns whether linear texture filtering (antialiasing) is enabled for this sprite.
setAntialiasing(boolean)
toggleAntialiasing()
getAlpha()
getFacing()
setFacing(int)
getBlendMode()
setBlendMode(FlixelBlendMode)
getColor()
getGdxColor()
setColor(Color)
Copies RGBA from color into this tint.
setColor(FlixelColor)
Copies RGBA from color into this tint.
setColor(float, float, float, float)
getShakeX()
Current shake channel X (for example graphic offset or world X).
getShakeY()
Current shake channel Y.
setShake(float, float)
Sets the shake channel to absolute coordinates (typically base plus jitter).
setAlpha(float)
flip(boolean, boolean)
isFlipX()
getFlipX()
setFlipX(boolean)
isFlipY()
getFlipY()
setFlipY(boolean)
setRegion(TextureRegion)
getFrame()
getRegion()
getRegionWidth()
getRegionHeight()
getAtlasRegions()
getCurrentFrame()
getFrames()
isClipRectEnabled()
setClipRect(float, float, float, float)
Sets the clip rectangle in screen-pixel space relative to the sprite's drawn position, and enables clipping.
Only the region inside the rectangle is drawn; pixels outside are discarded by the GPU scissor. Coordinates are in the same units as FlixelSprite.getWidth()/FlixelSprite.getHeight() - that is, they already account for scale, so x=0, y=0 anchors to the drawn bottom-left corner and width=getWidth() covers the full drawn width regardless of scale.
For example, to show only the left half of a sprite regardless of its current scale:
sprite.setClipRect(0, 0, sprite.getWidth() * 0.5f, sprite.getHeight());
// Slide the window right by 10 px later:
sprite.changeClipRectX(10);
// Remove clipping:
sprite.clearClipRect();
Parameters:
| Name | Description |
|---|---|
x | Left edge of the visible region, in screen pixels from the sprite's drawn left edge. |
y | Bottom edge of the visible region, in screen pixels from the sprite's drawn bottom edge. |
width | Width of the visible region, in screen pixels. |
height | Height of the visible region, in screen pixels. |
clearClipRect()
Disables the clip rectangle and resets all clip values to zero.