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:

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

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

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:

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.