Add markers to Animation

[chocola-mint]

Bugsquad edited:

• Closes Add a way to loop one section of an animation in AnimationPlayer godot-proposals#2159
• Closes Add markers and regions to Animation godot-proposals#8414
• Closes Allow for playback of only a specific section of an animation godot-proposals#8526

This PR introduces a marker system for Animations. Markers are keys that are inserted alongside the timeline, and can be used to play specific parts of animations. A pair of markers is called a section.

For the Animation resource class, there are now new methods to query marker information with.

For AnimationPlayer, there is now a new play_section method that can be used to specify a pair of markers that denote a playback section.

• When the start marker is set to an empty string, the system interprets it as the start of the original animation, and when the end marker is set to an empty string, the system interprets it as the end of the original animation.
  • The vanilla play method is equivalent to passing empty strings as start and end markers to play_section.
• Markers can be placed beyond the original animation's length, in which case the AnimationMixer effectively does nothing while playing the out-of-range part of the section. (FEEDBACK WELCOME: Is this behavior desirable?) The AnimationMixer will clamp the end of the section so it does not exceed the Animation's length.
• In the Animation editor, new markers can be inserted by right-clicking the timeline and then selecting a name through a dialog.
  • Names have to be unique. The validation panel in the dialog will alert the user and prevent them from creating a second marker with the same name.
• Select two markers and the section between them will be highlighted in red. Clicking play buttons will then make AnimationPlayer play the section.
  • play_section uses the original Animation's loop mode.

godot_anim_markers_v4_7.mp4

For AnimationTree, specifically AnimationNodeAnimation, Custom Timelines can now be configured using the Set Custom Timeline from Marker button.

• Clicking the button opens up a dialog that lets you select a start marker and an end marker. The start marker's time is copied to the timeline's start offset, and the end marker's time is copied to the timeline's length.

godot_anim_markers_v4_5.mp4

[joined72]

Exists the possibility to can loop a specific section only for a finite number of cycles?

[chocola-mint]

Exists the possibility to can loop a specific section only for a finite number of cycles?

It would be easily implementable by GDScript when/if #89525 gets merged.

[fire]

I'm interested in markers for animation, will try to review for Godot Engine 4.4.

[TokageItLab]

I had been discussing and supervising on discord with @chocola-mint before this was sent, so this PR should be quite clean in terms of architectural design.

I will test the behavior in more detail later, but I send feedback at this stage:

---

AnimationPlayer needs an api to set/unset section during playback. It corresponds to the enabling of the use custom timeline option in the AnimationNode in AnimationTree.

The API allows for A-B repeats in a Start-A-B animation, including the intro animation like Start-A-B-A-B-A-B... .

BTW sorry, since the use custom timeline option in AnimationNode is newly implemented and I found a problem with the offset being inverted. I have sent an urgent PR about this as #91822 and would appreciate it if you could take a look at it and proceed with the implementation.

---

The warning about duplicate names when adding markers is not needed. It should be consistent with the GUI when adding other animation resources.

↓

---

New icons for markers need to be added. How about the following?

Marker.zip

[chocola-mint]

AnimationPlayer needs an api to set/unset section during playback. It corresponds to the enabling of the use custom timeline option in the AnimationNode in AnimationTree.

AnimationPlayer::set_current_section lets the user change the current section during playback. To avoid issues with pingpong playback, the current animation position is clamped to the new section.

The warning about duplicate names when adding markers is not needed. It should be consistent with the GUI when adding other animation resources.

godot_anim_markers_v4_8.mp4

[TokageItLab]

For usability, can the marker name be displayed in tool tip when focused? Also, it would be helpful to have a shortcut such as ctrl+m (or other shortcut is fine as well as it doesn't conflict) to display the name under the all markers.

[Calinou]

For usability, can the marker name be displayed in tool tip when focused? Also, it would be helpful to have a shortcut such as ctrl+m (or other shortcut is fine as well as it doesn't conflict) to display the name under the all markers.

Markers could also be given a color (either random with a seed based on their name¹, or a custom color) so you can distinguish them from each other.

Footnotes

1. This approach is used by tags in the project manager. ↩

[chocola-mint]

godot_anim_markers_v4_9.mp4

(Shortcut: Key M when AnimationMarkerEdit is focused)
(Marker colors are derived from name hashes)

As it's not possible to force the tooltip to show up on demand, I've opted to just draw the markers' names beneath their marker keys. Would this work?

As AnimationMarkerEdit is currently a descendant of AnimationTimelineEdit in the scene tree, it will be drawn before other AnimationTracks, and so the marker names will get darkened by AnimationTrack groups. I haven't figured out a workaround for this yet, unfortunately.

[SatLess]

This is looking pretty neat and it's really exciting having markers in Godot. Also, these are more cosmetic suggestions, but I think they would be nice additions:

• being able so select which color the marker is when creating them (or after, in the dropdown menu with the mouse on it) — allows color-coding markers for better organization.
• Using a more blue-ish color for highlighting sections — it would fit more with Godot's color scheme.
• Have markers' names displayed only by using shortcut and the dropdown option — This makes it so it shows up only when necessary.

[TokageItLab]

Using a more blue-ish color for highlighting sections — it would fit more with Godot's color scheme.

I don't think this needs to be changed since we are already using the same color code as the animation key; Perhaps currently it have used multiplication for coloring, so it just has to be reverted back to the original color during the selection. In other words, coloring should only be done when it is not selected.

However, I agree with the rest.