Add ui_set_anchor_preset — Control layout presets for HUD and menus (#15)

First entry in the ui_* tool family. Wraps Control.set_anchors_and_offsets_preset so agents can pin a HUD element, pause menu, or upgrade-draft panel to an edge / corner / full rect with one call instead of eight coupled property sets.

- plugin/addons/godot_ai/handlers/ui_handler.gd maps string preset names and resize-mode names to Control enums, validates the node is a Control, and records an undo that restores all 8 anchor/offset properties.
- Python tool ui_set_anchor_preset (defer-loaded, session-targetable, require_writable gating).
- GDScript test_ui.gd covers happy path, validation errors, and undo restoration; Python unit + integration tests mirror the shim.

Author: dsarno

plugin/addons/godot_ai/handlers/ui_handler.gd

@@ -0,0 +1,138 @@
+@tool
+class_name UiHandler
+extends RefCounted
+
+## Handles UI-specific (Control) layout helpers: anchor presets, etc.
+##
+## Anchors/offsets are the worst part of Control layout to set one-property-at-a-time.
+## This handler wraps Godot's built-in presets (FULL_RECT, CENTER, TOP_LEFT, ...) so
+## callers can set a whole layout with one command, with proper undo.
+
+var _undo_redo: EditorUndoRedoManager
+
+
+const _PRESETS := {
+	"top_left": Control.PRESET_TOP_LEFT,
+	"top_right": Control.PRESET_TOP_RIGHT,
+	"bottom_left": Control.PRESET_BOTTOM_LEFT,
+	"bottom_right": Control.PRESET_BOTTOM_RIGHT,
+	"center_left": Control.PRESET_CENTER_LEFT,
+	"center_top": Control.PRESET_CENTER_TOP,
+	"center_right": Control.PRESET_CENTER_RIGHT,
+	"center_bottom": Control.PRESET_CENTER_BOTTOM,
+	"center": Control.PRESET_CENTER,
+	"left_wide": Control.PRESET_LEFT_WIDE,
+	"top_wide": Control.PRESET_TOP_WIDE,
+	"right_wide": Control.PRESET_RIGHT_WIDE,
+	"bottom_wide": Control.PRESET_BOTTOM_WIDE,
+	"vcenter_wide": Control.PRESET_VCENTER_WIDE,
+	"hcenter_wide": Control.PRESET_HCENTER_WIDE,
+	"full_rect": Control.PRESET_FULL_RECT,
+}
+
+const _RESIZE_MODES := {
+	"minsize": Control.PRESET_MODE_MINSIZE,
+	"keep_width": Control.PRESET_MODE_KEEP_WIDTH,
+	"keep_height": Control.PRESET_MODE_KEEP_HEIGHT,
+	"keep_size": Control.PRESET_MODE_KEEP_SIZE,
+}
+
+const _ANCHOR_OFFSET_PROPS := [
+	"anchor_left", "anchor_top", "anchor_right", "anchor_bottom",
+	"offset_left", "offset_top", "offset_right", "offset_bottom",
+]
+
+
+func _init(undo_redo: EditorUndoRedoManager) -> void:
+	_undo_redo = undo_redo
+
+
+## Apply a Control layout preset (anchors + offsets) to a UI node.
+##
+## Params:
+##   path        - scene path to a Control node (required)
+##   preset      - preset name: full_rect, center, top_left, ... (required)
+##   resize_mode - minsize | keep_width | keep_height | keep_size (default: minsize)
+##   margin      - integer margin in pixels from the anchor edges (default: 0)
+func set_anchor_preset(params: Dictionary) -> Dictionary:
+	var node_path: String = params.get("path", "")
+	if node_path.is_empty():
+		return McpErrorCodes.make(McpErrorCodes.INVALID_PARAMS, "Missing required param: path")
+
+	var preset_name: String = str(params.get("preset", "")).to_lower()
+	if preset_name.is_empty():
+		return McpErrorCodes.make(McpErrorCodes.INVALID_PARAMS, "Missing required param: preset")
+	if not _PRESETS.has(preset_name):
+		var names := _PRESETS.keys()
+		names.sort()
+		return McpErrorCodes.make(
+			McpErrorCodes.INVALID_PARAMS,
+			"Unknown preset '%s'. Valid: %s" % [preset_name, ", ".join(names)]
+		)
+
+	var resize_mode_name: String = str(params.get("resize_mode", "minsize")).to_lower()
+	if not _RESIZE_MODES.has(resize_mode_name):
+		var names := _RESIZE_MODES.keys()
+		names.sort()
+		return McpErrorCodes.make(
+			McpErrorCodes.INVALID_PARAMS,
+			"Unknown resize_mode '%s'. Valid: %s" % [resize_mode_name, ", ".join(names)]
+		)
+
+	var margin: int = int(params.get("margin", 0))
+
+	var scene_root := EditorInterface.get_edited_scene_root()
+	if scene_root == null:
+		return McpErrorCodes.make(McpErrorCodes.EDITOR_NOT_READY, "No scene open")
+
+	var node := ScenePath.resolve(node_path, scene_root)
+	if node == null:
+		return McpErrorCodes.make(McpErrorCodes.INVALID_PARAMS, "Node not found: %s" % node_path)
+	if not node is Control:
+		return McpErrorCodes.make(
+			McpErrorCodes.INVALID_PARAMS,
+			"Node %s is not a Control (got %s)" % [node_path, node.get_class()]
+		)
+
+	var control := node as Control
+	var preset_value: int = _PRESETS[preset_name]
+	var resize_mode_value: int = _RESIZE_MODES[resize_mode_name]
+
+	# Snapshot before so we can undo every property the preset may have touched.
+	var before: Dictionary = {}
+	for prop in _ANCHOR_OFFSET_PROPS:
+		before[prop] = control.get(prop)
+
+	_undo_redo.create_action("MCP: Set %s anchor preset %s" % [control.name, preset_name])
+	_undo_redo.add_do_method(
+		control, "set_anchors_and_offsets_preset", preset_value, resize_mode_value, margin
+	)
+	for prop in _ANCHOR_OFFSET_PROPS:
+		_undo_redo.add_undo_property(control, prop, before[prop])
+	_undo_redo.commit_action()
+
+	var after: Dictionary = {}
+	for prop in _ANCHOR_OFFSET_PROPS:
+		after[prop] = control.get(prop)
+
+	return {
+		"data": {
+			"path": node_path,
+			"preset": preset_name,
+			"resize_mode": resize_mode_name,
+			"margin": margin,
+			"anchors": {
+				"left": after.anchor_left,
+				"top": after.anchor_top,
+				"right": after.anchor_right,
+				"bottom": after.anchor_bottom,
+			},
+			"offsets": {
+				"left": after.offset_left,
+				"top": after.offset_top,
+				"right": after.offset_right,
+				"bottom": after.offset_bottom,
+			},
+			"undoable": true,
+		}
+	}

plugin/addons/godot_ai/plugin.gd

@@ -31,7 +31,8 @@ func _enter_tree() -> void:
 	var input_handler := InputHandler.new()
 	var test_handler := TestHandler.new(get_undo_redo(), _log_buffer)
 	var batch_handler := BatchHandler.new(_dispatcher, get_undo_redo())
-	_handlers = [editor_handler, scene_handler, node_handler, project_handler, client_handler, script_handler, resource_handler, filesystem_handler, signal_handler, autoload_handler, input_handler, test_handler, batch_handler]
+	var ui_handler := UiHandler.new(get_undo_redo())
+	_handlers = [editor_handler, scene_handler, node_handler, project_handler, client_handler, script_handler, resource_handler, filesystem_handler, signal_handler, autoload_handler, input_handler, test_handler, batch_handler, ui_handler]
 
 	_dispatcher.register("get_editor_state", editor_handler.get_editor_state)
 	_dispatcher.register("get_scene_tree", scene_handler.get_scene_tree)
@@ -93,6 +94,7 @@ func _enter_tree() -> void:
 	_dispatcher.register("run_tests", test_handler.run_tests)
 	_dispatcher.register("get_test_results", test_handler.get_test_results)
 	_dispatcher.register("batch_execute", batch_handler.batch_execute)
+	_dispatcher.register("set_anchor_preset", ui_handler.set_anchor_preset)
 
 	_connection.dispatcher = _dispatcher
 	add_child(_connection)

src/godot_ai/handlers/ui.py

@@ -0,0 +1,25 @@
+"""Shared handlers for UI (Control layout) tools."""
+
+from __future__ import annotations
+
+from godot_ai.handlers._readiness import require_writable
+from godot_ai.runtime.interface import Runtime
+
+
+async def ui_set_anchor_preset(
+    runtime: Runtime,
+    path: str,
+    preset: str,
+    resize_mode: str = "minsize",
+    margin: int = 0,
+) -> dict:
+    require_writable(runtime)
+    return await runtime.send_command(
+        "set_anchor_preset",
+        {
+            "path": path,
+            "preset": preset,
+            "resize_mode": resize_mode,
+            "margin": margin,
+        },
+    )

src/godot_ai/server.py

@@ -30,6 +30,7 @@
 from godot_ai.tools.session import register_session_tools
 from godot_ai.tools.signal import register_signal_tools
 from godot_ai.tools.testing import register_testing_tools
+from godot_ai.tools.ui import register_ui_tools
 from godot_ai.transport.websocket import GodotWebSocketServer
 
 logger = logging.getLogger(__name__)
@@ -84,6 +85,7 @@ async def _lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
             "  logs_*           — read or clear the editor log buffer\n"
             "  test_*           — run GDScript test suites and fetch results\n"
             "  batch_execute    — compose multi-step scene edits atomically\n"
+            "  ui_*             — Control layout helpers (anchor presets for HUD / menus)\n"
             "  client_*         — configure AI clients (Claude Code, Codex, Antigravity)\n\n"
             "Always connect to an editor session first (session_list / session_activate). "
             "Write operations require session readiness; check editor_state if a call is "
@@ -106,6 +108,7 @@ async def _lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     register_input_map_tools(mcp)
     register_testing_tools(mcp)
     register_batch_tools(mcp)
+    register_ui_tools(mcp)
     register_session_resources(mcp)
     register_scene_resources(mcp)
     register_editor_resources(mcp)

src/godot_ai/tools/ui.py

@@ -0,0 +1,54 @@
+"""MCP tools for UI (Control) authoring — HUD, pause menu, upgrade screens, etc."""
+
+from __future__ import annotations
+
+from fastmcp import Context, FastMCP
+
+from godot_ai.handlers import ui as ui_handlers
+from godot_ai.runtime.direct import DirectRuntime
+from godot_ai.tools import DEFER_META
+
+
+def register_ui_tools(mcp: FastMCP) -> None:
+    @mcp.tool(meta=DEFER_META)
+    async def ui_set_anchor_preset(
+        ctx: Context,
+        path: str,
+        preset: str,
+        resize_mode: str = "minsize",
+        margin: int = 0,
+        session_id: str = "",
+    ) -> dict:
+        """Apply a Control layout preset (anchors and offsets) to a UI node.
+
+        Wraps Godot's Control.set_anchors_and_offsets_preset — the fast way to
+        pin a HUD element, panel, pause menu, upgrade draft screen, or game-over
+        overlay to an edge, corner, or the full viewport. Much simpler than
+        setting anchor_left / anchor_top / anchor_right / anchor_bottom and the
+        four offset_* properties one at a time.
+
+        The target node must be a Control (or subclass — Panel, Label, Button,
+        Container, VBoxContainer, HBoxContainer, MarginContainer, etc.). Change
+        is undoable.
+
+        Args:
+            path: Scene path to a Control node (e.g. "/Main/HUD/HealthBar").
+            preset: Layout preset name. One of:
+                top_left, top_right, bottom_left, bottom_right,
+                center_left, center_top, center_right, center_bottom, center,
+                left_wide, top_wide, right_wide, bottom_wide,
+                vcenter_wide, hcenter_wide, full_rect.
+            resize_mode: How the existing size is handled when applying the
+                preset. One of: minsize (default — resize to minimum),
+                keep_width, keep_height, keep_size.
+            margin: Margin in pixels from the anchor edges. Default 0.
+            session_id: Optional Godot session to target. Empty = active session.
+        """
+        runtime = DirectRuntime.from_context(ctx, session_id=session_id or None)
+        return await ui_handlers.ui_set_anchor_preset(
+            runtime,
+            path=path,
+            preset=preset,
+            resize_mode=resize_mode,
+            margin=margin,
+        )