Collision layer e fisica in Godot 4

Perché i collision layer sono importanti

I collision layer sono la base di tutte le interazioni fisiche in Godot 4 — movimento, rilevamento dei colpi, raycasting, trigger delle Area e altro ancora. Comprendere la differenza tra Layer e Mask è fondamentale, e fraintenderla è uno dei punti dolenti più comuni sia per i principianti sia per gli sviluppatori esperti.

Layer vs Mask — Il modello mentale

Ogni oggetto fisico in Godot ha due proprietà bitmask:

• Layer = "Io esisto su questi layer" (ciò che sono)
• Mask = "Io scansiono questi layer" (ciò che posso vedere / colpire)

Assegnare nomi ai layer nelle impostazioni del progetto

Prima di scrivere qualsiasi codice, dai un nome ai tuoi layer. Questo rende l'Inspector molto più facile da usare ed evita confusione man mano che il progetto cresce.

Impostazioni progetto > Nomi layer > Fisica 2D (o Fisica 3D):

Impostare i layer nel codice (GDScript)

Godot 4 offre due approcci — l'API basata sui valori (consigliata) e l'assegnazione diretta della bitmask:

# 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)

Schemi di layer comuni

Platformer / Side-scroller

Top-down / Roguelike

Layer di Area2D / Area3D

Le Area usano lo stesso sistema Layer/Mask. In più, hanno due proprietà di attivazione:

• monitoring — Se true, questa Area rileva attivamente gli altri oggetti che vi entrano.
• monitorable — Se true, le altre Area possono rilevare questa Area.

Segnali: area_entered vs body_entered

body_entered viene emesso quando un PhysicsBody (CharacterBody, RigidBody, StaticBody) entra nell'Area. area_entered viene emesso quando un'altra Area vi entra. Assicurati di collegare il segnale giusto per il tuo caso d'uso.

# 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()

Collision mask del RayCast

I nodi RayCast hanno solo una Mask (nessun Layer), perché sono rilevatori e non corpi fisici. Imposta la Mask per filtrare ciò che il raggio può colpire:

# 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

Esempio pratico: Player – Enemy – Projectile

Ecco una configurazione completa dei layer per un tipico gioco d'azione. I commenti mostrano il ragionamento dietro ogni scelta:

# 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

Consigli per il debug

• Forme di collisione visibili: Nell'editor, vai su Debug > Forme di collisione visibili per disegnare tutte le forme di collisione a runtime. Questo rivela immediatamente i collider mancanti o disallineati.
• Verifica nell'Inspector: Seleziona un nodo ed espandi Collision > Layer e Collision > Mask nell'Inspector. Passa il mouse su ogni bit per vederne il nome (se li hai nominati nelle impostazioni del progetto).
• Stampa a runtime: print("Layer: ", collision_layer, " Mask: ", collision_mask) per verificare i valori della bitmask durante il gioco.

Modifiche di migrazione Godot 3 → 4

Errori comuni

1. Dimenticare di impostare la Mask

Il tuo oggetto ha un Layer ma la Mask è vuota (tutti zeri). L'oggetto esiste nel mondo fisico ma non rileva nulla. Gli altri oggetti con maschere corrispondenti continueranno a rilevare lui, ma move_and_slide() su questo oggetto attraverserà tutto.

2. Confondere Layer con Mask

Impostare il Layer del giocatore su 2 (Enemy) invece della sua Mask. Ora, per quanto riguarda il motore fisico, il giocatore è un nemico. Ricorda sempre: Layer = ciò che sono, Mask = ciò che scansiono.

3. Usare valori di bitmask invece dei numeri dei layer

Scrivere set_collision_layer_value(4, true) pensando che imposti il valore bitmask 4 (layer 1+2). In realtà attiva il layer 4. L'API basata sui valori accetta numeri di layer, non valori di bit.

4. Rilevamento unidirezionale dove ci si aspetta la bidirezionalità

L'oggetto A maschera il layer di B, ma B non maschera il layer di A. move_and_slide() su A collide con B, ma move_and_slide() su B attraversa A. Affinché due nodi CharacterBody si blocchino a vicenda, entrambi devono avere il layer dell'altro nella propria mask.