class_animationplayer.rst 26 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394
  1. .. Generated automatically by doc/tools/makerst.py in Godot's source tree.
  2. .. DO NOT EDIT THIS FILE, but the AnimationPlayer.xml source instead.
  3. .. The source is found in doc/classes or modules/<name>/doc_classes.
  4. .. _class_AnimationPlayer:
  5. AnimationPlayer
  6. ===============
  7. **Inherits:** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
  8. **Category:** Core
  9. Brief Description
  10. -----------------
  11. Container and player of :ref:`Animation<class_Animation>` resources.
  12. Properties
  13. ----------
  14. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  15. | :ref:`String<class_String>` | :ref:`assigned_animation<class_AnimationPlayer_assigned_animation>` |
  16. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  17. | :ref:`String<class_String>` | :ref:`autoplay<class_AnimationPlayer_autoplay>` |
  18. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  19. | :ref:`String<class_String>` | :ref:`current_animation<class_AnimationPlayer_current_animation>` |
  20. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  21. | :ref:`float<class_float>` | :ref:`current_animation_length<class_AnimationPlayer_current_animation_length>` |
  22. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  23. | :ref:`float<class_float>` | :ref:`current_animation_position<class_AnimationPlayer_current_animation_position>` |
  24. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  25. | :ref:`bool<class_bool>` | :ref:`playback_active<class_AnimationPlayer_playback_active>` |
  26. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  27. | :ref:`float<class_float>` | :ref:`playback_default_blend_time<class_AnimationPlayer_playback_default_blend_time>` |
  28. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  29. | :ref:`AnimationProcessMode<enum_AnimationPlayer_AnimationProcessMode>` | :ref:`playback_process_mode<class_AnimationPlayer_playback_process_mode>` |
  30. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  31. | :ref:`float<class_float>` | :ref:`playback_speed<class_AnimationPlayer_playback_speed>` |
  32. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  33. | :ref:`NodePath<class_NodePath>` | :ref:`root_node<class_AnimationPlayer_root_node>` |
  34. +------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
  35. Methods
  36. -------
  37. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  38. | :ref:`Error<enum_@GlobalScope_Error>` | :ref:`add_animation<class_AnimationPlayer_add_animation>` **(** :ref:`String<class_String>` name, :ref:`Animation<class_Animation>` animation **)** |
  39. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  40. | void | :ref:`advance<class_AnimationPlayer_advance>` **(** :ref:`float<class_float>` delta **)** |
  41. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  42. | :ref:`String<class_String>` | :ref:`animation_get_next<class_AnimationPlayer_animation_get_next>` **(** :ref:`String<class_String>` anim_from **)** const |
  43. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  44. | void | :ref:`animation_set_next<class_AnimationPlayer_animation_set_next>` **(** :ref:`String<class_String>` anim_from, :ref:`String<class_String>` anim_to **)** |
  45. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  46. | void | :ref:`clear_caches<class_AnimationPlayer_clear_caches>` **(** **)** |
  47. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  48. | void | :ref:`clear_queue<class_AnimationPlayer_clear_queue>` **(** **)** |
  49. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  50. | :ref:`String<class_String>` | :ref:`find_animation<class_AnimationPlayer_find_animation>` **(** :ref:`Animation<class_Animation>` animation **)** const |
  51. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  52. | :ref:`Animation<class_Animation>` | :ref:`get_animation<class_AnimationPlayer_get_animation>` **(** :ref:`String<class_String>` name **)** const |
  53. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  54. | :ref:`PoolStringArray<class_PoolStringArray>` | :ref:`get_animation_list<class_AnimationPlayer_get_animation_list>` **(** **)** const |
  55. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  56. | :ref:`float<class_float>` | :ref:`get_blend_time<class_AnimationPlayer_get_blend_time>` **(** :ref:`String<class_String>` anim_from, :ref:`String<class_String>` anim_to **)** const |
  57. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  58. | :ref:`float<class_float>` | :ref:`get_playing_speed<class_AnimationPlayer_get_playing_speed>` **(** **)** const |
  59. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  60. | :ref:`PoolStringArray<class_PoolStringArray>` | :ref:`get_queue<class_AnimationPlayer_get_queue>` **(** **)** |
  61. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  62. | :ref:`bool<class_bool>` | :ref:`has_animation<class_AnimationPlayer_has_animation>` **(** :ref:`String<class_String>` name **)** const |
  63. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  64. | :ref:`bool<class_bool>` | :ref:`is_playing<class_AnimationPlayer_is_playing>` **(** **)** const |
  65. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  66. | void | :ref:`play<class_AnimationPlayer_play>` **(** :ref:`String<class_String>` name="", :ref:`float<class_float>` custom_blend=-1, :ref:`float<class_float>` custom_speed=1.0, :ref:`bool<class_bool>` from_end=false **)** |
  67. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  68. | void | :ref:`play_backwards<class_AnimationPlayer_play_backwards>` **(** :ref:`String<class_String>` name="", :ref:`float<class_float>` custom_blend=-1 **)** |
  69. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  70. | void | :ref:`queue<class_AnimationPlayer_queue>` **(** :ref:`String<class_String>` name **)** |
  71. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  72. | void | :ref:`remove_animation<class_AnimationPlayer_remove_animation>` **(** :ref:`String<class_String>` name **)** |
  73. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  74. | void | :ref:`rename_animation<class_AnimationPlayer_rename_animation>` **(** :ref:`String<class_String>` name, :ref:`String<class_String>` newname **)** |
  75. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  76. | void | :ref:`seek<class_AnimationPlayer_seek>` **(** :ref:`float<class_float>` seconds, :ref:`bool<class_bool>` update=false **)** |
  77. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  78. | void | :ref:`set_blend_time<class_AnimationPlayer_set_blend_time>` **(** :ref:`String<class_String>` anim_from, :ref:`String<class_String>` anim_to, :ref:`float<class_float>` sec **)** |
  79. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  80. | void | :ref:`stop<class_AnimationPlayer_stop>` **(** :ref:`bool<class_bool>` reset=true **)** |
  81. +------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  82. Signals
  83. -------
  84. .. _class_AnimationPlayer_animation_changed:
  85. - **animation_changed** **(** :ref:`String<class_String>` old_name, :ref:`String<class_String>` new_name **)**
  86. If the currently being played animation changes, this signal will notify of such change.
  87. .. _class_AnimationPlayer_animation_finished:
  88. - **animation_finished** **(** :ref:`String<class_String>` anim_name **)**
  89. Notifies when an animation finished playing.
  90. .. _class_AnimationPlayer_animation_started:
  91. - **animation_started** **(** :ref:`String<class_String>` anim_name **)**
  92. Notifies when an animation starts playing.
  93. .. _class_AnimationPlayer_caches_cleared:
  94. - **caches_cleared** **(** **)**
  95. Enumerations
  96. ------------
  97. .. _enum_AnimationPlayer_AnimationProcessMode:
  98. enum **AnimationProcessMode**:
  99. - **ANIMATION_PROCESS_PHYSICS** = **0** --- Process animation during the physics process. This is especially useful when animating physics bodies.
  100. - **ANIMATION_PROCESS_IDLE** = **1** --- Process animation during the idle process.
  101. - **ANIMATION_PROCESS_MANUAL** = **2** --- Do not process animation. Use the 'advance' method to process the animation manually.
  102. Description
  103. -----------
  104. An animation player is used for general purpose playback of :ref:`Animation<class_Animation>` resources. It contains a dictionary of animations (referenced by name) and custom blend times between their transitions. Additionally, animations can be played and blended in different channels.
  105. Tutorials
  106. ---------
  107. - :doc:`../getting_started/step_by_step/animations`
  108. - :doc:`../tutorials/animation/index`
  109. Property Descriptions
  110. ---------------------
  111. .. _class_AnimationPlayer_assigned_animation:
  112. - :ref:`String<class_String>` **assigned_animation**
  113. +----------+-------------------------------+
  114. | *Setter* | set_assigned_animation(value) |
  115. +----------+-------------------------------+
  116. | *Getter* | get_assigned_animation() |
  117. +----------+-------------------------------+
  118. If playing, the current animation; otherwise, the animation last played. When set, would change the animation, but would not play it unless currently playing. See also :ref:`current_animation<class_AnimationPlayer_current_animation>`.
  119. .. _class_AnimationPlayer_autoplay:
  120. - :ref:`String<class_String>` **autoplay**
  121. +----------+---------------------+
  122. | *Setter* | set_autoplay(value) |
  123. +----------+---------------------+
  124. | *Getter* | get_autoplay() |
  125. +----------+---------------------+
  126. The name of the animation to play when the scene loads. Default value: ``""``.
  127. .. _class_AnimationPlayer_current_animation:
  128. - :ref:`String<class_String>` **current_animation**
  129. +----------+------------------------------+
  130. | *Setter* | set_current_animation(value) |
  131. +----------+------------------------------+
  132. | *Getter* | get_current_animation() |
  133. +----------+------------------------------+
  134. The name of the current animation, "" if not playing anything. When being set, does not restart the animation. See also :ref:`play<class_AnimationPlayer_play>`. Default value: ``""``.
  135. .. _class_AnimationPlayer_current_animation_length:
  136. - :ref:`float<class_float>` **current_animation_length**
  137. +----------+--------------------------------+
  138. | *Getter* | get_current_animation_length() |
  139. +----------+--------------------------------+
  140. The length (in seconds) of the currently being played animation.
  141. .. _class_AnimationPlayer_current_animation_position:
  142. - :ref:`float<class_float>` **current_animation_position**
  143. +----------+----------------------------------+
  144. | *Getter* | get_current_animation_position() |
  145. +----------+----------------------------------+
  146. The position (in seconds) of the currently playing animation.
  147. .. _class_AnimationPlayer_playback_active:
  148. - :ref:`bool<class_bool>` **playback_active**
  149. +----------+-------------------+
  150. | *Setter* | set_active(value) |
  151. +----------+-------------------+
  152. | *Getter* | is_active() |
  153. +----------+-------------------+
  154. If ``true``, updates animations in response to process-related notifications. Default value: ``true``.
  155. .. _class_AnimationPlayer_playback_default_blend_time:
  156. - :ref:`float<class_float>` **playback_default_blend_time**
  157. +----------+-------------------------------+
  158. | *Setter* | set_default_blend_time(value) |
  159. +----------+-------------------------------+
  160. | *Getter* | get_default_blend_time() |
  161. +----------+-------------------------------+
  162. The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 precision. Default value: ``0``.
  163. .. _class_AnimationPlayer_playback_process_mode:
  164. - :ref:`AnimationProcessMode<enum_AnimationPlayer_AnimationProcessMode>` **playback_process_mode**
  165. +----------+-----------------------------------+
  166. | *Setter* | set_animation_process_mode(value) |
  167. +----------+-----------------------------------+
  168. | *Getter* | get_animation_process_mode() |
  169. +----------+-----------------------------------+
  170. The process notification in which to update animations. Default value: ``ANIMATION_PROCESS_IDLE``.
  171. .. _class_AnimationPlayer_playback_speed:
  172. - :ref:`float<class_float>` **playback_speed**
  173. +----------+------------------------+
  174. | *Setter* | set_speed_scale(value) |
  175. +----------+------------------------+
  176. | *Getter* | get_speed_scale() |
  177. +----------+------------------------+
  178. The speed scaling ratio. For instance, if this value is 1 then the animation plays at normal speed. If it's 0.5 then it plays at half speed. If it's 2 then it plays at double speed. Default value: ``1``.
  179. .. _class_AnimationPlayer_root_node:
  180. - :ref:`NodePath<class_NodePath>` **root_node**
  181. +----------+-----------------+
  182. | *Setter* | set_root(value) |
  183. +----------+-----------------+
  184. | *Getter* | get_root() |
  185. +----------+-----------------+
  186. The node from which node path references will travel. Default value: ``".."``.
  187. Method Descriptions
  188. -------------------
  189. .. _class_AnimationPlayer_add_animation:
  190. - :ref:`Error<enum_@GlobalScope_Error>` **add_animation** **(** :ref:`String<class_String>` name, :ref:`Animation<class_Animation>` animation **)**
  191. Adds ``animation`` to the player accessible with the key ``name``.
  192. .. _class_AnimationPlayer_advance:
  193. - void **advance** **(** :ref:`float<class_float>` delta **)**
  194. Shifts position in the animation timeline. Delta is the time in seconds to shift.
  195. .. _class_AnimationPlayer_animation_get_next:
  196. - :ref:`String<class_String>` **animation_get_next** **(** :ref:`String<class_String>` anim_from **)** const
  197. Returns the name of the next animation in the queue.
  198. .. _class_AnimationPlayer_animation_set_next:
  199. - void **animation_set_next** **(** :ref:`String<class_String>` anim_from, :ref:`String<class_String>` anim_to **)**
  200. Triggers the ``anim_to`` animation when the ``anim_from`` animation completes.
  201. .. _class_AnimationPlayer_clear_caches:
  202. - void **clear_caches** **(** **)**
  203. ``AnimationPlayer`` caches animated nodes. It may not notice if a node disappears, so clear_caches forces it to update the cache again.
  204. .. _class_AnimationPlayer_clear_queue:
  205. - void **clear_queue** **(** **)**
  206. Clears all queued, unplayed animations.
  207. .. _class_AnimationPlayer_find_animation:
  208. - :ref:`String<class_String>` **find_animation** **(** :ref:`Animation<class_Animation>` animation **)** const
  209. Returns the name of ``animation`` or empty string if not found.
  210. .. _class_AnimationPlayer_get_animation:
  211. - :ref:`Animation<class_Animation>` **get_animation** **(** :ref:`String<class_String>` name **)** const
  212. Returns the :ref:`Animation<class_Animation>` with key ``name`` or ``null`` if not found.
  213. .. _class_AnimationPlayer_get_animation_list:
  214. - :ref:`PoolStringArray<class_PoolStringArray>` **get_animation_list** **(** **)** const
  215. Returns the list of stored animation names.
  216. .. _class_AnimationPlayer_get_blend_time:
  217. - :ref:`float<class_float>` **get_blend_time** **(** :ref:`String<class_String>` anim_from, :ref:`String<class_String>` anim_to **)** const
  218. Get the blend time (in seconds) between two animations, referenced by their names.
  219. .. _class_AnimationPlayer_get_playing_speed:
  220. - :ref:`float<class_float>` **get_playing_speed** **(** **)** const
  221. Get the actual playing speed of current animation or 0 if not playing. This speed is the ``playback_speed`` property multiplied by ``custom_speed`` argument specified when calling the ``play`` method.
  222. .. _class_AnimationPlayer_get_queue:
  223. - :ref:`PoolStringArray<class_PoolStringArray>` **get_queue** **(** **)**
  224. .. _class_AnimationPlayer_has_animation:
  225. - :ref:`bool<class_bool>` **has_animation** **(** :ref:`String<class_String>` name **)** const
  226. Returns ``true`` if the ``AnimationPlayer`` stores an :ref:`Animation<class_Animation>` with key ``name``.
  227. .. _class_AnimationPlayer_is_playing:
  228. - :ref:`bool<class_bool>` **is_playing** **(** **)** const
  229. Returns ``true`` if playing an animation.
  230. .. _class_AnimationPlayer_play:
  231. - void **play** **(** :ref:`String<class_String>` name="", :ref:`float<class_float>` custom_blend=-1, :ref:`float<class_float>` custom_speed=1.0, :ref:`bool<class_bool>` from_end=false **)**
  232. Play the animation with key ``name``. Custom speed and blend times can be set. If custom speed is negative (-1), 'from_end' being true can play the animation backwards.
  233. .. _class_AnimationPlayer_play_backwards:
  234. - void **play_backwards** **(** :ref:`String<class_String>` name="", :ref:`float<class_float>` custom_blend=-1 **)**
  235. Play the animation with key ``name`` in reverse.
  236. .. _class_AnimationPlayer_queue:
  237. - void **queue** **(** :ref:`String<class_String>` name **)**
  238. Queue an animation for playback once the current one is done.
  239. .. _class_AnimationPlayer_remove_animation:
  240. - void **remove_animation** **(** :ref:`String<class_String>` name **)**
  241. Remove the animation with key ``name``.
  242. .. _class_AnimationPlayer_rename_animation:
  243. - void **rename_animation** **(** :ref:`String<class_String>` name, :ref:`String<class_String>` newname **)**
  244. Rename an existing animation with key ``name`` to ``newname``.
  245. .. _class_AnimationPlayer_seek:
  246. - void **seek** **(** :ref:`float<class_float>` seconds, :ref:`bool<class_bool>` update=false **)**
  247. Seek the animation to the ``seconds`` point in time (in seconds). If ``update`` is ``true``, the animation updates too, otherwise it updates at process time.
  248. .. _class_AnimationPlayer_set_blend_time:
  249. - void **set_blend_time** **(** :ref:`String<class_String>` anim_from, :ref:`String<class_String>` anim_to, :ref:`float<class_float>` sec **)**
  250. Specify a blend time (in seconds) between two animations, referenced by their names.
  251. .. _class_AnimationPlayer_stop:
  252. - void **stop** **(** :ref:`bool<class_bool>` reset=true **)**
  253. Stop the currently playing animation. If ``reset`` is ``true``, the anim position is reset to ``0``.