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 wait function





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 1)

fade_out: boolean?

Whether the current sprite texture should fade out during the cross-fade (if false, it disappears at the end)

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 0.04)

fade_out: boolean?

Whether the current sprite texture should fade out during the cross-fade (if false, it disappears at the end)

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 100)

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:onClone(src: any)

Arguments:

src: any


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 num (frame numbers), ("num1-num2" sequential frames from num1 to num2), and "num1*num2" (repeat frame num1 num2 times)

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 1/30)

loop: boolean?

Whether the animation should loop (Defautls to false)

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. See Sprite:_basicAnimation(wait) for an example of an animation routine
  • table - 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 for
  • callback: fun(self: Sprite) - A callback that will run when the sprite stops animating. Receives the sprite as an argument
  • frames: (number|string)[] - A custom sequence of frame numbers to use for the aniamtion:
    Can use special notation: num (frame numbers), "num1-num2" (sequential frames from num1 to num2), and "num1*num2" (repeat frame num1 num2 times).
    Only takes effect when not using a custom animation routine
  • next: 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 true, this will not interrupt the current animation. Otherwise, any animation will be stopped.



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 path.

keep_anim: boolean?

If true, this will not interrupt the current animation. Otherwise, any animation will be stopped.



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 true, this will not interrupt the current animation. Otherwise, any animation will be stopped.



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 x.



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.



Undocumented