游戏引擎 / 系统课时
补上重力与地面检测
补上重力与地面检测
角色能左右移动却停在半空,通常是因为 CharacterBody3D 不会自动受到重力。本课将重力与地面接触判断放进固定物理步,完成下坠、触地和再次离开平台的循环,并避免角色落地后继续累积向下速度。
学习目标
- 搭建具备实际碰撞形状的角色与静态地面。
- 用
delta计算重力,并正确理解is_on_floor()的时机。 - 验证落地和离地,排除碰撞层、坡角与出生位置问题。
建立可碰撞的测试场景
在 Godot 4 的 Main(Node3D)下创建 Floor(StaticBody3D),添加 CollisionShape3D 和 MeshInstance3D。碰撞形状选 BoxShape3D,尺寸设为 Vector3(12, 0.4, 12);将地板中心放在 (0, -0.2, 0),顶面便位于 y=0。可见网格可使用等尺寸的 BoxMesh,但网格不能代替碰撞体。
再建 Player(CharacterBody3D),子节点 CollisionShape3D 采用 CapsuleShape3D,半径 0.35、高度 1.8,并添加可见胶囊网格。把角色中心放在 (0, 3, 0),避免初始重叠。角色的碰撞掩码必须包含地板所在层;初次测试保留默认配置即可。场景还应有对准角色与地板的当前 Camera3D。
在物理步中计算下落
将下面的完整脚本保存为 Player.gd,挂在 Player 根节点。ui_left、ui_right、ui_up、ui_down 是 Godot 项目的常用输入动作;若项目曾删除这些映射,请在输入映射中重新绑定方向键。
extends CharacterBody3D
@export var move_speed: float = 5.0
@export var gravity_acceleration: float = 9.8
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
# 接地时清除垂直下落速度;空中按物理步长累加重力。
if is_on_floor():
velocity.y = 0.0
else:
velocity.y -= gravity_acceleration * delta
# 根据每秒速度完成位移、滑动和碰撞更新。
move_and_slide()预期结果:运行场景后,角色从高处落下并停在地板表面;按方向键可水平移动,走出边缘后重新下落。velocity.y 在空中逐渐变负,触地时由碰撞响应修正,接地分支使它不再持续积累负值。
这里的 velocity 表示每秒速度,而重力是每秒速度的变化率,所以只给重力乘 delta;move_and_slide() 已使用物理步长计算移动,不能再把 velocity 乘一次 delta。也不要直接修改 position.y 来模拟重力,否则会绕过预期的角色滑动和碰撞处理。
看懂地面状态更新顺序
在 _physics_process() 开头读取 is_on_floor(),得到的是上一次 move_and_slide() 的地面接触结果。本帧先据此决定是否继续下坠,再调用 move_and_slide();调用结束后,新的接触状态才可供本帧后续逻辑或下一个物理帧读取。

is_on_floor() 并非独立的向下射线检测。它根据角色与其他碰撞体的接触、up_direction 和 floor_max_angle 判定地面;默认最大地面坡角约为 45°。如果角色沿缓坡下行出现短暂离地,可以在确认碰撞形状正确后检查 floor_snap_length,而不是盲目增加重力。
按现象定位落地问题
- 直接穿过地板:确认
Floor使用StaticBody3D和启用的CollisionShape3D,且角色碰撞掩码覆盖地板碰撞层;只有MeshInstance3D不会挡住角色。 - 碰到斜面仍被判为空中:检查坡角是否超过
floor_max_angle,以及up_direction是否保持符合场景重力方向的Vector3.UP。 - 出生后被顶开或抖动:检查胶囊底端是否在地板顶面以下,避免节点缩放造成碰撞形状失真。
- 站定仍反复离地:优先排除地板接缝、尺寸误差和过小的地面吸附距离,再观察每帧
is_on_floor()的变化。
先在水平静态平台上得到稳定的落地结果,再测试坡面和移动平台。相关碰撞属性可对照 CharacterBody3D 官方参考,不要把碰撞不成立的问题误判为重力数值太小。