┌──────────────────────────────────────────────────────┐
│                    动作定义层                        │
│   action_id / 显示名 / 分组 / 默认键盘 / 默认手柄     │
└──────────────────────┬───────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────┐
│               InputConfigManager.gd                  │
│                  （AutoLoad 单例）                   │
│                                                      │
│  1. 读取默认动作表                                   │
│  2. 加载用户配置                                     │
│  3. 应用到 Godot InputMap                            │
│  4. 提供 set / get / reset / conflict 接口          │
│  5. 保存到 user://settings.cfg                       │
└───────────────┬───────────────────────┬──────────────┘
                │                       │
                ▼                       ▼
┌────────────────────────┐   ┌─────────────────────────┐
│      KeybindPanel      │   │      游戏业务逻辑       │
│  Scroll + ActionRow    │   │ Input.is_action_pressed │
│                        │   │ 只认 action，不认具体键  │
└────────────────────────┘   └─────────────────────────┘

if Input.is_action_just_pressed("end_turn"):
    _end_turn()

if Input.is_key_pressed(KEY_E):
    _end_turn()

ui_confirm
ui_cancel
view_map
end_turn
select_card_1

Input.is_action_just_pressed("end_turn")

res://scripts/input/input_action_defs.gd

extends RefCounted
class_name InputActionDefs

const ACTION_DEFS: Array[Dictionary] = [
  # ── 通用 ─────────────────────────
  {
    "action": "ui_confirm",
    "label": "确认/选择",
    "group": "通用",
    "default_keyboard": KEY_ENTER,
    "default_gamepad": JOY_BUTTON_A
  },
  {
    "action": "ui_cancel",
    "label": "取消/返回",
    "group": "通用",
    "default_keyboard": KEY_ESCAPE,
    "default_gamepad": JOY_BUTTON_B
  },

  # ── 战斗 ─────────────────────────
  {
    "action": "end_turn",
    "label": "结束回合",
    "group": "战斗",
    "default_keyboard": KEY_E,
    "default_gamepad": JOY_BUTTON_Y
  },
  {
    "action": "view_deck",
    "label": "查看牌组",
    "group": "战斗",
    "default_keyboard": KEY_D,
    "default_gamepad": JOY_BUTTON_X
  },
  {
    "action": "view_map",
    "label": "查看地图",
    "group": "界面",
    "default_keyboard": KEY_M,
    "default_gamepad": JOY_BUTTON_LEFT_SHOULDER
  },

  # ── 数字选牌 ──────────────────────
  {
    "action": "select_card_1",
    "label": "选择牌 #1",
    "group": "卡牌选择",
    "default_keyboard": KEY_1,
    "default_gamepad": JOY_BUTTON_INVALID
  },
  {
    "action": "select_card_2",
    "label": "选择牌 #2",
    "group": "卡牌选择",
    "default_keyboard": KEY_2,
    "default_gamepad": JOY_BUTTON_INVALID
  },
  {
    "action": "select_card_3",
    "label": "选择牌 #3",
    "group": "卡牌选择",
    "default_keyboard": KEY_3,
    "default_gamepad": JOY_BUTTON_INVALID
  }
]

InputMap.action_erase_events(action)
InputMap.action_add_event(action, new_event)

get_keyboard_event(action: String) -> InputEventKey
get_gamepad_event(action: String) -> InputEventJoypadButton

set_keyboard_binding(action: String, keycode: Key) -> void
set_gamepad_binding(action: String, button_index: JoyButton) -> void

clear_keyboard_binding(action: String) -> void
clear_gamepad_binding(action: String) -> void

find_keyboard_conflict(keycode: Key, exclude_action: String) -> String
find_gamepad_conflict(button_index: JoyButton, exclude_action: String) -> String

extends Node

signal binding_changed(action: String, device: String)

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

var _defs: Array[Dictionary] = []
var _label_map: Dictionary = {}
var _group_map: Dictionary = {}

# 运行时真实配置
# 结构：
# {
#   "ui_confirm": {
#       "keyboard": KEY_ENTER,
#       "gamepad": JOY_BUTTON_A
#   }
# }
var bindings: Dictionary = {}

func _ready() -> void:
  _defs = InputActionDefs.ACTION_DEFS
  _build_maps()
  _load_or_init_defaults()
  _apply_all_to_input_map()

func _build_maps() -> void:
  for def in _defs:
    var action: String = str(def["action"])
    _label_map[action] = str(def["label"])
    _group_map[action] = str(def["group"])

    if not InputMap.has_action(action):
      InputMap.add_action(action)

func _load_or_init_defaults() -> void:
  bindings.clear()

  # 先填默认值
  for def in _defs:
    var action: String = str(def["action"])
    bindings[action] = {
      "keyboard": int(def["default_keyboard"]),
      "gamepad": int(def["default_gamepad"])
    }

  # 再尝试读取用户配置
  var cfg := ConfigFile.new()
  if cfg.load(SAVE_PATH) != OK:
    return

  for def in _defs:
    var action: String = str(def["action"])
    bindings[action]["keyboard"] = int(
      cfg.get_value("keybind_keyboard", action, bindings[action]["keyboard"])
    )
    bindings[action]["gamepad"] = int(
      cfg.get_value("keybind_gamepad", action, bindings[action]["gamepad"])
    )

func save_all() -> void:
  var cfg := ConfigFile.new()

  for action in bindings.keys():
    cfg.set_value("keybind_keyboard", action, bindings[action]["keyboard"])
    cfg.set_value("keybind_gamepad", action, bindings[action]["gamepad"])

  cfg.save(SAVE_PATH)

func reset_all_to_default() -> void:
  for def in _defs:
    var action: String = str(def["action"])
    bindings[action]["keyboard"] = int(def["default_keyboard"])
    bindings[action]["gamepad"] = int(def["default_gamepad"])

  _apply_all_to_input_map()
  save_all()

func reset_action_to_default(action: String) -> void:
  for def in _defs:
    if str(def["action"]) == action:
      bindings[action]["keyboard"] = int(def["default_keyboard"])
      bindings[action]["gamepad"] = int(def["default_gamepad"])
      _apply_action_to_input_map(action)
      save_all()
      binding_changed.emit(action, "keyboard")
      binding_changed.emit(action, "gamepad")
      return

func get_all_defs() -> Array[Dictionary]:
  return _defs

func get_label(action: String) -> String:
  return _label_map.get(action, action)

func get_group(action: String) -> String:
  return _group_map.get(action, "")

func get_keyboard_key(action: String) -> Key:
  if not bindings.has(action):
    return KEY_NONE
  return int(bindings[action]["keyboard"]) as Key

func get_gamepad_button(action: String) -> JoyButton:
  if not bindings.has(action):
    return JOY_BUTTON_INVALID
  return int(bindings[action]["gamepad"]) as JoyButton

func set_keyboard_binding(action: String, keycode: Key) -> void:
  if not bindings.has(action):
    return
  bindings[action]["keyboard"] = int(keycode)
  _apply_action_to_input_map(action)
  save_all()
  binding_changed.emit(action, "keyboard")

func set_gamepad_binding(action: String, button_index: JoyButton) -> void:
  if not bindings.has(action):
    return
  bindings[action]["gamepad"] = int(button_index)
  _apply_action_to_input_map(action)
  save_all()
  binding_changed.emit(action, "gamepad")

func clear_keyboard_binding(action: String) -> void:
  set_keyboard_binding(action, KEY_NONE)

func clear_gamepad_binding(action: String) -> void:
  set_gamepad_binding(action, JOY_BUTTON_INVALID)

func find_keyboard_conflict(keycode: Key, exclude_action: String = "") -> String:
  if keycode == KEY_NONE:
    return ""
  for action in bindings.keys():
    if action == exclude_action:
      continue
    if int(bindings[action]["keyboard"]) == int(keycode):
      return action
  return ""

func find_gamepad_conflict(button_index: JoyButton, exclude_action: String = "") -> String:
  if button_index == JOY_BUTTON_INVALID:
    return ""
  for action in bindings.keys():
    if action == exclude_action:
      continue
    if int(bindings[action]["gamepad"]) == int(button_index):
      return action
  return ""

func keyboard_to_text(keycode: Key) -> String:
  if keycode == KEY_NONE:
    return "— 未绑定 —"
  return OS.get_keycode_string(keycode)

func gamepad_to_text(button_index: JoyButton) -> String:
  match button_index:
    JOY_BUTTON_INVALID:
      return "— 未绑定 —"
    JOY_BUTTON_A:
      return "A"
    JOY_BUTTON_B:
      return "B"
    JOY_BUTTON_X:
      return "X"
    JOY_BUTTON_Y:
      return "Y"
    JOY_BUTTON_LEFT_SHOULDER:
      return "LB"
    JOY_BUTTON_RIGHT_SHOULDER:
      return "RB"
    JOY_BUTTON_BACK:
      return "Back"
    JOY_BUTTON_START:
      return "Start"
    _:
      return "Button %d" % button_index

func _apply_all_to_input_map() -> void:
  for action in bindings.keys():
    _apply_action_to_input_map(action)

func _apply_action_to_input_map(action: String) -> void:
  if not InputMap.has_action(action):
    InputMap.add_action(action)

  # 先清空
  InputMap.action_erase_events(action)

  # 再按当前配置重新写入
  var keycode: Key = get_keyboard_key(action)
  if keycode != KEY_NONE:
    var key_event := InputEventKey.new()
    key_event.keycode = keycode
    InputMap.action_add_event(action, key_event)

  var joy_button: JoyButton = get_gamepad_button(action)
  if joy_button != JOY_BUTTON_INVALID:
    var joy_event := InputEventJoypadButton.new()
    joy_event.button_index = joy_button
    InputMap.action_add_event(action, joy_event)

SettingsPopup
├─ Audio Page
├─ Video Page
└─ Keybind Page
   └─ KeybindPanel（独立脚本）
      └─ ActionBindRow × N（独立行）

IDLE
  ↓ 点击键盘列
LISTEN_KEYBOARD
  ↓ 按下新键
成功 / 冲突 / 取消

IDLE
  ↓ 点击手柄列
LISTEN_GAMEPAD
  ↓ 按下手柄按钮
成功 / 冲突 / 取消

                 点击键盘按钮
IDLE ─────────────────────────────► LISTEN_KEYBOARD
  ▲                                      │
  │                                      │ 捕获键盘输入
  │ ESC 取消 / 保存成功 / 关闭页面        ▼
  └──────────────────────────────────────┘

                    点击手柄按钮
IDLE ─────────────────────────────► LISTEN_GAMEPAD
  ▲                                      │
  │                                      │ 捕获手柄按钮
  │ ESC 取消 / 保存成功 / 关闭页面        ▼
  └──────────────────────────────────────┘

CONFLICT
  ↓ 显示提示 1.5 秒
IDLE

set_keybind(action, key)
get_key(action)

┌─────────────────────────────────────────────┐
│ 动作名称          键盘                手柄   │
├─────────────────────────────────────────────┤
│ 确认/选择         Enter               A      │
│ 取消/返回         Esc                 B      │
│ 查看地图          M                   LB     │
│ 结束回合          E                   Y      │
└─────────────────────────────────────────────┘

res://
├─ scenes/
│  └─ menu/
│     └─ ui/
│        ├─ SettingsPopup.tscn
│        ├─ KeybindPanel.tscn
│        └─ ActionBindRow.tscn
├─ scripts/
│  ├─ input/
│  │  ├─ input_action_defs.gd
│  │  └─ input_config_manager.gd
│  └─ menu/
│     ├─ settings_popup.gd
│     ├─ keybind_panel.gd
│     └─ action_bind_row.gd

ActionBindRow (HBoxContainer)
├─ LabelActionName (Label)
├─ BtnKeyboard (Button)
└─ BtnGamepad (Button)

extends HBoxContainer

signal request_rebind(action: String, device: String, row: Node)

enum RowState {
  IDLE,
  LISTEN_KEYBOARD,
  LISTEN_GAMEPAD,
  CONFLICT
}

var action_name: String = ""
var _state: RowState = RowState.IDLE

@onready var label_action_name: Label = $LabelActionName
@onready var btn_keyboard: Button = $BtnKeyboard
@onready var btn_gamepad: Button = $BtnGamepad

func setup(action: String) -> void:
  action_name = action
  label_action_name.text = InputConfigManager.get_label(action_name)
  refresh()

func _ready() -> void:
  btn_keyboard.pressed.connect(_on_keyboard_pressed)
  btn_gamepad.pressed.connect(_on_gamepad_pressed)

func refresh() -> void:
  btn_keyboard.text = InputConfigManager.keyboard_to_text(
    InputConfigManager.get_keyboard_key(action_name)
  )
  btn_gamepad.text = InputConfigManager.gamepad_to_text(
    InputConfigManager.get_gamepad_button(action_name)
  )

func enter_listen_keyboard() -> void:
  _state = RowState.LISTEN_KEYBOARD
  btn_keyboard.text = "按下新按键..."
  set_process_unhandled_input(true)

func enter_listen_gamepad() -> void:
  _state = RowState.LISTEN_GAMEPAD
  btn_gamepad.text = "按下手柄按钮..."
  set_process_unhandled_input(true)

func exit_listening() -> void:
  _state = RowState.IDLE
  set_process_unhandled_input(false)
  refresh()

func show_conflict(device: String, conflict_action: String) -> void:
  _state = RowState.CONFLICT
  var text := "冲突：" + InputConfigManager.get_label(conflict_action)

  if device == "keyboard":
    btn_keyboard.text = text
  else:
    btn_gamepad.text = text

  get_tree().create_timer(1.5).timeout.connect(func():
    exit_listening()
  )

func _on_keyboard_pressed() -> void:
  request_rebind.emit(action_name, "keyboard", self)
  enter_listen_keyboard()

func _on_gamepad_pressed() -> void:
  request_rebind.emit(action_name, "gamepad", self)
  enter_listen_gamepad()

func _unhandled_input(event: InputEvent) -> void:
  match _state:
    RowState.LISTEN_KEYBOARD:
      _handle_keyboard_input(event)
    RowState.LISTEN_GAMEPAD:
      _handle_gamepad_input(event)

func _handle_keyboard_input(event: InputEvent) -> void:
  if not (event is InputEventKey):
    return
  if not event.pressed:
    return

  get_viewport().set_input_as_handled()

  var key_event := event as InputEventKey
  var keycode: Key = key_event.keycode

  if keycode == KEY_ESCAPE:
    exit_listening()
    return

  if keycode == KEY_DELETE or keycode == KEY_BACKSPACE:
    InputConfigManager.clear_keyboard_binding(action_name)
    exit_listening()
    return

  var conflict := InputConfigManager.find_keyboard_conflict(keycode, action_name)
  if conflict != "":
    show_conflict("keyboard", conflict)
    return

  InputConfigManager.set_keyboard_binding(action_name, keycode)
  exit_listening()

func _handle_gamepad_input(event: InputEvent) -> void:
  if not (event is InputEventJoypadButton):
    return
  if not event.pressed:
    return

  get_viewport().set_input_as_handled()

  var joy_event := event as InputEventJoypadButton
  var button_index: JoyButton = joy_event.button_index

  var conflict := InputConfigManager.find_gamepad_conflict(button_index, action_name)
  if conflict != "":
    show_conflict("gamepad", conflict)
    return

  InputConfigManager.set_gamepad_binding(action_name, button_index)
  exit_listening()

KeybindPanel (VBoxContainer)
├─ HeaderRow (HBoxContainer)
│  ├─ LabelActionHeader
│  ├─ LabelKeyboardHeader
│  └─ LabelGamepadHeader
├─ ScrollContainer
│  └─ ActionList (VBoxContainer)
└─ BottomHint (Label)

extends VBoxContainer

@onready var action_list: VBoxContainer = $ScrollContainer/ActionList

var _active_row: Node = null
var _row_scene: PackedScene = preload("res://scenes/menu/ui/ActionBindRow.tscn")

func _ready() -> void:
  call_deferred("_build_rows")

  if not InputConfigManager.binding_changed.is_connected(_on_binding_changed):
    InputConfigManager.binding_changed.connect(_on_binding_changed)

func _build_rows() -> void:
  for child in action_list.get_children():
    child.queue_free()

  var current_group := ""

  for def in InputConfigManager.get_all_defs():
    var group: String = str(def["group"])
    var action: String = str(def["action"])

    if group != current_group:
      current_group = group
      action_list.add_child(_make_group_header(group))

    var row = _row_scene.instantiate()
    action_list.add_child(row)
    row.setup(action)
    row.request_rebind.connect(_on_request_rebind)

func _make_group_header(group_name: String) -> Control:
  var label := Label.new()
  label.text = "■ " + group_name
  label.add_theme_font_size_override("font_size", 15)
  return label

func _on_request_rebind(_action: String, _device: String, row: Node) -> void:
  if _active_row != null and _active_row != row and is_instance_valid(_active_row):
    if _active_row.has_method("exit_listening"):
      _active_row.exit_listening()
  _active_row = row

func _on_binding_changed(_action: String, _device: String) -> void:
  for child in action_list.get_children():
    if child.has_method("refresh"):
      child.refresh()

func cancel_listening() -> void:
  if _active_row != null and is_instance_valid(_active_row):
    if _active_row.has_method("exit_listening"):
      _active_row.exit_listening()
  _active_row = null

func reset_all() -> void:
  InputConfigManager.reset_all_to_default()
  cancel_listening()

SettingsPopup
└─ ContentPanel
   └─ Pages
      ├─ PageAudio
      ├─ PageVideo
      └─ PageKeybind
         └─ KeybindPanel

@onready var page_keybind: Control = $CenterContainer/PanelRoot/Root/VBox/ContentPanel/Pages/PageKeybind

func _switch_tab(tab_index: int) -> void:
  if page_keybind.has_method("cancel_listening"):
    page_keybind.cancel_listening()

  page_audio.visible = tab_index == TAB_AUDIO
  page_video.visible = tab_index == TAB_VIDEO
  page_keybind.visible = tab_index == TAB_KEYBIND

func _on_save_pressed() -> void:
  # 音频 / 图像保存 ...
  InputConfigManager.save_all()
  close_popup()

func _on_reset_pressed() -> void:
  if _current_tab == TAB_KEYBIND:
    if page_keybind.has_method("reset_all"):
      page_keybind.reset_all()

func close_popup() -> void:
  if page_keybind.has_method("cancel_listening"):
    page_keybind.cancel_listening()
  hide()

func _process(_delta: float) -> void:
  if Input.is_action_just_pressed("end_turn"):
    _end_turn()

  if Input.is_action_just_pressed("view_deck"):
    _toggle_deck()

  if Input.is_action_just_pressed("view_map"):
    _open_map()

  if Input.is_action_just_pressed("select_card_1"):
    _select_card(0)

  if Input.is_action_just_pressed("select_card_2"):
    _select_card(1)

default_mouse

get_mouse_event
set_mouse_binding
find_mouse_conflict

bindings[action]["keyboard"]

bindings[player_id][action]["keyboard"]
bindings[player_id][action]["gamepad"]

[E] 结束回合
[M] 地图
[A] 确认

SettingsManager
InputConfigManager

get_viewport().set_input_as_handled()

call_deferred("_build_rows")

InputConfigManager.binding_changed

print(InputConfigManager.keyboard_to_text(
  InputConfigManager.get_keyboard_key("end_turn")
))

做 ActionBindRow.tscn 和 action_bind_row.gd。