Back to Details

godot-input-handling

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Input Handling

输入处理

Handle keyboard, mouse, gamepad, and touch input with proper buffering and accessibility support.
处理键盘、鼠标、游戏手柄和触摸输入，同时提供完善的缓冲和无障碍支持。

Available Scripts

可用脚本

input_buffer.gd

input_buffer.gd

Input buffering for responsive controls - buffers actions for 150ms to ensure tight game feel.
用于实现响应式控制的输入缓冲脚本 - 将动作缓冲150毫秒，以确保流畅的游戏手感。

input_remapper

input_remapper

Runtime input rebinding with conflict detection and save/load persistence.
MANDATORY - For Responsive Controls: Read input_buffer.gd before implementing jump/dash mechanics.
支持运行时按键重绑定，具备冲突检测和保存/加载持久化功能。
响应式控制必备：在实现跳跃/冲刺机制前，请先阅读input_buffer.gd的内容。

NEVER Do in Input Handling

输入处理的禁忌

  • NEVER poll input in 
    _process()
    for gameplay actions     — Use 
    _physics_process()
    or 
    _unhandled_input()
    _process()` = frame-rate dependent, causes input drops at low FPS.
  • NEVER use hardcoded key checks (
    KEY_W
    , 
    KEY_SPACE
    )     — Use InputMap actions. Hardcoded keys = no rebinding, breaks non-QWERTY keyboards.
  • NEVER ignore controller deadzones — Stick drift at 0.05 magnitude = character walks alone. ALWAYS implement 
    Input.get_axis()
    with 0.15-0.2 deadzone.
  • NEVER assume single input device — Player might switch keyboard → gamepad mid-session. Listen to 
    Input.joy_connection_changed
    and update UI prompts dynamically.
  • NEVER use 
    //_input()
    for gameplay actions     — 
    _input()
    fires for ALL events (including UI). Use 
    _unhandled_input()
    which only fires if UI didn't consume the event.
  • NEVER forget input buffering for responsive controls — Player presses jump 50ms before landing? Without buffer, jump is lost. Buffer inputs for 100-150ms for tight game-feel.
  • 绝对不要在
    _process()
    中轮询游戏玩法相关的输入     — 请使用
    _physics_process()
    或
    _unhandled_input()
    。
    _process()
    依赖帧率，低帧率下会导致输入丢失。
  • 绝对不要使用硬编码的按键检查（如
    KEY_W
    、
    KEY_SPACE
    ）     — 请使用InputMap动作。硬编码按键不支持重绑定，且会在非QWERTY键盘上失效。
  • 绝对不要忽略控制器死区 — 摇杆漂移幅度达到0.05时，角色会自行移动。务必使用带0.15-0.2死区的
    Input.get_axis()
    。
  • 绝对不要假设玩家只使用单一输入设备 — 玩家可能在游戏过程中从键盘切换到游戏手柄。请监听
    Input.joy_connection_changed
    事件，并动态更新UI提示。
  • 绝对不要使用
    _input()
    处理游戏玩法相关的动作     — 
    _input()
    会响应所有事件（包括UI事件）。请使用
    _unhandled_input()
    ，它仅在UI未消耗该事件时触发。
  • 绝对不要忘记为响应式控制添加输入缓冲 — 玩家在落地前50毫秒按下跳跃键？如果没有缓冲，跳跃指令会丢失。为输入设置100-150毫秒的缓冲，以获得流畅的游戏手感。

InputMap Actions

InputMap动作

Setup: Project Settings → Input Map → Add action
gdscript
undefined
设置方法：项目设置 → 输入映射 → 添加动作
gdscript
undefined

Check if action pressed this frame

检查动作是否在当前帧被按下

if Input.is_action_just_pressed("jump"): jump()
if Input.is_action_just_pressed("jump"): jump()

Check if action held

检查动作是否被按住

if Input.is_action_pressed("fire"): shoot()
if Input.is_action_pressed("fire"): shoot()

Check if action released

检查动作是否在当前帧被释放

if Input.is_action_just_released("jump"): release_jump()
if Input.is_action_just_released("jump"): release_jump()

Get axis (-1 to 1)

获取轴值（范围-1到1）

var direction := Input.get_axis("move_left", "move_right")
var direction := Input.get_axis("move_left", "move_right")

Get vector

获取输入向量

var input_vector := Input.get_vector("left", "right", "up", "down")
undefined
var input_vector := Input.get_vector("left", "right", "up", "down")
undefined

InputEvent Processing

InputEvent处理

gdscript
func _input(event: InputEvent) -> void:
    if event is InputEventKey:
        if event.keycode == KEY_ESCAPE and event.pressed:
            pause_game()
    
    if event is InputEventMouseButton:
        if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
            click_position = event.position
gdscript
func _input(event: InputEvent) -> void:
    if event is InputEventKey:
        if event.keycode == KEY_ESCAPE and event.pressed:
            pause_game()
    
    if event is InputEventMouseButton:
        if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
            click_position = event.position

Gamepad Support

游戏手柄支持

gdscript
undefined
gdscript
undefined

Detect controller connection

检测控制器连接

func _ready() -> void: Input.joy_connection_changed.connect(_on_joy_connection_changed)
func _on_joy_connection_changed(device: int, connected: bool) -> void: if connected: print("Controller ", device, " connected")
undefined
func _ready() -> void: Input.joy_connection_changed.connect(_on_joy_connection_changed)
func _on_joy_connection_changed(device: int, connected: bool) -> void: if connected: print("控制器 ", device, " 已连接")
undefined

Reference

参考资料

Related

相关内容

  • Master Skill: godot-master
  • 主技能：godot-master