Add capture(real_t p_time) function to AnimationMixer

[TokageItLab]

Describe the project you are working on

Godot Animation features stabilization

Describe the problem or limitation you are having in your project

Related: godotengine/godot#83166

Capture mode has not worked since godotengine/godot#80813. However, as described in godotengine/godot#55110, it had not been working correctly with AnimationTree for a long time. The reason for it is that the Capture mode is strongly dependent on the AnimationPlayer::play() function.

It is not working with AnimationTree because AnimationTree does not detect things like resuming playback, and neither does AnimationMixer, which is based on AnimationTree.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Revive Capture mode with more flexible control

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

Capture mode usually works the same way as Continuous mode.

The AnimationMixer::capture() function creates a single AnimationInstance by iterating over the tracks in the current track cache that have Capture mode set before blending and fetching the values.

The AnimationInstance remains for the number of seconds specified by p_time, and will be interpolated with the "final result of the blend when no Capture is present".

The implementation of this function allows wrapper functions such as AnimationPlayer::play_with_capture() and the following AnimationTree controls.

Fade with capture at any transition of AnimationStateMachine:

anim_tree.capture(0.2) 
state_machine_playback.next()

If this enhancement will not be used often, can it be worked around with a few lines of script?

No

Is there a reason why this should be core and not an add-on in the asset library?

It is core behavior

[golddotasksquestions]

A long standing ask from users is to create dynamic animations with the AnimationPlayer. If Capture Mode has been removed and needs to be completely reimplemented from scratch anyway, I wonder if this could be considered for implementation.

The way dynamic animations would work, is that the user could set an influence value (0.0 - 1.0) for each key. Default being 1.0 for total infulence, = current behaviour. Godot would then blend the current property value with the value of the current animation key according to the influence of the key.
Edit: On second thought, this might be much harder to implement (or even impossible due to accumulative values over time), so maybe leaning into this this accumulative approach would be a better idea, see #1191 (comment)

Usecases for this would be if I want to play an animation but want to mix dynamic content into the animation. For example a cut scene where I want Capture Mode like behaviour in the middle of an animation somewhere or the end. Capture Mode so far only covered this for the first "key" of the animation.
Another Usecase would by any animation I would want to blend with user control or other dynamic property changes. For example a object being animated running in circles around something else. If an external physics object would interfere, the animation key influence would allow to easily blend the static animation with the dynamic with minimal user effort.

There are other ways around that problem using tweens and extensive coding, but non of them provide the ease of use and the power of the AnimationPlayer of keying all kinds of properties visually on a timeline.

[TokageItLab]

The way dynamic animations would work, is that the user could set an influence value (0.0 - 1.0) for each key. Godot would then blend the current property value with the value of the current animation key according to the influence of the key.

It may be difficult to do immediately now, but with the implementation of the AnimationMixer, it should be a big step toward making that.

There are PR/proposals to apply blend values to each track:

• Add AnimationTrackFilter and implement filter as an AnimationNode's parameter. godot#76788
• Add amount option to animation track filter #7578

they should help specify the blend values for each track.

I still don't know how to go about implementing to blend AnimationPlayer values with no animation playing scene values:

It is easy to record the values for one frame only and blend them, such as using the capture() function as I described above.

However, if you always retrieve the values from the scene, you may end up duplicating the results of a previous values which were applied by a previous AnimationPlayer. We are currently looking for a better way for update timing for that by reworking IK.

Once some of the above pieces are in place, it will definitely be possible. So it is fine if there is a proposal for the future.