SF
STS Forge

UI Widgets

Widget Blueprint verbs: widget-list, widget-add, widget-remove, widget-set-property, widget-set-slot.

Part of the BlueprintAIAssistant AI Reference.

Verbs for inspecting and editing UMG Widget Blueprint widget trees. All operations target the designer-time widget hierarchy: the named widgets visible in the Widget Blueprint's Designer panel. List, add, remove, and configure widgets and their slot/layout properties without opening the editor.

widget-list#

List the widget tree of a Widget Blueprint.

Category: Read (focused)

Arg Required Description
-asset= Yes Widget Blueprint asset path

Examples:

-verb=widget-list -asset=/Game/UI/WBP_HUD

Notes:

  • Returns the full widget hierarchy with names, classes, and parent-child relationships.
  • Returns an empty tree for Widget Blueprints with no designer widgets (no error).

widget-add#

Add a widget to the widget tree.

Category: Write (widgets)

Arg Required Description
-asset= Yes Widget Blueprint asset path
-name= Yes Widget name
-class= Yes Widget class (see supported classes below)
-parent= No Parent panel widget name to nest under

Supported widget classes: TextBlock, Image, Button, VerticalBox, HorizontalBox, CanvasPanel, ProgressBar, Slider, Border, Overlay, SizeBox, Spacer

Examples:

-verb=widget-add -asset=/Game/UI/WBP_HUD -name=HealthBar -class=ProgressBar -parent=RootCanvas
-verb=widget-add -asset=/Game/UI/WBP_HUD -name=PlayerName -class=TextBlock -parent=InfoPanel
-verb=widget-add -asset=/Game/UI/WBP_HUD -name=IconImage -class=Image

Notes:

  • Idempotent: if a widget with the same name already exists, returns success without duplicating.
  • If -parent= is omitted, the widget is added to the root of the tree.
  • The parent must be a panel widget (e.g., CanvasPanel, VerticalBox, HorizontalBox, Overlay, SizeBox, Border).

widget-remove#

Remove a widget from the tree. Idempotent.

Category: Write (widgets)

Arg Required Description
-asset= Yes Widget Blueprint asset path
-name= Yes Widget name to remove

Examples:

-verb=widget-remove -asset=/Game/UI/WBP_HUD -name=OldLabel -compile -save

Notes:

  • Idempotent: if the widget does not exist, returns success.
  • Child widgets nested under the removed widget are also removed.

widget-set-property#

Set a property on a widget via UE reflection.

Category: Write (widgets)

Arg Required Description
-asset= Yes Widget Blueprint asset path
-widget= Yes Widget name
-property= Yes Property name (e.g., Text, ColorAndOpacity, Visibility, bIsEnabled)
-value= Yes Value as string (parsed via UE ImportText)

Examples:

-verb=widget-set-property -asset=/Game/UI/WBP_HUD -widget=TitleLabel -property=Text -value="Game Over"
-verb=widget-set-property -asset=/Game/UI/WBP_HUD -widget=HealthBar -property=Percent -value=0.75
-verb=widget-set-property -asset=/Game/UI/WBP_HUD -widget=HealthBar -property=FillColorAndOpacity -value="(R=0.0,G=1.0,B=0.0,A=1.0)"
-verb=widget-set-property -asset=/Game/UI/WBP_HUD -widget=DeathOverlay -property=Visibility -value=Collapsed
-verb=widget-set-property -asset=/Game/UI/WBP_HUD -widget=AmmoCount -property=bIsEnabled -value=true -compile -save

Notes:

  • Property names and value formats follow UE reflection conventions (FProperty::ImportText()).
  • Supports dot-notation for nested struct fields (e.g., ColorAndOpacity.R).

widget-set-slot#

Set slot/layout properties on a widget. The available properties depend on the parent panel type.

Category: Write (widgets)

Arg Required Description
-asset= Yes Widget Blueprint asset path
-widget= Yes Widget name

Additional arguments depend on the parent panel type (see below).

CanvasPanel slot properties#

Used when the widget's parent is a CanvasPanel.

Arg Required Description
-posX= No Position X
-posY= No Position Y
-sizeX= No Size X
-sizeY= No Size Y
-anchorMinX= No Anchor minimum X (0.0-1.0)
-anchorMinY= No Anchor minimum Y (0.0-1.0)
-anchorMaxX= No Anchor maximum X (0.0-1.0)
-anchorMaxY= No Anchor maximum Y (0.0-1.0)
-alignmentX= No Alignment X (0.0-1.0)
-alignmentY= No Alignment Y (0.0-1.0)
-autoSize No Flag (presence-only): enable auto-size

Examples:

-verb=widget-set-slot -asset=/Game/UI/WBP_HUD -widget=HealthBar -posX=20 -posY=20 -sizeX=300 -sizeY=30
-verb=widget-set-slot -asset=/Game/UI/WBP_HUD -widget=Crosshair -anchorMinX=0.5 -anchorMinY=0.5 -anchorMaxX=0.5 -anchorMaxY=0.5 -alignmentX=0.5 -alignmentY=0.5 -autoSize

VerticalBox / HorizontalBox slot properties#

Used when the widget's parent is a VerticalBox or HorizontalBox.

Arg Required Description
-hAlign= No Horizontal alignment: Left, Center, Right, Fill
-vAlign= No Vertical alignment: Top, Center, Bottom, Fill
-padding= No Padding value
-fillSize= No Fill size (0.0 = auto, >0 = fill proportion)

Examples:

-verb=widget-set-slot -asset=/Game/UI/WBP_HUD -widget=PlayerName -hAlign=Center -vAlign=Top -padding=10
-verb=widget-set-slot -asset=/Game/UI/WBP_HUD -widget=HealthBar -hAlign=Fill -fillSize=1.0 -compile -save

Batch example: creating a simple HUD with a health bar#

This example creates a CanvasPanel root with a VerticalBox containing a label and a ProgressBar health bar, all in a single batch call.

{
    "defaultAsset": "/Game/UI/WBP_PlayerHUD",
    "operations": [
        {
            "verb": "widget-add",
            "args": { "name": "RootCanvas", "class": "CanvasPanel" }
        },
        {
            "verb": "widget-add",
            "args": { "name": "HealthGroup", "class": "VerticalBox", "parent": "RootCanvas" }
        },
        {
            "verb": "widget-set-slot",
            "args": {
                "widget": "HealthGroup",
                "posX": "20", "posY": "20",
                "sizeX": "300", "sizeY": "60"
            }
        },
        {
            "verb": "widget-add",
            "args": { "name": "HealthLabel", "class": "TextBlock", "parent": "HealthGroup" }
        },
        {
            "verb": "widget-set-property",
            "args": { "widget": "HealthLabel", "property": "Text", "value": "HEALTH" }
        },
        {
            "verb": "widget-set-slot",
            "args": { "widget": "HealthLabel", "hAlign": "Left", "vAlign": "Center", "padding": "4" }
        },
        {
            "verb": "widget-add",
            "args": { "name": "HealthBar", "class": "ProgressBar", "parent": "HealthGroup" }
        },
        {
            "verb": "widget-set-property",
            "args": { "widget": "HealthBar", "property": "Percent", "value": "1.0" }
        },
        {
            "verb": "widget-set-property",
            "args": { "widget": "HealthBar", "property": "FillColorAndOpacity", "value": "(R=0.0,G=0.8,B=0.0,A=1.0)" }
        },
        {
            "verb": "widget-set-slot",
            "args": { "widget": "HealthBar", "hAlign": "Fill", "fillSize": "1.0" }
        },
        { "verb": "compile" },
        { "verb": "save" }
    ]
}

Using HTTP:

curl -X POST http://localhost:7850/baa/v1/batch \
  -H "Content-Type: application/json" \
  -d @hud-batch.json

Using commandlet:

"C:\Unreal\UE571Source\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" \
  "C:\Unreal\ProjectLeyline\CombatDemo\CombatDemo.uproject" \
  -run=BlueprintAIAssistant \
  -verb=batch \
  -input=hud-batch.json \
  -nullrhi -nosplash -nosound -unattended

Tips#

  • Use widget-list first. Before modifying a Widget Blueprint, list the existing tree to see current widget names and hierarchy.
  • Panel parents only. widget-add with -parent= requires the parent to be a panel widget (CanvasPanel, VerticalBox, HorizontalBox, Overlay, SizeBox, Border). Adding a child to a non-panel widget (e.g., TextBlock) will fail.
  • Slot type must match parent. widget-set-slot properties depend on the parent panel type. CanvasPanel slot args (posX, sizeX, anchors) do not apply to VerticalBox children, and vice versa.
  • Use batch for multi-widget layouts. Building a widget tree requires many operations. Batching avoids repeated commandlet launches (30-60s each).
  • Compile and save. Use -compile -save on the last write verb, or add explicit compile and save steps at the end of a batch.