UI Mapping

Free This tool is free but requires the Godot addon.

What is UI Mapping?

Static analysis can tell you what Control nodes exist in your .tscn files. But it can’t tell you what text a Label is actually showing, whether a button is currently visible, or what the progress bar value is. Those are runtime states.

godotiq_ui_map reads the live UI tree from the running game via the bridge connection. It captures every Control node’s current properties: text content, visibility, position, size, theme overrides, and signal connections. This gives your AI a complete picture of the UI as it appears to the player.

godotiq_ui_map

Map all UI elements on screen: positions, text, interactivity, visibility. Call BEFORE godotiq_input to know what’s on screen.

When to Use It

Understanding the UI structure of a running game
Finding a specific UI element to modify (e.g., “find the health bar label”)
Debugging UI issues like elements hidden, wrong text, or unexpected layout
Getting the current state of dynamic UI (inventory slots, dialogue text, scores)

Parameters

Parameter	Type	Default	Description
`root`	`string`	`"/root"`	Root node to start mapping from
`filter_type`	`string`	`null`	Filter to specific Control types (e.g., `"Button"`, `"Label"`)
`include_hidden`	`bool`	`true`	Include invisible controls
`detail`	`string`	`"normal"`	Output verbosity

Example

Prompt: “Show me the current UI layout of the HUD.”

{
  "tool": "godotiq_ui_map",
  "args": {
    "root": "/root/Main/UI/HUD",
    "detail": "normal"
  }
}

{
  "root": "/root/Main/UI/HUD",
  "control_count": 14,
  "tree": {
    "name": "HUD",
    "type": "CanvasLayer",
    "children": [
      {
        "name": "TopBar",
        "type": "HBoxContainer",
        "rect": { "position": [0, 0], "size": [1920, 60] },
        "children": [
          {
            "name": "HealthBar",
            "type": "ProgressBar",
            "rect": { "position": [20, 10], "size": [200, 40] },
            "value": 75,
            "max_value": 100,
            "visible": true
          },
          {
            "name": "HealthLabel",
            "type": "Label",
            "text": "75 / 100",
            "visible": true,
            "theme_overrides": { "font_color": "#ff4444" }
          },
          {
            "name": "ScoreLabel",
            "type": "Label",
            "text": "Score: 1,250",
            "visible": true
          }
        ]
      },
      {
        "name": "BottomBar",
        "type": "HBoxContainer",
        "rect": { "position": [0, 1020], "size": [1920, 60] },
        "children": [
          {
            "name": "InteractPrompt",
            "type": "Label",
            "text": "Press E to open",
            "visible": false
          },
          {
            "name": "MiniMap",
            "type": "SubViewportContainer",
            "rect": { "position": [1720, 0], "size": [180, 180] },
            "visible": true
          }
        ]
      }
    ]
  },
  "signals": [
    {
      "node": "HealthBar",
      "signal": "value_changed",
      "connected_to": "HUD._on_health_changed"
    }
  ]
}

Tips

Use filter_type: "Button" to find only interactive elements, or "Label" to find only text elements
Set include_hidden: false to see only what the player currently sees
The detail: "full" mode includes theme overrides, custom fonts, anchor/margin values, and all Control-specific properties
Combine with godotiq_node_ops to modify UI elements: first find the node with godotiq_ui_map, then change its properties with godotiq_node_ops

Common Workflow

Map the UI with godotiq_ui_map to understand the current structure
Identify the target. Find the specific Label, Button, or Container you need.
Modify with godotiq_node_ops. Set properties on the running UI for immediate feedback.
Update the scene file. Once you’re happy with the changes, edit the .tscn to make them permanent.

Bridge tools: godotiq_node_ops to modify UI nodes, godotiq_screenshot to capture the visual result
Code analysis: godotiq_signal_map to trace UI signal connections in the codebase
Installation: Setup guide including addon installation

Tools Overview See all 22 GodotIQ tools.