Skip to content

Class "Sprite"⚓︎

Info

此类可通过其构造函数或以下函数访问:

Example Code 
1
local mySprite = Sprite()

Constructors⚓︎

Sprite ()⚓︎

Sprite Sprite ( )⚓︎

Functions⚓︎

Get·Animation ()⚓︎

string GetAnimation ( )⚓︎

返回当前正在播放的动画的名称.

Get·Default·Animation ()⚓︎

string GetDefaultAnimation ( )⚓︎

从当前加载的 anm2 文件中返回 DefaultAnimation 的值.

此函数似乎与 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 ( )⚓︎

从当前加载的 anm2 文件中返回 DefaultAnimation 的值.

此函数似乎与 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 ( )⚓︎

返回精灵上加载的 anm2 文件的路径.

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 ( )⚓︎

返回当前正在渲染的动画的帧序号.

Get·Layer·Count ()⚓︎

int GetLayerCount ( )⚓︎

返回精灵上加载的 anm2 文件中的图层数量。所有动画使用相同数量的图层.

Get·Overlay·Animation ()⚓︎

string GetOverlayAnimation ( )⚓︎

返回当前播放的叠加动画的名称。（叠加动画是可以与正常动画同时播放的独立次要动画。）

Get·Overlay·Frame ()⚓︎

int GetOverlayFrame ( )⚓︎

返回当前正在渲染的叠加动画的帧编号。（叠加动画是可以与正常动画同时播放的独立次要动画。）

Get·Texel ()⚓︎

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

返回精灵在给定采样位置的像素颜色。RenderPos 可以忽略并设置为零向量

Is·Event·Triggered ()⚓︎

boolean IsEventTriggered ( string EventName )⚓︎

如果动画中指定的事件当前正在触发，则返回 true.

Is·Finished ()⚓︎

boolean IsFinished ( string AnimationName )⚓︎

boolean IsFinished ( )⚓︎

如果动画播放完成，则为true

Is·Loaded ()⚓︎

boolean IsLoaded ( )⚓︎

如果使用Sprite:Load()加载的动画加载成功了，则为true

Is·Overlay·Finished ()⚓︎

boolean IsOverlayFinished ( string AnimationName )⚓︎

boolean IsOverlayFinished ( )⚓︎

如叠加动画播放完成，则为true

Is·Overlay·Playing ()⚓︎

boolean IsOverlayPlaying ( string AnimationName )⚓︎

boolean IsOverlayPlaying ( )⚓︎

根据精灵是否正在播放提供的叠加动画名称返回 true/false。名称在给定精灵的 anm2 文件中设置

Is·Playing ()⚓︎

boolean IsPlaying ( string AnimationName )⚓︎

boolean IsPlaying ( )⚓︎

根据精灵是否正在播放提供的动画名称返回 true/false。名称在给定精灵的 anm2 文件中设置.

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 )⚓︎

加载给定的 anm2 文件。每个精灵必须加载一个 anm2 文件才能显示任何内容.

  • ANM2Path - 包含此精灵所有动画的 anm2 文件的路径。这应该是相对于 “resources” 文件夹的路径.
  • LoadGraphics - 是否在加载 anm2 文件后自动调用Sprite.LoadGraphics方法.
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 ( )⚓︎

用于加载精灵的 anm2 中指定的 PNG 文件。通常，只有在之前向Sprite.Load方法的loadGraphics参数传递了 false，或者调用了Sprite.ReplaceSpritesheet方法时，才会调用此方法.

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 )⚓︎

开始执行给定的动画，从第 0 帧开始。调用此方法后，必须在每个更新帧上调用Sprite.Update方法（如果要在渲染回调中更新动画，请确保仅在偶数帧上运行），以便将动画推进到下一帧。（通常，您还会使用Sprite.IsFinished方法检查动画是否完成。）

再次调用此方法将把当前帧重置回 0.

  • Force - 如果为 true，当前正在播放的动画（如果有）将被停止。如果为 false，并且已经有当前正在播放的动画，此方法将不执行任何操作，当前动画将继续播放.
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 )⚓︎

开始执行给定的叠加动画，从第 0 帧开始。（叠加动画是可以与正常动画同时播放的独立次要动画。）调用此方法后，必须在每个更新帧上调用Sprite.Update方法（如果要在渲染回调中更新动画，请确保仅在偶数帧上运行），以便将动画推进到下一帧。（通常，您还会使用Sprite.IsOverlayFinished方法检查动画是否完成。）

再次调用此函数将始终把当前叠加帧重置回 0.

  • Force - Force - 如果为 true，当前正在播放的动画（如果有）将被停止。如果为 false，并且已经有当前正在播放的动画，此方法将不执行任何操作，当前动画将继续播放.
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 )⚓︎

从当前加载的 anm2 文件中播放随机动画.

Reload ()⚓︎

void Reload ( )⚓︎

重新加载anm2文件

Remove·Overlay ()⚓︎

void RemoveOverlay ( )⚓︎

取消执行给定的叠加动画

Render ()⚓︎

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

在给定的屏幕位置渲染精灵对象，其中 (0, 0) 是屏幕的左上角。

为了绘制精灵，需要在每个渲染帧上调用此函数。（例如在MC_POST_RENDER回调中。）

TopLeftClamp 和 BottomRightClamp 可用于裁剪精灵。

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 )⚓︎

在给定的屏幕位置渲染精灵的特定图层，其中 (0,0) 是屏幕的左上角。

这与Sprite.Render方法类似，但它只会渲染精灵的特定图层，而不是一次渲染所有图层。

TopLeftClamp 和 BottomRightClamp 可用于裁剪精灵。

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 )⚓︎

boolean ReplaceSpritesheet ( int LayerId, string PngFilename )⚓︎

更改与精灵特定图层关联的 “.png” 文件。这不会更改使用正在被替换的 “.png” 文件的其他图层。

替换精灵表后，必须随后调用Sprite.LoadGraphics方法.

In Repentance+, this returns true if the spritesheet at the given layer id was successfully replaced and if the new spritesheet is not the same as the old one, otherwise returns false.

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 )⚓︎

与Sprite.Play方法类似，但不会启动动画.

  • Reset - 为 false 时将从当前帧继续动画。这对于动态在不同 FloatDirection 动画之间交替的随从以及其他遵循类似行为的实体来说是一个非常好的工具.

Set·Frame ()⚓︎

void SetFrame ( int FrameNum )⚓︎

void SetFrame ( string AnimationName, int FrameNum )⚓︎

将当前动画更改为特定帧。

请注意，通常，您会使用Sprite.Update方法自动迭代精灵的动画帧。因此，此方法通常用于不播放动画的精灵。

Sprite.SetFrame方法有两个重载：一个支持同时设置动画，另一个使用当前正在播放的动画。

Set·Last·Frame ()⚓︎

void SetLastFrame ( )⚓︎

将当前播放的动画设置为其最后一帧.

Set·Layer·Frame ()⚓︎

void SetLayerFrame ( int LayerId, int FrameNum )⚓︎

Set·Overlay·Animation ()⚓︎

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

与Sprite.PlayOverlay方法类似，但不会启动动画.

  • Reset - 为 false 时将从当前帧继续动画。这对于动态在不同 FloatDirection 动画之间交替的随从以及其他遵循类似行为的实体来说是一个非常好的工具.

Set·Overlay·Frame ()⚓︎

void SetOverlayFrame ( string AnimationName, int FrameNum )⚓︎

Set·Overlay·Render·Priority ()⚓︎

void SetOverlayRenderPriority ( boolean RenderFirst )⚓︎

Stop ()⚓︎

void Stop ( )⚓︎

Update ()⚓︎

void Update ( )⚓︎

将当前播放的动画推进一帧.

Was·Event·Triggered ()⚓︎

boolean WasEventTriggered ( string EventName )⚓︎

如果动画中指定的事件在某个时刻被触发，则返回 true，并在动画停止播放前保持为 true.

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: September 13, 2025