godot-mobile-ui-doctor 0.1.3

Check Godot mobile UI metadata for touch targets, safe areas, and text overflow risk.

Godot Mobile UI Doctor

godot-mobile-ui-doctor checks exported Godot UI metadata for common mobile layout risks: small touch targets, cramped controls, safe-area overlap, off-screen nodes, duplicate ids, and text that is likely to overflow its rectangle.

The first version reads JSON metadata, so it can run in CI without opening the Godot editor. Projects can generate the metadata from their own debug tools, test harnesses, editor scripts, or screenshot pipelines.

Install

python -m pip install godot-mobile-ui-doctor

From a source checkout:

python -m pip install -e .\godot-mobile-ui-doctor

Quick Start

godot-mobile-ui-doctor examples\tiny-mobile-ui-project\mobile-ui.json --format markdown

Fail CI when warnings are present:

godot-mobile-ui-doctor mobile-ui.json --fail-on warning --format json --output reports\mobile-ui.json

Build a screen-by-screen readiness matrix:

godot-mobile-ui-doctor matrix mobile-ui.json --format markdown --output reports\mobile-ui-matrix.md

Render PNG overlays for quick visual review:

godot-mobile-ui-doctor overlays mobile-ui.json --output-dir reports\mobile-ui-overlays --fail-on none

Reuse viewport definitions from a visual smoke capture plan:

godot-visual-smoke plan visual-smoke.toml --project . --format json --output reports\visual-plan.json
godot-mobile-ui-doctor matrix mobile-ui.json --visual-smoke-plan reports\visual-plan.json --format markdown
godot-mobile-ui-doctor overlays mobile-ui.json --visual-smoke-plan reports\visual-plan.json --output-dir reports\mobile-ui-overlays

Metadata Shape

{
  "thresholds": {
    "min_touch_size": 44,
    "min_touch_spacing": 8
  },
  "viewports": [
    {
      "name": "portrait_phone",
      "width": 720,
      "height": 1280,
      "safe_area": {"left": 0, "top": 48, "right": 0, "bottom": 24}
    }
  ],
  "screens": [
    {
      "name": "main_menu",
      "viewport": "portrait_phone",
      "nodes": [
        {
          "id": "play",
          "kind": "button",
          "x": 24,
          "y": 96,
          "width": 44,
          "height": 44,
          "text": "Play",
          "interactive": true
        }
      ]
    }
  ]
}

Coordinates are expected to be viewport pixels after layout. The tool does not need scene files or a Godot binary for this first metadata-based check.

If the UI metadata omits viewports, pass --visual-smoke-plan with JSON from godot-visual-smoke plan --format json. Viewports in mobile-ui.json override matching visual-smoke viewport names, so project-specific layout exports can still take precedence.

Checks

• missing_viewport: a screen references a viewport that was not exported.
• duplicate_node_id: a screen repeats a node id.
• node_outside_viewport: a node rectangle leaves the viewport bounds.
• safe_area_overlap: an important node overlaps a safe-area inset.
• touch_target_too_small: an interactive node is smaller than the configured target size.
• touch_targets_too_close: interactive rectangles are too close together.
• text_overflow_risk: text is unlikely to fit in the exported rectangle.
• no_interactive_controls: a screen has no interactive controls in the metadata.

Outputs

• text: readable terminal report.
• json: CI and scripts.
• markdown: PR comments, release notes, and report artifacts.
• png: optional overlay previews from the overlays command.

Mobile Readiness Matrix

The matrix command groups findings by screen and viewport. It is useful when a project has several phone and tablet captures and you want a quick table showing which screens are clean, which need review, and which need action.

The matrix includes safe-area, touch-target, spacing, text-fit, and viewport bounds status for each screen.

Overlay Previews

The overlays command writes one PNG per screen and viewport. It draws the safe-area rectangle, exported control bounds, interactive touch targets, and any rule ids attached to a control. The output is useful for PR artifacts because a reviewer can see the risky rectangles without opening the Godot project.

godot-mobile-ui-doctor overlays mobile-ui.json --output-dir reports\mobile-ui-overlays --scale 0.5 --fail-on none

How To Export Metadata

The tool deliberately keeps the input format simple. A project-specific exporter can walk visible Control nodes after layout and write each node's id, class, global rectangle, visible text, font size, and whether it is interactive.

Good ids are stable names such as cargo_buy_button or settings_back, not generated scene-instance paths. Stable ids make reports easier to compare across runs.