Constructor
Sprite(texture: any, x: any, y: any, width: any, height: any, path: any)
Arguments:
texture: any | |
x: any | |
y: any | |
width: any | |
height: any | |
path: any |
Methods
Sprite:_basicAnimation(wait: fun( number))
(Called internally) Default animation routine
@param wait
— The animation coroutine's wait
function
Arguments:
wait: fun( number) | The animation coroutine's |
Sprite:crossFadeTo(texture: string|love.Image, time: number?, fade_out: boolean?, after: fun( Sprite)?)
Starts a cross-fade from the current sprite to a new texture
@param texture
— The texture to fade into
@param time
— The time, in seconds, that the cross-fade should take (Defaults to 1
)
@param fade_out
— Whether the current sprite texture should fade out during the cross-fade (if false
, it disappears at the end)
@param after
— The function to run when the cross-fade is complete
Arguments:
texture: string|love.Image | The texture to fade into |
time: number? | The time, in seconds, that the cross-fade should take (Defaults to |
fade_out: boolean? | Whether the current sprite texture should fade out during the cross-fade (if |
after: fun( Sprite)? | The function to run when the cross-fade is complete |
Sprite:crossFadeToSpeed(texture: string|love.Image, speed: number?, fade_out: boolean?, after: fun( Sprite)?)
Starts a cross-fade from the current sprite to a new texture
@param texture
— The texture to fade into
@param speed
— The speed at which the alpha of both sprites change, meaasured as the alpha value change per frame at 30FPS (Defaults to 0.04
)
@param fade_out
— Whether the current sprite texture should fade out during the cross-fade (if false
, it disappears at the end)
@param after
— The function to run when the cross-fade is complete
Arguments:
texture: string|love.Image | The texture to fade into |
speed: number? | The speed at which the alpha of both sprites change, meaasured as the alpha value change per frame at 30FPS (Defaults to |
fade_out: boolean? | Whether the current sprite texture should fade out during the cross-fade (if |
after: fun( Sprite)? | The function to run when the cross-fade is complete |
Sprite:flash(offset_x: number?, offset_y: number?, layer: number?)
@param offset_x
— The x-offset of the flash sprite
@param offset_y
— The y-offset of the flash sprite
@param layer
— (Defaults to 100
)
Arguments:
offset_x: number? | The x-offset of the flash sprite |
offset_y: number? | The y-offset of the flash sprite |
layer: number? | (Defaults to |
Returns:
1: FlashFade |
Sprite:getPath(name: string)
(Called internally) Gets the full path to the texture this sprite should use
given a path by Sprite:setSprite()
. If this sprite's path
is not empty,
it will be prepended to the given path.
@param name
— The relative path of the sprite to get the full path of.
Arguments:
name: string | The relative path of the sprite to get the full path of. |
Returns:
1: string |
Sprite:getTexture()
@return texture
— The current texture of the sprite, if it exists.
Returns:
texture: love.Image|nil | The current texture of the sprite, if it exists. |
Sprite:hasSprite(texture: string)
@param texture
— The texture to check the existence of, relative to this sprite's path.
@return exists
— Whether the given texture exists.
Arguments:
texture: string | The texture to check the existence of, relative to this sprite's path. |
Returns:
exists: boolean | Whether the given texture exists. |
Sprite:isSprite(texture: string)
@param texture
— The texture to check against this sprite's current texture, relative to this sprite's path.
@return equal
— Whether the textures are equal.
Arguments:
texture: string | The texture to check against this sprite's current texture, relative to this sprite's path. |
Returns:
equal: boolean | Whether the textures are equal. |
Sprite:parseFrames(frames: (string|number)[]?)
(Called internally) Parses animation frame data into a table of frame numbers
@param frames
— Input animation: Can use num
(frame numbers), ("num1-num2"
sequential frames from num1
to num2
), and "num1*num2"
(repeat frame num1
num2
times)
@return anim
— Output animation: Uses only frame numbers
Arguments:
frames: (string|number)[]? | Input animation: Can use |
Returns:
anim: number[]? | Output animation: Uses only frame numbers |
Sprite:play(speed: number?, loop: boolean?, on_finished: fun( Sprite)?)
Starts animating the sprite's current texture
@param speed
— The speed of the animation as the number of seconds between frames (Defaults to 1/30
)
@param loop
— Whether the animation should loop (Defautls to false
)
@param on_finished
— A function to run when the animation finishes
Arguments:
speed: number? | The speed of the animation as the number of seconds between frames (Defaults to |
loop: boolean? | Whether the animation should loop (Defautls to |
on_finished: fun( Sprite)? | A function to run when the animation finishes |
Sprite:resetCrossFade()
Stops the cross-fade on the current sprite
Sprite:set(texture: string|table|love.Image)
Sets the sprite to either a texture or an animation.
If the given texture is a string or image, it will be passed into Sprite:setSprite()
.
If the given texture is a table, it will be passed into Sprite:setAnimation()
.
@param texture
— The texture or animation to set the sprite to.
Arguments:
texture: string|table|love.Image | The texture or animation to set the sprite to. |
Sprite:setAnimation(anim: string| number, [3]( Sprite) number, frames(string|number) string|table })
Sets the animation of the current sprite.
The animation specified in anim
can take on multiple forms:
fun(wait: fun(time: number))
- The animation routine. Receives the animation coroutine's wait function. SeeSprite:_basicAnimation(wait)
for an example of an animation routinetable
- A table of animation data, in one of these three formats:-
string|table
- The name of the sprite, or a table of frames of the animation,
number
- The time, in seconds, between each frame,
boolean
- Whether the animation should loop
-
string|table
- The name of the sprite, or a table of frames of the animation,
fun(wait: fun(time: number))
- An animation routine
-
fun(wait: fun(time: number))
- An animation routine
Additionally, these keys can be defined in the anim
table for further customisation:
duration: number
- The time, in seconds, that the animation will run forcallback: fun(self: Sprite)
- A callback that will run when the sprite stops animating. Receives the sprite as an argumentframes: (number|string)[]
- A custom sequence of frame numbers to use for the aniamtion:
Can use special notation:num
(frame numbers),"num1-num2"
(sequential frames fromnum1
tonum2
), and"num1*num2"
(repeat framenum1
num2
times).
Only takes effect when not using a custom animation routinenext: string|table
- Another animation to play when the current one finishes. If this is a table, a random entry will be selected as the next animation
Arguments:
anim: string| number, [3]( Sprite) number, frames(string|number) string|table } |
Sprite:setCrossFadeTexture(texture: string|love.Image)
(Called internally) Sets the target texture for the current cross-fade
Arguments:
texture: string|love.Image |
Sprite:setFrame(frame: number)
Sets the frame of the current sprite.
If the sprite has no frames, this will do nothing.
@param frame
— The frame to set the sprite to. If this is outside of the range of frames, it will wrap around.
Arguments:
frame: number | The frame to set the sprite to. If this is outside of the range of frames, it will wrap around. |
Sprite:setFrames(frames: string|table, keep_anim: boolean?)
(Called internally) Sets the current sprite to a list of frames, and updates the texture.
Note: Ignores path
and single-frame textures. Use Sprite:setSprite()
instead.
@param frames
— The frames to set the sprite to.
@param keep_anim
— If true
, this will not interrupt the current animation. Otherwise, any animation will be stopped.
Arguments:
frames: string|table | The frames to set the sprite to. |
keep_anim: boolean? | If |
Sprite:setProgress(progress: number)
Sets the current frame to a percentage between 0 - 1.
If progress
is outside of this range, it will wrap around.
@param progress
— The percentage (0 - 1) of the animation to set the frame to.
Arguments:
progress: number | The percentage (0 - 1) of the animation to set the frame to. |
Sprite:setSprite(texture: string|table|love.Image, keep_anim: boolean?)
Sets the current sprite.
@param texture
— The texture to set the sprite to. If this is a string, it will be relative to this sprite's path
.
@param keep_anim
— If true
, this will not interrupt the current animation. Otherwise, any animation will be stopped.
Arguments:
texture: string|table|love.Image | The texture to set the sprite to. If this is a string, it will be relative to this sprite's |
keep_anim: boolean? | If |
Sprite:setTexture(texture: string|love.Image, keep_anim: boolean?)
(Called internally) Sets the current sprite to a single texture.
Note: Ignores path
and frames. Use Sprite:setSprite()
instead.
@param texture
— The texture to set the sprite to.
@param keep_anim
— If true
, this will not interrupt the current animation. Otherwise, any animation will be stopped.
Arguments:
texture: string|love.Image | The texture to set the sprite to. |
keep_anim: boolean? | If |
Sprite:setTextureExact(texture: any)
(Called internally) Sets the current sprite to a single texture.
Note: Only for internal overrides. Use Sprite:setSprite()
instead.
Arguments:
texture: any |
Sprite:setWrap(x: boolean, y: boolean?)
Sets the wrapping mode of the sprite.
The texture will repeat across the whole screen in the direction(s) specified.
@param x
— Whether the texture should repeat horizontally.
@param y
— Whether the texture should repeat vertically. If not specified, this will be the same as x
.
Arguments:
x: boolean | Whether the texture should repeat horizontally. |
y: boolean? | Whether the texture should repeat vertically. If not specified, this will be the same as |
Sprite:stop(keep_frame: boolean?)
Stops the animation of the current sprite
@param keep_frame
— Whether to keep the current frame of the sprite. If false, the sprite sets back to the first frame
Arguments:
keep_frame: boolean? | Whether to keep the current frame of the sprite. If false, the sprite sets back to the first frame |
Sprite:updateTexture()
(Called internally) Updates the sprite's texture to its current frame.
If the sprite has no frames, this will do nothing.
Fields
Sprite.anim_callback: fun( Sprite)|nil
A function that is called when the current animation finishes.
Sprite.anim_delay: number
(Read-only) The delay between frames in the current animation.
Sprite.anim_duration: number
(Read-only) The duration of the current animation. If greater than 0, the animation will stop after this many seconds.
Sprite.anim_frames: number[]|nil
(Read-only) A list of frame indexes the current animation loops through. If nil
, the animation loops through all frames.
Sprite.anim_routine: thread|nil
(Read-only) The coroutine of the current sprite animation.
Sprite.anim_routine_func: fun( fun( number))|nil
(Read-only) The function of the current sprite animation.
Sprite.anim_speed: number
A multiplier for how fast the sprite animates. (Defaults to 1
)
Sprite.anim_sprite: string
(Read-only) The name of the sprite used in the current animation.
Sprite.anim_wait_func: fun( number)
(Read-only) The function used to wait for the next frame of the animation.
Sprite.anim_waiting: number
(Read-only) Set by the wait
function of an animation routine. The amount of time left until the animation continues.
Sprite.frame: number
(Read-only) The current frame of the sprite. Set with Sprite:setFrame()
.
Sprite.frames: love.Image[]|nil
(Read-only) The animation frames of the sprite, or nil
if the texture has no frames.
Sprite.loop: boolean
Whether the sprite will continuously loop its animation. (Defaults to false
)
Sprite.path: string
The base path of the sprite.
Any calls to Sprite:setSprite()
will have this path prepended to them,
only checking for textures inside this folder.
Note: This path is still relative to assets/sprites/
!
Sprite.playing: boolean
(Read-only) Whether an animation is currently playing.
Sprite.texture: love.Image|nil
(Read-only) The current texture of the sprite, if it exists.
Sprite.texture_path: string|nil
(Read-only) The string ID of the current texture, if it exists.
Sprite.use_texture_size: boolean
Whether this sprite's width
and height
will be updated to the size of the texture.
Defaults to true
if a width and height is not specified in the constructor.
Sprite.wrap_texture_x: boolean
If enabled, the texture will repeat horizontally across the screen.
Sprite.wrap_texture_y: boolean
If enabled, the texture will repeat vertically across the screen.