Godot 4 GDScript：2D角色按键单次移动32像素问题排查

问题概述 #

使用Godot 4编写2D角色控制脚本，期望按下方向键后角色单次移动32像素、跳跃动作正常抬升，但实际角色仅移动1像素，跳跃高度也仅1像素。调试日志显示measured_distance已累计到32，但实际移动效果不符合预期。

核心问题分析 #

1. 跳跃逻辑错误：给velocity.y赋值时错误乘以delta，导致跳跃速度被大幅缩小（如-230 * 0.016 ≈ -3.68），实际仅能跳跃极小距离。
2. 移动速度计算错误：CharacterBody2D的velocity是每秒移动量，无需手动乘delta，但原代码中错误地将velocity.x设置为dir * speed * delta，导致实际速度极低，一帧仅移动约1像素。
3. 步进距离测量逻辑错误：measured_distance累加的是每秒速度值而非实际帧移动距离，且通过min直接将其限制为32，导致第一帧就触发停止条件，角色仅移动一帧就停止。

修复后的完整代码 #

extends CharacterBody2D

# MOVEMENT
@export var speed: int = 100
@export var step_distance: int = 32  # 单次步进目标距离（像素）
@export var jump_velocity: int = -230  # 跳跃初始速度（向上为负）
var measured_distance: float = 0  # 累计已移动距离（用float避免精度丢失）
var stepping: bool = false
var target_step: float = 0  # 目标移动距离（±step_distance）

# PHYSICS
var gravity = ProjectSettings.get_setting("physics/2d/default_gravity")

# 初始化步进流程
func start_step(target: float):
    stepping = true
    measured_distance = 0
    target_step = target

# 停止水平移动
func stop_step():
    velocity.x = move_toward(velocity.x, 0, speed)

# 处理步进移动逻辑
func process_step(delta):
    if target_step != 0:
        var direction = sign(target_step)
        # 计算当前帧最大可移动距离
        var max_frame_move = speed * delta
        # 计算剩余需要移动的距离
        var remaining = abs(target_step) - measured_distance
        
        if remaining <= max_frame_move:
            # 剩余距离不足一帧，直接移动剩余距离
            velocity.x = direction * remaining / delta
            measured_distance += remaining
            # 完成步进，重置状态
            target_step = 0
            stepping = false
        else:
            # 按最大速度移动
            velocity.x = direction * speed
            measured_distance += max_frame_move
    else:
        stop_step()

func _physics_process(delta):
    # 重力施加
    if !is_on_floor():
        velocity.y += gravity * delta
    
    # 跳跃修复：移除多余的delta
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = jump_velocity
    
    # 触发步进：未步进时响应方向键
    if !stepping:
        if Input.is_action_just_pressed("right"):
            start_step(step_distance)
        elif Input.is_action_just_pressed("left"):
            start_step(-step_distance)
    
    # 处理步进移动
    process_step(delta)
    
    # 执行移动
    move_and_slide()

关键修改说明 #

• 跳跃修复：删除velocity.y = jump_velocity * delta中的* delta，velocity作为每秒速度，move_and_slide会自动结合delta计算帧移动量。
• 步进逻辑重构：
  • 改用剩余距离判断，每帧计算实际可移动的最大距离，避免超量移动。
  • 将measured_distance改为float类型，避免整数精度丢失。
  • 当剩余距离不足一帧时，调整速度确保刚好移动到目标距离，避免过冲。
• 速度设置修正：velocity.x直接设置为方向 × speed（每秒速度），符合Godot的CharacterBody2D速度规范。

优化建议 #

• 使用Tween简化步进：可以用Godot的Tween节点实现更流畅的步进移动，无需手动处理delta和速度计算，代码更简洁：

  func start_step(target: float):
      stepping = true
      var tween = create_tween()
      tween.tween_property(self, "position:x", position.x + target, abs(target)/speed)
      tween.finished.connect():=
          stepping = false
  

• 添加输入冷却：防止快速连续按键导致的步进状态冲突。
• 代码模块化：将步进逻辑封装为单独函数或节点，提高复用性。

推荐教程 #

• Godot官方中文文档：《2D角色移动》，详细讲解CharacterBody2D的核心移动逻辑。
• Godot官方教程：《俯视角角色控制》，核心移动逻辑可复用至平台跳跃游戏。
• B站《Godot 4 2D平台游戏入门》系列，适合新手快速掌握基础控制逻辑。

内容的提问来源于stack exchange，提问作者Mimo