AnimatedSprite2D
A 2D frame-based sprite with its own playback cursor.
Plays named animations from SpriteFrames. The resource holds frame data; this entity holds the clip name, Frame, FrameProgress and playback state. Sharing a resource does not share entity cursors, but editing its frames or FPS affects every user.
Play/Pause/Stop control the cursor; IsPlaying can be true at zero speed. Assigning a different SpriteFrames resource stops playback. The sprite does not create a physics shape or gameplay event by itself.
Complete movement example · Timing and frames.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
AnimatedSprite2DConstructor
public AnimatedSprite2D();Properties10
AnimationProperty
public StringName Animation { get; set; }Selected clip name. Changing it selects the directional start: the first frame for forward playback or the last for reverse playback. This is not a separate Play command or an unconditional reset to zero.
AutoplayProperty
public string Autoplay { get; set; }The key of the animation to play when the scene loads.
CenteredProperty
public bool Centered { get; set; }If true, texture will be centered.
Note: For games with a pixel art aesthetic, textures may appear deformed when centered. This is caused by their position being between pixels. To prevent this, set this property to false, or consider enabling ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel and ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel.
FlipHProperty
public bool FlipH { get; set; }If true, texture is flipped horizontally.
FlipVProperty
public bool FlipV { get; set; }If true, texture is flipped vertically.
FrameProperty
public int Frame { get; set; }Displayed frame index. Assignment also sets FrameProgress to 1 when GetPlayingSpeed is negative, otherwise 0, including while paused. Use SetFrameAndProgress to preserve an explicit fraction.
FrameProgressProperty
public float FrameProgress { get; set; }Current frame fraction, normally increasing from 0 to 1 forward and decreasing from 1 to 0 in reverse. Explicit assignments are not automatically clamped to that interval. Use [0,1] for ordinary cursor positioning.
OffsetProperty
public Vector2 Offset { get; set; }The texture's drawing offset.
SpeedScaleProperty
public float SpeedScale { get; set; }Entity playback multiplier. Direction follows the sign of SpeedScale multiplied by the Play customSpeed. Zero freezes advancement without calling Pause. Stop preserves SpeedScale. This value is not clip FPS.
SpriteFramesProperty
public SpriteFrames SpriteFrames { get; set; }Source of frames and clips. Assigning a different resource stops playback and resets the cursor; assigning the identical instance again does not reset it. Edits to shared data are visible to other users.
Methods27
GetAnimationStringName
public StringName GetAnimation();StringNameGetAutoplaystring
public string GetAutoplay();stringGetFrameint
public int GetFrame();intGetFrameProgressfloat
public float GetFrameProgress();floatGetOffsetVector2
public Vector2 GetOffset();Vector2GetPlayingSpeedfloat
public float GetPlayingSpeed();Returns SpeedScale multiplied by customSpeed while playback is enabled, otherwise 0. It excludes clip FPS and relative frame duration.
floatSigned multiplier: negative for reverse playback, zero while paused, stopped or when the product is zero.
GetSpeedScalefloat
public float GetSpeedScale();floatGetSpriteFramesSpriteFrames
public SpriteFrames GetSpriteFrames();SpriteFramesIsCenteredbool
public bool IsCentered();boolIsFlippedHbool
public bool IsFlippedH();boolIsFlippedVbool
public bool IsFlippedV();boolIsPlayingbool
public bool IsPlaying();Checks the playback flag, not visible advancement. Zero SpeedScale, customSpeed or FPS can leave this true. Pause, Stop and one-shot completion disable playback.
booltrue while playback is enabled; this does not alone guarantee frame changes.
Pausevoid
public void Pause();Disables playback while preserving Frame and FrameProgress. Play of the same clip resumes that cursor using the new call customSpeed. GetPlayingSpeed returns 0 while paused.
Playvoid
public void Play(StringName name = null, float customSpeed = 1f, bool fromEnd = false);Plays an existing nonempty clip. Changing the name selects its beginning or end according to fromEnd. The same name resumes the cursor after Pause; every call replaces customSpeed. Use Stop followed by Play for an explicit restart.
| Name | Type | Default |
|---|---|---|
name | StringName | null |
customSpeed | float | 1f |
fromEnd | bool | false |
nameClip name in SpriteFrames. The default selects the current clip, not the first clip in the library.
customSpeedPer-call multiplier combined with SpeedScale. Zero prevents advancement; a negative product plays in reverse. A later Play call omitting this argument uses 1 again.
fromEndStart at the end when selecting a new clip. This chooses a cursor position, not a reverse direction. Use SetFrameAndProgress for arbitrary positioning within the same clip.
PlayBackwardsvoid
public void PlayBackwards(StringName name = null);Shorthand for Play(name, -1, true). A positive SpeedScale gives the expected reverse direction; negative SpeedScale reverses the product again. After pausing, the same clip can resume its saved cursor.
| Name | Type | Default |
|---|---|---|
name | StringName | null |
nameExisting clip name; the default uses the current clip.
SetAnimationvoid
public void SetAnimation(StringName name);| Name | Type | Default |
|---|---|---|
name | StringName | — |
SetAutoplayvoid
public void SetAutoplay(string name);| Name | Type | Default |
|---|---|---|
name | string | — |
SetCenteredvoid
public void SetCentered(bool centered);| Name | Type | Default |
|---|---|---|
centered | bool | — |
SetFlipHvoid
public void SetFlipH(bool flipH);| Name | Type | Default |
|---|---|---|
flipH | bool | — |
SetFlipVvoid
public void SetFlipV(bool flipV);| Name | Type | Default |
|---|---|---|
flipV | bool | — |
SetFramevoid
public void SetFrame(int frame);| Name | Type | Default |
|---|---|---|
frame | int | — |
SetFrameAndProgressvoid
public void SetFrameAndProgress(int frame, float progress);Explicitly sets the frame index and fraction without changing the playback flag. With an existing clip, the index is clamped to available frames; progress is not automatically clamped.
| Name | Type | Default |
|---|---|---|
frame | int | — |
progress | float | — |
frameZero-based index. A negative index becomes 0; one beyond an existing clip becomes its last valid frame.
progressFrame fraction, normally [0,1]: 0 starts forward advancement and 1 starts reverse advancement. The method stores the supplied value without clamping.
SetFrameProgressvoid
public void SetFrameProgress(float progress);| Name | Type | Default |
|---|---|---|
progress | float | — |
SetOffsetvoid
public void SetOffset(Vector2 offset);| Name | Type | Default |
|---|---|---|
offset | Vector2 | — |
SetSpeedScalevoid
public void SetSpeedScale(float speedScale);| Name | Type | Default |
|---|---|---|
speedScale | float | — |
SetSpriteFramesvoid
public void SetSpriteFrames(SpriteFrames spriteFrames);| Name | Type | Default |
|---|---|---|
spriteFrames | SpriteFrames | — |
Stopvoid
public void Stop();Disables playback, resets Frame and FrameProgress to 0 and customSpeed to 1. Preserves SpeedScale and the selected Animation name. Use Pause to retain the cursor.
Signals and events5
AnimationChangedEvent
public event Action AnimationChanged;Emitted when AnimatedSprite2D.Animation changes.
AnimationFinishedEvent
public event Action AnimationFinished;Signals reaching the end of a one-shot clip forward or its beginning in reverse. Playback pauses at that boundary. Use AnimationLooped for loops; awaiting this event on an endless clip does not finish at each cycle.
AnimationLoopedEvent
public event Action AnimationLooped;Signals crossing a looping clip boundary. Pingpong changes direction there; Linear begins another pass. This is not AnimationFinished or an independent gameplay event.
FrameChangedEvent
public event Action FrameChanged;Sprite frame-change notification, including manual cursor operations. Do not use it as a screen-frame counter or a guarantee of one gameplay effect per action.
SpriteFramesChangedEvent
public event Action SpriteFramesChanged;Emitted when AnimatedSprite2D.SpriteFrames changes.