claude-code-arcane 2.2.0 → 2.4.0

package/skills/ue-ui-umg-slate/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: ue-ui-umg-slate
+description: "UMG, Slate, UserWidget, HUD, BindWidget, Common UI, MVVM"
+category: "gamedev"
+argument-hint: "[widget o UI flow]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# UE UI: UMG, Slate, and Common UI
+
+You are an expert in Unreal Engine's UI systems (UMG, Slate, and Common UI).
+
+Ask before writing: this skill edits widget classes and UMG assets. Propose the change and get approval before using Write or Edit.
+
+## Context Check
+
+Read `docs/unreal/project-context.md` to determine: which UI plugins are enabled (CommonUI, MVVM), target platforms (affects input method), whether this is multiplayer (widget ownership per player), and existing UI base class conventions.
+
+## Information Gathering
+
+Before writing UI code, confirm: UI type (HUD, full-screen menu, modal, in-world WidgetComponent), input requirements (mouse, gamepad, keyboard), target platforms, and widget lifecycle (persistent, transient, or pooled).
+
+---
+
+## 1. UUserWidget in C++
+
+```cpp
+// MyWidget.h
+UCLASS()
+class MYGAME_API UMyWidget : public UUserWidget
+{
+    GENERATED_BODY()
+protected:
+    virtual void NativeConstruct() override; // Bind delegates here — BindWidget refs valid
+    virtual void NativeDestruct() override;
+    virtual void NativeTick(const FGeometry& MyGeometry, float InDeltaTime) override;
+};
+
+// MyWidget.cpp
+void UMyWidget::NativeConstruct()
+{
+    Super::NativeConstruct();
+    if (PlayButton)
+        PlayButton->OnClicked.AddDynamic(this, &UMyWidget::HandlePlayClicked);
+}
+```
+
+### Lifecycle and GC
+
+```cpp
+// Creation — always pass the owning PlayerController for player-UI
+UMyWidget* Widget = CreateWidget<UMyWidget>(GetOwningPlayer(), MyWidgetClass);
+Widget->AddToViewport(0);          // ZOrder: higher = on top. Roots the widget (won't GC).
+Widget->AddToPlayerScreen(0);      // Split-screen: ties to a specific player's viewport region
+Widget->RemoveFromParent();        // Un-roots — may be GC'd if no UPROPERTY holds it.
+
+UPROPERTY() TObjectPtr<UMyWidget> CachedWidget; // Strong ref keeps alive after RemoveFromParent
+
+// Visibility
+Widget->SetVisibility(ESlateVisibility::Collapsed); // Not drawn, takes no space
+Widget->SetVisibility(ESlateVisibility::Hidden);    // Not drawn, takes space
+Widget->SetVisibility(ESlateVisibility::Visible);   // Drawn, receives input
+// HitTestInvisible: drawn, passes input through; SelfHitTestInvisible: children receive input
+```
+
+---
+
+## 2. BindWidget Pattern
+
+```cpp
+UCLASS()
+class MYGAME_API UMyWidget : public UUserWidget
+{
+    GENERATED_BODY()
+protected:
+    UPROPERTY(meta=(BindWidget))             // Required — compiler warning if absent in UMG BP
+    TObjectPtr<UButton> PlayButton;
+
+    UPROPERTY(meta=(BindWidgetOptional))     // Optional — always null-check before use
+    TObjectPtr<UTextBlock> SubtitleText;
+
+    UPROPERTY(meta=(BindWidgetAnim), Transient) // Transient is required for anim bindings
+    TObjectPtr<UWidgetAnimation> IntroAnim;
+
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UTextBlock> ScoreText;
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UImage> PlayerAvatar;
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UProgressBar> HealthBar;
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UListView> ItemList;
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UScrollBox> ContentScroll; // Scrollable container
+};
+```
+
+Name must match the UMG Blueprint widget name exactly (case-sensitive). Always null-check optional bindings.
+
+---
+
+## 3. Widget Interaction
+
+### UButton (Button.h)
+
+```cpp
+// Delegates: OnClicked, OnPressed, OnReleased, OnHovered, OnUnhovered
+PlayButton->OnClicked.AddDynamic(this, &UMyWidget::HandlePlayClicked);
+PlayButton->OnHovered.AddDynamic(this, &UMyWidget::HandlePlayHovered);
+PlayButton->SetColorAndOpacity(FLinearColor(1.f, 0.8f, 0.f, 1.f));
+PlayButton->SetIsEnabled(false);
+// UE5.2+: WidgetStyle, ColorAndOpacity, ClickMethod direct access deprecated — use setters
+```
+
+### UTextBlock (TextBlock.h)
+
+```cpp
+// SetText wipes any Blueprint binding on Text
+ScoreText->SetText(FText::Format(NSLOCTEXT("HUD", "ScoreFmt", "Score: {0}"), FText::AsNumber(Score)));
+ScoreText->SetColorAndOpacity(FSlateColor(FLinearColor::White));
+ScoreText->SetTextTransformPolicy(ETextTransformPolicy::ToUpper);
+ScoreText->SetTextOverflowPolicy(ETextOverflowPolicy::Ellipsis);
+```
+
+### UImage (Image.h)
+
+```cpp
+PlayerAvatar->SetBrushFromTexture(AvatarTexture, /*bMatchSize=*/false);
+PlayerAvatar->SetBrushFromMaterial(IconMaterial);
+UMaterialInstanceDynamic* MID = PlayerAvatar->GetDynamicMaterial();
+MID->SetScalarParameterValue(TEXT("Opacity"), 0.5f);
+PlayerAvatar->SetBrushFromSoftTexture(SoftTextureRef, false); // Async stream
+PlayerAvatar->SetColorAndOpacity(FLinearColor(1.f, 1.f, 1.f, 0.5f));
+```
+
+### UProgressBar (ProgressBar.h)
+
+```cpp
+HealthBar->SetPercent(CurrentHealth / MaxHealth); // 0.0–1.0
+HealthBar->SetFillColorAndOpacity(FLinearColor(0.f, 1.f, 0.f, 1.f));
+LoadingBar->SetIsMarquee(true); // Indeterminate animation
+```
+
+### UScrollBox (ScrollBox.h)
+
+`UScrollBox` is a BindWidget-compatible container for scrollable content. Supports vertical and horizontal scroll. Add child widgets in Blueprint; query or modify scroll offset in C++:
+
+```cpp
+ContentScroll->ScrollToEnd();
+ContentScroll->SetScrollOffset(0.f);
+ContentScroll->SetOrientation(Orient_Vertical); // default
+```
+
+### UListView + UTileView + IUserObjectListEntry (ListView.h, TileView.h, IUserObjectListEntry.h)
+
+`UListView` — virtualised vertical list. `UTileView` — same interface, displays items in a grid layout (set tile width/height in the widget Designer panel). Both use `IUserObjectListEntry`.
+
+```cpp
+// Entry widget must implement the interface
+UCLASS()
+class UItemEntryWidget : public UUserWidget, public IUserObjectListEntry
+{
+    GENERATED_BODY()
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UTextBlock> NameText;
+protected:
+    virtual void NativeOnListItemObjectSet(UObject* ListItemObject) override
+    {
+        IUserObjectListEntry::NativeOnListItemObjectSet(ListItemObject);
+        if (UItemData* Data = Cast<UItemData>(ListItemObject))
+            NameText->SetText(FText::FromString(Data->ItemName));
+    }
+};
+
+// Populate
+ItemList->ClearListItems();
+for (const FItemInfo& Info : Items)
+{
+    UItemData* Data = NewObject<UItemData>(this);
+    Data->ItemName = Info.Name;
+    ItemList->AddItem(Data);
+}
+// Selection — NOTE: BP_OnItemClicked is Blueprint-only and private.
+// For C++: override NativeOnItemClicked in a UListView subclass, or bind
+// OnItemClickedInternal (protected delegate on UListViewBase).
+UItemData* Selected = ItemList->GetSelectedItem<UItemData>();
+```
+
+---
+
+## 4. Input Mode Management
+
+```cpp
+// UI-only — full-screen menus. Game input blocked.
+FInputModeUIOnly UIMode;
+UIMode.SetWidgetToFocus(Widget->TakeWidget());
+GetOwningPlayer()->SetInputMode(UIMode);
+GetOwningPlayer()->SetShowMouseCursor(true);
+
+// Game-only — restore gameplay.
+GetOwningPlayer()->SetInputMode(FInputModeGameOnly());
+GetOwningPlayer()->SetShowMouseCursor(false);
+
+// Game and UI — HUD tooltips, keeps game input active.
+FInputModeGameAndUI GameUIMode;
+GameUIMode.SetLockMouseToViewportBehavior(EMouseLockMode::LockOnCapture);
+GetOwningPlayer()->SetInputMode(GameUIMode);
+GetOwningPlayer()->SetShowMouseCursor(true);
+```
+
+Set input mode from calling code (HUD/GameMode) after `AddToViewport`, not from `NativeConstruct`.
+
+---
+
+## 5. Common UI (Plugin)
+
+See `references/common-ui-setup.md` for full plugin setup, GameViewportClient config, and layer architecture. Enable `CommonUI` and `CommonInput` plugins. Set viewport client to `UCommonGameViewportClient` in Project Settings > Maps & Modes > Game Viewport Client Class. `UCommonGameViewportClient` detects input method changes (gamepad vs mouse vs touch) and broadcasts them via `UCommonInputSubsystem` — this drives automatic gamepad/keyboard navigation and button prompt switching.
+
+### UCommonActivatableWidget (CommonActivatableWidget.h)
+
+```cpp
+UCLASS()
+class MYGAME_API UMyMenuScreen : public UCommonActivatableWidget
+{
+    GENERATED_BODY()
+protected:
+    virtual void NativeOnActivated() override;
+    virtual void NativeOnDeactivated() override;
+    virtual UWidget* NativeGetDesiredFocusTarget() const override { return CloseButton; }
+    virtual TOptional<FUIInputConfig> GetDesiredInputConfig() const override
+    {
+        return FUIInputConfig(ECommonInputMode::Menu, EMouseCaptureMode::NoCapture);
+    }
+    UPROPERTY(meta=(BindWidget)) TObjectPtr<UCommonButtonBase> CloseButton;
+};
+
+void UMyMenuScreen::NativeOnActivated()
+{
+    Super::NativeOnActivated(); // Always call Super
+    CloseButton->OnClicked().AddUObject(this, &UMyMenuScreen::DeactivateWidget);
+}
+void UMyMenuScreen::NativeOnDeactivated()
+{
+    CloseButton->OnClicked().RemoveAll(this);
+    Super::NativeOnDeactivated(); // Always call Super
+}
+```
+
+### Widget Containers (CommonActivatableWidgetContainerBase.h)
+
+`UCommonActivatableWidgetContainerBase` is the base class for Common UI widget containers. Two concrete subclasses:
+
+- **`UCommonActivatableWidgetStack`** — shows only the topmost widget; deactivating reveals the previous one (stack behaviour). This is the correct stack class — do NOT use `UCommonActivatableWidgetSwitcher` here, which inherits from `UCommonAnimatedSwitcher`/`UWidgetSwitcher` and is a different widget entirely.
+- **`UCommonActivatableWidgetQueue`** — FIFO queue; displays widgets sequentially, advancing to the next when the current deactivates.
+
+```cpp
+UPROPERTY(meta=(BindWidget)) TObjectPtr<UCommonActivatableWidgetStack> MenuLayer;
+UPROPERTY(meta=(BindWidget)) TObjectPtr<UCommonActivatableWidgetQueue> NotificationQueue;
+
+// Push screen onto the stack — AddWidget creates the widget internally
+UMyMenuScreen* Screen = Cast<UMyMenuScreen>(MenuLayer->AddWidget(UMyMenuScreen::StaticClass()));
+Screen->ActivateWidget();
+
+// Go back — deactivate re-activates the previous widget in the stack
+Screen->DeactivateWidget();
+
+// Queue a notification — plays after the current one finishes
+NotificationQueue->AddWidget(UMyNotificationWidget::StaticClass());
+```
+
+### UCommonButtonBase
+
+Uses `FCommonButtonEvent` (declared via `DECLARE_EVENT`) — use `AddUObject`, not `AddDynamic`:
+```cpp
+MyButton->OnClicked().AddUObject(this, &UMyScreen::HandleClick);
+MyButton->OnClicked().RemoveAll(this); // In NativeOnDeactivated
+```
+
+### UCommonUIActionRouter
+
+Handles input routing between game and UI layers; Common UI drives it automatically via `GetDesiredInputConfig`. Access directly when you need to query the current input mode:
+
+```cpp
+#include "Input/CommonUIActionRouterBase.h"
+// Get() takes a const UWidget& — call from within a widget (or pass any valid UWidget in scope):
+UCommonUIActionRouterBase* Router = UCommonUIActionRouterBase::Get(*ContextWidget); // ContextWidget: const UWidget&
+if (Router) { /* query active input config */ }
+```
+
+### Gamepad / Keyboard Navigation
+
+Common UI provides automatic gamepad and keyboard navigation without extra setup. Key behaviours:
+
+- `UCommonButtonBase` highlights automatically when it receives focus via D-pad or Tab navigation.
+- `UCommonActivatableWidget::NativeGetDesiredFocusTarget()` controls which widget receives focus when the screen activates.
+- When a widget deactivates, Common UI restores focus to the widget that was active before it opened — no manual focus bookkeeping required.
+- Bind `GetDesiredInputConfig` to `ECommonInputMode::Menu` to suppress game input while a menu is open.
+
+---
+
+## 6. Slate Fundamentals
+
+Use Slate for editor extensions, custom renderers, or when UMG doesn't expose required functionality.
+
+`SWidget` is the abstract base of all Slate widgets. `SCompoundWidget` (shown below) is the typical subclass for custom widgets.
+
+```cpp
+// Custom widget — SMyWidget.h
+class SMyWidget : public SCompoundWidget
+{
+public:
+    SLATE_BEGIN_ARGS(SMyWidget)
+        : _LabelText(FText::GetEmpty()), _OnClicked() {}
+        SLATE_ATTRIBUTE(FText, LabelText)
+        SLATE_EVENT(FSimpleDelegate, OnClicked)
+    SLATE_END_ARGS()
+
+    void Construct(const FArguments& InArgs);
+private:
+    TAttribute<FText> LabelText;
+    FSimpleDelegate OnClicked;
+};
+
+// SMyWidget.cpp
+void SMyWidget::Construct(const FArguments& InArgs)
+{
+    LabelText = InArgs._LabelText;
+    OnClicked = InArgs._OnClicked;
+    ChildSlot
+    [
+        SNew(SButton)
+        .OnClicked_Lambda([this]() -> FReply { OnClicked.ExecuteIfBound(); return FReply::Handled(); })
+        [ SNew(STextBlock).Text(LabelText) ]
+    ];
+}
+
+// Instantiation
+TSharedRef<SMyWidget> W = SNew(SMyWidget).LabelText(NSLOCTEXT("UI", "Btn", "Go"));
+TSharedPtr<SButton> Btn;
+SAssignNew(Btn, SButton).OnClicked(FOnClicked::CreateUObject(this, &UMyClass::Handle));
+```
+
+**Common Slate widgets:** `STextBlock`, `SButton`, `SVerticalBox`, `SHorizontalBox`, `SOverlay`, `SBorder`, `SBox`, `SScrollBox`, `SImage`, `SEditableTextBox`.
+
+**Slate vs UMG:** Use Slate for editor tools and maximum control. Use UMG for game runtime UI, Blueprint extensibility, animations, and BindWidget.
+
+---
+
+## 7. MVVM (UE 5.1+, ModelViewViewModel plugin)
+
+```cpp
+// ViewModel — MyGameViewModel.h
+UCLASS()
+class MYGAME_API UMyGameViewModel : public UMVVMViewModelBase
+{
+    GENERATED_BODY()
+public:
+    // UE_MVVM_SET_PROPERTY_VALUE: checks equality, sets, broadcasts field change
+    void SetScore(int32 NewScore) { UE_MVVM_SET_PROPERTY_VALUE(Score, NewScore); }
+    void SetPlayerName(FText NewName) { UE_MVVM_SET_PROPERTY_VALUE(PlayerName, NewName); }
+    int32 GetScore() const { return Score; }
+    FText GetPlayerName() const { return PlayerName; }
+private:
+    UPROPERTY(BlueprintReadOnly, FieldNotify, Getter, meta=(AllowPrivateAccess))
+    int32 Score = 0;
+    UPROPERTY(BlueprintReadOnly, FieldNotify, Getter, meta=(AllowPrivateAccess))
+    FText PlayerName;
+};
+
+// From game code — UI updates automatically via field notifications:
+void AMyPlayerState::OnScoreChanged(int32 NewScore) { ViewModel->SetScore(NewScore); }
+```
+
+To bind a ViewModel at runtime: create with `NewObject<UMyGameViewModel>(this)`, then configure in the widget Blueprint's Bindings panel. The `UMVVMView` component on the widget handles one-way and two-way property bindings automatically once the ViewModel class is set.
+
+---
+
+## Common Mistakes
+
+| Anti-pattern | Correct approach |
+|---|---|
+| `SetVisibility(Hidden)` to "hide" a menu | `RemoveFromParent()` to stop rendering and input |
+| `CreateWidget(GetWorld(), ...)` for HUD widgets | `CreateWidget(GetOwningPlayer(), ...)` |
+| `SetInputMode(FInputModeUIOnly())` for a HUD | Use `FInputModeGameAndUI` or Common UI's `GetDesiredInputConfig` |
+| `AddDynamic` with `UCommonButtonBase::OnClicked()` | `AddUObject` — it's `FCommonButtonEvent` not DYNAMIC |
+| Binding delegates in `NativeTick` | Bind once in `NativeConstruct`, unbind in `NativeDestruct` |
+| Skipping `Super::NativeOnActivated/Deactivated` | Always call Super — it routes focus and input |
+| One widget for all players in split-screen | `AddToPlayerScreen` with per-player widgets |
+| No UPROPERTY reference after `RemoveFromParent` (widget leak) | Hold a `UPROPERTY() TObjectPtr<>` to prevent GC, or call `RemoveFromParent()` to allow GC when no longer needed |
+| Z-order conflicts | Multiple widgets at same Z-order causes undefined draw order | Use explicit Z-order in `AddToViewport(ZOrder)` — higher values draw on top. Reserve ranges: HUD 0-9, menus 10-19, popups 20+ |
+| Invisible widgets still tick | Hidden widgets with `NativeTick` consume CPU | Set `SetVisibility(ESlateVisibility::Collapsed)` (removes from layout) or call `RemoveFromParent()` for unused widgets. Override `NativeTick` with an early-out: `if (!IsVisible()) return;` |
+
+---
+
+## Build.cs
+
+```csharp
+PublicDependencyModuleNames.AddRange(new string[] { "UMG", "Slate", "SlateCore" });
+PrivateDependencyModuleNames.Add("CommonUI");      // If using CommonUI
+PrivateDependencyModuleNames.Add("CommonInput");   // If using CommonInput
+PrivateDependencyModuleNames.Add("ModelViewViewModel"); // If using MVVM
+```
+
+---
+
+## Related Skills
+
+- `/ue-cpp-foundations` — UPROPERTY meta specifiers, TObjectPtr, module setup
+- `/ue-input-system` — Enhanced Input, FInputModeXxx, input contexts
+- `/ue-editor-tools` — Slate for editor detail panels and custom tools
+- `/ue-naming-conventions` — asset prefixes and Content folder layout for these assets
+
+## Reference Files
+
+- `references/widget-types.md` — UMG widget type catalogue with the panel/layout decision guide
+
+---
+
+## Checklist
+
+Validate before considering the work done:
+
+- [ ] Widgets are data-bound or event-driven, not polling gameplay state every tick
+- [ ] Focus, navigation and gamepad input were verified, not just mouse
+- [ ] Widgets are pooled or properly removed rather than accumulating
+- [ ] Conventions in `docs/unreal/project-context.md` were read and followed
+- [ ] The Common Mistakes section of this skill was reviewed against the change
+
+**PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks correctness, replication or the frame budget; fix it before handing the work over.
+
+## Next Steps
+
+- `/accessibility` — check contrast, scaling and navigation
+- `/perf-profile` — check widget tick and paint cost
+- `/code-review` — architectural and quality review of the change
+- `/commit` — conventional commit once the change is verified