Слои коллизий и физика в Godot 4

Почему слои коллизий важны

Слои коллизий — это основа всех физических взаимодействий в Godot 4 — движения, обнаружения попаданий, рейкастинга, триггеров Area и не только. Понимание разницы между Layer и Mask крайне важно, а её недопонимание — одна из самых распространённых проблем как для новичков, так и для опытных разработчиков.

Layer против Mask — ментальная модель

У каждого физического объекта в Godot есть два свойства-битмаски:

• Layer = «Я существую на этих слоях» (то, чем я являюсь)
• Mask = «Я сканирую эти слои» (то, что я могу видеть / поразить)

Именование слоёв в настройках проекта

Прежде чем писать какой-либо код, дайте имена своим слоям. Это делает инспектор гораздо удобнее в использовании и предотвращает путаницу по мере роста проекта.

Настройки проекта > Имена слоёв > 2D-физика (или 3D-физика):

Установка слоёв в коде (GDScript)

Godot 4 предоставляет два подхода — API на основе значений (рекомендуется) и прямое присваивание битмаски:

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

Распространённые схемы слоёв

Платформер / сайд-скроллер

Вид сверху / рогалик

Слои Area2D / Area3D

Area используют ту же систему Layer/Mask. Кроме того, у них есть два свойства-переключателя:

• monitoring — Если true, эта Area активно обнаруживает другие объекты, входящие в неё.
• monitorable — Если true, другие Area могут обнаружить эту Area.

Сигналы: area_entered против body_entered

body_entered срабатывает, когда PhysicsBody (CharacterBody, RigidBody, StaticBody) входит в Area. area_entered срабатывает, когда входит другая Area. Убедитесь, что вы подключаете правильный сигнал для своего случая.

# 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

У узлов RayCast есть только Mask (нет Layer), потому что они являются детекторами, а не физическими телами. Задайте маску, чтобы отфильтровать, по чему может попадать луч:

# 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

Практический пример: Player – Enemy – Projectile

Вот полная настройка слоёв для типичной экшн-игры. Комментарии показывают логику каждого выбора:

# 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

Советы по отладке

• Отображение форм коллизий: в редакторе перейдите в Отладка > Отображать формы коллизий, чтобы отрисовывать все формы коллизий во время выполнения. Это сразу выявляет отсутствующие или смещённые коллайдеры.
• Проверка в инспекторе: выберите узел и разверните Collision > Layer и Collision > Mask в инспекторе. Наведите курсор на каждый бит, чтобы увидеть его имя (если вы дали им имена в настройках проекта).
• Вывод во время выполнения: print("Layer: ", collision_layer, " Mask: ", collision_mask), чтобы проверить значения битмаски во время игры.

Изменения при миграции с Godot 3 → 4

Распространённые ошибки

1. Забыть задать Mask

У вашего объекта есть Layer, но Mask пуста (все нули). Объект существует в физическом мире, но ничего не обнаруживает. Другие объекты с подходящими масками по-прежнему будут обнаруживать его, но move_and_slide() на этом объекте будет проходить сквозь всё.

2. Спутать Layer с Mask

Установить Layer игрока в 2 (Enemy) вместо его Mask. Теперь игрок является врагом с точки зрения физического движка. Всегда помните: Layer = то, чем я являюсь, Mask = то, что я сканирую.

3. Использовать значения битмаски вместо номеров слоёв

Написать set_collision_layer_value(4, true), думая, что это задаёт значение битмаски 4 (слои 1+2). На самом деле это включает слой 4. API на основе значений принимает номера слоёв, а не битовые значения.

4. Одностороннее обнаружение там, где ожидается двустороннее

Объект A маскирует слой B, но B не маскирует слой A. move_and_slide() на A столкнётся с B, но move_and_slide() на B пройдёт сквозь A. Чтобы два узла CharacterBody блокировали друг друга, оба должны иметь слой другого в своей маске.