Godot入門：AspectRatioContainerの使い方と活用法

はじめに
AspectRatioContainerとは？
このノードを使うべき場面
主なプロパティと機能
もっと使いこなす：カスタマイズできるパラメータ
まとめ
シリーズ：Godot 4 ノード解説

はじめに

ゲームのミニマップやスキルアイコンを作ったとき、ウィンドウサイズを変えたら縦横比が崩れてつぶれてしまった——という経験はないでしょうか。AspectRatioContainer はその問題を解決するコンテナです。子ノードの縦横比を維持したまま、コンテナのサイズに合わせてリサイズしてくれます。

この記事では、AspectRatioContainer の仕組みと使いどころ、よく触るプロパティを紹介します。

AspectRatioContainerとは？

AspectRatioContainer は 指定した縦横比（アスペクト比）を保ちながら、子ノードのサイズを自動調整するUIコンテナです。親のサイズが変わっても、子が「つぶれる」「引き伸ばされる」ことなく、常に正しい比率を維持します。

テレビの「画面サイズ変更」ボタンをイメージしてください。16:9 のまま大きくする／小さくするとき、映像は縦横比を保ちながらスケールします。AspectRatioContainer はその動きを UI ノードで実現します。

継承ツリーは AspectRatioContainer → Container → Control → CanvasItem → Node です。子ノードは1つが基本で、複数まとめたいときは内側に別のコンテナを挟みます。

アスペクト比あり／なしの比較図 — 左：比率を保たないと縦横が歪む／右：AspectRatioContainer で常に正しい比率を維持

このノードを使うべき場面

ミニマップ：正方形や16:9などの比率を崩さずに画面の端に表示したいとき
スキル・アイテムアイコン：アイコン枠を正方形に固定しつつ、レイアウトに合わせてサイズを変えたいとき
ビデオ・画像プレビュー：16:9の動画プレビューを埋め込む領域が可変サイズのとき
カードUI：カードのサムネイルを常に決まった比率で表示したいとき
レスポンシブなゲームビューポート：画面解像度が変わっても常に指定比率でゲーム画面を表示したいとき

別のノードが適切な場面：

比率を維持する必要がなく、単に中央に置きたいだけ → CenterContainer の方がシンプル
テクスチャ画像の比率維持だけが目的 → TextureRect の expand_mode と stretch_mode で対応できる場合もある

主なプロパティと機能

AspectRatioContainer の代表的なプロパティをまとめました。

プロパティ	型	役割
`ratio`	float	幅 ÷ 高さで表したアスペクト比。16:9 なら `1.777...`、1:1 なら `1.0`
`stretch_mode`	enum	比率の合わせ方（WIDTH_CONTROLS_HEIGHT / HEIGHT_CONTROLS_WIDTH / FIT / COVER）
`alignment_horizontal`	enum	子ノードの水平方向の配置（LEFT / CENTER / RIGHT）
`alignment_vertical`	enum	子ノードの垂直方向の配置（TOP / CENTER / BOTTOM）

stretch_mode の選択肢は用途によって使い分けます。

stretch_mode	動作	向いている場面
`WIDTH_CONTROLS_HEIGHT`	幅を基準に高さを自動計算	横幅が可変・縦を追従させたいとき（デフォルト）
`HEIGHT_CONTROLS_WIDTH`	高さを基準に幅を自動計算	縦幅が可変・横を追従させたいとき
`FIT`	比率を保ちつつコンテナに収まる最大サイズ	コンテナ内に余白が出てもはみ出したくないとき
`COVER`	比率を保ちつつコンテナ全体を覆う最小サイズ	コンテナを完全に埋めたいとき（はみ出しあり）

stretch_mode 4種類の動作の違い — stretch_mode によって、子ノードのサイズがどう決まるかが変わる

コード例：16:9 のビデオプレビュー枠を作る

@onready var video_frame: AspectRatioContainer = $AspectRatioContainer

func _ready() -> void:
    # 16:9 のアスペクト比を設定
    video_frame.ratio = 16.0 / 9.0
    # コンテナに収まるよう FIT モードに
    video_frame.stretch_mode = AspectRatioContainer.STRETCH_FIT
    # 中央揃え
    video_frame.alignment_horizontal = AspectRatioContainer.ALIGNMENT_CENTER
    video_frame.alignment_vertical   = AspectRatioContainer.ALIGNMENT_CENTER

コード例：正方形のミニマップ枠を作る

@onready var minimap_frame: AspectRatioContainer = $MinimapFrame

func _ready() -> void:
    minimap_frame.ratio = 1.0  # 1:1（正方形）
    minimap_frame.stretch_mode = AspectRatioContainer.STRETCH_WIDTH_CONTROLS_HEIGHT

もっと使いこなす：カスタマイズできるパラメータ

まずは基本を動かしてみてから、余裕が出たら試してみてください。

パラメータ・テクニック	変えると何が起きるか
`ratio` を `16.0 / 9.0` に	映像コンテンツの標準比率になる。動画・スクリーンショットのプレビューに使いやすい
`ratio` を `1.0` に	常に正方形を維持する。アイコン・アバター・ミニマップに最適
`stretch_mode` を `FIT` に	余白が出てもはみ出さない安全な表示になる。汎用的に使いやすいモード
`stretch_mode` を `COVER` に	コンテナ全体を必ず埋める。背景やサムネイル表示に向いている
`alignment_horizontal/vertical` を変える	比率維持で余白が生まれたとき、子ノードを左上・右下・中央などに寄せられる
CenterContainer と組み合わせる	画面中央に比率固定のコンテンツを配置したいときに、外側を CenterContainer で包む