godot-docs/classes/class_animatedtexture.rst

:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the AnimatedTexture.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_AnimatedTexture:

AnimatedTexture
===============

**Inherits:** :ref:`Texture<class_Texture>` **<** :ref:`Resource<class_Resource>` **<** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`

Proxy texture for simple frame-based animations.

Description
-----------

``AnimatedTexture`` is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame. Unlike :ref:`AnimationPlayer<class_AnimationPlayer>` or :ref:`AnimatedSprite<class_AnimatedSprite>`, it isn't a :ref:`Node<class_Node>`, but has the advantage of being usable anywhere a :ref:`Texture<class_Texture>` resource can be used, e.g. in a :ref:`TileSet<class_TileSet>`.

The playback of the animation is controlled by the :ref:`fps<class_AnimatedTexture_property_fps>` property as well as each frame's optional delay (see :ref:`set_frame_delay<class_AnimatedTexture_method_set_frame_delay>`). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame.

``AnimatedTexture`` currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one.

**Note:** AnimatedTexture doesn't support using :ref:`AtlasTexture<class_AtlasTexture>`\ s. Each frame needs to be a separate :ref:`Texture<class_Texture>`.

Properties
----------

+---------------------------+--------------------------------------------------------------------+---------------------------+
| :ref:`int<class_int>`     | :ref:`current_frame<class_AnimatedTexture_property_current_frame>` |                           |
+---------------------------+--------------------------------------------------------------------+---------------------------+
| :ref:`int<class_int>`     | flags                                                              | ``0`` *(parent override)* |
+---------------------------+--------------------------------------------------------------------+---------------------------+
| :ref:`float<class_float>` | :ref:`fps<class_AnimatedTexture_property_fps>`                     | ``4.0``                   |
+---------------------------+--------------------------------------------------------------------+---------------------------+
| :ref:`int<class_int>`     | :ref:`frames<class_AnimatedTexture_property_frames>`               | ``1``                     |
+---------------------------+--------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`   | :ref:`oneshot<class_AnimatedTexture_property_oneshot>`             | ``false``                 |
+---------------------------+--------------------------------------------------------------------+---------------------------+
| :ref:`bool<class_bool>`   | :ref:`pause<class_AnimatedTexture_property_pause>`                 | ``false``                 |
+---------------------------+--------------------------------------------------------------------+---------------------------+

Methods
-------

+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>`     | :ref:`get_frame_delay<class_AnimatedTexture_method_get_frame_delay>` **(** :ref:`int<class_int>` frame **)** |const|                                    |
+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Texture<class_Texture>` | :ref:`get_frame_texture<class_AnimatedTexture_method_get_frame_texture>` **(** :ref:`int<class_int>` frame **)** |const|                                |
+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_frame_delay<class_AnimatedTexture_method_set_frame_delay>` **(** :ref:`int<class_int>` frame, :ref:`float<class_float>` delay **)**           |
+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                          | :ref:`set_frame_texture<class_AnimatedTexture_method_set_frame_texture>` **(** :ref:`int<class_int>` frame, :ref:`Texture<class_Texture>` texture **)** |
+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+

Constants
---------

.. _class_AnimatedTexture_constant_MAX_FRAMES:

- **MAX_FRAMES** = **256** --- The maximum number of frames supported by ``AnimatedTexture``. If you need more frames in your animation, use :ref:`AnimationPlayer<class_AnimationPlayer>` or :ref:`AnimatedSprite<class_AnimatedSprite>`.

Property Descriptions
---------------------

.. _class_AnimatedTexture_property_current_frame:

- :ref:`int<class_int>` **current_frame**

+----------+--------------------------+
| *Setter* | set_current_frame(value) |
+----------+--------------------------+
| *Getter* | get_current_frame()      |
+----------+--------------------------+

Sets the currently visible frame of the texture.

----

.. _class_AnimatedTexture_property_fps:

- :ref:`float<class_float>` **fps**

+-----------+----------------+
| *Default* | ``4.0``        |
+-----------+----------------+
| *Setter*  | set_fps(value) |
+-----------+----------------+
| *Getter*  | get_fps()      |
+-----------+----------------+

Animation speed in frames per second. This value defines the default time interval between two frames of the animation, and thus the overall duration of the animation loop based on the :ref:`frames<class_AnimatedTexture_property_frames>` property. A value of 0 means no predefined number of frames per second, the animation will play according to each frame's frame delay (see :ref:`set_frame_delay<class_AnimatedTexture_method_set_frame_delay>`).

For example, an animation with 8 frames, no frame delay and a ``fps`` value of 2 will run for 4 seconds, with each frame lasting 0.5 seconds.

----

.. _class_AnimatedTexture_property_frames:

- :ref:`int<class_int>` **frames**

+-----------+-------------------+
| *Default* | ``1``             |
+-----------+-------------------+
| *Setter*  | set_frames(value) |
+-----------+-------------------+
| *Getter*  | get_frames()      |
+-----------+-------------------+

Number of frames to use in the animation. While you can create the frames independently with :ref:`set_frame_texture<class_AnimatedTexture_method_set_frame_texture>`, you need to set this value for the animation to take new frames into account. The maximum number of frames is :ref:`MAX_FRAMES<class_AnimatedTexture_constant_MAX_FRAMES>`.

----

.. _class_AnimatedTexture_property_oneshot:

- :ref:`bool<class_bool>` **oneshot**

+-----------+--------------------+
| *Default* | ``false``          |
+-----------+--------------------+
| *Setter*  | set_oneshot(value) |
+-----------+--------------------+
| *Getter*  | get_oneshot()      |
+-----------+--------------------+

If ``true``, the animation will only play once and will not loop back to the first frame after reaching the end. Note that reaching the end will not set :ref:`pause<class_AnimatedTexture_property_pause>` to ``true``.

----

.. _class_AnimatedTexture_property_pause:

- :ref:`bool<class_bool>` **pause**

+-----------+------------------+
| *Default* | ``false``        |
+-----------+------------------+
| *Setter*  | set_pause(value) |
+-----------+------------------+
| *Getter*  | get_pause()      |
+-----------+------------------+

If ``true``, the animation will pause where it currently is (i.e. at :ref:`current_frame<class_AnimatedTexture_property_current_frame>`). The animation will continue from where it was paused when changing this property to ``false``.

Method Descriptions
-------------------

.. _class_AnimatedTexture_method_get_frame_delay:

- :ref:`float<class_float>` **get_frame_delay** **(** :ref:`int<class_int>` frame **)** |const|

Returns the given frame's delay value.

----

.. _class_AnimatedTexture_method_get_frame_texture:

- :ref:`Texture<class_Texture>` **get_frame_texture** **(** :ref:`int<class_int>` frame **)** |const|

Returns the given frame's :ref:`Texture<class_Texture>`.

----

.. _class_AnimatedTexture_method_set_frame_delay:

- void **set_frame_delay** **(** :ref:`int<class_int>` frame, :ref:`float<class_float>` delay **)**

Sets an additional delay (in seconds) between this frame and the next one, that will be added to the time interval defined by :ref:`fps<class_AnimatedTexture_property_fps>`. By default, frames have no delay defined. If a delay value is defined, the final time interval between this frame and the next will be ``1.0 / fps + delay``.

For example, for an animation with 3 frames, 2 FPS and a frame delay on the second frame of 1.2, the resulting playback will be:

::

    Frame 0: 0.5 s (1 / fps)
    Frame 1: 1.7 s (1 / fps + 1.2)
    Frame 2: 0.5 s (1 / fps)
    Total duration: 2.7 s

----

.. _class_AnimatedTexture_method_set_frame_texture:

- void **set_frame_texture** **(** :ref:`int<class_int>` frame, :ref:`Texture<class_Texture>` texture **)**

Assigns a :ref:`Texture<class_Texture>` to the given frame. Frame IDs start at 0, so the first frame has ID 0, and the last frame of the animation has ID :ref:`frames<class_AnimatedTexture_property_frames>` - 1.

You can define any number of textures up to :ref:`MAX_FRAMES<class_AnimatedTexture_constant_MAX_FRAMES>`, but keep in mind that only frames from 0 to :ref:`frames<class_AnimatedTexture_property_frames>` - 1 will be part of the animation.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`