Godot editor ui

Godot Editor UI

Build embedded editor interfaces against the editor's own theme and scale. Treat an EditorPlugin as editor chrome, not as a game window: project stretch settings and runtime Window.content_scale_factor are not its layout authority.

Start with the embedding boundary

1. Confirm whether the UI is an editor main screen, dock, bottom panel, inspector plugin, popup, or a runtime scene.
2. For an embedded editor UI, inherit the parent Editor Theme. Do not attach the project's game Theme at the root unless the design explicitly requires isolation.
3. Read both values from the editor:

var editor_scale := EditorInterface.get_editor_scale()
var editor_theme := EditorInterface.get_editor_theme()

4. Remember that changing the editor display scale requires an editor restart. Reload or re-enable the plugin after changing its scene; an existing instance can show a stale layout.

Read references/scaling-and-layout.md when diagnosing mixed scaling, custom geometry, or responsive-container failures.

Author the scene first

• Keep the complete static Control tree in .tscn; attach a thin @tool script for references, signals, data, and the scale adapter.
• If the project generates scenes, edit the builder and regenerate. Do not hand-edit generated .tscn output and leave the recipe stale.
• Let ordinary Label, Button, OptionButton, LineEdit, CheckButton, dialogs, and scrollbars inherit editor fonts, padding, icons, and minimum sizes.
• Use semantic colors or editor icons for hierarchy before introducing literal sizes.
• Put variable-height content inside ScrollContainer; let the page body fill the available width.

Remove the mixed-scale causes

For ordinary body text and controls, remove:

• theme_override_font_sizes/font_size;
• fixed custom_minimum_size.y;
• copied game-theme font resources;
• whole-tree scale transforms;
• embedded-window content_scale_factor workarounds.

An explicit font_size = 12 remains 12 even when the editor UI is 1.5x or 2x. A neighboring Button that inherits the Editor Theme grows, producing the characteristic "large buttons, tiny plugin copy" failure.

Do not use Theme.default_base_scale as a universal fix. It does not automatically scale explicit font overrides, MarginContainer constants, custom_minimum_size, or StyleBoxFlat border and corner metrics.

Keep branded typography narrow

Use explicit scaling only for the few labels that must be relatively larger than the editor body font, such as one product title or page heading. Prefer LabelSettings authored in the scene over node-level font-size overrides.

Choose exactly one sizing basis:

• Logical size: roundi(base_logical_size * editor_scale).
• Editor body ratio: roundi(editor_theme.get_font_size("font_size", "Label") * ratio).

The editor theme value is already scaled. Never multiply the second form by editor_scale again.

Make repeated configuration idempotent: retain the authored base or ratio and always recompute from it. Never multiply the label's current size, which compounds after plugin reloads or theme changes.

Scale only custom geometry

First delete custom metrics that the Editor Theme can own. For the remaining branded panel padding, container gaps, progress thickness, or other deliberate geometry:

1. Store an unscaled authored value in the scene or resource.
2. Multiply it exactly once by EditorInterface.get_editor_scale().
3. Recompute from the authored value on every application.
4. Apply the same rule to all four margins and both axes where relevant.

Keep this adapter scoped. It may update authored numeric properties or duplicated resources, but it must not build the UI tree or invent styling at runtime.

Design for dock-constrained width

An editor main screen rarely owns the whole window. Test with Scene/Inspector/FileSystem docks open and with a narrow main area.

• Prefer a deterministic VBoxContainer header over a two-column summary when the right column contains wrapping text.
• Do not combine a horizontally expanding first Grid column with an autowrapped second Label. The first column can consume the surplus while the Label reports a tiny minimum width, producing one character per line and a screen-height header.
• Do not preserve a fixed centered body width after increasing fonts. Fill the available width and use margins for breathing room.
• For step rails or action grids, choose column count from the children's real get_combined_minimum_size() values plus separation. Do not guess from monitor resolution.
• Prefer wrapping or fewer columns over clipping and horizontal scrolling.

Verification contract

Do all three levels; each catches a different class of failure.

1. Static/source checks
   • No ordinary body label has a literal font-size override.
   • The plugin passes the actual editor scale.
   • Scale-sensitive custom metrics retain an authored base.
2. Focused scene tests
   • Instantiate the scene.
   • Apply 1.0x, 1.5x, and 2.0x.
   • Assert title size, margins, separation, and retained minimum heights.
   • Apply 2.0x then 1.5x and assert values resolve from base rather than accumulating.
   • Exercise narrow and wide step-rail layouts.
3. Headful editor proof
   • Reload the plugin in the real editor.
   • Capture with docks open at the user's actual Display Scale.
   • Inspect typography, clipping, one-character wrapping, scroll reachability, and button hit areas.
   • Also inspect a wider/distraction-free editor state when that is a supported use.

Do not call a UI fix complete from headless tests alone. Headless scenes do not inherit the actual Editor Theme and therefore cannot prove the user's display-scale result.

Report evidence precisely

Distinguish these claims:

• Source changed: the intended inheritance/scale contract is implemented.
• Focused tests passed: numeric and structural invariants hold.
• Editor observed: the plugin was reloaded and inspected in the real editor.
• User confirmed: the user's own display and dock layout look correct.

Never substitute one level for another.