Kollisions-Layer & Physik in Godot 4

Warum Kollisions-Layer wichtig sind

Kollisions-Layer sind die Grundlage aller Physik-Interaktionen in Godot 4 — Bewegung, Trefferabfrage, Raycasting, Area-Trigger und mehr. Den Unterschied zwischen Layer und Mask zu verstehen ist entscheidend, und ihn misszuverstehen ist einer der häufigsten Stolpersteine für Einsteiger wie auch erfahrene Entwickler.

Layer vs. Mask — Das mentale Modell

Jedes Physik-Objekt in Godot hat zwei Bitmask-Eigenschaften:

• Layer = „Ich existiere auf diesen Layern" (was ich bin)
• Mask = „Ich scanne diese Layer" (was ich sehen / treffen kann)

Layer in den Projekteinstellungen benennen

Bevor du irgendeinen Code schreibst, benenne deine Layer. Das macht den Inspector deutlich einfacher zu nutzen und verhindert Verwirrung, wenn dein Projekt wächst.

Projekteinstellungen > Layer-Namen > 2D-Physik (oder 3D-Physik):

Layer im Code setzen (GDScript)

Godot 4 bietet zwei Ansätze — die wertbasierte API (empfohlen) und die direkte Bitmask-Zuweisung:

# Godot 4 API — value-based (1-indexed, recommended)
set_collision_layer_value(1, true)   # I am on layer 1
set_collision_mask_value(2, true)    # I detect layer 2

# Or use bitmask directly
collision_layer = 1   # Layer 1 only (bit 0)
collision_mask = 6    # Layers 2 and 3 (bits 1 + 2 = 6)

# Read current state
var on_layer_1: bool = get_collision_layer_value(1)
var scans_layer_2: bool = get_collision_mask_value(2)

Gängige Layer-Schemata

Platformer / Side-Scroller

Top-Down / Roguelike

Area2D / Area3D Layer

Areas nutzen dasselbe Layer/Mask-System. Zusätzlich haben sie zwei Umschalt-Eigenschaften:

• monitoring — Wenn true, erkennt diese Area aktiv andere Objekte, die sie betreten.
• monitorable — Wenn true, können andere Areas diese Area erkennen.

Signale: area_entered vs. body_entered

body_entered wird ausgelöst, wenn ein PhysicsBody (CharacterBody, RigidBody, StaticBody) die Area betritt. area_entered wird ausgelöst, wenn eine andere Area sie betritt. Achte darauf, für deinen Anwendungsfall das richtige Signal zu verbinden.

# Pickup Area2D — detect when the Player body enters
func _ready() -> void:
    body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node2D) -> void:
    if body.is_in_group("player"):
        collect()
        queue_free()

RayCast Kollisionsmaske

RayCast-Nodes haben nur eine Mask (keinen Layer), weil sie Detektoren und keine physischen Körper sind. Setze die Mask, um zu filtern, was der Strahl treffen kann:

# RayCast that only detects enemies (layer 2)
$RayCast2D.collision_mask = 2  # Layer 2 = Enemy
# Or use the value-based API:
$RayCast2D.set_collision_mask_value(1, false)  # Ignore Player
$RayCast2D.set_collision_mask_value(2, true)   # Detect Enemy
$RayCast2D.set_collision_mask_value(3, false)  # Ignore Environment

# Line-of-sight ray that ignores projectiles
$LineOfSight.collision_mask = 0
$LineOfSight.set_collision_mask_value(1, true)  # Player
$LineOfSight.set_collision_mask_value(3, true)  # Environment

Praktisches Beispiel: Player – Enemy – Projectile

Hier ist ein vollständiges Layer-Setup für ein typisches Action-Spiel. Kommentare zeigen die Überlegung hinter jeder Entscheidung:

# Player (CharacterBody2D)
# Layer: 1 (Player)          — "I am the player"
# Mask: 2 (Enemy), 3 (Environment), 5 (Pickup)
#   — I collide with enemies, walls, and can pick up items

# Enemy (CharacterBody2D)
# Layer: 2 (Enemy)            — "I am an enemy"
# Mask: 1 (Player), 3 (Environment)
#   — I collide with the player and walls

# Player Bullet (Area2D)
# Layer: 4 (Projectile)       — "I am a projectile"
# Mask: 2 (Enemy), 3 (Environment)
#   — I hit enemies and walls, but NOT the player who fired me

# Enemy Bullet (Area2D)
# Layer: 4 (Projectile)       — "I am a projectile"
# Mask: 1 (Player), 3 (Environment)
#   — I hit the player and walls, but NOT the enemy who fired me

Debugging-Tipps

• Sichtbare Kollisionsformen: Gehe im Editor zu Debug > Sichtbare Kollisionsformen, um alle Kollisionsformen zur Laufzeit darzustellen. Das offenbart sofort fehlende oder falsch ausgerichtete Collider.
• Inspector-Prüfung: Wähle einen Node aus und klappe Collision > Layer und Collision > Mask im Inspector auf. Fahre über jedes Bit, um seinen Namen zu sehen (falls du sie in den Projekteinstellungen benannt hast).
• Zur Laufzeit ausgeben: print("Layer: ", collision_layer, " Mask: ", collision_mask), um Bitmask-Werte während des Spielens zu verifizieren.

Migrationsänderungen Godot 3 → 4

Häufige Fehler

1. Vergessen, die Mask zu setzen

Dein Objekt hat einen Layer, aber die Mask ist leer (alles Nullen). Das Objekt existiert in der Physikwelt, erkennt aber nichts. Andere Objekte mit passenden Masken erkennen es weiterhin, aber move_and_slide() auf diesem Objekt geht durch alles hindurch.

2. Layer mit Mask verwechseln

Den Layer des Spielers auf 2 (Enemy) setzen statt seine Mask. Jetzt ist der Spieler ein Gegner, soweit es die Physik-Engine betrifft. Merke dir immer: Layer = was ich bin, Mask = was ich scanne.

3. Bitmask-Werte statt Layer-Nummern verwenden

set_collision_layer_value(4, true) schreiben in dem Glauben, es setze den Bitmask-Wert 4 (Layer 1+2). In Wirklichkeit aktiviert es Layer 4. Die wertbasierte API nimmt Layer-Nummern, keine Bit-Werte.

4. Einseitige Erkennung, wo Beidseitigkeit erwartet wird

Objekt A maskiert B's Layer, aber B maskiert nicht A's Layer. move_and_slide() auf A kollidiert mit B, aber move_and_slide() auf B geht durch A hindurch. Damit sich zwei CharacterBody-Nodes gegenseitig blockieren, müssen beide den Layer des anderen in ihrer Mask haben.