AnimatedSprite{2D,3D} improvements

[dalexeev]

• Add support for individual frame duration to SpriteFrames.
• Various minor improvements.

---

Closes godotengine/godot-proposals#2214.

#65188 recently added similar changes to AnimatedTexture.

You can specify the duration of individual frames (default 1.0 s).

This PR introduces backward incompatible changes to the public API and the SpriteFrames serialization format.

[Mickeon]

This PR does not supersede #64155. In that PR the code was harmonised and polished. One thing at the time. It doesn't quite supersede #65148 either because the implementation is different. But that's fine.

[TokageItLab]

For the AnimatedTexture, it would make sense to include its own timeline within it as a Resource referenced by other Nodes.

But since AnimatedSprite is a Node, so its frames can be controlled by AnimationPlayer. Therefore, I am a little skeptical that this feature (individual frame duration in AnimatedSprite) is really necessary and I wonder whether there is a need for such comprehensive support.

[dalexeev]

AnimationPlayer is for advanced cases, AnimatedSprite is for simple ones, but I still want to be able to adjust the duration of individual frames, and not duplicate them.

With this feature it will be much faster to set up the animation. AnimationPlayer is too versatile and inconvenient.

Frame duration/delay is also available in other similar animation editors (for example, in Construct).

[Mickeon]

I would like this but I am mostly concerned about implementation. The PR introduced many things at once and it's hard to grasp a focus on how the individual frame duration is accomplished. Ideally, it should be completely optional and preferably not noticeable until the user decides to make use of it. Because, as useful as frame duration may be, it's somewhat situational and I would not encourage beginning users to experiment, and see way too many overwhelming numbers.

[fire-forge]

The changes done in this PR are nice, but I wonder if it would be better to merge SpriteFrames and AnimatedTexture since their feature sets are so similar.

[dalexeev]

The changes done in this PR are nice, but I wonder if it would be better to merge SpriteFrames and AnimatedTexture since their feature sets are so similar.

An AnimatedTexture can be used as a property value without being added to the tree as a node. For example, in 3.x AnimatedTexture can be used for animated tiles (however, in 4.0-dev, animation in TileMap is done separately). It seems to me that in 4.0 AnimatedTexture is mostly not needed. Only as a workaround for possible corner cases (like animated tiles in 3.x). Or as a replacement for GIF, which is not supported by Godot.

AnimatedSprite is mostly used for characters, NPCs, interactive objects I think.

Perhaps we could add frames property (of type SpriteFrames) to the AnimatedTexture? In this case, we will have the same interface for editing AnimatedSprite2D, AnimatedSprite3D and AnimatedTexture frames. However, SpriteFrames is an animation library (contains multiple animations), and AnimatedTexture only needs one animation.

[KoBeWi]

AnimatedTexture can't really get new features, because it does the animation on the GPU and also it doesn't support texture atlases, unlike AnimatedSprite. They are 2 completely different things.

[TokageItLab]

Regardless of the naming for props, I think this is in a mergeable state for now, and as I mentioned in #69621, it would be better to merge this as long as we don't know where AnimationTexture is going to go in the future.

[TokageItLab]

Approved in the previous animation meeting. Breaks compat, should probably be mergeable, reduz' feedback doesn't seem like a blocker.

[YuriSizov]

Some suggestions and corrections for the documentation, as requested.

[dalexeev]

Note: The docs of other SpriteFrames methods should also be improved in the future.

[YuriSizov]

Docs are good now.

[akien-mga]

Thanks!

[dalexeev]

@TokageItLab @YuriSizov Thanks for your reviews!

[FeralBytes]

Latest documentation is not good, https://docs.godotengine.org/en/latest/classes/class_spriteframes.html still has a method of get_frame() but should be get_frame_texture(). This was merged for beta11.

[dalexeev]

Latest documentation is not good, https://docs.godotengine.org/en/latest/classes/class_spriteframes.html still has a method of get_frame() but should be get_frame_texture().

As far as I know, the docs on the website is updated with some delay.

[dalexeev]

Doesn't break compatibility (see godotengine/godot-proposals#2214 (comment)):

godot/scene/resources/sprite_frames.cpp

Lines 204 to 212 in 5034478

	#ifndef DISABLE_DEPRECATED
	// For compatibility.
	Ref<Resource> res = frames[j];
	if (res.is_valid()) {
	Frame frame = { res, 1.0 };
	anim.frames.push_back(frame);
	continue;
	}
	#endif

[YuriSizov]

I would say that presence of compatibility code doesn't mean it doesn't break it. In this case it's tricky a bit, because DISABLE_DEPRECATED was added in #73741, not in this PR. So technically this PR just supports 2 formats, and #73741 breaks compatibility.

The point is that such compatibility code is temporary and optional.

[dalexeev]

The frames property was renamed to sprite_frames not in this PR, but in #71907 (diff). The data loss on conversion fixed in #73741 was a consequence of how the converter works (regexp based approach), not this PR or #71907 (it has a compatibility code, diff).

The point is that such compatibility code is temporary and optional.

If we consider the code inside #ifndef DISABLE_DEPRECATED as temporary and "non-existent", then I agree with you.

[IsotoxalDev]

Please mention the unit of duration for the parameter in add_frame. get_frame_duration gives relative duration. Is the duration in add_frame also relative duration? Is it in seconds?