class_skeleton.rst 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324
  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. Skeleton for characters and animated objects.
  10. Description
  11. -----------
  12. Skeleton provides a hierarchical interface for managing bones, including pose, rest and animation (see :ref:`Animation<class_Animation>`). It can also use ragdoll physics.
  13. The overall transform of a bone with respect to the skeleton is determined by the following hierarchical order: rest pose, custom pose and pose.
  14. 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.
  15. Tutorials
  16. ---------
  17. - `3D Inverse Kinematics Demo <https://godotengine.org/asset-library/asset/523>`_
  18. - `Third Person Shooter Demo <https://godotengine.org/asset-library/asset/678>`_
  19. Methods
  20. -------
  21. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  22. | void | :ref:`add_bone<class_Skeleton_method_add_bone>` **(** :ref:`String<class_String>` name **)** |
  23. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  24. | 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 **)** |
  25. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  26. | void | :ref:`clear_bones<class_Skeleton_method_clear_bones>` **(** **)** |
  27. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  28. | void | :ref:`clear_bones_global_pose_override<class_Skeleton_method_clear_bones_global_pose_override>` **(** **)** |
  29. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  30. | :ref:`int<class_int>` | :ref:`find_bone<class_Skeleton_method_find_bone>` **(** :ref:`String<class_String>` name **)** |const| |
  31. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  32. | :ref:`int<class_int>` | :ref:`get_bone_count<class_Skeleton_method_get_bone_count>` **(** **)** |const| |
  33. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  34. | :ref:`Transform<class_Transform>` | :ref:`get_bone_custom_pose<class_Skeleton_method_get_bone_custom_pose>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  35. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  36. | :ref:`Transform<class_Transform>` | :ref:`get_bone_global_pose<class_Skeleton_method_get_bone_global_pose>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  37. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  38. | :ref:`Transform<class_Transform>` | :ref:`get_bone_global_pose_no_override<class_Skeleton_method_get_bone_global_pose_no_override>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  39. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  40. | :ref:`String<class_String>` | :ref:`get_bone_name<class_Skeleton_method_get_bone_name>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  41. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  42. | :ref:`int<class_int>` | :ref:`get_bone_parent<class_Skeleton_method_get_bone_parent>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  43. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  44. | :ref:`Transform<class_Transform>` | :ref:`get_bone_pose<class_Skeleton_method_get_bone_pose>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  45. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  46. | :ref:`Transform<class_Transform>` | :ref:`get_bone_rest<class_Skeleton_method_get_bone_rest>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  47. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  48. | :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| |
  49. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  50. | :ref:`bool<class_bool>` | :ref:`is_bone_rest_disabled<class_Skeleton_method_is_bone_rest_disabled>` **(** :ref:`int<class_int>` bone_idx **)** |const| |
  51. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  52. | void | :ref:`localize_rests<class_Skeleton_method_localize_rests>` **(** **)** |
  53. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  54. | void | :ref:`physical_bones_add_collision_exception<class_Skeleton_method_physical_bones_add_collision_exception>` **(** :ref:`RID<class_RID>` exception **)** |
  55. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  56. | void | :ref:`physical_bones_remove_collision_exception<class_Skeleton_method_physical_bones_remove_collision_exception>` **(** :ref:`RID<class_RID>` exception **)** |
  57. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  58. | void | :ref:`physical_bones_start_simulation<class_Skeleton_method_physical_bones_start_simulation>` **(** :ref:`Array<class_Array>` bones=[ ] **)** |
  59. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  60. | void | :ref:`physical_bones_stop_simulation<class_Skeleton_method_physical_bones_stop_simulation>` **(** **)** |
  61. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  62. | :ref:`SkinReference<class_SkinReference>` | :ref:`register_skin<class_Skeleton_method_register_skin>` **(** :ref:`Skin<class_Skin>` skin **)** |
  63. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  64. | 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 **)** |
  65. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  66. | void | :ref:`set_bone_disable_rest<class_Skeleton_method_set_bone_disable_rest>` **(** :ref:`int<class_int>` bone_idx, :ref:`bool<class_bool>` disable **)** |
  67. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  68. | void | :ref:`set_bone_global_pose_override<class_Skeleton_method_set_bone_global_pose_override>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose, :ref:`float<class_float>` amount, :ref:`bool<class_bool>` persistent=false **)** |
  69. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  70. | void | :ref:`set_bone_parent<class_Skeleton_method_set_bone_parent>` **(** :ref:`int<class_int>` bone_idx, :ref:`int<class_int>` parent_idx **)** |
  71. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  72. | void | :ref:`set_bone_pose<class_Skeleton_method_set_bone_pose>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose **)** |
  73. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  74. | void | :ref:`set_bone_rest<class_Skeleton_method_set_bone_rest>` **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` rest **)** |
  75. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  76. | 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 **)** |
  77. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  78. | void | :ref:`unparent_bone_and_rest<class_Skeleton_method_unparent_bone_and_rest>` **(** :ref:`int<class_int>` bone_idx **)** |
  79. +-------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  80. Signals
  81. -------
  82. .. _class_Skeleton_signal_skeleton_updated:
  83. - **skeleton_updated** **(** **)**
  84. Constants
  85. ---------
  86. .. _class_Skeleton_constant_NOTIFICATION_UPDATE_SKELETON:
  87. - **NOTIFICATION_UPDATE_SKELETON** = **50**
  88. Method Descriptions
  89. -------------------
  90. .. _class_Skeleton_method_add_bone:
  91. - void **add_bone** **(** :ref:`String<class_String>` name **)**
  92. Adds a bone, with name ``name``. :ref:`get_bone_count<class_Skeleton_method_get_bone_count>` will become the bone index.
  93. ----
  94. .. _class_Skeleton_method_bind_child_node_to_bone:
  95. - void **bind_child_node_to_bone** **(** :ref:`int<class_int>` bone_idx, :ref:`Node<class_Node>` node **)**
  96. *Deprecated soon.*
  97. ----
  98. .. _class_Skeleton_method_clear_bones:
  99. - void **clear_bones** **(** **)**
  100. Clear all the bones in this skeleton.
  101. ----
  102. .. _class_Skeleton_method_clear_bones_global_pose_override:
  103. - void **clear_bones_global_pose_override** **(** **)**
  104. ----
  105. .. _class_Skeleton_method_find_bone:
  106. - :ref:`int<class_int>` **find_bone** **(** :ref:`String<class_String>` name **)** |const|
  107. Returns the bone index that matches ``name`` as its name.
  108. ----
  109. .. _class_Skeleton_method_get_bone_count:
  110. - :ref:`int<class_int>` **get_bone_count** **(** **)** |const|
  111. Returns the amount of bones in the skeleton.
  112. ----
  113. .. _class_Skeleton_method_get_bone_custom_pose:
  114. - :ref:`Transform<class_Transform>` **get_bone_custom_pose** **(** :ref:`int<class_int>` bone_idx **)** |const|
  115. Returns the custom pose of the specified bone. Custom pose is applied on top of the rest pose.
  116. ----
  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. ----
  121. .. _class_Skeleton_method_get_bone_global_pose_no_override:
  122. - :ref:`Transform<class_Transform>` **get_bone_global_pose_no_override** **(** :ref:`int<class_int>` bone_idx **)** |const|
  123. Returns the overall transform of the specified bone, with respect to the skeleton, but without any global pose overrides. Being relative to the skeleton frame, this is not the actual "global" transform of the bone.
  124. ----
  125. .. _class_Skeleton_method_get_bone_name:
  126. - :ref:`String<class_String>` **get_bone_name** **(** :ref:`int<class_int>` bone_idx **)** |const|
  127. Returns the name of the bone at index ``index``.
  128. ----
  129. .. _class_Skeleton_method_get_bone_parent:
  130. - :ref:`int<class_int>` **get_bone_parent** **(** :ref:`int<class_int>` bone_idx **)** |const|
  131. Returns the bone index which is the parent of the bone at ``bone_idx``. If -1, then bone has no parent.
  132. **Note:** The parent bone returned will always be less than ``bone_idx``.
  133. ----
  134. .. _class_Skeleton_method_get_bone_pose:
  135. - :ref:`Transform<class_Transform>` **get_bone_pose** **(** :ref:`int<class_int>` bone_idx **)** |const|
  136. 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.
  137. ----
  138. .. _class_Skeleton_method_get_bone_rest:
  139. - :ref:`Transform<class_Transform>` **get_bone_rest** **(** :ref:`int<class_int>` bone_idx **)** |const|
  140. Returns the rest transform for a bone ``bone_idx``.
  141. ----
  142. .. _class_Skeleton_method_get_bound_child_nodes_to_bone:
  143. - :ref:`Array<class_Array>` **get_bound_child_nodes_to_bone** **(** :ref:`int<class_int>` bone_idx **)** |const|
  144. *Deprecated soon.*
  145. ----
  146. .. _class_Skeleton_method_is_bone_rest_disabled:
  147. - :ref:`bool<class_bool>` **is_bone_rest_disabled** **(** :ref:`int<class_int>` bone_idx **)** |const|
  148. ----
  149. .. _class_Skeleton_method_localize_rests:
  150. - void **localize_rests** **(** **)**
  151. ----
  152. .. _class_Skeleton_method_physical_bones_add_collision_exception:
  153. - void **physical_bones_add_collision_exception** **(** :ref:`RID<class_RID>` exception **)**
  154. ----
  155. .. _class_Skeleton_method_physical_bones_remove_collision_exception:
  156. - void **physical_bones_remove_collision_exception** **(** :ref:`RID<class_RID>` exception **)**
  157. ----
  158. .. _class_Skeleton_method_physical_bones_start_simulation:
  159. - void **physical_bones_start_simulation** **(** :ref:`Array<class_Array>` bones=[ ] **)**
  160. ----
  161. .. _class_Skeleton_method_physical_bones_stop_simulation:
  162. - void **physical_bones_stop_simulation** **(** **)**
  163. ----
  164. .. _class_Skeleton_method_register_skin:
  165. - :ref:`SkinReference<class_SkinReference>` **register_skin** **(** :ref:`Skin<class_Skin>` skin **)**
  166. ----
  167. .. _class_Skeleton_method_set_bone_custom_pose:
  168. - void **set_bone_custom_pose** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` custom_pose **)**
  169. ----
  170. .. _class_Skeleton_method_set_bone_disable_rest:
  171. - void **set_bone_disable_rest** **(** :ref:`int<class_int>` bone_idx, :ref:`bool<class_bool>` disable **)**
  172. ----
  173. .. _class_Skeleton_method_set_bone_global_pose_override:
  174. - void **set_bone_global_pose_override** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose, :ref:`float<class_float>` amount, :ref:`bool<class_bool>` persistent=false **)**
  175. ----
  176. .. _class_Skeleton_method_set_bone_parent:
  177. - void **set_bone_parent** **(** :ref:`int<class_int>` bone_idx, :ref:`int<class_int>` parent_idx **)**
  178. Sets the bone index ``parent_idx`` as the parent of the bone at ``bone_idx``. If -1, then bone has no parent.
  179. **Note:** ``parent_idx`` must be less than ``bone_idx``.
  180. ----
  181. .. _class_Skeleton_method_set_bone_pose:
  182. - void **set_bone_pose** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` pose **)**
  183. Sets the pose transform for bone ``bone_idx``.
  184. ----
  185. .. _class_Skeleton_method_set_bone_rest:
  186. - void **set_bone_rest** **(** :ref:`int<class_int>` bone_idx, :ref:`Transform<class_Transform>` rest **)**
  187. Sets the rest transform for bone ``bone_idx``.
  188. ----
  189. .. _class_Skeleton_method_unbind_child_node_from_bone:
  190. - void **unbind_child_node_from_bone** **(** :ref:`int<class_int>` bone_idx, :ref:`Node<class_Node>` node **)**
  191. *Deprecated soon.*
  192. ----
  193. .. _class_Skeleton_method_unparent_bone_and_rest:
  194. - void **unparent_bone_and_rest** **(** :ref:`int<class_int>` bone_idx **)**
  195. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
  196. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
  197. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`