godot-ui-containers

判定ツリー：コンテナの種類 → スクリプト

必要なもの	推奨	必須スクリプト
ブレークポイント対応のシェル／全画面に適応するルート	Margin + Box コンテナ	responsive_layout_builder.gd
幅に応じて変化する固定列	GridContainer	responsive_grid.gd / responsive_inventory_grid.gd
折り返し表示するチップ／タグ	HFlowContainer	responsive_tag_cloud.gd
数千行のスクロール	仮想プール（子ノードを直接並べない）	virtual_list.gd
ログ／チャットの自動スクロール	ScrollContainer	terminal_autoscroll.gd
UI 内の 3D キャラクター／アイテムのプレビュー	SubViewportContainer	viewport_3d_preview.gd
深いネストでレイアウトの負荷が急増する場合	代わりにアンカー／オフセットを使用	performance_anchor_layout.gd
放射状／ホイールメニュー	カスタム Container	custom_radial_container.gd

シナリオ別：読み込まないもの

シナリオ	読み込む	読み込まない
インベントリ／ショップのグリッド	responsive_grid.gd / responsive_inventory_grid.gd	custom_radial_container.gd、viewport_3d_preview.gd
タグクラウド／チップの折り返し	responsive_tag_cloud.gd	グリッド列用スクリプト、virtual_list.gd
数千行のログ／チャット	virtual_list.gd + terminal_autoscroll.gd	インベントリ／放射状メニュー／ビューポート用スクリプト
3D アイテム／キャラクターのプレビュー	viewport_3d_preview.gd	放射状メニュー用スクリプト + インベントリグリッド用スクリプト
放射状／ホイールメニュー	custom_radial_container.gd	仮想リスト + タグクラウド
深いネスト／レイアウトの負荷急増	performance_anchor_layout.gd	レスポンシブビルダーの全カタログ

利用可能なスクリプト

virtual_list.gd

仮想リストのプーリング — 少数の Control プールとスペーサーの高さを再利用し、ScrollContainer の行を O(1) で処理します。

responsive_layout_builder.gd

ブレークポイントに基づくレスポンシブレイアウトを構築する、エキスパート向けコンテナビルダーです。

responsive_grid.gd

利用可能な幅に応じて列数を変更する、自動調整式の GridContainer です。

responsive_inventory_grid.gd

利用可能な幅とアイテムの最小サイズに基づいて、グリッドの列数を動的に決めるエキスパート向けロジックです。

terminal_autoscroll.gd

安全な ScrollContainer 管理を行います。ログやチャットを追加する際によく発生する「1 フレーム遅延」バグに対処します。

viewport_3d_preview.gd

高性能な 3D UI 表示のセットアップです。キャラクターのプレビューに stretch_shrink と transparent_bg を使用します。

dynamic_tab_manager.gd

タブの動的生成、カスタムタイトル、タブを閉じるロジックのパターンです。

responsive_tag_cloud.gd

HFlowContainer を使ってアイテム一覧を折り返します。タグクラウドやレスポンシブメニューに不可欠です。

performance_anchor_layout.gd

最適化のアーキテクチャです。深いコンテナのネストを、軽量なアンカーとオフセットのロジックに置き換えます。

custom_radial_container.gd

NOTIFICATION_SORT_CHILDREN を使って放射状／円形のレイアウトを実装する、エキスパート向けのカスタムコンテナロジックです。

animated_container_shuffle.gd

インタラクティブな UI リストで、動的に兄弟ノードの順序を変更し、アニメーションさせるロジックです。

aspect_ratio_mini_map.gd

AspectRatioContainer を使い、ウィンドウサイズの流動的な変更に対して厳密なアスペクト比（例：1:1、16:9）を維持します。

container_size_flags_pro.gd

重み付けレイアウトに SIZE_EXPAND_FILL と stretch_ratio を使う、高度なサイズ調整ロジックです。

UI コンテナで絶対にしてはいけないこと

• mouse_filter プロパティを絶対に無視しないでください。オーバーレイコンテナでは、背後にあるボタンへのクリックを妨げないよう、必ず PASS または IGNORE を設定してください。
• ScrollContainer に何千ものノードを絶対にインスタンス化しないでください。必ず 仮想リストのプーリングを使用してください。O(1) の描画パフォーマンスを実現するには、virtual_list.gd（VScrollBar フック＋単一のスペーサー子ノード）を必ず読んでください。
• レスポンシブグリッドのカード寸法を手動で計算しないでください。親コンテナによるスケーリングを可能にしながら比率（例：2:3）を固定するには、必ず AspectRatioContainer を使用してください。
• Container 内で子ノードの position や size を手動で設定しないでください — queue_sort() 中に Container が子ノードのトランスフォームを上書きします。代わりに custom_minimum_size または size_flags を使用してください [1]。
• 拡張用の size_flags を絶対に設定し忘れないでください — デフォルトは SIZE_SHRINK_BEGIN です。レスポンシブコンテナでは SIZE_EXPAND_FILL を設定しない限り、子ノードは小さいままになります。
• columns を設定せずに GridContainer を絶対に使用しないでください — デフォルトは 1 で、単純な縦並びになります。レスポンシブな折り返しには、代わりに HFlowContainer を使用してください [8]。
• コンテナを深くネストしすぎないでください（10 レベル以上） — 深いネストはレイアウト再計算の急増を引き起こします。静的なパディングには、中間コンテナをアンカーレイアウトに置き換えてください [16]。
• 間隔のオーバーライドを絶対に省略しないでください — デフォルトのテーマの間隔は狭すぎることがよくあります。プロフェッショナルな余白を確保するには、add_theme_constant_override("separation", value) を使用してください。
• 最小サイズを指定せずに ScrollContainer を絶対に使用しないでください — 指定しないと、コンテナがゼロまで縮小したり無限に拡大したりして、スクロール機能が壊れる可能性があります。
• 新しい子ノードを追加したフレームと同じフレームで、絶対にその子ノードまでスクロールしないでください — まだレイアウトが更新されていません。scroll_vertical を設定する前に、必ず await get_tree().process_frame を実行してください [5]。
• サイズを変更するために SubViewportContainer を絶対にスケールしないでください — 描画内容が歪みます。代わりにマージンを調整するか、stretch と stretch_shrink プロパティを使用してください [2]。
• レイヤー化された Viewport で、mouse_filter を絶対にデフォルトのままにしないでください — 入力イベントが子ノードに届かない場合があります。イベントが子ノードまで伝わるよう、MOUSE_FILTER_PASS または STOP を使用してください [6]。
• レスポンシブな折り返しに GridContainer を絶対に使用しないでください — 幅に応じてアイテムを折り返すには、HFlowContainer を使用してください。GridContainer では列数が厳密に固定されます [7]。
• コンテナ内で position を直接アニメーションしないでください — 遷移中に兄弟ノードを滑らかに「押し出す」には、Tween を使って custom_minimum_size をアニメーションしてください [1]。

---

エキスパート向けレイアウトパターン

1. 分割画面コンテナ（動的）

HSplitContainer を使った、ローカルマルチプレイヤーや比較向けの標準パターンです。

# split_screen.gd
func setup_split(v1: SubViewport, v2: SubViewport):
    var hsplit = HSplitContainer.new()
    var c1 = SubViewportContainer.new()
    c1.stretch = true # Resize viewport to match container
    c1.add_child(v1)
    hsplit.add_child(c1)
    # repeat for c2/v2...

2. 仮想リストの ScrollContainer（プーリング）

何千ものアイテムに対応する高パフォーマンスなリストです。実装には、必ず virtual_list.gd（setup_pool＋set_data）を使用してください。一度きりのスクロールリサイクラーをインラインに貼り付けないでください。

3. アスペクト比固定カード

どのグリッドやフローコンテナでも比率（例：2:3）を維持するレスポンシブカードです。

# card_grid.gd
func add_card(texture: Texture2D):
    var arc = AspectRatioContainer.new()
    arc.ratio = 0.66 # 2:3 proportions
    arc.stretch_mode = AspectRatioContainer.STRETCH_FIT
    
    var tr = TextureRect.new()
    tr.texture = texture
    tr.expand_mode = TextureRect.EXPAND_IGNORE_SIZE
    tr.stretch_mode = TextureRect.STRETCH_KEEP_ASPECT_CENTERED
    
    arc.add_child(tr)
    grid_container.add_child(arc)

サイズフラグのレシピ：必須の container_size_flags_pro.gd を参照してください。初心者向けの SIZE_EXPAND_FILL チュートリアルをインラインに貼り付けないでください。

詳細レシピ（必要に応じて）

LLM の知識不足に関するルール：一般的なエージェントが読まないと知らないような内容は、ここか scripts/ に置いてください。削除せず、移動してください。

トピック	参照
アンカー、フラグ、間隔	container-layout-recipes.md

参考資料

段階的開示：特定の API を調査するときに限り公式ドキュメントのリンクを開いてください。関連スキルは、関連する領域へ振り分けるときに読み込んでください。全体をあらかじめ読み込まないでください。

公式ドキュメント

• コンテナの使用 — ボックス／グリッド／フロー／分割コンテナ、サイズフラグ、およびコンテナが子の変換を上書きするタイミングに関する標準ガイドです。
• サイズとアンカー — 深いコンテナのネストを意図的に避ける場合に、レスポンシブな Control の配置に使うアンカープリセットとオフセットを説明しています。
• Control ノードギャラリー — Control／Container の種類を視覚的にまとめたカタログです。エージェントが HFlow、Grid、Split を適切に選ぶのに役立ちます。
• カスタム GUI コントロール — カスタムの放射状レイアウトやレイアウトに必要な NOTIFICATION_SORT_CHILDREN と fit_child_in_rect のパターンを説明しています。
• GUI ナビゲーション — コンテナで構築されたメニュー内で、フォーカス先の指定やキーボード／ゲームパッドでの移動を行う方法を説明しています。
• 複数の解像度 — コンテナ駆動のレスポンシブ UI に影響するストレッチモードとコンテンツスケールを説明しています。
• Control — あらゆるレイアウトスクリプトで使用する size_flags_*、custom_minimum_size、mouse_filter、アンカー API を説明しています。
• Container — 手動での子の位置やサイズの設定を禁止する、基本のソートライフサイクル（queue_sort／SORT_CHILDREN）を説明しています。
• ScrollContainer — ログ／チャット UI におけるスクロールバー、最小サイズに関する注意点、フレーム後の scroll_vertical 更新を説明しています。
• HFlowContainer — タグクラウドやチップリストで、幅に応じて折り返す方法を説明しています（列数固定の GridContainer よりこちらを推奨します）。
• AspectRatioContainer — サイズが変動する親の下で、カードやミニマップの縦横比を固定します。
• SubViewportContainer — スケーリングによる歪みを避けながら、UI 内の 3D プレビューに stretch／stretch_shrink を使用します。

関連スキル

前提条件

• godot-project-foundations — レスポンシブメニューでコンテナを接続する前提となる、シーンツリーの所有権、Control のルート、プロジェクトレイアウトの規約を説明しています。
• godot-gdscript-mastery — 実行時にグリッドやタブを構築する際に使う、型付き Control API、@onready、安全な子ノードの再構築ループを説明しています。
• godot-signal-architecture — リサイズ、タブ変更、インベントリ更新のシグナルは、レイアウトスクリプトがゲーム状態を所有しないよう、シグナルを上方向へ伝播し、呼び出しを下方向へ行うべきです。

補完

• godot-ui-theming — テーマ定数（separation、マージン）とタイプバリエーションを使うと、レイアウトコードに色をハードコードせずにコンテナの枠をスタイリングできます。
• godot-ui-rich-text — RichTextLabel の最小サイズと BBCode コンテンツが ScrollContainer の高さを決めます。レイアウトの枠組みができた後に組み合わせてください。
• godot-tweening — コンテナ内の position をトゥイーンする代わりに、custom_minimum_size や並べ替え時のフィードバックをアニメーションさせます。
• godot-input-handling — コンテナで構築した操作可能なリストやタブに、フォーカス、mouse_filter、アクションマップを設定します。
• godot-adapt-desktop-to-mobile — ブレークポイントに応じた列数とセーフエリアのマージンは、レスポンシブな Grid/HFlow ビルダーと組み合わせて使えます。
• godot-inventory-system — インベントリグリッドではレスポンシブな列数ロジックを使います。コンテナがスロットを表示し、アイテムの状態はインベントリが管理します。
• godot-performance-optimization — ScrollContainer で数千もの Control が生成される場合は、仮想リストのプーリングと浅いアンカーレイアウトを使用します。

下流／利用先

• godot-dialogue-system — 会話の選択肢リストと履歴パネルは、オートスクロールと間隔のパターンを再利用する Scroll/VBox レイアウトです。
• godot-genre-card-game — 手札の弧状配置、ドラッグレイヤー、デッキ UI は、カードの Resources を囲む AspectRatio/HFlow コンテナを組み立てます。
• godot-composition-apps — ツールやアプリの UI では、ゲームプレイ HUD 以外でも同じ Container のサイズフラグと分割パターンを再利用します。

マスター

• godot-master — エージェントがライブラリのインデックスから開始する場合に、UI Containers 用のルーターおよび対応するモジュールエントリーとして機能します。