class_skeleton.rst 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272
  1. :github_url: hide
  2. .. Generated automatically by doc/tools/makerst.py in Godot's source tree.
  3. .. DO NOT EDIT THIS FILE, but the Skeleton.xml source instead.
  4. .. The source is found in doc/classes or modules/<name>/doc_classes.
  5. .. _class_Skeleton:
  6. Skeleton
  7. ========
  8. **Inherits:** :ref:`Spatial<class_Spatial>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
  9. **Category:** Core
  10. Brief Description
  11. -----------------
  12. Skeleton for characters and animated objects.
  13. Properties
  14. ----------
  15. +-------------------------+-----------------------------------------------------------------------------------+-------+
  16. | :ref:`bool<class_bool>` | :ref:`bones_in_world_transform<class_Skeleton_property_bones_in_world_transform>` | false |
  17. +-------------------------+-----------------------------------------------------------------------------------+-------+
  18. Methods
  19. -------
  20. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  21. | void | :ref:`add_bone<class_Skeleton_method_add_bone>` **(** :ref:`String<class_String>` name **)** |
  22. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  23. | void | :ref:`bind_child_node_to_bone<class_Skeleton_method_bind_child_node_to_bone>` **(** :ref:`int<class_int>` bone_idx, :ref:`Node<class_Node>` node **)** |
  24. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  25. | void | :ref:`clear_bones<class_Skeleton_method_clear_bones>` **(** **)** |
  26. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  27. | :ref:`int<class_int>` | :ref:`find_bone<class_Skeleton_method_find_bone>` **(** :ref:`String<class_String>` name **)** const |
  28. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  29. | :ref:`int<class_int>` | :ref:`get_bone_count<class_Skeleton_method_get_bone_count>` **(** **)** const |
  30. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  31. | :ref:`Transform<class_Transform>` | :ref:`get_bone_custom_pose<class_Skeleton_method_get_bone_custom_pose>` **(** :ref:`int<class_int>` bone_idx **)** const |
  32. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  33. | :ref:`Transform<class_Transform>` | :ref:`get_bone_global_pose<class_Skeleton_method_get_bone_global_pose>` **(** :ref:`int<class_int>` bone_idx **)** const |
  34. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  35. | :ref:`String<class_String>` | :ref:`get_bone_name<class_Skeleton_method_get_bone_name>` **(** :ref:`int<class_int>` bone_idx **)** const |
  36. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  37. | :ref:`int<class_int>` | :ref:`get_bone_parent<class_Skeleton_method_get_bone_parent>` **(** :ref:`int<class_int>` bone_idx **)** const |
  38. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  39. | :ref:`Transform<class_Transform>` | :ref:`get_bone_pose<class_Skeleton_method_get_bone_pose>` **(** :ref:`int<class_int>` bone_idx **)** const |
  40. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  41. | :ref:`Transform<class_Transform>` | :ref:`get_bone_rest<class_Skeleton_method_get_bone_rest>` **(** :ref:`int<class_int>` bone_idx **)** const |
  42. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  43. | :ref:`Transform<class_Transform>` | :ref:`get_bone_transform<class_Skeleton_method_get_bone_transform>` **(** :ref:`int<class_int>` bone_idx **)** const |
  44. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  45. | :ref:`Array<class_Array>` | :ref:`get_bound_child_nodes_to_bone<class_Skeleton_method_get_bound_child_nodes_to_bone>` **(** :ref:`int<class_int>` bone_idx **)** const |
  46. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  47. | :ref:`bool<class_bool>` | :ref:`is_bone_rest_disabled<class_Skeleton_method_is_bone_rest_disabled>` **(** :ref:`int<class_int>` bone_idx **)** const |
  48. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  49. | void | :ref:`localize_rests<class_Skeleton_method_localize_rests>` **(** **)** |
  50. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  51. | void | :ref:`physical_bones_add_collision_exception<class_Skeleton_method_physical_bones_add_collision_exception>` **(** :ref:`RID<class_RID>` exception **)** |
  52. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  53. | void | :ref:`physical_bones_remove_collision_exception<class_Skeleton_method_physical_bones_remove_collision_exception>` **(** :ref:`RID<class_RID>` exception **)** |
  54. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  55. | void | :ref:`physical_bones_start_simulation<class_Skeleton_method_physical_bones_start_simulation>` **(** :ref:`Array<class_Array>` bones=[ ] **)** |
  56. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  57. | void | :ref:`physical_bones_stop_simulation<class_Skeleton_method_physical_bones_stop_simulation>` **(** **)** |
  58. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  59. | void | :ref:`set_bone_custom_pose<class_Skeleton_method_set_bone_custom_pose>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` custom_pose **)** |
  60. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  61. | void | :ref:`set_bone_disable_rest<class_Skeleton_method_set_bone_disable_rest>` **(** :ref:`int<class_int>` bone_idx, :ref:`bool<class_bool>` disable **)** |
  62. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  63. | void | :ref:`set_bone_global_pose<class_Skeleton_method_set_bone_global_pose>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose **)** |
  64. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  65. | void | :ref:`set_bone_ignore_animation<class_Skeleton_method_set_bone_ignore_animation>` **(** :ref:`int<class_int>` bone, :ref:`bool<class_bool>` ignore **)** |
  66. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  67. | void | :ref:`set_bone_parent<class_Skeleton_method_set_bone_parent>` **(** :ref:`int<class_int>` bone_idx, :ref:`int<class_int>` parent_idx **)** |
  68. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  69. | void | :ref:`set_bone_pose<class_Skeleton_method_set_bone_pose>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose **)** |
  70. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  71. | void | :ref:`set_bone_rest<class_Skeleton_method_set_bone_rest>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` rest **)** |
  72. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  73. | void | :ref:`unbind_child_node_from_bone<class_Skeleton_method_unbind_child_node_from_bone>` **(** :ref:`int<class_int>` bone_idx, :ref:`Node<class_Node>` node **)** |
  74. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  75. | void | :ref:`unparent_bone_and_rest<class_Skeleton_method_unparent_bone_and_rest>` **(** :ref:`int<class_int>` bone_idx **)** |
  76. +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  77. Constants
  78. ---------
  79. .. _class_Skeleton_constant_NOTIFICATION_UPDATE_SKELETON:
  80. - **NOTIFICATION_UPDATE_SKELETON** = **50**
  81. Description
  82. -----------
  83. Skeleton provides a hierarchical interface for managing bones, including pose, rest and animation (see :ref:`Animation<class_Animation>`). Skeleton will support rag doll dynamics in the future.
  84. The overall transform of a bone with respect to the skeleton is determined by the following hierarchical order: rest pose, custom pose and pose.
  85. Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it not the actual global/world transform of the bone.
  86. Property Descriptions
  87. ---------------------
  88. .. _class_Skeleton_property_bones_in_world_transform:
  89. - :ref:`bool<class_bool>` **bones_in_world_transform**
  90. +-----------+-----------------------------------------+
  91. | *Default* | false |
  92. +-----------+-----------------------------------------+
  93. | *Setter* | set_use_bones_in_world_transform(value) |
  94. +-----------+-----------------------------------------+
  95. | *Getter* | is_using_bones_in_world_transform() |
  96. +-----------+-----------------------------------------+
  97. Method Descriptions
  98. -------------------
  99. .. _class_Skeleton_method_add_bone:
  100. - void **add_bone** **(** :ref:`String<class_String>` name **)**
  101. Adds a bone, with name ``name``. :ref:`get_bone_count<class_Skeleton_method_get_bone_count>` will become the bone index.
  102. .. _class_Skeleton_method_bind_child_node_to_bone:
  103. - void **bind_child_node_to_bone** **(** :ref:`int<class_int>` bone_idx, :ref:`Node<class_Node>` node **)**
  104. *Deprecated soon.*
  105. .. _class_Skeleton_method_clear_bones:
  106. - void **clear_bones** **(** **)**
  107. Clear all the bones in this skeleton.
  108. .. _class_Skeleton_method_find_bone:
  109. - :ref:`int<class_int>` **find_bone** **(** :ref:`String<class_String>` name **)** const
  110. Returns the bone index that matches ``name`` as its name.
  111. .. _class_Skeleton_method_get_bone_count:
  112. - :ref:`int<class_int>` **get_bone_count** **(** **)** const
  113. Returns the amount of bones in the skeleton.
  114. .. _class_Skeleton_method_get_bone_custom_pose:
  115. - :ref:`Transform<class_Transform>` **get_bone_custom_pose** **(** :ref:`int<class_int>` bone_idx **)** const
  116. Returns the custom pose of the specified bone. Custom pose is applied on top of the rest pose.
  117. .. _class_Skeleton_method_get_bone_global_pose:
  118. - :ref:`Transform<class_Transform>` **get_bone_global_pose** **(** :ref:`int<class_int>` bone_idx **)** const
  119. Returns the overall transform of the specified bone, with respect to the skeleton. Being relative to the skeleton frame, this is not the actual "global" transform of the bone.
  120. .. _class_Skeleton_method_get_bone_name:
  121. - :ref:`String<class_String>` **get_bone_name** **(** :ref:`int<class_int>` bone_idx **)** const
  122. Returns the name of the bone at index ``index``.
  123. .. _class_Skeleton_method_get_bone_parent:
  124. - :ref:`int<class_int>` **get_bone_parent** **(** :ref:`int<class_int>` bone_idx **)** const
  125. Returns the bone index which is the parent of the bone at ``bone_idx``. If -1, then bone has no parent.
  126. **Note:** The parent bone returned will always be less than ``bone_idx``.
  127. .. _class_Skeleton_method_get_bone_pose:
  128. - :ref:`Transform<class_Transform>` **get_bone_pose** **(** :ref:`int<class_int>` bone_idx **)** const
  129. Returns the pose transform of the specified bone. Pose is applied on top of the custom pose, which is applied on top the rest pose.
  130. .. _class_Skeleton_method_get_bone_rest:
  131. - :ref:`Transform<class_Transform>` **get_bone_rest** **(** :ref:`int<class_int>` bone_idx **)** const
  132. Returns the rest transform for a bone ``bone_idx``.
  133. .. _class_Skeleton_method_get_bone_transform:
  134. - :ref:`Transform<class_Transform>` **get_bone_transform** **(** :ref:`int<class_int>` bone_idx **)** const
  135. Returns the combination of custom pose and pose. The returned transform is in skeleton's reference frame.
  136. .. _class_Skeleton_method_get_bound_child_nodes_to_bone:
  137. - :ref:`Array<class_Array>` **get_bound_child_nodes_to_bone** **(** :ref:`int<class_int>` bone_idx **)** const
  138. *Deprecated soon.*
  139. .. _class_Skeleton_method_is_bone_rest_disabled:
  140. - :ref:`bool<class_bool>` **is_bone_rest_disabled** **(** :ref:`int<class_int>` bone_idx **)** const
  141. .. _class_Skeleton_method_localize_rests:
  142. - void **localize_rests** **(** **)**
  143. .. _class_Skeleton_method_physical_bones_add_collision_exception:
  144. - void **physical_bones_add_collision_exception** **(** :ref:`RID<class_RID>` exception **)**
  145. .. _class_Skeleton_method_physical_bones_remove_collision_exception:
  146. - void **physical_bones_remove_collision_exception** **(** :ref:`RID<class_RID>` exception **)**
  147. .. _class_Skeleton_method_physical_bones_start_simulation:
  148. - void **physical_bones_start_simulation** **(** :ref:`Array<class_Array>` bones=[ ] **)**
  149. .. _class_Skeleton_method_physical_bones_stop_simulation:
  150. - void **physical_bones_stop_simulation** **(** **)**
  151. .. _class_Skeleton_method_set_bone_custom_pose:
  152. - void **set_bone_custom_pose** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` custom_pose **)**
  153. .. _class_Skeleton_method_set_bone_disable_rest:
  154. - void **set_bone_disable_rest** **(** :ref:`int<class_int>` bone_idx, :ref:`bool<class_bool>` disable **)**
  155. .. _class_Skeleton_method_set_bone_global_pose:
  156. - void **set_bone_global_pose** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose **)**
  157. .. _class_Skeleton_method_set_bone_ignore_animation:
  158. - void **set_bone_ignore_animation** **(** :ref:`int<class_int>` bone, :ref:`bool<class_bool>` ignore **)**
  159. .. _class_Skeleton_method_set_bone_parent:
  160. - void **set_bone_parent** **(** :ref:`int<class_int>` bone_idx, :ref:`int<class_int>` parent_idx **)**
  161. Sets the bone index ``parent_idx`` as the parent of the bone at ``bone_idx``. If -1, then bone has no parent.
  162. **Note:** ``parent_idx`` must be less than ``bone_idx``.
  163. .. _class_Skeleton_method_set_bone_pose:
  164. - void **set_bone_pose** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose **)**
  165. Returns the pose transform for bone ``bone_idx``.
  166. .. _class_Skeleton_method_set_bone_rest:
  167. - void **set_bone_rest** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` rest **)**
  168. Sets the rest transform for bone ``bone_idx``.
  169. .. _class_Skeleton_method_unbind_child_node_from_bone:
  170. - void **unbind_child_node_from_bone** **(** :ref:`int<class_int>` bone_idx, :ref:`Node<class_Node>` node **)**
  171. *Deprecated soon.*
  172. .. _class_Skeleton_method_unparent_bone_and_rest:
  173. - void **unparent_bone_and_rest** **(** :ref:`int<class_int>` bone_idx **)**