ProximityGroup

Inherits: Spatial < Node < Object

General-purpose 3D proximity detection node.

Description

General-purpose proximity detection node. 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.

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 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:

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

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

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

• The larger the grid radius, the more coordinates and the more SceneTree 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 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 )

Emitted when the user calls the broadcast method and has set dispatch_mode 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 dispatch_mode is MODE_PROXY.

Enumerations

enum 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

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

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

• String 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 "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

• void broadcast ( String method, Variant parameters )

Calls on all intersecting ProximityGroup the given method and parameters.

If the dispatch_mode is set to MODE_PROXY (the default), all calls are delegated to their respective parent Node.