Fix #439: validate input_map deadzone + diagnostic bind_event errors (#440)

Author: dsarno

plugin/addons/godot_ai/handlers/input_handler.gd

@@ -54,6 +54,10 @@ func add_action(params: Dictionary) -> Dictionary:
 	if action.is_empty():
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: action")
 
+	if deadzone < 0.0 or deadzone > 1.0:
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE,
+			"deadzone must be in [0.0, 1.0] (got %s). Typical values are 0.2-0.5; default is 0.5." % deadzone)
+
 	if InputMap.has_action(action):
 		return ErrorCodes.make(ErrorCodes.INVALID_PARAMS, "Action '%s' already exists" % action)
 
@@ -127,11 +131,13 @@ func bind_event(params: Dictionary) -> Dictionary:
 		return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM, "Missing required param: event_type")
 
 	if not InputMap.has_action(action):
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Action '%s' not found" % action)
+		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE,
+			"Action '%s' not found. Call input_map_manage(op='add_action', params={action: '%s'}) first." % [action, action])
 
-	var event: InputEvent = _create_event(event_type, params)
-	if event == null:
-		return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE, "Unsupported event_type: %s (use key, mouse_button, or joy_button)" % event_type)
+	var event_or_error = _create_event(event_type, params)
+	if event_or_error is Dictionary:
+		return event_or_error
+	var event: InputEvent = event_or_error
 
 	InputMap.action_add_event(action, event)
 
@@ -151,35 +157,45 @@ func bind_event(params: Dictionary) -> Dictionary:
 	}
 
 
-func _create_event(event_type: String, params: Dictionary) -> InputEvent:
+## Returns an InputEvent on success, or a Dictionary error on failure.
+## Caller must check ``result is Dictionary`` before treating it as an event.
+func _create_event(event_type: String, params: Dictionary):
 	match event_type:
 		"key":
 			var ev := InputEventKey.new()
 			var keycode_str: String = params.get("keycode", "")
 			if keycode_str.is_empty():
-				return null
+				return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM,
+					"event_type='key' requires keycode (e.g. 'Space', 'A', 'Enter', 'Escape', 'F1').")
 			ev.keycode = OS.find_keycode_from_string(keycode_str)
 			if ev.keycode == KEY_NONE:
-				return null
+				return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE,
+					"Invalid keycode '%s'. Use Godot keycode names like 'A', 'Space', 'Enter', 'Escape', 'F1', 'Left', 'Right'." % keycode_str)
 			ev.ctrl_pressed = params.get("ctrl", false)
 			ev.alt_pressed = params.get("alt", false)
 			ev.shift_pressed = params.get("shift", false)
 			ev.meta_pressed = params.get("meta", false)
 			return ev
 		"mouse_button":
-			var ev := InputEventMouseButton.new()
-			var button: int = params.get("button", 0)
+			if not params.has("button"):
+				return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM,
+					"event_type='mouse_button' requires button (1=left, 2=right, 3=middle, 4=wheel up, 5=wheel down).")
+			var button: int = int(params.get("button", 0))
 			if button <= 0:
-				return null
+				return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE,
+					"mouse_button button must be > 0 (got %d). Use 1=left, 2=right, 3=middle, 4=wheel up, 5=wheel down." % button)
+			var ev := InputEventMouseButton.new()
 			ev.button_index = button
 			return ev
 		"joy_button":
-			var ev := InputEventJoypadButton.new()
 			if not params.has("button"):
-				return null
+				return ErrorCodes.make(ErrorCodes.MISSING_REQUIRED_PARAM,
+					"event_type='joy_button' requires button (JoyButton index, e.g. 0=A/Cross, 1=B/Circle).")
+			var ev := InputEventJoypadButton.new()
 			ev.button_index = int(params.get("button", 0))
 			return ev
-	return null
+	return ErrorCodes.make(ErrorCodes.VALUE_OUT_OF_RANGE,
+		"Unsupported event_type: '%s'. Use 'key', 'mouse_button', or 'joy_button'." % event_type)
 
 
 func _serialize_event(event: InputEvent) -> Dictionary:

src/godot_ai/tools/input_map.py

@@ -22,14 +22,26 @@
         (``spatial_editor/*``, etc.). The ``is_builtin`` field on each
         entry is true for any action not authored by the user.
   • add_action(action, deadzone=0.5)
-        Create a new empty input action.
+        Create a new empty input action. ``deadzone`` must be in
+        ``[0.0, 1.0]`` — Godot uses it as the analog-stick dead-zone
+        threshold; values outside this range are rejected with
+        ``VALUE_OUT_OF_RANGE``. Typical values are 0.2-0.5; leave the
+        default 0.5 unless you have a reason. Not a key-repeat delay.
   • remove_action(action)
         Remove an action and all its event bindings.
   • bind_event(action, event_type, keycode="", ctrl=False, alt=False,
                 shift=False, meta=False, button=None)
-        Bind a key/mouse/gamepad event to an action. event_type is
-        "key" | "mouse_button" | "joy_button". keycode is required for
-        "key"; button is required for the others.
+        Bind a key/mouse/gamepad event to an action. The action must
+        already exist (call ``add_action`` first). ``event_type`` is
+        ``"key"`` | ``"mouse_button"`` | ``"joy_button"``.
+          - ``key``: ``keycode`` is a Godot keycode *name string* like
+            ``"A"``, ``"Space"``, ``"Enter"``, ``"Escape"``, ``"F1"``,
+            ``"Left"`` — not an integer and not ``KEY_*``. Modifier
+            booleans ``ctrl`` / ``alt`` / ``shift`` / ``meta`` optional.
+          - ``mouse_button``: ``button`` is an int — 1=left, 2=right,
+            3=middle, 4=wheel up, 5=wheel down.
+          - ``joy_button``: ``button`` is the ``JoyButton`` index
+            (e.g. 0=A/Cross, 1=B/Circle).
 """
 
 

test_project/tests/test_input.gd

@@ -101,6 +101,29 @@ func test_add_action_duplicate() -> void:
 	_handler.remove_action({"action": TEST_ACTION})
 
 
+func test_add_action_rejects_deadzone_below_zero() -> void:
+	## Issue #439: callers (LLMs) pass deadzone values outside [0, 1].
+	## Reject explicitly with VALUE_OUT_OF_RANGE so retries can converge.
+	var result := _handler.add_action({"action": TEST_ACTION, "deadzone": -0.1})
+	assert_is_error(result, ErrorCodes.VALUE_OUT_OF_RANGE)
+	assert_false(InputMap.has_action(TEST_ACTION), "Action must not be created on validation failure")
+
+
+func test_add_action_rejects_deadzone_above_one() -> void:
+	var result := _handler.add_action({"action": TEST_ACTION, "deadzone": 1.5})
+	assert_is_error(result, ErrorCodes.VALUE_OUT_OF_RANGE)
+	assert_false(InputMap.has_action(TEST_ACTION), "Action must not be created on validation failure")
+
+
+func test_add_action_accepts_boundary_deadzones() -> void:
+	var result := _handler.add_action({"action": TEST_ACTION, "deadzone": 0.0})
+	assert_has_key(result, "data")
+	_handler.remove_action({"action": TEST_ACTION})
+	result = _handler.add_action({"action": TEST_ACTION, "deadzone": 1.0})
+	assert_has_key(result, "data")
+	_handler.remove_action({"action": TEST_ACTION})
+
+
 # ----- remove_action -----
 
 func test_remove_action_missing_name() -> void:
@@ -142,6 +165,61 @@ func test_bind_event_unsupported_type() -> void:
 	_handler.remove_action({"action": TEST_ACTION})
 
 
+func test_bind_event_key_missing_keycode() -> void:
+	## Issue #439: was collapsed into "Unsupported event_type" — now reports
+	## the actual missing param so retries can converge.
+	_handler.add_action({"action": TEST_ACTION})
+	var result := _handler.bind_event({
+		"action": TEST_ACTION,
+		"event_type": "key",
+	})
+	assert_is_error(result, ErrorCodes.MISSING_REQUIRED_PARAM)
+	_handler.remove_action({"action": TEST_ACTION})
+
+
+func test_bind_event_key_invalid_keycode() -> void:
+	_handler.add_action({"action": TEST_ACTION})
+	var result := _handler.bind_event({
+		"action": TEST_ACTION,
+		"event_type": "key",
+		"keycode": "NotARealKey",
+	})
+	assert_is_error(result, ErrorCodes.VALUE_OUT_OF_RANGE)
+	_handler.remove_action({"action": TEST_ACTION})
+
+
+func test_bind_event_mouse_button_missing_button() -> void:
+	_handler.add_action({"action": TEST_ACTION})
+	var result := _handler.bind_event({
+		"action": TEST_ACTION,
+		"event_type": "mouse_button",
+	})
+	assert_is_error(result, ErrorCodes.MISSING_REQUIRED_PARAM)
+	_handler.remove_action({"action": TEST_ACTION})
+
+
+func test_bind_event_mouse_button_zero_button() -> void:
+	_handler.add_action({"action": TEST_ACTION})
+	var result := _handler.bind_event({
+		"action": TEST_ACTION,
+		"event_type": "mouse_button",
+		"button": 0,
+	})
+	assert_is_error(result, ErrorCodes.VALUE_OUT_OF_RANGE)
+	_handler.remove_action({"action": TEST_ACTION})
+
+
+func test_bind_event_unknown_action_message_suggests_add_action() -> void:
+	## The error string should point the caller at the fix so they don't loop.
+	var result := _handler.bind_event({
+		"action": "_nope_xyz",
+		"event_type": "key",
+		"keycode": "Space",
+	})
+	assert_is_error(result, ErrorCodes.VALUE_OUT_OF_RANGE)
+	assert_contains(result.error.message, "add_action")
+
+
 func test_bind_key_event() -> void:
 	_handler.add_action({"action": TEST_ACTION})
 	var result := _handler.bind_event({