Warstwy kolizji i fizyka w Godot 4

Dlaczego warstwy kolizji są ważne

Warstwy kolizji są podstawą wszystkich interakcji fizycznych w Godot 4 — ruchu, wykrywania trafień, raycastingu, wyzwalaczy Area i nie tylko. Zrozumienie różnicy między Layer a Mask jest kluczowe, a jej niezrozumienie to jeden z najczęstszych problemów zarówno dla początkujących, jak i dla doświadczonych deweloperów.

Layer vs Mask — Model myślowy

Każdy obiekt fizyczny w Godot ma dwie właściwości typu bitmaska:

• Layer = „Istnieję na tych warstwach" (czym jestem)
• Mask = „Skanuję te warstwy" (co mogę widzieć / trafić)

Nazywanie warstw w ustawieniach projektu

Zanim napiszesz jakikolwiek kod, nazwij swoje warstwy. Dzięki temu inspektor jest znacznie łatwiejszy w użyciu i unikniesz zamieszania, gdy projekt się rozrośnie.

Ustawienia projektu > Nazwy warstw > Fizyka 2D (lub Fizyka 3D):

Ustawianie warstw w kodzie (GDScript)

Godot 4 oferuje dwa podejścia — API oparte na wartościach (zalecane) oraz bezpośrednie przypisanie bitmaski:

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

Typowe schematy warstw

Platformówka / Side-scroller

Top-down / Roguelike

Warstwy Area2D / Area3D

Area używa tego samego systemu Layer/Mask. Dodatkowo posiada dwie właściwości przełączane:

• monitoring — Gdy true, ta Area aktywnie wykrywa inne obiekty do niej wchodzące.
• monitorable — Gdy true, inne Area mogą wykryć tę Area.

Sygnały: area_entered vs body_entered

body_entered uruchamia się, gdy do Area wchodzi PhysicsBody (CharacterBody, RigidBody, StaticBody). area_entered uruchamia się, gdy wchodzi inna Area. Upewnij się, że podłączasz właściwy sygnał do swojego przypadku użycia.

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

Maska kolizji RayCast

Węzły RayCast mają tylko Mask (bez Layer), ponieważ są detektorami, a nie ciałami fizycznymi. Ustaw maskę, aby filtrować to, w co promień może trafić:

# 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

Praktyczny przykład: Player – Enemy – Projectile

Oto kompletna konfiguracja warstw dla typowej gry akcji. Komentarze pokazują tok rozumowania stojący za każdą decyzją:

# 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

Wskazówki do debugowania

• Widoczne kształty kolizji: W edytorze przejdź do Debugowanie > Widoczne kształty kolizji, aby renderować wszystkie kształty kolizji w czasie działania. Natychmiast ujawnia to brakujące lub źle wyrównane collidery.
• Sprawdzenie w inspektorze: Wybierz węzeł i rozwiń Collision > Layer oraz Collision > Mask w inspektorze. Najedź na każdy bit, aby zobaczyć jego nazwę (jeśli nazwałeś je w ustawieniach projektu).
• Wypisz w czasie działania: print("Layer: ", collision_layer, " Mask: ", collision_mask), aby zweryfikować wartości bitmaski podczas rozgrywki.

Zmiany migracyjne Godot 3 → 4

Częste błędy

1. Zapomnienie o ustawieniu maski

Twój obiekt ma warstwę, ale maska jest pusta (same zera). Obiekt istnieje w świecie fizyki, ale niczego nie wykrywa. Inne obiekty z pasującymi maskami wciąż go wykryją, ale move_and_slide() na tym obiekcie będzie przenikać przez wszystko.

2. Mylenie Layer z Mask

Ustawienie Layer gracza na 2 (Enemy) zamiast jego Mask. Teraz gracz jest przeciwnikiem z punktu widzenia silnika fizyki. Zawsze pamiętaj: Layer = czym jestem, Mask = co skanuję.

3. Używanie wartości bitmaski zamiast numerów warstw

Napisanie set_collision_layer_value(4, true) w przekonaniu, że ustawia ono wartość bitmaski 4 (warstwy 1+2). W rzeczywistości włącza to warstwę 4. API oparte na wartościach przyjmuje numery warstw, a nie wartości bitów.

4. Jednokierunkowe wykrywanie tam, gdzie oczekiwane jest dwukierunkowe

Obiekt A maskuje warstwę B, ale B nie maskuje warstwy A. move_and_slide() na A zderzy się z B, ale move_and_slide() na B przeniknie przez A. Aby dwa węzły CharacterBody wzajemnie się blokowały, oba muszą mieć warstwę drugiego w swojej masce.