ProximityGroup

    General-purpose 3D proximity detection node.

    General-purpose proximity detection node. can be used for approximate distance checks, which are faster than exact distance checks using or Vector3.distance_squared_to.

    ProximityGroup nodes are automatically grouped together, as long as they share the same 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 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 to a non-empty String. As soon as this object’s shape intersects with another ProximityGroup object’ shape, and both share the same , they will belong together for as long as they intersect.

    Since ProximityGroup doesn’t rely the physics engine, you don’t need to add any other node as a child (unlike PhysicsBody).

    The ProximityGroup uses the groups in the background by calling the method Node.add_to_group internally. The group names are constructed by combining the group_name with its coordinates, which are calculated using the you defined beforehand.

    Example: A ProximityGroup node named "PlanetEarth" at position Vector3(6, 6, 6) with a group_name set to "planets" and a of Vector3(1, 2, 3) will create the following SceneTree group names:

    If there is another ProximityGroup named with group name "planets", and one of its coordinates is Vector3(5, 4, 7), it would normally create the 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.

    There are 3 caveats to keep in mind when using ProximityGroup:

    • The larger the grid radius, the more coordinates and the more groups are created. This can have a performance impact if too many groups are created.

    • 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.

    • If your 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 functionality. For most use cases, Vector3.distance_to or are fast enough too, especially if you call them less often using a Timer node.

    Properties

    Signals

    • broadcast ( String method, parameters )

    Emitted when the user calls the broadcast method and has set to MODE_SIGNAL.

    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.

    Note: This signal is not emitted by default, as the default is MODE_PROXY.

    enum DispatchMode:

    • MODE_SIGNAL = 1 —- This ProximityGroup will emit the broadcast signal when calling the method.

    Property Descriptions

    • dispatch_mode

    Specifies which node gets contacted on a call of method broadcast.

    • grid_radius

    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 grid_radius values can be used for more precise proximity checks at the cost of performance, since more groups will be created.

    • group_name

    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.

    For example, if you have a ProximityGroup node named "Earth" and another called "Mars", with both nodes having as their group_name. Give both planets a significantly larger than their actual radius, position them close enough and they’ll be automatically grouped.

    • void broadcast ( method, Variant parameters )

    Calls on all intersecting ProximityGroup the given method and parameters.