godot-ui

Godot UI

レイアウトルール、再利用可能なビジュアルリソース、明確なインタラクション状態に基づいてインターフェースを構築します。座標を大量に並べてレスポンシブレイアウトを解決したり、ポインター入力だけを唯一の操作手段にしたりしないでください。

編集前の確認

シーン、スクリプト、テーマ、プロジェクト設定を変更する前に、次の確認を完了してください。

1. project.godot の場所を特定し、プロジェクトのルートを確認します。config/features、ディスプレイの基本サイズ、ストレッチモードとアスペクト比、GUI テーマ設定、ローカライズ設定、Input Map アクションを読み取ります。
2. 利用可能な場合は、プロジェクトで指定されている Godot 実行ファイルを --version 付きで実行します。その正確な Godot 4.x リリースの API とインスペクターのプロパティ名を使用します。
3. 代表的な UI シーンとスクリプトを調べます。ルートの型、CanvasLayer の使用状況、アンカーとコンテナのパターン、サイズフラグ、一意なノード名、シグナル接続のスタイル、型指定された GDScript の規約、シーンの構成、命名規則を記録します。
4. 既存の .tres テーマ、フォント、フォントのフォールバック、アイコン、ローカライズファイル、UI スケールの設定、および定義済みのすべてのインタラクション状態を確認します。
5. 現在の UI を、想定されるデザインサイズ、サポートされる最小サイズ、実用上の最大サイズ、特殊なアスペクト比で実行します。翻訳がある場合は、少なくとも 1 つの長いロケールでテストします。
6. マウスを使わずに操作します。初期フォーカス、Tab の移動順序、方向キーでの移動先、決定／キャンセルの動作、フォーカスの視認性、フォーカスがトラップされたり失われたりするコントロールを記録します。

既存のすべてのインターフェースへの影響を確認せずに、1 つのシーンを修正するためにプロジェクト全体のストレッチ、テーマ、入力設定を上書きしないでください。

基本的なレイアウトルール

• ビューポートまたは UI 領域に追従する Control ルートを使用します。
• アンカーを使って、親に対する主要な領域の位置を決めます。
• これらの領域内で動的な子要素を配置するには、コンテナを使用します。
• 直接の子要素の位置とサイズは Container に管理させます。オフセットで競合させるのではなく、サイズフラグ、ストレッチ比率、最小サイズ、テーマの間隔、ラッパーコントロールを使用します。
• 余白には MarginContainer、スタイル付きのコンテンツ面には PanelContainer、行や列にはボックスコンテナ、列数が決まっている場合は GridContainer を使用します。
• 有効なコンテンツが利用可能な領域を超える場合は、ScrollContainer を使用します。技術的に収まるまでテキストやコントロールを縮小しないでください。
• タッチターゲット、読みやすいコントロール、アートの境界、レイアウト制約など、意図がある場合に限り、固定オフセットと最小サイズを設定します。
• ワールドカメラから独立させる必要がある画面空間のゲーム UI は、CanvasLayer の下に配置します。

ワークフロー

1. サポートするウィンドウサイズ、アスペクト比、UI スケールの範囲、入力デバイス、ロケール、アクセシビリティオプションを定義します。
2. ノードの型を選ぶ前に、意味上の領域と読み取り順序をスケッチします。
3. プレースホルダーのコンテンツを使い、アンカーとコンテナで構造ツリーを構築します。スタイルを適用する前に、サイズ変更に対応させます。
4. ラベル、入力欄、ボタン、リスト、画像、動的コンテンツを追加します。意味のある名前と、繰り返し使うコンポーネント向けの再利用可能なサブシーンを使用します。
5. 共有 Theme を適切な最上位のルートに適用します。プライマリ、破壊的、コンパクト、見出しなどの役割には型バリエーションを使用し、ノードごとの上書きは本当に例外的な場合に限ります。
6. pressed、value_changed、item_selected、text_submitted など、意味に即したシグナルを接続します。標準コントロールでは実現できないカスタム操作に限り、_gui_input を使用します。
7. すべての画面とモーダルについて、フォーカスの開始位置、順序、方向キーでの移動、アクティブ化、キャンセル時の動作、フォーカスの復元を定義します。
8. アクセシビリティを追加します。常に表示されるラベル、視認できるフォーカス、十分なコントラスト、色に依存しない手がかり、拡大可能なテキスト、モーションの抑制、必要に応じて再割り当て可能な操作、読みやすいステータス／エラー表示を取り入れます。
9. レイアウト、テーマの状態、入力経路、ローカライズ、実行時の更新をまとめて検証します。

型付きレスポンシブの例

この例では、デバイスの種類を推測せず、実際に利用可能な幅に応じてフォームのグリッドを2列から1列に変更します。

extends Control

@export_range(320.0, 1600.0, 8.0) var compact_width: float = 720.0
@onready var settings_grid: GridContainer = %SettingsGrid

func _ready() -> void:
    resized.connect(_refresh_layout)
    _refresh_layout()

func _refresh_layout() -> void:
    settings_grid.columns = 1 if size.x < compact_width else 2

コンテナーを通じて自然に再配置されるレイアウトを優先してください。幅が制限されたときに情報構造が本当に変わる場合に限り、ブレークポイント用のスクリプトを追加してください。

入力とフォーカスの契約

• インタラクティブなコントロールにのみフォーカスを設定してください。カスタムコントロールで適切な focus_mode が使用されていることを確認してください。
• 画面が表示された後に初期フォーカスを設定してください。ダイアログやサブ画面を閉じた後は、開いた元のコントロールにフォーカスを戻してください。
• プロジェクトで意図的に再割り当てしている場合を除き、組み込みの ui_* アクションのセマンティクスを維持してください。ゲームプレイのアクションとUIナビゲーションは分離してください。
• キーボードやコントローラーを使うユーザーがすべてのアクションにアクセスでき、すべての複合コントロールから抜けられるようにしてください。
• フォーカスインジケーターは、ホバー状態や押下状態と視覚的に区別できるようにしてください。
• 可能な限り、テキスト編集、選択、クリップボード、IME、支援技術向けのセマンティクスは標準コントロールに任せてください。
• 装飾用オーバーレイには適切な mouse_filter を設定し、下にあるコントロールを妨げないようにしてください。
• キャンセルや戻る操作は、各子要素で個別に処理するのではなく、所有する画面またはナビゲーションレイヤーで処理してください。

検証

• 対応するエディターでインポートして解析してください。サポートされている場合は、<godot> --headless --path <project> --editor --quit を実行し、すべての出力を確認してください。
• 対応範囲内で連続的にサイズを変更してください。プロジェクトに該当する場合は、横向き、縦向き、ウルトラワイド、狭幅、高DPIの各シナリオをテストしてください。
• クリッピング、重なり、サイズがゼロのコントロール、意図しないスクロールバー、過剰な空白、テクスチャの歪み、パネルからはみ出すコンテンツがないか確認してください。
• ラベルを長文、複数行のテキスト、空のテキスト、大きな数値、サポートされている場合は右から左へ記述するテキスト、実行時に生成されるコンテンツに置き換えてください。
• UIやコンテンツのスケールを大きくし、レイアウトが切り取られずに再配置されることを確認してください。
• 適用可能なすべてのコントロール状態をテストしてください。通常、ホバー、押下、フォーカス、無効、選択済み、無効な入力、読み込み中、空の状態です。
• TabとShift+Tabのみ、方向アクションのみ、決定とキャンセルのみ、対応するコントローラーのみを使って、新しい画面から操作してください。
• コントロールが重なっている場合やゲームプレイ画面上にある場合に、マウス、タッチ、キーボードのイベント伝播をテストしてください。
• フォーカスがモーダルに入ること、必要な場合はその内部に留まること、開いた元のコントロールに戻ること、シーン変更後も見える状態に保たれることを確認してください。
• 対象となるエンジンやプラットフォームの正確なサポート状況に応じて、コントラスト、フォーカス表示、色に依存しない状態インジケーター、モーション低減への対応、テキストによる代替、エラー通知を確認してください。
• 孤立したコンポーネントだけでなく、統合されたシーンを実行し、テストしていないデバイス、ロケール、支援技術の動作があれば報告してください。

注意点

• コンテナーの直接の子要素にオフセットを設定して、コンテナーにリセットされる理由が分からなくなること。
• 動的コンテンツの管理をコンテナーに任せず、リストやフォームのすべての項目にアンカーを使うこと。
• Control を収めるために scale を使うこと。表示がぼやけたり、入力領域の形状とレイアウトの意図がずれたりする可能性があります。
• 解像度、ラベルの長さ、フォントのメトリクス、入力デバイスをそれぞれ1種類だけに固定すること。
• 実際のデザインシステムが見えなくなるほど多くのテーマオーバーライドを適用すること。
• focus スタイルを省略したり、フォーカスをホバーと視覚的に同じにしたりすること。
• 非表示の画面が表示される前にフォーカスを取得したり、初期フォーカスをまったく設定しなかったりすること。
• _input で標準のボタン操作を処理して、二重に操作されたり、GUIイベントルーティングを迂回したりすること。
• MOUSE_FILTER_STOP が設定された装飾用の Control に、その下にあるボタンを妨げさせること。
• キャレット、選択範囲、貼り付け、IMEの動作を維持せず、キー入力のたびに LineEdit.text を書き換えること。
• ツールチップや色だけを、コントロールやエラーを説明する唯一の手段として扱うこと。
• すべての Godot 4.x リリースで同じネイティブのアクセシビリティAPIが公開されていると思い込むこと。正確なバージョンを調べ、対象となる各プラットフォームで検証してください。

参考資料

• レスポンシブレイアウト
• テーマと視覚状態
• 入力、フォーカス、アクセシビリティ