ProximityGroup

Inherits: Spatial < Node < Object General-purpose 3D proximity detection node.

Description

ProximityGroup can be used for approximate distance checks, which are faster than exact distance checks using Vector3.distance_to or Vector3.distance_squared_to. ProximityGroup nodes are automatically grouped together, as long as they share the same group_name and intersect with each other. By calling the broadcast, you can invoke a specified method with various parameters to all intersecting members. ProximityGroup is cuboid-shaped and consists of a cluster of Vector3 coordinates. The coordinates are automatically calculated by calling grid_radius. To allow ProximityGroup to find its peers (and perform automatic grouping), you need to define its group_name to a non-empty String. As soon as this object’s shape intersects with another ProximityGroup object’ shape, and both share the same group_name, they will belong together for as long as they intersect. ProximityGroup doesn’t rely the physics engine, you don’t need to add any other node as a child (unlike PhysicsBody). ProximityGroup uses the SceneTree groups in the background by calling the method Node.add_to_group internally. The SceneTree group names are constructed by combining the group_name with its coordinates, which are calculated using the grid_radius you defined beforehand. Example: A ProximityGroup node named "PlanetEarth" at position Vector3(6, 6, 6) with a group_name set to "planets" and a grid_radius of Vector3(1, 2, 3) will create the following SceneTree group names:

  1. - "planets|5|4|3"- "planets|5|4|4"- "planets|5|4|5"- "planets|5|4|6"- "planets|5|4|7"- "planets|5|4|8"- "planets|5|4|9"- ...

ProximityGroup named "PlanetMars" with group name "planets", and one of its coordinates is Vector3(5, 4, 7), it would normally create the 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 broadcast will affect both ProximityGroup nodes. ProximityGroup:

  • SceneTree groups are created. This can have a performance impact if too many groups are created.
  • 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.
  • 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. Note: ProximityGroup will be removed in Godot 4.0 in favor of more effective and faster VisibilityNotifier functionality. For most use cases, Vector3.distance_to or Vector3.distance_squared_to are fast enough too, especially if you call them less often using a Timer node.

    Properties

    Methods

    Signals

  • broadcast ( String method, Array parameters ) broadcast method and has set dispatch_mode to MODE_SIGNAL. ProximityGroup node this node is grouped together with. Note: This signal is not emitted by default, as the default dispatch_mode is MODE_PROXY.

    Enumerations

    DispatchMode:
  • MODE_PROXY = 0 —- This ProximityGroup‘s parent will be target of broadcast.
  • MODE_SIGNAL = 1 —- This ProximityGroup will emit the broadcast signal when calling the broadcast method.

    Property Descriptions

  • DispatchMode dispatch_mode broadcast.
  • Vector3 grid_radius ProximityGroup nodes are intersecting or not. Smaller grid_radius values can be used for more precise proximity checks at the cost of performance, since more groups will be created.
  • String group_name ProximityGroup nodes know, if they should be auto-grouped with this node in case they intersect with each other. ProximityGroup node named "Earth" and another called "Mars", with both nodes having "planet" as their group_name. Give both planets a significantly larger grid_radius than their actual radius, position them close enough and they’ll be automatically grouped.

    Method Descriptions

  • broadcast ( String method, Variant parameters ) ProximityGroup the given method and parameters. dispatch_mode is set to MODE_PROXY (the default), all calls are delegated to their respective parent Node.