Skip to content

Class "Sprite"⚓︎

Info

This class can be accessed by using its constructor or the following function:

Example Code 
1
local mySprite = Sprite()

Constructors⚓︎

Sprite ()⚓︎

Sprite Sprite ( )⚓︎

Functions⚓︎

Get·Animation ()⚓︎

string GetAnimation ( )⚓︎

Return the name of the currently playing animation.

Get·Default·Animation ()⚓︎

string GetDefaultAnimation ( )⚓︎

Returns the DefaultAnimation value from the currently loaded anm2 file.

This function seems to be the same as GetDefaultAnimationName().

Example Code

This code print the default animation name "WalkDown" of the player sprite.

1
2
3
local player = Isaac.GetPlayer()
local sprite = player:GetSprite()
print(sprite:GetDefaultAnimation()) -- this prints "WalkDown"

Get·Default·Animation·Name ()⚓︎

string GetDefaultAnimationName ( )⚓︎

Returns the DefaultAnimation value from the currently loaded anm2 file.

This function seems to be the same as GetDefaultAnimation().

Example Code

This code print the default animation name "WalkDown" of the player sprite.

1
2
3
local player = Isaac.GetPlayer()
local sprite = player:GetSprite()
print(sprite:GetDefaultAnimationName()) -- this prints "WalkDown"

Get·Filename ()⚓︎

string GetFilename ( )⚓︎

Returns the path to the anm2 file that is loaded on the sprite.

Example Code

This code print the .anm2 path of the player sprite.

1
2
3
local player = Isaac.GetPlayer()
local sprite = player:GetSprite()
print(sprite:GetFilename()) -- this prints "gfx/001.000_Player.anm2"

Get·Frame ()⚓︎

int GetFrame ( )⚓︎

Returns the frame number of the animation that is currently being rendered.

Get·Layer·Count ()⚓︎

int GetLayerCount ( )⚓︎

Returns the number of layers in the anm2 file that is loaded on the sprite. All animations use the same amount of layers.

Get·Overlay·Animation ()⚓︎

string GetOverlayAnimation ( )⚓︎

Returns the name of the currently playing overlay animation. (The overlay animation is an independent secondary animation that can be played at the same time as the normal animation.)

Get·Overlay·Frame ()⚓︎

int GetOverlayFrame ( )⚓︎

Returns the frame number of the overlay animation that is currently being rendered. (The overlay animation is an independent secondary animation that can be played at the same time as the normal animation.)

Get·Texel ()⚓︎

KColor GetTexel ( Vector SamplePos, Vector RenderPos, float AlphaThreshold, int LayerID = 0 )⚓︎

Returns the color of the pixel of the sprite at the given sample position. RenderPos can be neglected and set to a null vector

Is·Event·Triggered ()⚓︎

boolean IsEventTriggered ( string EventName )⚓︎

Returns true if the specified event in the animation is currently being triggered.

Is·Finished ()⚓︎

boolean IsFinished ( string AnimationName )⚓︎

boolean IsFinished ( )⚓︎

Is·Loaded ()⚓︎

boolean IsLoaded ( )⚓︎

Is·Overlay·Finished ()⚓︎

boolean IsOverlayFinished ( string AnimationName )⚓︎

boolean IsOverlayFinished ( )⚓︎

Is·Overlay·Playing ()⚓︎

boolean IsOverlayPlaying ( string AnimationName )⚓︎

boolean IsOverlayPlaying ( )⚓︎

Is·Playing ()⚓︎

boolean IsPlaying ( string AnimationName )⚓︎

boolean IsPlaying ( )⚓︎

Returns true/false depending on if the sprite is playing the provided animation name. Names are set in a given sprite's anm2 file.

Example Code

This code checks the name of the current animation ("Appear" and "Idle" are used by cards), then replaces its animations with ones loaded from a custom anm2 file called "Custom_Animations.anm2", which has the same animation names.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
if mySprite:IsPlaying("Appear") then
    mySprite:Load("gfx/Custom_Animations.anm2", true)
    mySprite:LoadGraphics()
    mySprite:Play("Appear",true)
    mySprite:Update()
elseif mySprite:IsPlaying("Idle") then
    mySprite:Load("gfx/Custom_Animations.anm2", true)
    mySprite:LoadGraphics()
    mySprite:Play("Idle",true)
    mySprite:Update()
end

Load ()⚓︎

void Load ( string ANM2Path, boolean LoadGraphics )⚓︎

Loads a given anm2 file. Each sprite must have an anm2 file loaded in order for it to display anything.

  • ANM2Path - The path to the anm2 file that contains all of the animations for this sprite. This should be relative to the "resources" folder.
  • LoadGraphics - Whether or not the Sprite.LoadGraphics method is automatically called after the anm2 file is loaded.
Example Code

This code creates a new sprite object, loads an .anm2 file and renders it on the screen.

1
2
3
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)
mySprite:Render(Vector(75,75), Vector(0,0), Vector(0,0))

Load·Graphics ()⚓︎

void LoadGraphics ( )⚓︎

Used to load the PNG files that are specified in the sprite's anm2. Typically, you would only call this method if you have previously passed false to the loadGraphics argument of the Sprite.Load method or you have called the Sprite.ReplaceSpritesheet method.

Example Code

This code creates a new sprite object and replaces the spritesheet of layer 0 of a sprite object with a different spritesheet.

1
2
3
4
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)
mySprite:ReplaceSpritesheet(0, "gfx/my_new_spritesheet.png")
mySprite:LoadGraphics()

Play ()⚓︎

void Play ( string AnimationName, boolean Force )⚓︎

Starts executing the given animation, starting at frame 0. After calling this method, you must call the Sprite.Update method on every update frame (if you want to update the animation in a render callback, make sure to only run it on even frames) in order to advance the animation to the next frame. (Typically, you would also check to see if the animation is finished by using the Sprite.IsFinished method.)

Calling this method again will reset the current frame back to 0.

  • Force - If true, the currently playing animation will be stopped, if any. If false, and there is already a currently playing animation, this method will do nothing and the current animation will continue to play.
Example Code

This code plays and renders a sprite.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    -- Sprite objects only need to be created and loaded once.
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)

-- Execute this function only once! for example when an event is triggered
function myPlaySpriteFunction()
    mySprite:Play("MyAnimation", true)
end

-- Execute this function every POST_RENDER. For example in the MC_POST_RENDER callback.
function myRenderSpriteFunction()
    mySprite:Update()
    mySprite:Render(Vector(50,50), Vector(0,0), Vector(0,0))
end

Play·Overlay ()⚓︎

void PlayOverlay ( string AnimationName, boolean Force )⚓︎

Starts executing the given overlay animation, starting at frame 0. (The overlay animation is an independent secondary animation that can be played at the same time as the normal animation.) After calling this method, you must call the Sprite.Update method on every update frame (if you want to update the animation in a render callback, make sure to only run it on even frames) in order to advance the animation to the next frame. (Typically, you would also check to see if the animation is finished by using the Sprite.IsOverlayFinished method.)

Calling this function again will always reset the current overlay frame back to 0.

  • Force - If true, the currently playing animation will be stopped, if any. If false, and there is already a currently playing animation, this method will do nothing and the current animation will continue to play.
Example Code

This code plays and renders an overlay sprite.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    -- Sprite objects only need to be created and loaded once.
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)

-- Execute this function only once! for example when an event is triggered
function myPlaySpriteFunction()
    mySprite:PlayOverlay("MyOverlayAnimation", true)
end

-- Execute this function every POST_RENDER. For example in the MC_POST_RENDER callback.
function myRenderSpriteFunction()
    mySprite:Render(Vector(50,50), Vector(0,0), Vector(0,0))
end

Play·Random ()⚓︎

void PlayRandom ( int Seed )⚓︎

Plays a random animation from the currently loaded anm2 file.

Reload ()⚓︎

void Reload ( )⚓︎

Remove·Overlay ()⚓︎

void RemoveOverlay ( )⚓︎

Render ()⚓︎

void Render ( Vector Position, Vector Vector TopLeftClamp = Vector.Zero, Vector BottomRightClamp = Vector.Zero )⚓︎

Renders the sprite object at a given screen position, where (0, 0) is the top left corner of the screen.

In order for the sprite to be drawn, this function needs to be called on every render frame. (For example in the MC_POST_RENDER callback.)

TopLeftClamp and BottomRightClamp can be used to crop the sprite.

Example Code

This code renders a sprite.

1
2
3
4
5
6
7
8
    -- Sprite objects only need to be created and loaded once.
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)

-- Execute this function every POST_RENDER. For example in the MC_POST_RENDER callback.
function myRenderSpriteFunction()
    mySprite:Render(Vector(50,50))
end

Render·Layer ()⚓︎

void RenderLayer ( int LayerId, Vector Position, Vector TopLeftClamp = Vector.Zero, Vector BottomRightClamp = Vector.Zero )⚓︎

Renders a specific layer of the sprite at a given screen position, where (0,0) is the top left corner of the screen.

This is similar to the Sprite.Render method, but it will only render a specific layer of the sprite instead of all of the layers at once.

TopLeftClamp and BottomRightClamp can be used to crop the sprite.

Example Code

This code renders layer 3 of a sprite. Layer IDs in most cases start at index 0!

1
2
3
4
5
6
7
8
    -- Sprite objects only need to be created and loaded once.
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)

-- Execute this function every POST_RENDER. For example in the MC_POST_RENDER callback.
function myRenderSpriteFunction()
    mySprite:RenderLayer(2, Vector(50,50))
end

Replace·Spritesheet ()⚓︎

void ReplaceSpritesheet ( int LayerId, string PngFilename )⚓︎

Changes the ".png" file associated with a specific layer of a sprite. This does not change other layers using the ".png" file that is being replaced.

After replacing a spritesheet, you must call the Sprite.LoadGraphics method afterwards.

Example Code

This code creates a new sprite object and replaces the spritesheet of layer 0 of a sprite object with a different spritesheet.

1
2
3
4
local mySprite = Sprite()
mySprite:Load("gfx/myCoolAnimation.anm2", true)
mySprite:ReplaceSpritesheet(0, "gfx/my_new_spritesheet.png")
mySprite:LoadGraphics()

Reset ()⚓︎

void Reset ( )⚓︎

Set·Animation ()⚓︎

boolean SetAnimation ( string AnimationName, boolean Reset = true )⚓︎

Similar to the Sprite.Play method, but does not start the animation.

  • Reset - as false will continue the animation from the current frame. This is a really good tool for familiars that alternate between different FloatDirection animations dynamically and other entities that follow similar behaviors.

Set·Frame ()⚓︎

void SetFrame ( int FrameNum )⚓︎

void SetFrame ( string AnimationName, int FrameNum )⚓︎

Changes the current animation to a specific frame.

Note that normally, you would use the Sprite.Update method to automatically iterate the sprite's animation frame. Thus, this method is typically used for sprites that don't play animations.

The Sprite.SetFrame method has two overloads: one which supports setting an animation at the same time, and one that uses the currently playing animation.

Set·Last·Frame ()⚓︎

void SetLastFrame ( )⚓︎

Sets the currently playing animation to be on its last frame.

Set·Layer·Frame ()⚓︎

void SetLayerFrame ( int LayerId, int FrameNum )⚓︎

Set·Overlay·Animation ()⚓︎

boolean SetOverlayAnimation ( string AnimationName, bool Reset = true )⚓︎

Similar to the Sprite.PlayOverlay method, but does not start the animation.

  • Reset - as false will continue the animation from the current frame. This is a really good tool for familiars that alternate between different FloatDirection animations dynamically and other entities that follow similar behaviors.

Set·Overlay·Frame ()⚓︎

void SetOverlayFrame ( string AnimationName, int FrameNum )⚓︎

Set·Overlay·Render·Priority ()⚓︎

void SetOverlayRenderPriority ( boolean RenderFirst )⚓︎

Stop ()⚓︎

void Stop ( )⚓︎

Update ()⚓︎

void Update ( )⚓︎

Advances the currently playing animation by one frame.

Was·Event·Triggered ()⚓︎

boolean WasEventTriggered ( string EventName )⚓︎

Returns true if the specified event in the animation was triggered at some point, and remains true until the animation stops playing.

Variables⚓︎

Color⚓︎

Color Color⚓︎

FlipX⚓︎

boolean FlipX⚓︎

FlipY⚓︎

boolean FlipY⚓︎

Offset⚓︎

Vector Offset⚓︎

Playback·Speed⚓︎

float PlaybackSpeed⚓︎

Rotation⚓︎

float Rotation⚓︎

Scale⚓︎

Vector Scale⚓︎

Last update: April 26, 2024