Files
godot-docs/classes/class_animationnodeblendspace1d.rst
2026-04-18 04:07:54 +00:00

469 lines
26 KiB
ReStructuredText

:github_url: hide
.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AnimationNodeBlendSpace1D.xml.
.. _class_AnimationNodeBlendSpace1D:
AnimationNodeBlendSpace1D
=========================
**Inherits:** :ref:`AnimationRootNode<class_AnimationRootNode>` **<** :ref:`AnimationNode<class_AnimationNode>` **<** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
A set of :ref:`AnimationRootNode<class_AnimationRootNode>`\ s placed on a virtual axis, crossfading between the two adjacent ones. Used by :ref:`AnimationTree<class_AnimationTree>`.
.. rst-class:: classref-introduction-group
Description
-----------
A resource used by :ref:`AnimationNodeBlendTree<class_AnimationNodeBlendTree>`.
\ **AnimationNodeBlendSpace1D** represents a virtual axis on which any type of :ref:`AnimationRootNode<class_AnimationRootNode>`\ s can be added using :ref:`add_blend_point()<class_AnimationNodeBlendSpace1D_method_add_blend_point>`. Outputs the linear blend of the two :ref:`AnimationRootNode<class_AnimationRootNode>`\ s adjacent to the current value.
You can set the extents of the axis with :ref:`min_space<class_AnimationNodeBlendSpace1D_property_min_space>` and :ref:`max_space<class_AnimationNodeBlendSpace1D_property_max_space>`.
.. rst-class:: classref-introduction-group
Tutorials
---------
- :doc:`Using AnimationTree <../tutorials/animation/animation_tree>`
.. rst-class:: classref-reftable-group
Properties
----------
.. table::
:widths: auto
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>` | :ref:`blend_mode<class_AnimationNodeBlendSpace1D_property_blend_mode>` | ``0`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`float<class_float>` | :ref:`cyclic_length<class_AnimationNodeBlendSpace1D_property_cyclic_length>` | ``0.0`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`float<class_float>` | :ref:`max_space<class_AnimationNodeBlendSpace1D_property_max_space>` | ``1.0`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`float<class_float>` | :ref:`min_space<class_AnimationNodeBlendSpace1D_property_min_space>` | ``-1.0`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`float<class_float>` | :ref:`snap<class_AnimationNodeBlendSpace1D_property_snap>` | ``0.1`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`bool<class_bool>` | :ref:`sync<class_AnimationNodeBlendSpace1D_property_sync>` | |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` | :ref:`sync_mode<class_AnimationNodeBlendSpace1D_property_sync_mode>` | ``0`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
| :ref:`String<class_String>` | :ref:`value_label<class_AnimationNodeBlendSpace1D_property_value_label>` | ``"value"`` |
+------------------------------------------------------------+------------------------------------------------------------------------------+-------------+
.. rst-class:: classref-reftable-group
Methods
-------
.. table::
:widths: auto
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`add_blend_point<class_AnimationNodeBlendSpace1D_method_add_blend_point>`\ (\ node\: :ref:`AnimationRootNode<class_AnimationRootNode>`, pos\: :ref:`float<class_float>`, at_index\: :ref:`int<class_int>` = -1, name\: :ref:`StringName<class_StringName>` = &""\ ) |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`find_blend_point_by_name<class_AnimationNodeBlendSpace1D_method_find_blend_point_by_name>`\ (\ name\: :ref:`StringName<class_StringName>`\ ) |const| |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`get_blend_point_count<class_AnimationNodeBlendSpace1D_method_get_blend_point_count>`\ (\ ) |const| |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`StringName<class_StringName>` | :ref:`get_blend_point_name<class_AnimationNodeBlendSpace1D_method_get_blend_point_name>`\ (\ point\: :ref:`int<class_int>`\ ) |const| |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`AnimationRootNode<class_AnimationRootNode>` | :ref:`get_blend_point_node<class_AnimationNodeBlendSpace1D_method_get_blend_point_node>`\ (\ point\: :ref:`int<class_int>`\ ) |const| |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_blend_point_position<class_AnimationNodeBlendSpace1D_method_get_blend_point_position>`\ (\ point\: :ref:`int<class_int>`\ ) |const| |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`remove_blend_point<class_AnimationNodeBlendSpace1D_method_remove_blend_point>`\ (\ point\: :ref:`int<class_int>`\ ) |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`reorder_blend_point<class_AnimationNodeBlendSpace1D_method_reorder_blend_point>`\ (\ from_index\: :ref:`int<class_int>`, to_index\: :ref:`int<class_int>`\ ) |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`set_blend_point_name<class_AnimationNodeBlendSpace1D_method_set_blend_point_name>`\ (\ point\: :ref:`int<class_int>`, name\: :ref:`StringName<class_StringName>`\ ) |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`set_blend_point_node<class_AnimationNodeBlendSpace1D_method_set_blend_point_node>`\ (\ point\: :ref:`int<class_int>`, node\: :ref:`AnimationRootNode<class_AnimationRootNode>`\ ) |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |void| | :ref:`set_blend_point_position<class_AnimationNodeBlendSpace1D_method_set_blend_point_position>`\ (\ point\: :ref:`int<class_int>`, pos\: :ref:`float<class_float>`\ ) |
+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Enumerations
------------
.. _enum_AnimationNodeBlendSpace1D_BlendMode:
.. rst-class:: classref-enumeration
enum **BlendMode**: :ref:`🔗<enum_AnimationNodeBlendSpace1D_BlendMode>`
.. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_INTERPOLATED:
.. rst-class:: classref-enumeration-constant
:ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>` **BLEND_MODE_INTERPOLATED** = ``0``
The interpolation between animations is linear.
.. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE:
.. rst-class:: classref-enumeration-constant
:ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>` **BLEND_MODE_DISCRETE** = ``1``
The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations.
.. _class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE_CARRY:
.. rst-class:: classref-enumeration-constant
:ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>` **BLEND_MODE_DISCRETE_CARRY** = ``2``
Similar to :ref:`BLEND_MODE_DISCRETE<class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE>`, but starts the new animation at the last animation's playback position.
.. rst-class:: classref-item-separator
----
.. _enum_AnimationNodeBlendSpace1D_SyncMode:
.. rst-class:: classref-enumeration
enum **SyncMode**: :ref:`🔗<enum_AnimationNodeBlendSpace1D_SyncMode>`
.. _class_AnimationNodeBlendSpace1D_constant_SYNC_MODE_NONE:
.. rst-class:: classref-enumeration-constant
:ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` **SYNC_MODE_NONE** = ``0``
Inactive animations are frozen and do not advance.
.. _class_AnimationNodeBlendSpace1D_constant_SYNC_MODE_INDEPENDENT:
.. rst-class:: classref-enumeration-constant
:ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` **SYNC_MODE_INDEPENDENT** = ``1``
Inactive animations advance with a weight of ``0``. This is equivalent to the previous ``sync = true`` behavior.
.. _class_AnimationNodeBlendSpace1D_constant_SYNC_MODE_CYCLIC_MUTABLE:
.. rst-class:: classref-enumeration-constant
:ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` **SYNC_MODE_CYCLIC_MUTABLE** = ``2``
All animations are time-scaled so they stay in sync, with the cycle length dynamically computed from active blend weights. This is self-normalizing: a solo animation plays at normal speed.
\ **Note:** If you apply :ref:`AnimationNodeTimeSeek<class_AnimationNodeTimeSeek>` to the result when handling animations of different lengths, synchronization will be broken. In such cases, it is recommended to use :ref:`AnimationNodeAnimation.use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` to align the animation lengths.
.. _class_AnimationNodeBlendSpace1D_constant_SYNC_MODE_CYCLIC_CONSTANT:
.. rst-class:: classref-enumeration-constant
:ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` **SYNC_MODE_CYCLIC_CONSTANT** = ``3``
All animations are time-scaled so they complete one cycle in :ref:`cyclic_length<class_AnimationNodeBlendSpace1D_property_cyclic_length>` seconds, keeping them in sync regardless of their individual lengths.
\ **Note:** If you apply :ref:`AnimationNodeTimeSeek<class_AnimationNodeTimeSeek>` to the result when handling animations of different lengths, synchronization will be broken. In such cases, it is recommended to use :ref:`AnimationNodeAnimation.use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` to align the animation lengths.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Property Descriptions
---------------------
.. _class_AnimationNodeBlendSpace1D_property_blend_mode:
.. rst-class:: classref-property
:ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>` **blend_mode** = ``0`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_blend_mode>`
.. rst-class:: classref-property-setget
- |void| **set_blend_mode**\ (\ value\: :ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>`\ )
- :ref:`BlendMode<enum_AnimationNodeBlendSpace1D_BlendMode>` **get_blend_mode**\ (\ )
Controls the interpolation between animations.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_cyclic_length:
.. rst-class:: classref-property
:ref:`float<class_float>` **cyclic_length** = ``0.0`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_cyclic_length>`
.. rst-class:: classref-property-setget
- |void| **set_cyclic_length**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_cyclic_length**\ (\ )
The cycle length in seconds used by :ref:`SYNC_MODE_CYCLIC_CONSTANT<class_AnimationNodeBlendSpace1D_constant_SYNC_MODE_CYCLIC_CONSTANT>`. All animations are time-scaled so they complete one full cycle in this duration. Must be greater than ``0`` for cyclic sync to take effect.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_max_space:
.. rst-class:: classref-property
:ref:`float<class_float>` **max_space** = ``1.0`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_max_space>`
.. rst-class:: classref-property-setget
- |void| **set_max_space**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_max_space**\ (\ )
The blend space's axis's upper limit for the points' position. See :ref:`add_blend_point()<class_AnimationNodeBlendSpace1D_method_add_blend_point>`.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_min_space:
.. rst-class:: classref-property
:ref:`float<class_float>` **min_space** = ``-1.0`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_min_space>`
.. rst-class:: classref-property-setget
- |void| **set_min_space**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_min_space**\ (\ )
The blend space's axis's lower limit for the points' position. See :ref:`add_blend_point()<class_AnimationNodeBlendSpace1D_method_add_blend_point>`.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_snap:
.. rst-class:: classref-property
:ref:`float<class_float>` **snap** = ``0.1`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_snap>`
.. rst-class:: classref-property-setget
- |void| **set_snap**\ (\ value\: :ref:`float<class_float>`\ )
- :ref:`float<class_float>` **get_snap**\ (\ )
Position increment to snap to when moving a point on the axis.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_sync:
.. rst-class:: classref-property
:ref:`bool<class_bool>` **sync** :ref:`🔗<class_AnimationNodeBlendSpace1D_property_sync>`
.. rst-class:: classref-property-setget
- |void| **set_use_sync**\ (\ value\: :ref:`bool<class_bool>`\ )
- :ref:`bool<class_bool>` **is_using_sync**\ (\ )
**Deprecated:** Use :ref:`sync_mode<class_AnimationNodeBlendSpace1D_property_sync_mode>` instead.
If ``true``, sync mode is enabled (equivalent to :ref:`SYNC_MODE_INDEPENDENT<class_AnimationNodeBlendSpace1D_constant_SYNC_MODE_INDEPENDENT>`). This property is kept for backward compatibility.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_sync_mode:
.. rst-class:: classref-property
:ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` **sync_mode** = ``0`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_sync_mode>`
.. rst-class:: classref-property-setget
- |void| **set_sync_mode**\ (\ value\: :ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>`\ )
- :ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` **get_sync_mode**\ (\ )
Controls how animations are synced when blended. See :ref:`SyncMode<enum_AnimationNodeBlendSpace1D_SyncMode>` for available options.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_property_value_label:
.. rst-class:: classref-property
:ref:`String<class_String>` **value_label** = ``"value"`` :ref:`🔗<class_AnimationNodeBlendSpace1D_property_value_label>`
.. rst-class:: classref-property-setget
- |void| **set_value_label**\ (\ value\: :ref:`String<class_String>`\ )
- :ref:`String<class_String>` **get_value_label**\ (\ )
Label of the virtual axis of the blend space.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Method Descriptions
-------------------
.. _class_AnimationNodeBlendSpace1D_method_add_blend_point:
.. rst-class:: classref-method
|void| **add_blend_point**\ (\ node\: :ref:`AnimationRootNode<class_AnimationRootNode>`, pos\: :ref:`float<class_float>`, at_index\: :ref:`int<class_int>` = -1, name\: :ref:`StringName<class_StringName>` = &""\ ) :ref:`🔗<class_AnimationNodeBlendSpace1D_method_add_blend_point>`
Adds a new point with ``name`` that represents a ``node`` on the virtual axis at a given position set by ``pos``. You can insert it at a specific index using the ``at_index`` argument. If you use the default value for ``at_index``, the point is inserted at the end of the blend points array.
\ **Note:** If no name is provided, safe index is used as reference. In the future, empty names will be deprecated, so explicitly passing a name is recommended.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_find_blend_point_by_name:
.. rst-class:: classref-method
:ref:`int<class_int>` **find_blend_point_by_name**\ (\ name\: :ref:`StringName<class_StringName>`\ ) |const| :ref:`🔗<class_AnimationNodeBlendSpace1D_method_find_blend_point_by_name>`
Returns the index of the blend point with the given ``name``. Returns ``-1`` if no blend point with that name is found.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_get_blend_point_count:
.. rst-class:: classref-method
:ref:`int<class_int>` **get_blend_point_count**\ (\ ) |const| :ref:`🔗<class_AnimationNodeBlendSpace1D_method_get_blend_point_count>`
Returns the number of points on the blend axis.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_get_blend_point_name:
.. rst-class:: classref-method
:ref:`StringName<class_StringName>` **get_blend_point_name**\ (\ point\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_AnimationNodeBlendSpace1D_method_get_blend_point_name>`
Returns the name of the blend point at index ``point``.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_get_blend_point_node:
.. rst-class:: classref-method
:ref:`AnimationRootNode<class_AnimationRootNode>` **get_blend_point_node**\ (\ point\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_AnimationNodeBlendSpace1D_method_get_blend_point_node>`
Returns the :ref:`AnimationNode<class_AnimationNode>` referenced by the point at index ``point``.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_get_blend_point_position:
.. rst-class:: classref-method
:ref:`float<class_float>` **get_blend_point_position**\ (\ point\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_AnimationNodeBlendSpace1D_method_get_blend_point_position>`
Returns the position of the point at index ``point``.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_remove_blend_point:
.. rst-class:: classref-method
|void| **remove_blend_point**\ (\ point\: :ref:`int<class_int>`\ ) :ref:`🔗<class_AnimationNodeBlendSpace1D_method_remove_blend_point>`
Removes the point at index ``point`` from the blend axis.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_reorder_blend_point:
.. rst-class:: classref-method
|void| **reorder_blend_point**\ (\ from_index\: :ref:`int<class_int>`, to_index\: :ref:`int<class_int>`\ ) :ref:`🔗<class_AnimationNodeBlendSpace1D_method_reorder_blend_point>`
Swaps the blend points at indices ``from_index`` and ``to_index``, exchanging their positions and properties.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_set_blend_point_name:
.. rst-class:: classref-method
|void| **set_blend_point_name**\ (\ point\: :ref:`int<class_int>`, name\: :ref:`StringName<class_StringName>`\ ) :ref:`🔗<class_AnimationNodeBlendSpace1D_method_set_blend_point_name>`
Sets the name of the blend point at index ``point``. If the name conflicts with an existing point, a unique name will be generated automatically.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_set_blend_point_node:
.. rst-class:: classref-method
|void| **set_blend_point_node**\ (\ point\: :ref:`int<class_int>`, node\: :ref:`AnimationRootNode<class_AnimationRootNode>`\ ) :ref:`🔗<class_AnimationNodeBlendSpace1D_method_set_blend_point_node>`
Changes the :ref:`AnimationNode<class_AnimationNode>` referenced by the point at index ``point``.
.. rst-class:: classref-item-separator
----
.. _class_AnimationNodeBlendSpace1D_method_set_blend_point_position:
.. rst-class:: classref-method
|void| **set_blend_point_position**\ (\ point\: :ref:`int<class_int>`, pos\: :ref:`float<class_float>`\ ) :ref:`🔗<class_AnimationNodeBlendSpace1D_method_set_blend_point_position>`
Updates the position of the point at index ``point`` on the blend axis.
.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
.. |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.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
.. |void| replace:: :abbr:`void (No return value.)`