Unity UI

Unity UI Skills

When to Use

Use this module for Unity UGUI / Canvas workflows. It is separate from UI Toolkit.

Routing:

• Check ../../mcp-tools.md first for a dedicated official Unity MCP tool.
• If no native tool covers the operation, use ../../recipes/ui/<command>.md.
• For UXML/USS/UIDocument → use uitoolkit.
• For XR-compatible world-space Canvas conversion → use xr_setup_ui_canvas.
• For text updates after creation → use ui_set_text.
• For layout and alignment → use ui_layout_children, ui_align_selected, ui_distribute_selected.

Creating 2+ elements: call the individual ui_create_<primitive> recipes in a single Unity_RunCommand — one CommandScript.Execute block can instantiate any number of UI elements by chaining the per-primitive setup inline.

Common Mistakes

DO NOT (common hallucinations):

• ui_add_canvas does not exist -> use ui_create_canvas
• ui_create_label does not exist -> use ui_create_text
• ui_create_checkbox does not exist -> use ui_create_toggle
• ui_set_color does not exist -> use component_set_property on Image/Text, or the dedicated UI property skills when available
• Do not confuse UGUI (ui) with UI Toolkit (uitoolkit)

Quick Reference

Create Skills

Query and Layout Skills

Property and Effect Skills

High-Frequency Defaults

Canvas and Parenting

• ui_create_canvas defaults to ScreenSpaceOverlay.
• Most create skills accept parent; if omitted, Unity will create under the active Canvas or scene root depending on the implementation context.
• For reusable menu groups, create the Canvas once, then create a Panel and put all child controls under that panel.

Common Create Parameters

Important:

• Most create skills do not take explicit x/y placement.
• Create first, then place/anchor with ui_set_rect, ui_set_anchor, or ui_layout_children.

Layout and Anchoring Rules

• ui_set_anchor is the fastest way to move a control into a standard layout position.
• ui_set_rect is better for precise size/offset edits after anchoring.
• ui_layout_children is preferred over hand-positioning every child when building vertical, horizontal, or grid menus.

Anchor presets commonly used in production:

• MiddleCenter for modal/menu panels
• TopLeft or TopRight for HUD corners
• StretchAll for full-screen backgrounds

TextMeshPro Note

Text creation auto-detects TMP:

• TMP available -> TextMeshProUGUI
• TMP unavailable -> legacy Text

Read the response payload if you need to know which one was created before later component-specific edits.

Workflow Notes

1. Create a Canvas first.
2. Use panels to group related controls.
3. Prefer ui_create_batch for menus, HUD groups, and repeated widgets.
4. Use anchors and layout groups before hand-placing every child.
5. Text creation auto-detects TextMeshPro. Responses indicate whether TMP was used.
6. For world-space gameplay UI, build the Canvas here first, then convert for XR only if needed.
7. ui_create_batch is mainly for bulk creation, not precise positioning. Follow it with layout or rect/anchor adjustments.
8. ui_create_batch.items is a JSON string parameter, not a raw array object.

Typical Menu Workflow

ui_create_canvas  name="MainMenu" renderMode="ScreenSpaceOverlay"
ui_create_panel   name="MenuPanel" parent="MainMenu" a=0.65
ui_set_rect       name="MenuPanel" width=300 height=200
ui_create_batch   items=[
  {type:"Button", name:"StartBtn",   parent:"MenuPanel", text:"Start",   width:220, height:44},
  {type:"Button", name:"OptionsBtn", parent:"MenuPanel", text:"Options", width:220, height:44},
  {type:"Button", name:"QuitBtn",    parent:"MenuPanel", text:"Quit",    width:220, height:44}
]
ui_layout_children name="MenuPanel" layoutType="Vertical" spacing=12

RunCommand Examples

Recipe path rule: ../../recipes/ui/<command>.md

See ../../recipes/ui/<command>.md for C# templates.

UI Authoring Loop

Standard 3-phase loop for running an editor authoring menu, capturing a screenshot, and verifying the result. Use whenever a [MenuItem] script modifies scene objects and requires visual confirmation.

Phase 1 — Wait for compile

internal class CommandScript : IRunCommand
{
    public void Execute(ExecutionResult result)
    {
        result.Log("compiling=" + UnityEditor.EditorApplication.isCompiling);
    }
}

Poll until compiling=False. If True, wait 2–3 seconds and re-run.

Phase 2 — Run the authoring menu

internal class CommandScript : IRunCommand
{
    public void Execute(ExecutionResult result)
    {
        bool ok = UnityEditor.EditorApplication.ExecuteMenuItem("Tools/Authoring/YourMenuName");
        result.Log("menu ok=" + ok);
    }
}

Expected: menu ok=True plus any [Log] lines from the menu itself. If ok=False the menu path is wrong or the [MenuItem] attribute string does not match.

Phase 3 — Screenshot and verify

Prerequisite: Tools/UI/Screenshot/ menu items must exist in the project. If they do not, install the screenshot Editor script first — see tooling/ui/ui_screenshot_tool.md. Create the script via Unity_CreateScript, wait for Unity to recompile, then continue.

internal class CommandScript : IRunCommand
{
    public void Execute(ExecutionResult result)
    {
        bool ok = UnityEditor.EditorApplication.ExecuteMenuItem("Tools/UI/Screenshot/ScreenName");
        result.Log("screenshot ok=" + ok);
    }
}

After this call, use the Read tool on the output PNG to confirm the visual result.

Pitfalls

• ExecuteMenuItem returns false silently if the path is wrong. Always log and check the return value.
• isCompiling may stay true for several seconds after saving a file. Do not skip the poll.
• Screenshot tools may modify CanvasScaler render mode temporarily. They should restore it — if they don't, the scene will be left dirty with wrong scaler settings.

Quality gate — always compare against a spec file

When verifying screenshots, open the relevant design spec file (e.g. a .jsx or .css reference) and compare values directly. Do NOT derive the checklist from the screenshot — that produces a circular pass. Example:

Spec says xpBar.height: 54. Current screenshot bar height looks ~20px. → FAIL.

Self-derived checklists ("button is not white") only catch regressions, not spec divergence.

Mobile UI Sizing Principles

Web spec px values do not map directly to Unity canvas pixels. Use these baselines instead of copying px numbers from a web design file.

Touch targets

HUD bars (mobile portrait baseline)

Width as percentage of canvas width; height as design-unit minimums. These values assume a portrait mobile canvas — scale proportionally for landscape or tablet.

Text inside a bar (e.g. "LVL 3") needs at minimum the bar's own height to be legible — a 24 px bar cannot hold 22 px text with padding.

Minimum bar height when text is inside: 44 px. If a design spec shows a smaller value, the spec is wrong for mobile — do not copy it.

Typography

Pitfalls

• Web spec values are starting points, not answers. When the canvas reference width matches the spec's pixel width, the numbers are 1:1 — but web specs optimize for visual appearance, not touch targets or game-condition readability. Always check the value against the table above: if it's below the table minimum, use the minimum. If it's in range, verify it still meets the text-inside-bar rule (44 px floor) if text will be inside.
• Never use enableAutoSizing as a crutch for wrong sizes. Auto-sizing down to the minimum means the size is wrong, not that auto-sizing fixed it.
• Set enableAutoSizing = true BEFORE fontSizeMin / fontSizeMax. TMP silently ignores the size range if auto-sizing is enabled after the size fields are written.
• Safe area. On iOS (notch / Dynamic Island) and Android (punch-hole), the top ~44 px and bottom ~34 px are unsafe. Use Screen.safeArea to inset any HUD elements that anchor to the screen edges.
• Project code is not the authority for sizing. It may already contain under-sized values. Use the sizing tables above to verify existing implementation, especially the text-inside-bar floor (44 px).