From 5a185cb0cfe48af946952c82ef2dcd7be6656ad3 Mon Sep 17 00:00:00 2001
From: skyace65 <matthewehr@hotmail.com>
Date: Sun, 16 Feb 2025 21:01:03 -0500
Subject: [PATCH] Document animation markers

---
 .../img/animation_marker_click_area.webp      | Bin 0 -> 992 bytes
 .../img/animation_marker_selected.webp        | Bin 0 -> 998 bytes
 tutorials/animation/introduction.rst          |  37 ++++++++++++++++++
 3 files changed, 37 insertions(+)
 create mode 100644 tutorials/animation/img/animation_marker_click_area.webp
 create mode 100644 tutorials/animation/img/animation_marker_selected.webp

diff --git a/tutorials/animation/img/animation_marker_click_area.webp b/tutorials/animation/img/animation_marker_click_area.webp
new file mode 100644
index 0000000000000000000000000000000000000000..d67882ab884daa7310655bb34cae4554a1aef448
GIT binary patch
literal 992
zcmV<610VcSNk&H40{{S5MM6+kP&iD?0{{Ro(ZLn~wMeqHZEc&yl=l%ZvmItM225cx
zYF=*VJ>3A0!#K;d`{*nUzSYr@OMx$u%ov6WV%tWNq`oKrghzBiXd6k8oV@uhXNKDM
zpMl#(irhVBh9`Xg|Nl*zG8dZW5I9Hpwd8~Q;9tCy^>&-yX113m7gD9$M`WPPHAsX2
zE@TB$UQHRL7^EMiu$sh7Re)@gBuVN9NLOwpqF9A<Ds4(#;b`PbctUuj2~P4nm9SA!
zIIrj9)~fb=_B}NqZH?g*RHZvYi*#kuI8I;`)kke5^%}w>s0%S*NC{_j%I6ir(IrTm
z)RMXK!b#`z`Fvd+tAjH_pR%fQGX(Am6EoTvG=@Vkidx)f6_H)@H@R?H)GAW}Yg^Km
zF|cddA`wYmqNM^L`PC%s9o9o<e!>m8hdu}=Y}FyEt|E-F7-U6cP-IR}TC{RY6UikV
zA@`U`c-``YR9<?G(J7#Umv&JQq{Ar^qMZ|%%g8ipl!y(Y6P8j@?tpsnA#>AS?1C{@
zgaT28k~tIya~l!S{5}_Kb`YXkKqEvswyFTsi5tSw>sD8_5<S4Ei<v<*`ft}H87LbA
z5Ku++kqcr|0rw~g(;||UGt5|m;$)NgTaLxjBUnX1>g4Nc6nAihF=U0bCAZ9^QH+r^
zMO2}psgPuDm}((4<g7JzCF+7(%bJ?9tKhUnx<P5y=8jgeS9%zS(9Z^aF(blwNirsi
zQqm_Zg(PjE=t@!+5e29bQisMU0BI8ChR9UMY9UY4f>ENZP~<g#vx>-`#eH(I)?vvm
zLeoo1!l<KDKA#WKBz0j~6s4k2GGVeriektEWdfWMkg#cP=N4gK_x#{y^o$Q%tJ?Hw
zdpX2brE4z+ZA4ZmmTHY&sxsG*hJc=U*bb%ArV?vv0vouEvMOM=+PF0c0UZUVvY^K!
zOc$k6w-WM#IVfplRRq0oO0Q;i-}Lr+;;dCy%xp?^P%iugC(0BqN~|R-cLLmvTf53#
zoMg8Ggm9w_P<f5hDeOnq?I5{a(IA4chOvZ4dc~sullT3{8Ge)IUM~jCzW?_9x9`8d
zo;>_s44Qraaf~P5d;Gna^T<Ex4O%hI!*JV?zZ;&Fcb4C|;bVo%j{M!>+Wo%0pRjs|
zmlf_h@{hhZWd8+05Z2%C-M%65_`Kh@{*EAQ6u&*}vBl%w*ZUJTW%16i_`8uT-4QnB
z^BvaA;9<`{H$SAjB=}f2XC3+YplxhO$~RBG%gg4>T}M7XXv_Coy2H~dE<5t^tk3va
O#l9mSgJ$1<9N`p>q~gi|

literal 0
HcmV?d00001

diff --git a/tutorials/animation/img/animation_marker_selected.webp b/tutorials/animation/img/animation_marker_selected.webp
new file mode 100644
index 0000000000000000000000000000000000000000..581b8ef01ae296a674dc5f01ead29924c25e8efa
GIT binary patch
literal 998
zcmV<C0~!2MNk&HA0{{S5MM6+kP&iD{0{{RoMZp#Tl}NI+ZEc&iq})9;W_Fl4F$9f4
zm6@4&-qR`5IE=GQyA?r5uc$1U{_`8*NRs4Qc{e~_08FZ{j;pm+?h8DE13VLRr)J?c
zlH^EMwR4?W(?%TCZccs9nf(2C;5L#Xx#nQGwK)3)hZCQH5>)Lm+%8Q(L4j8u**U!Y
zzbh8Moqg-YVllF_-%H^Rr-)H+v?5fZ8V{}TN>uZq6<se;4T$PG{UesY^17LA=9=f?
zHCU~c6M9WAX<R)Ov__l^egJb~ASPfUbVeu#gu*zLq=LbYNH5#ZP0)nPuhwIMayw6J
zz%*1^%sGuIm<uBir@)+;fL5@h8PiZBVF0XX!vG8ekgu}bHEIkaViqS}10M*LXBEqg
zk>JBPfCZr~!UvMUkCfJc4iqqJ6K{p(HI;yY8!?Px1!HTZ3Banx@z4-QLwYE<0IDCt
zV8(PXb^}mU7aD%K#jd!b)l{x%hk<H`K%g`cu<SS)hQI-4tVBZ*sn{QqRH-XcpqL6Q
zP6$};w2m4B$q!?}jBsw840hya_aIU|MniM#hIpt0paCNs2pX*1DUBKfDj4$<fsp(p
z6$T_H=B-F6jfYwQvf~60N<CP#BaXMSI4KxLq+IU8&Z3{zh%vBiNVp`a#%M?A=wzrz
zmIcdB1oDGmZMqMED|(`znxF}pFU|ATK=M`2=(IK&E}jauw+|nnoiR>%(Sd<D6ey4d
zlc7Bl(h(EEj6lB1i*~+iwt3n53{-dJMk`21DR0#$cEor{Qh{Ja=we<Rf+Xa^(T!U1
z{r#ugsrB~m^j{EWTMCESmT>2kl}yj~o$2YFOV`hx;>i*&J>PeKVvGG<9$bE#-<}9D
zeLdfQ_#PQ&g)>~2qUr025cAt}F8+H_vVQ8Rb=|%BE2Qr{|1#TBynZUPU9+aIC-d9$
z-J8Et>rGC*eN1CNO4HllWfSu=P~tPA1|&Dub#YrwuuZ~X;8QYC(e*tResQ}NMBI=2
zt7V#cQ$>^^tUZ=hcT8Ty{P*8~|NX7u&}f;a(Rtt`$`IBb%W60xFJk^l?&#<vqg9?%
zj>6IE6T)al-AUvqluxy5%UE4TDWmG7aTLn>#@v1^TY7yCwy8Nu9EHQ9Pf8`tWpmly
zbe%Mk%zZs^s4|3=-COSMlG!$IyEd1>9tEy3a;REtN2<TiU0RUkIZhdE;B>h%hwvzT
zokR2$9I9s85^r@G)0$E70cjkCqoYp<S8#TwJvyeEkKXN30JPP)t<0gPRDH2s9tA`r
UGm=vGe(G+Hf>wNg|HrsI02Z>`F8}}l

literal 0
HcmV?d00001

diff --git a/tutorials/animation/introduction.rst b/tutorials/animation/introduction.rst
index ca72c26db..8d63c6d31 100644
--- a/tutorials/animation/introduction.rst
+++ b/tutorials/animation/introduction.rst
@@ -391,3 +391,40 @@ is being animated in its previous positions in the animation.
 The three dots button next to the onion skinning button opens a dropdown
 menu that lets you adjust how it works, including the ability to use
 onion skinning for future frames.
+
+Animation Markers
+-----------------
+
+Animation markers can be used to play a specific part of an animation rather than
+the whole thing. Here is a use case example, there's an animation file that has a
+character doing two distinct actions, and the project requires the whole animation,
+as well as both actions individually. Instead of making two additional animations,
+markers can be placed on the timeline, and both actions can now be played
+individually.
+
+To add a marker to an animation right click the space above the timeline and select
+**Insert Marker...**.
+
+.. image:: img/animation_marker_click_area.webp
+
+All markers require a unique name within the animation. You can also set the color
+of the markers for improved organization.
+
+To play the part of the animation between two markers use the :ref:`play_section_with_markers()<class_AnimationPlayer_method_play_section_with_markers>`
+and :ref:`play_section_with_markers_backwards()<class_AnimationPlayer_method_play_section_with_markers_backwards>`
+methods. If no start marker is specified then the beginning of the animation is
+used, and if no end marker is specified, then the end of the animation is used.
+
+If the end marker is after the end of the animation then the ``AnimationPlayer`` will
+clamp the end of the section so it does not go past the end of the animation.
+
+To preview the animation between two markers use :kbd:`Shift + Click` to
+select the markers. When two are selected the space between them should be
+highlighted in red.
+
+.. image:: img/animation_marker_selected.webp
+
+Now all of the play animation buttons will act as if the selected
+area is the whole animation. **Play Animation from Start** will treat the first
+marker as the start of the animation, **Play Animation Backwards from End**
+will treat the second marker as the end, and so on.