GDScript Groups & Pickups Practice

Groups decouple your systems. A weapon doesn't need to know every enemy type—it just damages anything in the "enemy" group. A pickup doesn't need a direct player reference—it heals anything in the "player" group.

# Without groups: brittle, breaks if you rename/add enemies
if body.name == "Goblin" or body.name == "Skeleton":
    body.take_damage(10)

# With groups: flexible, scales to any number of enemy types
if body.is_in_group(&"enemy"):
    body.take_damage(10)

You don't always need code to assign groups:

1. Node dock method: Select a node → Node tab (next to Inspector) → Groups section → type a name and click Add
2. Global Groups (Project Settings): Project → Project Settings → Global Groups → define groups here, then assign them to any node via the Node dock dropdown

Global Groups are useful for project-wide consistency—define player, enemy, pickup once, and they appear in every node's group dropdown.

This is the core pattern for coins, health packs, power-ups, and collectibles:

extends Area2D
@export var heal_amount := 25

const GROUP_PLAYER := &"player"

func _ready() -> void:
    body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node) -> void:
    if not body.is_in_group(GROUP_PLAYER):
        return

    # If the player implements heal(), this works.
    # call() ignores nodes that don't have the method.
    body.call(&"heal", heal_amount)
    queue_free()

Key insight: Groups are not a replacement for collision layers/masks—they're a second filter. Use layers/masks to control which physics objects can overlap, then use groups to identify what role that object plays ("is this a player?").

# Freeze all enemies (runs IMMEDIATELY in Godot 4)
get_tree().call_group(&"enemy", &"freeze", 2.0)

# Heal all allies
get_tree().call_group(&"ally", &"heal", 50)

# Pause all AI
get_tree().call_group(&"ai", &"set_active", false)

Godot 4 behavior: call_group() acts immediately—not end-of-frame. Nodes that don't have the method are silently ignored (no error). If you need end-of-frame timing:

# Deferred call_group (runs at end of frame, like call_deferred)
get_tree().call_group_flags(
    SceneTree.GROUP_CALL_DEFERRED,
    &"enemy",
    &"freeze",
    2.0
)

# Find all enemies
var enemies := get_tree().get_nodes_in_group(&"enemy")

Find Closest Enemy (Safe Pattern)

The array returns Node references, so cast before accessing global_position. For more iteration patterns and safe removal techniques, see arrays & loops.

const GROUP_ENEMY := &"enemy"

var closest: Node2D = null
var best_d2 := INF

for node in get_tree().get_nodes_in_group(GROUP_ENEMY):
    var enemy := node as Node2D
    if enemy == null:
        continue  # Skip non-Node2D entries

    # Squared distance is cheaper (no sqrt)
    var d2 := global_position.distance_squared_to(enemy.global_position)
    if d2 < best_d2:
        best_d2 = d2
        closest = enemy

Performance note: get_nodes_in_group() allocates an Array every call. Don't call it every frame—cache the result or use signals for dynamic membership.

In Godot 4, group names and method names are StringName parameters. Using the &"literal" syntax avoids String→StringName conversion and enables fast comparisons:

# Best practice: define as StringName constants
const GROUP_PLAYER := &"player"
const GROUP_ENEMY := &"enemy"
const GROUP_PICKUP := &"pickup"

# Usage
add_to_group(GROUP_ENEMY)
if body.is_in_group(GROUP_PLAYER):
    ...
get_tree().call_group(GROUP_ENEMY, &"freeze", 1.0)

This is a small optimization, but it signals "I know the Godot 4 API."

State groups seem convenient but create sync bugs—you'll forget to remove the group when state changes. Use a var is_stunned: bool instead. For advanced group-based data patterns like mapping group members to stats, see our dictionary map blog post.