class FlxSprite
package flixel
extends FlxObject › FlxBasic
extended by FlxParticle, FlxTypedSpriteGroup, FlxBGSprite, FlxText, FlxTileblock, FlxBar, FlxTypedButton
The main "game object" class, the sprite is a FlxObject
with a bunch of graphics options and abilities, like animation and stamping.
Load an image onto a sprite using the loadGraphic*() functions,
or create a base monochromatic rectangle using makeGraphic().
The image BitmapData is stored in the pixels field.
Constructor
new(X:Float = 0, Y:Float = 0, ?SimpleGraphic:Null<FlxGraphicAsset>)
Creates a FlxSprite at a specified position with a specified one-frame graphic.
If none is provided, a 16x16 image of the HaxeFlixel logo is used.
Parameters:
X | The initial X position of the sprite. |
|---|---|
Y | The initial Y position of the sprite. |
SimpleGraphic | The graphic you want to display (OPTIONAL - for simple stuff only, do NOT use for animated images!). |
Variables
read onlybakedRotationAngle:Float = 0
The minimum angle (out of 360°) for which a new baked rotation exists. Example: 90 means there
are 4 baked rotations in the spritesheet. 0 if this sprite does not have any baked rotations.
clipRect:FlxRect
Clipping rectangle for this sprite.
Changing the rect's properties directly doesn't have any effect,
reassign the property to update it (sprite.clipRect = sprite.clipRect;).
Set to null to discard graphic frame clipping.
color:FlxColor = 0xffffff
Tints the whole sprite to a color (0xRRGGBB format) - similar to OpenGL vertex colors. You can use
0xAARRGGBB colors, but the alpha value will simply be ignored. To change the opacity use alpha.
dirty:Bool = true
Set this flag to true to force the sprite to update during the draw() call.
NOTE: Rarely if ever necessary, most sprite operations will flip this flag automatically.
facing:FlxDirectionFlags = RIGHT
Can be set to LEFT, RIGHT, UP, and DOWN to take advantage
of flipped sprites and/or just track player orientation more easily.
read onlyframeHeight:Int = 0
The height of the actual graphic or image being displayed (not necessarily the game object/bounding box).
framePixels:BitmapData
The current display state of the sprite including current animation frame,
tint, flip etc... may be null unless useFramePixels is true.
read onlyframeWidth:Int = 0
The width of the actual graphic or image being displayed (not necessarily the game object/bounding box).
read onlynumFrames:Int = 0
The total number of frames in this image. WARNING: assumes each row in the sprite sheet is full!
read onlyoffset:FlxPoint
Controls the position of the sprite's hitbox. Likely needs to be adjusted after
changing a sprite's width, height or scale.
read onlyorigin:FlxPoint
WARNING: The origin of the sprite will default to its center. If you change this,
the visuals and the collisions will likely be pretty out-of-sync if you do any rotation.
pixels:BitmapData
This sprite's graphic / BitmapData object.
Automatically adjusts graphic size and render helpers if changed.
read onlyscale:FlxPoint
Change the size of your sprite's graphic.
NOTE: The hitbox is not automatically adjusted, use updateHitbox() for that (or setGraphicSize()).
WARNING: With FlxG.renderBlit, scaling sprites decreases rendering performance by a factor of about x10!
shader:FlxShader
GLSL shader for this sprite. Only works with OpenFL Next or WebGL. Avoid changing it frequently as this is a costly operation.
4.1.0
.read onlyuseColorTransform:Bool = false
Whether or not to use a ColorTransform set via setColorTransform().
useFramePixels:Bool = true
Always true on FlxG.renderBlit. On FlxG.renderTile it determines whether
framePixels is used and defaults to false for performance reasons.
Methods
centerOffsets(AdjustPosition:Bool = false):Void
Helper function that adjusts the offset automatically to center the bounding box within the graphic.
Parameters:
AdjustPosition | Adjusts the actual X and Y position just once to match the offset change. |
|---|
inlinecenterOrigin():Void
Sets the sprite's origin to its center - useful after adjusting
scale to make sure rotations work as expected.
destroy():Void
WARNING: A destroyed FlxBasic can't be used anymore.
It may even cause crashes if it is still part of a group or state.
You may want to use kill() instead if you want to disable the object temporarily only and revive() it later.
This function is usually not called manually (Flixel calls it automatically during state switches for all add()ed objects).
Override this function to null out variables manually or call destroy() on class members if necessary.
Don't forget to call super.destroy()!
draw():Void
Called by game loop, updates then blits or renders current frame of animation to the screen.
drawFrame(Force:Bool = false):Void
Request (or force) that the sprite update the frame before rendering. Useful if you are doing procedural generation or other weirdness!
Parameters:
Force | Force the frame to redraw, even if its not flagged as necessary. |
|---|
getGraphicMidpoint(?point:FlxPoint):FlxPoint
getRotatedBounds(?newRect:FlxRect):FlxRect
Calculates the smallest globally aligned bounding box that encompasses this
sprite's width and height, at its current rotation.
Note, if called on a FlxSprite, the origin is used, but scale and offset are ignored.
Use getScreenBounds to use these properties.
Parameters:
newRect | The optional output |
|---|
Returns:
A globally aligned FlxRect that fully contains the input object's width and height.
4.11.0
.getScreenBounds(?newRect:FlxRect, ?camera:FlxCamera):FlxRect
Calculates the smallest globally aligned bounding box that encompasses this sprite's graphic as it would be displayed. Honors scrollFactor, rotation, scale, offset and origin.
Parameters:
newRect | Optional output |
|---|---|
camera | Optional camera used for scrollFactor, if null |
Returns:
A globally aligned FlxRect that fully contains the input sprite.
4.11.0
.graphicLoaded():Void
Called whenever a new graphic is loaded for this sprite (after loadGraphic(), makeGraphic() etc).
isOnScreen(?camera:FlxCamera):Bool
Check and see if this object is currently on screen. Differs from FlxObject's implementation
in that it takes the actual graphic into account, not just the hitbox or bounding box or whatever.
Parameters:
Camera | Specify which game camera you want. If |
|---|
Returns:
Whether the object is on screen or not.
isSimpleRender(?camera:FlxCamera):Bool
Returns the result of isSimpleRenderBlit() if FlxG.renderBlit is
true, or false if FlxG.renderTile is true.
isSimpleRenderBlit(?camera:FlxCamera):Bool
Determines the function used for rendering in blitting:
copyPixels() for simple sprites, draw() for complex ones.
Sprites are considered simple when they have an angle of 0, a scale of 1,
don't use blend and pixelPerfectRender is true.
Parameters:
camera | If a camera is passed its |
|---|
loadGraphic(Graphic:FlxGraphicAsset, Animated:Bool = false, Width:Int = 0, Height:Int = 0, Unique:Bool = false, ?Key:String):FlxSprite
Load an image from an embedded graphic file.
HaxeFlixel's graphic caching system keeps track of loaded image data.
When you load an identical copy of a previously used image, by default
HaxeFlixel copies the previous reference onto the pixels field instead
of creating another copy of the image data, to save memory.
Parameters:
Graphic | The image you want to use. |
|---|---|
Animated | Whether the |
Width | Specify the width of your sprite (helps figure out what to do with non-square sprites or sprite sheets). |
Height | Specify the height of your sprite (helps figure out what to do with non-square sprites or sprite sheets). |
Unique | Whether the graphic should be a unique instance in the graphics cache.
Set this to |
Key | Set this parameter if you're loading |
Returns:
This FlxSprite instance (nice for chaining stuff together, if you're into that).
loadGraphicFromSprite(Sprite:FlxSprite):FlxSprite
loadRotatedFrame(Frame:FlxFrame, Rotations:Int = 16, AntiAliasing:Bool = false, AutoBuffer:Bool = false):FlxSprite
Helper method which allows using FlxFrame as graphic source for sprite's loadRotatedGraphic() method.
Parameters:
frame | Frame to load into this sprite. |
|---|---|
rotations | The number of rotation frames the final sprite should have.
For small sprites this can be quite a large number ( |
antiAliasing | Whether to use high quality rotations when creating the graphic. Default is |
autoBuffer | Whether to automatically increase the image size to accommodate rotated corners. Will create frames that are 150% larger on each axis than the original frame or graphic. |
Returns:
this FlxSprite with loaded rotated graphic in it.
loadRotatedGraphic(Graphic:FlxGraphicAsset, Rotations:Int = 16, Frame:Int = -1, AntiAliasing:Bool = false, AutoBuffer:Bool = false, ?Key:String):FlxSprite
Create a pre-rotated sprite sheet from a simple sprite. This can make a huge difference in graphical performance on blitting targets!
Parameters:
Graphic | The image you want to rotate and stamp. |
|---|---|
Rotations | The number of rotation frames the final sprite should have.
For small sprites this can be quite a large number ( |
Frame | If the |
AntiAliasing | Whether to use high quality rotations when creating the graphic. Default is |
AutoBuffer | Whether to automatically increase the image size to accommodate rotated corners. Will create frames that are 150% larger on each axis than the original frame or graphic. |
Key | Optional, set this parameter if you're loading |
Returns:
This FlxSprite instance (nice for chaining stuff together, if you're into that).
makeGraphic(Width:Int, Height:Int, Color:FlxColor = FlxColor.WHITE, Unique:Bool = false, ?Key:String):FlxSprite
This function creates a flat colored rectangular image dynamically.
HaxeFlixel's graphic caching system keeps track of loaded image data. When you make an identical copy of a previously used image, by default HaxeFlixel copies the previous reference onto the pixels field instead of creating another copy of the image data, to save memory.
Parameters:
Width | The width of the sprite you want to generate. |
|---|---|
Height | The height of the sprite you want to generate. |
Color | Specifies the color of the generated block (ARGB format). |
Unique | Whether the graphic should be a unique instance in the graphics cache. Default is |
Key | An optional |
Returns:
This FlxSprite instance (nice for chaining stuff together, if you're into that).
pixelsOverlapPoint(point:FlxPoint, Mask:Int = 0xFF, ?Camera:FlxCamera):Bool
Checks to see if a point in 2D world space overlaps this FlxSprite object's current displayed pixels.
This check is ALWAYS made in screen space, and always takes scrollFactor into account.
Parameters:
Point | The point in world space you want to check. |
|---|---|
Mask | Used in the pixel hit test to determine what counts as solid. |
Camera | Specify which game camera you want. If |
Returns:
Whether or not the point overlaps this object.
replaceColor(Color:FlxColor, NewColor:FlxColor, FetchPositions:Bool = false):Array<FlxPoint>
Replaces all pixels with specified Color with NewColor pixels.
WARNING: very expensive (especially on big graphics) as it iterates over every single pixel.
Parameters:
Color | Color to replace |
|---|---|
NewColor | New color |
FetchPositions | Whether we need to store positions of pixels which colors were replaced. |
Returns:
Array with replaced pixels positions
inlineresetFrame():Void
Helper method just for convenience, so you don't need to type
sprite.frame = sprite.frame;
You may need this method in tile render mode,
when you want sprite to use its original graphic, not the graphic generated from its framePixels.
setColorTransform(redMultiplier:Float = 1.0, greenMultiplier:Float = 1.0, blueMultiplier:Float = 1.0, alphaMultiplier:Float = 1.0, redOffset:Int = 0, greenOffset:Int = 0, blueOffset:Int = 0, alphaOffset:Int = 0):Void
Sets the sprite's color transformation with control over color offsets.
With FlxG.renderTile, offsets are only supported on OpenFL Next version 3.6.0 or higher.
Parameters:
redMultiplier | The value for the red multiplier, in the range from |
|---|---|
greenMultiplier | The value for the green multiplier, in the range from |
blueMultiplier | The value for the blue multiplier, in the range from |
alphaMultiplier | The value for the alpha transparency multiplier, in the range from |
redOffset | The offset value for the red color channel, in the range from |
greenOffset | The offset value for the green color channel, in the range from |
blueOffset | The offset for the blue color channel value, in the range from |
alphaOffset | The offset for alpha transparency channel value, in the range from |
inlinesetFacingFlip(Direction:FlxDirectionFlags, FlipX:Bool, FlipY:Bool):Void
Set how a sprite flips when facing in a particular direction.
Parameters:
Direction | Use constants |
|---|---|
FlipX | Whether to flip the sprite on the X axis. |
FlipY | Whether to flip the sprite on the Y axis. |
setFrames(Frames:FlxFramesCollection, saveAnimations:Bool = true):FlxSprite
Sets frames and allows you to save animations in sprite's animation controller
Parameters:
Frames | Frames collection to set for this sprite. |
|---|---|
saveAnimations | Whether to save animations in animation controller or not. |
Returns:
This sprite with loaded frames
setGraphicSize(Width:Int = 0, Height:Int = 0):Void
Helper function to set the graphic's dimensions by using scale, allowing you to keep the current aspect ratio
should one of the Integers be <= 0. It might make sense to call updateHitbox() afterwards!
Parameters:
Width | How wide the graphic should be. If |
|---|---|
Height | How high the graphic should be. If |
stamp(Brush:FlxSprite, X:Int = 0, Y:Int = 0):Void
Stamps / draws another FlxSprite onto this FlxSprite.
This function is NOT intended to replace draw()!
Parameters:
Brush | The sprite you want to use as a brush or stamp or pen or whatever. |
|---|---|
X | The X coordinate of the brush's top left corner on this sprite. |
Y | They Y coordinate of the brush's top left corner on this sprite. |
updateFramePixels():BitmapData
Retrieves the BitmapData of the current FlxFrame. Updates framePixels.
updateHitbox():Void
Updates the sprite's hitbox (width, height, offset) according to the current scale.
Also calls centerOrigin().