游戏引擎 / 系统课时

排查角色卡墙与穿地

排查角色卡墙与穿地

角色贴着墙角无法转身、走过窄门时卡住,或落地后继续下沉,可能来自形状不合适、碰撞层不匹配,也可能是脚本直接改位置绕开了物理移动。本课按可见形状、碰撞资格、移动方法的顺序定位问题,再用接触状态日志核实修复。

学习目标

  • 使用碰撞形状可视化,区分正常挡墙与异常卡住。
  • 检查角色、地板和墙的层、遮罩、形状尺寸与偏移。
  • 用 move_and_slide() 及接触状态日志验证落地和贴墙行为。

先把症状对应到可检查的物理条件

站在墙前按住前进键而停止,是正确的阻挡;只有角色在足够宽的通道内也被卡住、轻微转向就抖动,才需要排查形状。穿地则先区分“始终没有地面碰撞”和“移动、瞬移后才穿透”两种情况。

运行场景时,在 Godot 编辑器顶部打开 Debug > Visible Collision Shapes,确认角色胶囊、墙盒和地板盒的真实边界。视觉网格 MeshInstance3D 的大小与碰撞盒未必相同,所以不要只看角色模型是否碰到了墙。

角色卡墙与穿地的分支排查流程

先修正层、遮罩和形状

建立最小复现场景:Player (CharacterBody3D) 下有启用的胶囊 CollisionShape3D;Floor 和 Wall 分别是带盒形状的 StaticBody3D。让地板、墙位于物理第 1 层,角色位于第 2 层,角色碰撞遮罩勾选第 1 层。物理体的层写着它“属于哪里”,角色遮罩决定它会扫描哪些障碍。

接着检查三个空间细节。首先,胶囊底部应接近脚底,而不是延伸到地板下方;其次,墙的盒形状不要比可见墙面多伸出很大一截,门洞宽度应大于胶囊直径并留合理余量;最后,尽量让角色根节点和 CollisionShape3D 保持统一缩放,通过 CapsuleShape3D 的半径、高度修正尺寸,避免非等比缩放造成形状判断不直观。

用物理帧移动和接触日志复现

把下面的完整脚本挂在 Player (CharacterBody3D) 上。预先摆好地板、墙和胶囊,让角色从地面上方开始下落。它使用 Godot 默认的 ui_left、ui_right、ui_up、ui_down 输入动作,可先用方向键测试;若项目改过输入映射,请确保四个动作仍存在且已绑定按键。

gdscript
extends CharacterBody3D

@export var move_speed: float = 5.0
@export var gravity_accel: float = 18.0

var last_floor: bool = false
var last_wall: bool = false

func _ready() -> void:
    # 吸附用于减轻小坡度落差造成的短暂离地,不修复缺失碰撞
    floor_snap_length = 0.2

func _physics_process(delta: float) -> void:
    var axis := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    velocity.x = axis.x * move_speed
    velocity.z = axis.y * move_speed

    # 速度以单位/秒表示;只有重力累积需要在这里乘 delta
    if is_on_floor():
        velocity.y = 0.0
    else:
        velocity.y -= gravity_accel * delta

    move_and_slide()

    var floor_now := is_on_floor()
    var wall_now := is_on_wall()
    if floor_now != last_floor or wall_now != last_wall:
        print("floor=", floor_now, " wall=", wall_now)
        last_floor = floor_now
        last_wall = wall_now

预期输出(角色先落地,再朝垂直墙面持续移动;接触时序可能随初始位置变化):

text
floor=true wall=false
floor=true wall=true

is_on_floor() 和 is_on_wall() 反映最近一次 move_and_slide() 的接触分类。因此先调用移动方法,再读状态。日志只在状态变化时打印,不会每个物理帧刷屏。move_and_slide() 会按物理步长使用 velocity,不要额外把水平速度乘以 delta,也不要在同一帧随后用 global_position += ... 覆盖碰撞结果。

按现象修复并复测

现象 优先检查 正确修复方向
宽门看起来能过,角色却卡住 胶囊直径、门洞碰撞盒、偏移 调整实际碰撞尺寸或通道宽度,而不是只改可见模型
贴墙抖动、角落突然弹开 初始形状重叠、非等比缩放、多面接触 先消除重叠,再根据场景微调 safe_margin
角色持续穿过地板 地板物理体及形状、角色遮罩 补齐 StaticBody3D 和形状,保证第 1 层被角色扫描
正常走路能碰撞,瞬移后穿入墙地 直接赋值位置、出生点嵌入障碍 调整出生点,移动期间统一使用物理移动方法

每次只改一个因素并重复同一条路径:从固定高度落地、沿墙移动、穿过目标门洞。合格结果是落地日志出现 floor=true,贴墙时出现 wall=true,离开障碍后状态正确复原,而且不存在可见模型与碰撞边界明显错位。floor_snap_length 用于坡面接地,safe_margin 用于碰撞恢复;它们都不能代替层、形状和移动方式的根本修复。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查角色卡墙与穿地

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通