Umg Widgets

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "umg-and-slate"} for UE domain knowledge on this topic — correct APIs, architecture, best practices — and treat it as the rubric for any review / "best practices" question. If no such tool is available (e.g. running under Claude Code or Codex without that MCP), skip this line entirely and proceed with this skill alone — do NOT attempt the call.

UMG Widget Blueprints Skill

This skill covers authoring Widget Blueprints (WBP) with WidgetService. Read the Critical Rules below first — they prevent the most common failures. Then pick a task from the Task Index and load the matching workflow doc and/or run the matching sample script.

Load the blueprints skill when you also need to add Blueprint variables, functions, or components, and blueprint-graphs when wiring event-graph nodes for bound events.

Critical Rules

🚨 Creating Widget Blueprints — only one pattern works

WidgetService does not create the asset. Create it with the factory, then use WidgetService to populate it:

pythonCopy code
import unreal
factory = unreal.WidgetBlueprintFactory()
factory.set_editor_property("parent_class", unreal.UserWidget)
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
asset_tools.create_asset("MainMenu", "/Game/UI", unreal.WidgetBlueprint, factory)

Do not call BlueprintEditorLibrary.get_blueprint_class(), unreal.create_widget_blueprint(), or WidgetService.create_widget() — none exist. (Runnable: scripts/create_widget.txt.)

🚨 Hierarchy: set the root first, parents before children

pythonCopy code
unreal.WidgetService.add_component(path, "CanvasPanel", "RootCanvas", "", True)   # empty parent -> becomes root
unreal.WidgetService.add_component(path, "Button", "PlayButton", "RootCanvas", False)

That 5th argument is is_variable, not set_as_root — a widget becomes the root because its parent name is empty, not because of that flag. A 6th argument, child_index, inserts at a position instead of appending; reorder_component moves an existing widget within its parent. See reference.md ▸ Child order.

⚠️ Widget names are unique per-blueprint, NOT per-parent. UMG enforces one name across the whole Widget Blueprint, so you can't add an ItemLabel/ItemButton under each of Item1, Item2, Item3. Suffix per-parent (Item1Label, Item2Label, …) — reusing a name silently lands the component on the wrong parent or no-ops.

🚨 Property values are ALWAYS strings

pythonCopy code
unreal.WidgetService.set_property(path, "PlayText", "Font.Size", "24")  # "24", not 24

🚨 Color properties: FSlateColor vs FLinearColor — verify with a readback

ColorAndOpacity on text/image widgets is FSlateColor, whose export text is "(SpecifiedColor=(R=1.0,G=0.5,B=0.0,A=1.0))" — a bare LinearColor string is auto-wrapped into that form by set_property. ShadowColorAndOpacity is a plain FLinearColor: "(R=0.0,G=0.0,B=0.0,A=1.0)". Named color strings ("red", "orange") are NOT supported on either — pass numeric RGBA.

Always get_property after set_property and compare. A struct set can return True while writing nothing (UE struct import ignores unrecognized member names). If the readback still shows the old value, your value string didn't match the struct's member layout — check list_properties for the property's real type and use its export-text form.

🚨 Use dedicated style APIs for full font/brush edits

Use set_font / set_brush (with WidgetFontInfo / WidgetBrushInfo) when changing a complete font or brush — they keep related fields together. Use set_property only for single leaf values or slot aliases like Position X, Size Y, Anchor Min X. See reference.md for every field name; runnable examples in scripts/apply_font.txt and scripts/apply_brush.txt.

set_brush requires a slot_name: set_brush(widget_path, component_name, slot_name, brush_info) (for an Image the slot is "Brush"). set_font takes an optional property_name that defaults to "Font".

⚠️ set_property("Font.Typeface", ...) silently returns False (size and color leaf-sets work, but typeface/family do not go through the struct sub-property path). Always change typeface/family via set_font with a WidgetFontInfo. Don't trust the True/False return of set_property on nested struct sub-fields — read it back to confirm.

✅ set_font colour is now applied (ColorAndOpacity is an FSlateColor; the old path silently no-op'd a bare (R=,G=,B=,A=) tuple). Pass a LINEAR tuple, e.g. (R=0.035,G=0.002,B=0.002,A=1); set_font returns False and logs a Warning if a supplied colour did not land, so trust the return.

⚠️ get_font readback quirk (issue #470): the struct-typed string fields color, shadow_color, and shadow_offset come back as two concatenated representations glued together, e.g. shadow_offset == "(X=0.0,Y=0.0)(X=1.000000,Y=1.000000)". The trailing parenthesized group is the real value. Scalar fields (size, typeface, font_family, letter_spacing, outline_size) are clean. When verifying a font round-trip, parse the last (...) group of these three fields (or compare scalars only) until #470 is fixed.

🚨 Override-gated properties (SizeBox width/height etc.)

set_editor_property("width_override", 34.0) on a USizeBox stores the value but leaves the paired bOverride_WidthOverride edit-condition flag false — the override silently never applies (the value even reads back as 34.0). Call the dedicated setters (set_width_override(), set_height_override(), set_min_desired_width(), ...) which set flag + value together. Applies to any widget property gated by a bOverride_* flag; after a raw property set, read the flag back before trusting the layout.

🚨 Animations require real property paths

add_animation_track / add_keyframe target actual widget properties or slot aliases (RenderOpacity, ColorAndOpacity, Position X/Y, Size X/Y). Always create the animation first, then the track, then keyframes. (Runnable: scripts/create_animation.txt.)

🚨 Preview vs PIE — different purposes

• capture_preview renders an editor-side PNG without starting gameplay — use for appearance checks. It now renders with a single gamma pass (an sRGB PNG matching the designer, no more double-gamma) and a layout prepass (Overlay-centred content is centred, not bottom-aligned).
• start_pie + spawn_widget_in_pie are for runtime state / live property reads — use only when you need a live instance.

🚨 Custom WBPs as components — discover first, pass the asset name

Use list_widget_blueprints("") to find existing WBPs, then pass just the asset name (e.g. "WBP_HealthBar", not the full package path) as component_type. The child WBP must already exist; circular references are rejected; the parent recompiles automatically.

🚨 Field-name gotchas (return objects)

WidgetInfo complete fields: widget_name, widget_class, parent_widget, is_root_widget, is_variable, children.

children is an Array[str] of widget NAMES, not nested objects. Iterating it and reading .widget_name/.is_variable raises AttributeError: 'str' object has no attribute .... To walk the tree, build a name→info map first:

pythonCopy code
infos = {w.widget_name: w for w in unreal.WidgetService.get_hierarchy(path)}
for child_name in infos["RootCanvas"].children:
    child = infos[child_name]          # look the child up by name
    print(child.widget_name, child.widget_class, child.is_variable)

get_widget_snapshot(path) returns full data (hierarchy + slot + all properties) for a valid path — if it comes back empty, the path is wrong; do not conclude the widget is empty.

Full field tables for every return type are in reference.md.

🚨 Auditing widgets (best-practices review) — use these exact APIs

For "do our widgets follow best practices?" style audits:

• Property bindings (the #1 anti-pattern): in a snapshot's properties, any *Delegate entry (e.g. VisibilityDelegate, TextDelegate) with current_value of (null).None is unbound — a function name there means a polling property binding exists.
• Tick/graph checks go through BlueprintService (a WBP is a Blueprint): list_graphs(path) → get_nodes_in_graph(path, "EventGraph") → find Event Tick → get_node_pins(path, graph, node_id) and check each pin's connected flag. A Tick node with no connected pins is just the default stub, not live logic.
• These methods do NOT exist — do not guess them: BlueprintService.get_graphs, get_functions, get_connected_nodes, unreal.find_class. Use list_graphs, list_functions, get_nodes_in_graph, get_node_details (includes pin connections), and unreal.load_class(None, path) instead.

Slot editing via set_property

set_property edits slot layout through these aliases (string values):

• Canvas children: Position X/Y, Size X/Y, Anchor Min X/Y, Anchor Max X/Y, Alignment X/Y (pivot — set to 0.5 with anchors at 0.5 to truly center), ZOrder (or Z Order).
• Box/Overlay children (VerticalBox/HorizontalBox/Overlay): Horizontal Alignment / Vertical Alignment (values Fill/Left/Center/Right/Top/Bottom), Padding (one value or (Left=..,Top=..,Right=..,Bottom=..)), Padding Left/Top/Right/Bottom, and on box slots Size Rule (Fill/Automatic) + Size Value.

pythonCopy code
unreal.WidgetService.set_property(path, "PlayButton", "ZOrder", "5")
unreal.WidgetService.set_property(path, "HeaderRow", "Vertical Alignment", "Top")
unreal.WidgetService.set_property(path, "HeaderRow", "Padding", "8")

Shadowed names prefer the WIDGET (fixed in issue #553). A name that exists on both a widget and its slot (e.g. HorizontalAlignment on a Border sitting in an Overlay) now writes the widget's own property; a log warning notes the ambiguity. To target the slot explicitly, prefix with Slot. — e.g. set_property(path, "BackgroundBorder", "Slot.HorizontalAlignment", "Center") (value aliases like Fill/Center still work behind the prefix). Names that exist only as slot aliases (the lists above) keep resolving to the slot with no prefix needed.

Reparenting — reparent_widget

Move an existing widget to a new parent panel (preserves the widget object/GUID):

pythonCopy code
unreal.WidgetService.reparent_widget(path, "BackgroundImage", "MainContainer")

Rejects moving a panel into itself/a descendant; the root cannot be reparented.

Panel types

Task Index

Pick the task, load its workflow section, and/or run its sample script via execute_python_code. Sample scripts under scripts/ are runnable examples — edit the variables at the top, then execute.

Sub-docs

Load these only when the task needs them — read the sibling file directly under Plugins/VibeUE/Content/Skills/umg-widgets/ (the engine AgentSkillToolset GetSkills is the loader that exposes this skill; there is no vibeue-skills-manager tool):

• workflows.md — step-by-step task workflows with copy-paste Python for every task above.
• reference.md — field-name tables for every return type (FWidgetInfo, FWidgetComponentSnapshot, FWidgetSlotInfo, FWidgetFontInfo, FWidgetBrushInfo, FWidgetAnimInfo, FWidgetPreviewResult, FPIEWidgetHandle), the WidgetService action list, common properties, and event names.
• mvvm.md — MVVM ViewModel support: rules, creation types, binding modes, field names, and full add/bind/list/remove workflows.

Verification (do this before claiming success)

1. After hierarchy edits: re-read with get_widget_snapshot(path) and confirm the expected widgets/parents.
2. After property/style edits: read the value back (get_property / get_font / get_brush).
3. Open/compile the WBP and confirm no errors, then unreal.EditorAssetLibrary.save_asset(path).

Never report a widget as created/configured until it appears in a fresh get_widget_snapshot result.

Additional gotchas

• capture_preview renders correct gamma/colour now, but still confirm slot values with get_component_snapshot and layout in PIE. UMG colours are LINEAR — a dark sRGB red is about (0.035, 0.002, 0.002).
• Slot values written through ObjectIterator are discarded on the next compile; set them with set_property(path, widget, "Slot.<Prop>", value) or in C++ NativeConstruct.
• A fresh WBP has no root: the first add_component(path, type, name, parent_name="") becomes it. BindWidget binds only when the tree widget is is_variable=True; reading a bound member from Python is blocked, so enumerate ObjectIterator(unreal.TextBlock) filtered by the instance path.
• bind_event is only provably bound on the GameInstance_*-outered PIE instance (asset/preview instances always read unbound); simulate a click with on_clicked.broadcast() on that instance. Hand-built bound-event nodes compile but never fire — use create_component_bound_event.
• A widget can be fully authored yet never compiled; compile a legacy widget and read the error first. UE 5.8 renamed WidgetBlueprintLibrary to unreal.WidgetLibrary, and UserWidget instances do not expose get_widget_from_name.
• Input modes: a UI-only mode drops the first WASD press after it closes, so use SetInputMode_GameAndUIEx in Construct; the input mode survives ServerTravel; DefaultInput.ini holds a full serialised InputSettings block mid-file, so a key appended at the section top is silently overridden.