ue5-ui-umg-slate

クイックスタート

• 機能が UMG、Slate、またはハイブリッドブリッジのどれに属するかを特定します。
• データソースとなるコンポーネント／サブシステムと、UI のバインディングポイントを定義します。
• ウィジェットツリーの意図と、実行時のバインディング順序を示します。

API アンカー（UE5.6-UE5.8）

• UMG のライフサイクルとビューポートのアンカー：
  • UUserWidget::NativeConstruct()、UUserWidget::NativeDestruct()
  • UUserWidget::AddToViewport(...)
  • UWidget::RemoveFromParent()
  • UWidget::SetVisibility(...)
  • UWidget::SetKeyboardFocus()
• UMG の入力モードのアンカー：
  • UWidgetBlueprintLibrary::SetInputMode_UIOnlyEx(...)
  • UWidgetBlueprintLibrary::SetInputMode_GameAndUIEx(...)
  • UWidgetBlueprintLibrary::SetInputMode_GameOnly(...)
• UMG／Slate ブリッジのアンカー：
  • Slate ブリッジへの受け渡しには UWidget::TakeWidget() を使用します
  • SCompoundWidget、SLATE_BEGIN_ARGS(...)
  • FSlateApplication::SetKeyboardFocus(...)、SetUserFocus(...)
• ビューポートのジオメトリのアンカー：
  • UGameViewportClient::GetViewportSize(...)

UI ステージの契約

• すべての UI タスクで、以下を定義する必要があります。
  • UI レイヤーの所有者（UMG のみ、Slate のみ、またはハイブリッドブリッジ）
  • データソースと更新のトリガー（プル、プッシュ、イベント、または混合）
  • フォーカスと入力の所有権の切り替え
  • ツールチップ／ポップアップのビューポート内に収まる配置動作
  • バインド解除とウィジェット削除のための破棄／クリーンアップ手順
• いずれかの項目が欠けている場合、UI の実装は未完成です。

ワークフロー

1）UI アーキテクチャの決定

• 標準的なゲーム HUD／メニューには UMG を選択します。
• UMG では適切に表現できないカスタム描画／入力動作には Slate を選択します。
• UWidget ホストにカスタム Slate コンテンツを埋め込む必要がある場合は、ハイブリッドを選択します。

2）構築とライフタイム

• 構築／初期化の処理でウィジェットのバインディングを初期化します。
• イベントリスナーは一度だけ登録し、必要に応じてハンドルを保存します。
• 古いバインディングが残らないよう、破棄／登録解除の処理を明示的に定義します。

3）データバインディングと更新

• 1 つの信頼できるデータソース（サブシステム／コンポーネント／ビューモデル）から実行時データをバインドします。
• 可能な場合は、高頻度データの更新にイベント駆動方式を使用します。
• ゲームプレイ状態の変更は、表示用ウィジェットから行わないようにします。

4）入力とフォーカスの所有権

• UI コンテキストを開く／閉じる際は、入力モードを意図的に設定します。
• キーボード／ユーザーフォーカスを対象のルートウィジェットに設定します。
• UI を閉じた際にゲームプレイへフォーカスを戻す経路を確保します。

5）ツールチップ／ポップアップのビューポート内への配置

• アンカーとカーソル／ウィジェットのジオメトリから、ツールチップの配置位置を計算します。
• 画面外への描画を防ぐため、最終的な配置をビューポートの範囲内に収めます。
• ちらつきを防ぐため、高頻度のホバー更新を間引きます。

6）削除とクリーンアップ

• 閉じる際は、ウィジェットを親またはビューポートから削除します。
• タイマー／デリゲートと一時的な参照をクリアします。
• 再度開いたときに重複インスタンスが残らないことを確認します。

制約

• UI の描画とゲームプレイ状態の変更を分離します。
• 表示専用ウィジェットからゲームプレイ状態を直接書き換えないようにします。
• ツールチップとポップアップの配置をビューポート内に収めます。
• 入力の所有権とフォーカスの切り替えには、決定的な方式を優先します。
• Slate のみのコードは、明確なブリッジ境界の内側に隔離します。
• イベント駆動の更新が利用できる場合は、フレームごとのポーリングに依存しないでください。

障害への対処

• 症状：ウィジェットは表示されますが、更新されません。
  • 確認箇所：構築のタイミング、バインディングの登録、ソースイベントの発火。
  • 対処：ソースの準備完了後にバインドし、イベントのサブスクリプション経路を確認します。
• 症状：ウィジェットは一度更新されますが、その後停止します。
  • 確認箇所：デリゲートハンドルの喪失、または再バインドなしでのウィジェットの再作成。
  • 対処：構築時に再バインドし、破棄時にバインドを解除します。また、重複した作成・破棄の繰り返しを防ぎます。
• 症状：入力が予期せず UI によって処理されません。
  • 確認箇所：現在の入力モードと、フォーカスされたウィジェットの経路。
  • 対処：意図した入力モードを適用し、明示的なフォーカス先を設定します。
• 症状：ポップアップを開いた後、キーボードやコントローラーのナビゲーションが機能しなくなります。
  • 確認箇所：フォーカスの移動と復帰経路。
  • 対処：以前のフォーカス所有者を保存し、ポップアップを閉じたときに復元します。
• 症状：画面の端でツールチップがちらつきます。
  • 確認箇所：クランプ出力の振動とホバー元の揺れ。
  • 対処：ホバーの更新をデバウンスし、安定したビューポートの測定値でクランプします。
• 症状：開閉を繰り返すとメモリ使用量が増加します。
  • 確認箇所：古いデリゲート、タイマー、参照の保持。
  • 対処：終了処理でバインディングと一時的な参照をクリアします。

UE5.6-UE5.8 の互換性に関する注意事項

• 上記の UMG ライフサイクル、入力モード、Slate フォーカス API は、UE5.6-UE5.8 で安定しています。
• サポート対象のすべてのバージョンで、Enhanced Input と明示的な UI 入力モードの所有権を優先してください。

エスカレーション

• プロジェクトの範囲を超えるエンジンレベルの Slate カスタマイズが必要な場合は、エスカレーションしてください。
• UI アーキテクチャが既存の CommonUI フレームワークの方針と競合する場合は、エスカレーションしてください。