Home Explore Help
Sign In
godotengine
/
godot-docs
mirror of https://github.com/godotengine/godot-docs
Watch 1
Star 1
Fork 0
Files
Tree: 7a86ac6a30
Branches Tags
godot-docs
/
classes
/
class_proximitygroup.rst

class_proximitygroup.rst 10 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165 
  1. :github_url: hide
    2. 

  2. 

  3. .. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
    4. 

  4. .. DO NOT EDIT THIS FILE, but the ProximityGroup.xml source instead.
    5. 

  5. .. The source is found in doc/classes or modules/<name>/doc_classes.
    6. 

  6. 

  7. .. _class_ProximityGroup:
    8. 

  8. 

  9. ProximityGroup
    10. 

  10. ==============
    11. 

  11. 

  12. **Inherits:** :ref:`Spatial<class_Spatial>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
    13. 

  13. 

  14. General-purpose 3D proximity detection node.
    15. 

  15. 

  16. Description
    17. 

  17. -----------
    18. 

  18. 

  19. General-purpose proximity detection node. ``ProximityGroup`` can be used for *approximate* distance checks, which are faster than exact distance checks using :ref:`Vector3.distance_to<class_Vector3_method_distance_to>` or :ref:`Vector3.distance_squared_to<class_Vector3_method_distance_squared_to>`.
    20. 

  20. 

  21. ``ProximityGroup`` nodes are automatically grouped together, as long as they share the same :ref:`group_name<class_ProximityGroup_property_group_name>` and intersect with each other. By calling the :ref:`broadcast<class_ProximityGroup_method_broadcast>`, you can invoke a specified method with various parameters to all intersecting members.
    22. 

  22. 

  23. ``ProximityGroup`` is cuboid-shaped and consists of a cluster of :ref:`Vector3<class_Vector3>` coordinates. The coordinates are automatically calculated by calling :ref:`grid_radius<class_ProximityGroup_property_grid_radius>`. To allow ``ProximityGroup`` to find its peers (and perform automatic grouping), you need to define its :ref:`group_name<class_ProximityGroup_property_group_name>` to a non-empty :ref:`String<class_String>`. As soon as this object's shape intersects with another ``ProximityGroup`` object' shape, and both share the same :ref:`group_name<class_ProximityGroup_property_group_name>`, they will belong together for as long as they intersect.
    24. 

  24. 

  25. Since ``ProximityGroup`` doesn't rely the physics engine, you don't need to add any other node as a child (unlike :ref:`PhysicsBody<class_PhysicsBody>`).
    26. 

  26. 

  27. The ``ProximityGroup`` uses the :ref:`SceneTree<class_SceneTree>` groups in the background by calling the method :ref:`Node.add_to_group<class_Node_method_add_to_group>` internally. The :ref:`SceneTree<class_SceneTree>` group names are constructed by combining the :ref:`group_name<class_ProximityGroup_property_group_name>` with its coordinates, which are calculated using the :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` you defined beforehand.
    28. 

  28. 

  29. **Example:** A ``ProximityGroup`` node named ``"PlanetEarth"`` at position ``Vector3(6, 6, 6)`` with a :ref:`group_name<class_ProximityGroup_property_group_name>` set to ``"planets"`` and a :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` of ``Vector3(1, 2, 3)`` will create the following :ref:`SceneTree<class_SceneTree>` group names:
    30. 

  30. 

  31. ::
    32. 

  32. 

  33.     - "planets|5|4|3"
    34. 

  34.     - "planets|5|4|4"
    35. 

  35.     - "planets|5|4|5"
    36. 

  36.     - "planets|5|4|6"
    37. 

  37.     - "planets|5|4|7"
    38. 

  38.     - "planets|5|4|8"
    39. 

  39.     - "planets|5|4|9"
    40. 

  40.     - ...
    41. 

  41. 

  42. If there is another ``ProximityGroup`` named ``"PlanetMars"`` with group name ``"planets"``, and one of its coordinates is ``Vector3(5, 4, 7)``, it would normally create the :ref:`SceneTree<class_SceneTree>` group called ``"planets|5|4|7"``. However, since this group name already exists, this ``ProximityGroup`` object will be *added* to the existing one. ``"PlanetEarth"`` is already in this group. As long as both nodes don't change their transform and stop intersecting (or exit the scene tree), they are grouped together. As long as this intersection exists, any call to :ref:`broadcast<class_ProximityGroup_method_broadcast>` will affect *both* ``ProximityGroup`` nodes.
    43. 

  43. 

  44. There are 3 caveats to keep in mind when using ``ProximityGroup``:
    45. 

  45. 

  46. - The larger the grid radius, the more coordinates and the more :ref:`SceneTree<class_SceneTree>` groups are created. This can have a performance impact if too many groups are created.
    47. 

  47. 

  48. - If the ``ProximityGroup`` node is transformed in any way (or is removed from the scene tree), the groupings will have to be recalculated. This can also have a performance impact.
    49. 

  49. 

  50. - If your :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` is smaller than ``Vector3(1, 1, 1)``, it will be rounded up to ``Vector3(1, 1, 1)``. Therefore, small grid radius values may lead to unwanted groupings.
    51. 

  51. 

  52. **Note:** ``ProximityGroup`` will be removed in Godot 4.0 in favor of more effective and faster :ref:`VisibilityNotifier<class_VisibilityNotifier>` functionality. For most use cases, :ref:`Vector3.distance_to<class_Vector3_method_distance_to>` or :ref:`Vector3.distance_squared_to<class_Vector3_method_distance_squared_to>` are fast enough too, especially if you call them less often using a :ref:`Timer<class_Timer>` node.
    53. 

  53. 

  54. Properties
    55. 

  55. ----------
    56. 

  56. 

  57. +-------------------------------------------------------+-------------------------------------------------------------------+------------------------+
    58. 

  58. | :ref:`DispatchMode<enum_ProximityGroup_DispatchMode>` | :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` | ``0``                  |
    59. 

  59. +-------------------------------------------------------+-------------------------------------------------------------------+------------------------+
    60. 

  60. | :ref:`Vector3<class_Vector3>`                         | :ref:`grid_radius<class_ProximityGroup_property_grid_radius>`     | ``Vector3( 1, 1, 1 )`` |
    61. 

  61. +-------------------------------------------------------+-------------------------------------------------------------------+------------------------+
    62. 

  62. | :ref:`String<class_String>`                           | :ref:`group_name<class_ProximityGroup_property_group_name>`       | ``""``                 |
    63. 

  63. +-------------------------------------------------------+-------------------------------------------------------------------+------------------------+
    64. 

  64. 

  65. Methods
    66. 

  66. -------
    67. 

  67. 

  68. +------+--------------------------------------------------------------------------------------------------------------------------------------------------+
    69. 

  69. | void | :ref:`broadcast<class_ProximityGroup_method_broadcast>` **(** :ref:`String<class_String>` method, :ref:`Variant<class_Variant>` parameters **)** |
    70. 

  70. +------+--------------------------------------------------------------------------------------------------------------------------------------------------+
    71. 

  71. 

  72. Signals
    73. 

  73. -------
    74. 

  74. 

  75. .. _class_ProximityGroup_signal_broadcast:
    76. 

  76. 

  77. - **broadcast** **(** :ref:`String<class_String>` method, :ref:`Array<class_Array>` parameters **)**
    78. 

  78. 

  79. Emitted when the user calls the :ref:`broadcast<class_ProximityGroup_method_broadcast>` method and has set :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` to :ref:`MODE_SIGNAL<class_ProximityGroup_constant_MODE_SIGNAL>`.
    80. 

  80. 

  81. The given method and its parameters are passed on to the listeners who connected to this signal of this object, as well as any ``ProximityGroup`` node this node is grouped together with.
    82. 

  82. 

  83. **Note:** This signal is *not* emitted by default, as the default :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` is :ref:`MODE_PROXY<class_ProximityGroup_constant_MODE_PROXY>`.
    84. 

  84. 

  85. Enumerations
    86. 

  86. ------------
    87. 

  87. 

  88. .. _enum_ProximityGroup_DispatchMode:
    89. 

  89. 

  90. .. _class_ProximityGroup_constant_MODE_PROXY:
    91. 

  91. 

  92. .. _class_ProximityGroup_constant_MODE_SIGNAL:
    93. 

  93. 

  94. enum **DispatchMode**:
    95. 

  95. 

  96. - **MODE_PROXY** = **0** --- This ``ProximityGroup``'s parent will be target of :ref:`broadcast<class_ProximityGroup_method_broadcast>`.
    97. 

  97. 

  98. - **MODE_SIGNAL** = **1** --- This ``ProximityGroup`` will emit the :ref:`broadcast<class_ProximityGroup_signal_broadcast>` *signal* when calling the :ref:`broadcast<class_ProximityGroup_method_broadcast>` *method*.
    99. 

  99. 

  100. Property Descriptions
    101. 

  101. ---------------------
    102. 

  102. 

  103. .. _class_ProximityGroup_property_dispatch_mode:
    104. 

  104. 

  105. - :ref:`DispatchMode<enum_ProximityGroup_DispatchMode>` **dispatch_mode**
    106. 

  106. 

  107. +-----------+--------------------------+
    108. 

  108. | *Default* | ``0``                    |
    109. 

  109. +-----------+--------------------------+
    110. 

  110. | *Setter*  | set_dispatch_mode(value) |
    111. 

  111. +-----------+--------------------------+
    112. 

  112. | *Getter*  | get_dispatch_mode()      |
    113. 

  113. +-----------+--------------------------+
    114. 

  114. 

  115. Specifies which node gets contacted on a call of method :ref:`broadcast<class_ProximityGroup_method_broadcast>`.
    116. 

  116. 

  117. ----
    118. 

  118. 

  119. .. _class_ProximityGroup_property_grid_radius:
    120. 

  120. 

  121. - :ref:`Vector3<class_Vector3>` **grid_radius**
    122. 

  122. 

  123. +-----------+------------------------+
    124. 

  124. | *Default* | ``Vector3( 1, 1, 1 )`` |
    125. 

  125. +-----------+------------------------+
    126. 

  126. | *Setter*  | set_grid_radius(value) |
    127. 

  127. +-----------+------------------------+
    128. 

  128. | *Getter*  | get_grid_radius()      |
    129. 

  129. +-----------+------------------------+
    130. 

  130. 

  131. The size of the space in 3D units. This also sets the amount of coordinates required to calculate whether two ``ProximityGroup`` nodes are intersecting or not. Smaller :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` values can be used for more precise proximity checks at the cost of performance, since more groups will be created.
    132. 

  132. 

  133. ----
    134. 

  134. 

  135. .. _class_ProximityGroup_property_group_name:
    136. 

  136. 

  137. - :ref:`String<class_String>` **group_name**
    138. 

  138. 

  139. +-----------+-----------------------+
    140. 

  140. | *Default* | ``""``                |
    141. 

  141. +-----------+-----------------------+
    142. 

  142. | *Setter*  | set_group_name(value) |
    143. 

  143. +-----------+-----------------------+
    144. 

  144. | *Getter*  | get_group_name()      |
    145. 

  145. +-----------+-----------------------+
    146. 

  146. 

  147. Specify the common group name, to let other ``ProximityGroup`` nodes know, if they should be auto-grouped with this node in case they intersect with each other.
    148. 

  148. 

  149. For example, if you have a ``ProximityGroup`` node named ``"Earth"`` and another called ``"Mars"``, with both nodes having ``"planet"`` as their :ref:`group_name<class_ProximityGroup_property_group_name>`. Give both planets a significantly larger :ref:`grid_radius<class_ProximityGroup_property_grid_radius>` than their actual radius, position them close enough and they'll be automatically grouped.
    150. 

  150. 

  151. Method Descriptions
    152. 

  152. -------------------
    153. 

  153. 

  154. .. _class_ProximityGroup_method_broadcast:
    155. 

  155. 

  156. - void **broadcast** **(** :ref:`String<class_String>` method, :ref:`Variant<class_Variant>` parameters **)**
    157. 

  157. 

  158. Calls on all intersecting ``ProximityGroup`` the given method and parameters.
    159. 

  159. 

  160. If the :ref:`dispatch_mode<class_ProximityGroup_property_dispatch_mode>` is set to :ref:`MODE_PROXY<class_ProximityGroup_constant_MODE_PROXY>` (the default), all calls are delegated to their respective parent :ref:`Node<class_Node>`.
    161. 

  161. 

  162. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
    163. 

  163. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
    164. 

  164. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
    165. 

  165.