Godot 输入

玩法输入走 InputMap 动作，同一动作绑键盘与手柄，用 Input 的轴和向量接口读值。

范围

先查内置

做法

定义动作

在项目设置 Input Map 页添加，键盘与手柄放进同一个动作：

[input]

jump={
"deadzone": 0.2,
"events": Array[InputEvent]([Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":32,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
, Object(InputEventJoypadButton,"resource_local_to_scene":false,"resource_name":"","device":-1,"button_index":0,"pressure":0.0,"pressed":false,"script":null)
])
}

• 动作名用玩法语义，不复用驱动 UI 焦点的 ui_accept ui_up

extends CharacterBody2D

const SPEED := 220.0

func _physics_process(_delta: float) -> void:
	velocity = Input.get_vector(&"move_left", &"move_right", &"move_up", &"move_down") * SPEED
	move_and_slide()

• get_vector 长度已限制为 1，不用再 normalized()
• get_vector 第五个参数可覆盖死区
• 只有横向的平台游戏用 Input.get_axis(&"move_left", &"move_right")
• 模拟量用 Input.get_action_strength

回调选择

事件顺序：_input、GUI、_shortcut_input、_unhandled_key_input、_unhandled_input。处理完调 get_viewport().set_input_as_handled()。

• 事件回调里用 event.is_action_pressed(&"jump")，不用 Input.is_action_just_pressed
• event.is_action_pressed 默认不含按住重复，要重复传 allow_echo = true
• Input.is_action_just_pressed 在 _process 里按帧、在 _physics_process 里按 tick 判断
• 一帧跑多个 tick 时只有一个 tick 为 true，按下后迅速松开也为 true
• 在哪个回调里消费就在哪个回调里读，不在 _process 置标志给物理消费

输入缓冲

_unhandled_input 记录，物理里消费。时间用 Engine.get_physics_frames()，回放时结果一致：

extends CharacterBody2D

const BUFFER_TICKS := 6
const JUMP_SPEED := -420.0

var _jump_pressed_tick: int = -1000

func _unhandled_input(event: InputEvent) -> void:
	if event.is_action_pressed(&"jump"):
		_jump_pressed_tick = Engine.get_physics_frames()

func _physics_process(delta: float) -> void:
	if not is_on_floor():
		velocity += get_gravity() * delta
	elif Engine.get_physics_frames() - _jump_pressed_tick <= BUFFER_TICKS:
		velocity.y = JUMP_SPEED
		_jump_pressed_tick = -1000
	move_and_slide()

改键

extends Node

const SAVE_PATH := "user://keybinds.cfg"

func rebind(action: StringName, event: InputEventKey) -> void:
	_apply(action, event)
	var cfg := ConfigFile.new()
	cfg.load(SAVE_PATH)
	cfg.set_value("keys", action, event.physical_keycode)
	cfg.save(SAVE_PATH)

func load_saved(actions: Array[StringName]) -> void:
	var cfg := ConfigFile.new()
	if cfg.load(SAVE_PATH) != OK:
		return
	for action in actions:
		if cfg.has_section_key("keys", action):
			var event := InputEventKey.new()
			event.physical_keycode = cfg.get_value("keys", action) as Key
			_apply(action, event)

func _apply(action: StringName, event: InputEventKey) -> void:
	for old: InputEvent in InputMap.action_get_events(action):
		if old is InputEventKey:
			InputMap.action_erase_event(action, old)
	InputMap.action_add_event(action, event)

• 只清同一类设备的事件，改键盘键不清手柄绑定
• 存档存键码整数，启动时调一次 load_saved
• 恢复默认：InputMap.load_from_project_settings() 再删存档文件
• 冲突检测：遍历 InputMap.get_actions() 逐个 InputMap.action_has_event()
• 捕获新按键：监听状态下在 _input 里接第一个 pressed 的 InputEventKey，调 set_input_as_handled()
• 捕获时 Esc 取消，手柄接 InputEventJoypadButton

鼠标与触屏

• InputEventMouseMotion.relative 按拉伸缩放，灵敏度随分辨率变
• VirtualJoystick 的 action_* 默认是 ui_*，必须改成玩法动作
• VirtualJoystick 的 deadzone_ratio 默认 0.0，设了以后先于动作死区生效
• input_devices/pointing/emulate_mouse_from_touch 默认开，触摸合成鼠标事件

手柄

• 震动：Input.start_joy_vibration(device, weak, strong, duration)，强度 0 到 1
• duration 为 0 时约 65 秒，Input.stop_joy_vibration 提前停，给玩家留关闭选项
• 热插拔：连 Input.joy_connection_changed 信号，已连接设备用 Input.get_connected_joypads()

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• https://docs.godotengine.org/en/stable/tutorials/inputs/inputevent.html
• https://docs.godotengine.org/en/stable/tutorials/inputs/input_examples.html
• https://docs.godotengine.org/en/stable/tutorials/inputs/controllers_gamepads_joysticks.html