Implement AnimationMixer as a base class of AnimationPlayer and AnimationTree

[TokageItLab]

Implement godotengine/godot-proposals#5972.

Currently AnimationPlayer and AnimationTree have separate duplicate implementations of playback and blending, so implement the base class to unify them.

Internally, this is a major change, but most compatibility will be kept.

However, Changes to conflicting method and property names between AnimationPlayer and AnimationTree are unavoidable, since retaining only one of them will destroy compatibility with the other.

• AnimationPlayer.playback_active
• AnimationTree.active
  • -> AnimationMixer.active (but not change the setter/getter method since AnimationPlayer has already have the AnimationPlayer.set_active() as setter of AnimationPlayer.playback_active)
• AnimationPlayer.playback_process_mode
• AnimationTree.process_callback
  • -> AnimationMixer.callback_mode_process
• AnimationPlayer.method_call_mode
  • -> AnimationMixer.callback_mode_method (to follow above change to make group in the inspector)

Note: Old methods and property names will be kept for compatibility.

This change allows AnimationTree to have an AnimationLibrary. Also, when an AnimationTree is selected, a dummy AnimationPlayer is added to the editor internally.

If the AnimationTree specifies an AnimationPlayer, the dummy AnimationPlayer's resources will be referenced specified AnimationPlayer (make them read-only in AnimationTree).

Todo:

• Implement AnimationMixer to unify blend methods
• Control active property between dummy player and selected node
• Implement blending algorithm which is not needed for RESET tracks for compatibility with old AnimationPlayer blending: Added Deterministic option, see comment
• New/Re-implement "reset on save" for AnimationMixer (as mentioned in Convert to Godot 4.1, remove binary data from scene files, prevent spurious diffs, and fix load warnings gdquest-demos/godot-4-3d-third-person-controller#30 (comment))
• Rework AnimationPlaybackTrack to fix AnimationTree does not stop playing looping AnimationPlayer's Animation Playback tracks #70338 Will do it later as a separate PR

---

• Closes RESET alters parameters during animation tree transition #82135
• Closes Unused parameters get reset to 0 when animated by an active AnimationNodeStateMachine AnimationTree despite nothing explicitly defining them. #80971
• Closes CanvasItem-parameters set to unexpected defaults on RESET/AnimationTree's state transition unless explicitly set in RESET #73571
• Closes AnimationPlayer blending and AnimationTree blending are inconsistent #70207
• Closes Strange animation rotation when combining "default blend time" and angular interpolation #79020
• Closes Animation Player resetting main spine rotation when playing animation #70123
• Closes Audio track key end_offset does not work when it exists outside the animation length #75197

[TokageItLab]

For compatibility, the old setters and getters have been added. It means that some internal properties will have two property names, setters and getters.

@reduz has rejected this and suggested implementing separate property names, setters and getters for AnimationPlayer and AnimationTree, but I disagree strongly with that.

It makes the result in missing properties during interconversion between AnimationPlayer and AnimationTree. This causes problems with the "Change type" option of the SceneTreeDock and the creation of the DummyPlayer (these use set(prop.name, prop.value) iteratively). So we must have at least one shared property name.

For that, @reduz suggested putting an option in AnimationPlayerEditor, but honestly it's confusing and there is no need to ignore SceneTreeDock.

Having two property names, setters and getters is certainly redundant, but I argue that redundancy is far better than going the inconvenient way and having a method that only those who have read the manuals can understand.

Edited:
On Rocket chat we agreed on redundancy for this case.

[YuriSizov]

Just to be clear, this is still a breaking compatibility change because the inheritance chain is modified. This may or may not be an issue for 3rd party language bindings. And we may or may not accept it as allowed.

[TokageItLab]

What I remember for about reset_on_save is if there is no reset animation, I think it is made to use the initial (mostly zero) value to avoid updating the scene file. If you disable reset_on_save, does that mean that onion skin will work? And for onion skin, does it mean that reset_on_save is not available?

[RandomShaper]

Unless it changed after I implemented it, reset-on-save would only work in AnimationPlayers having a reset animation. Without such an animation, the feature is no-op.

The problem with onion skinning is that it works like this:

• Save all current values for every track and the current position (time).
• For every step, seek to the relevant time, render and take screenshot.
• Seek back to the original position and restore the backup.

It didn't require a reset animation, nor it it fitting for this purpose the way I envisioned it, because the current values in the animated properties may not even be the ones in the animation. For instance, say you have a Node2D animated such as its X position moves from 0 to 100 in some track. The current animation at the current time sets position to 50. The user drags the node manually to 15 and then enables onion skinning. After all the process involved (done on every frame), the user wants to still see the position is 15. The fact that seeking the AnimationPlayer is being used under the hood to capture the onion layers is kept hidden and unnoticed to the user.

With the reset animation there are a couple of downsides:

1. Well, you need to have a proper reset animation involving all the values that you want to behave correctly in the onion layers.
2. The onion skinning internal machinery is no longer hidden, since, the second you enable it, properties the user may have modified manually will be reset to the values mandated by the animation.

Neither is the end of the world, and I think that is good enough to bring onion skinning back to life. However, as I said, I'd like it to work as transparently (no pun intended) as it used to do in a future iteration.