responsive-ui

Godot 4.3+ のレスポンシブ UI

すべての例は、非推奨 API を使用せずに Godot 4.3+ を対象としています。まず GDScript、次に C# を示します。

関連スキル： Control ノードのレイアウトとテーマについては godot-ui、プラットフォーム固有のエクスポート設定については export-pipeline、初期プロジェクトの解像度設定については godot-project-setup、タッチ入力とデスクトップ入力の適応については input-handling、ロケールごとのレイアウト調整については localization、セーフエリアとノッチへの対応については mobile-development を参照してください。

---

1. 解像度のプロジェクト設定

Project > Project Settings > Display > Window で、基準解像度とストレッチの動作を設定します。

主な設定と、project.godot の [display] セクションにおけるキーは次のとおりです。

設定	project.godot のキー	推奨値
ビューポートの幅	window/size/viewport_width	1920（または基準となるデザイン幅）
ビューポートの高さ	window/size/viewport_height	1080（または基準となるデザインの高さ）
ストレッチモード	window/stretch/mode	canvas_items（ほとんどのゲーム）
ストレッチのアスペクト比	window/stretch/aspect	expand（画面全体に表示）または keep（レターボックス表示）
スケール係数	window/stretch/scale	1
スケールモード	window/stretch/scale_mode	fractional。ピクセルアートには integer

Godot 4.7+： Godot 4.7 で新規作成されたプロジェクトでは、display/window/stretch/mode のデフォルトが canvas_items、display/window/stretch/aspect のデフォルトが expand になっています（以前は disabled／keep）。つまり、上記の推奨値が初期設定になりました。以前のバージョンで作成されたプロジェクトには変更がなく、プロパティのデフォルト値は引き続き disabled です。そのため、アップグレード時には両方を明示的に設定してください。4.7 移行ガイドを参照してください。

エンジンは起動時にこれらの設定を一度だけ読み込みます。後から ProjectSettings.set_setting() で変更しても反映されません。実行時には、代わりに対応する Window プロパティを設定してください。

GDScript：

# Read current viewport size
var viewport_size: Vector2 = get_viewport().get_visible_rect().size

# Change stretch mode at runtime (takes effect immediately)
get_window().content_scale_mode = Window.CONTENT_SCALE_MODE_CANVAS_ITEMS

C#：

// Read current viewport size
Vector2 viewportSize = GetViewport().GetVisibleRect().Size;

// Change stretch mode at runtime (takes effect immediately)
GetWindow().ContentScaleMode = Window.ContentScaleModeEnum.CanvasItems;

---

2. ストレッチモードの比較

モード	project.godot の値	描画	最適な用途
canvas_items	"canvas_items"	ウィンドウの解像度で描画されます。2D ノードと UI はデザイン解像度からスケーリングされるため、テキストが鮮明に保たれます	ほとんどの 2D ゲームおよび UI 中心のゲーム
viewport	"viewport"	ビューポート全体がデザイン解像度で描画され、ストレッチされます。サブピクセルブレンディングは発生しません	ピクセル単位で正確な出力が必要なピクセルアートゲーム
disabled	"disabled"	自動スケーリングは行われません。ビューポートはウィンドウサイズになるため、ウィンドウを大きくすると、同じピクセルサイズのまま表示範囲が広がります（アンカーとコンテナによるレイアウトは引き続き適用されます）	複雑なカスタムスケーリング、Control の HUD を備えた 3D ゲーム

各モードの選び方：

• canvas_items — デフォルトの推奨設定です。あらゆる解像度で滑らかにスケーリングされます。Control ノードとアンカーで構築された UI は自然に対応します。content_scale_factor と組み合わせると、高 DPI でもテキストとアイコンが鮮明に保たれます。
• viewport — 描画をデザイン解像度に固定します。整数スケーリングとニアレストネイバー補間を組み合わせることで、クラシックなピクセルパーフェクト表示を実現できます。意図的に粗いピクセルにしたい場合を除き、高 DPI ディスプレイでの使用は避けてください。
• disabled — 完全な手動制御が必要な場合に使用します。たとえば、Godot によるスケーリングを行わずに、セーフエリアや特殊なアスペクト比に UI を適応させる必要がある 3D ゲームなどです。

---

3. アスペクト比の処理

Project > Project Settings > Display > Window > Stretch > Aspect または window/stretch/aspect キーで設定します。

モード	表示結果	用途
keep	レターボックス（上下に黒帯）またはピラーボックス（左右に帯） — 設計時の領域が正確に維持されます	クロップしてはならない固定レイアウトのゲーム（例：スコア制のアーケードゲーム、パズル）
expand	画面全体に表示され、横長または縦長のディスプレイではゲームの表示領域が広がります	アクションゲーム、プラットフォーマー — プレイ領域が広く表示されるのは問題ではなく、むしろ利点です
keep_width	幅が固定され、縦長の画面（モバイルのポートレート表示）では高さが広がります	横方向の配置を厳密に保つ縦向きモバイルゲーム
keep_height	高さが固定され、横長の画面では幅が広がります	縦方向の配置を厳密に保つ横向きゲーム（例：横スクロールゲームの HUD）

アダプティブ UI を使った expand は、デスクトップとモバイルの両方を対象とするゲームに最も汎用性の高い選択肢です。HUD 要素を画面の端にアンカーして、拡張された表示領域に追従するようにします。

---

4. ピクセルアートの設定

鮮明なピクセルアートゲームにするには、Project Settings → Display → Window → Stretch → Mode = viewport を設定し、ベース解像度をネイティブのピクセルサイズ（例：320×180）にします。テスト時にウィンドウを大きくするには、Window Width/Height Override（例：1280×720）を設定します。不均一なピクセルを避けるには、整数スケーリング（Stretch → Scale Mode = integer）を使用します。

プロジェクト設定、整数スケーリングスクリプト、ニアレストネイバー補間のフィルターオーバーライドについては、references/pixel-art-setup.md を参照してください。

---

5. DPI スケーリング

Retina／高 DPI ディスプレイでは、content_scale_factor を設定して UI 全体を比例的に拡大縮小します。実行時に DisplayServer.screen_get_dpi() を照会すると、デバイスごとにスケーリングを調整できます。

content_scale_factor の設定方法と DPI の照会パターンについては、references/dpi-scaling.md を参照してください。

---

6. モバイルでの考慮事項

モバイル特有の考慮事項は 4 つあります。タッチ入力（タップ、スワイプ、マルチタッチ）、セーフエリアのインセット（ノッチ／ダイナミックアイランドを避ける）、画面の向きの固定（縦向き／横向きの固定）、仮想キーボード（UI が隠れないように表示／非表示を処理すること）です。

各項目の GDScript 全文と、iOS／Android 固有の注意点については、references/mobile.md を参照してください。

---

7. アダプティブレイアウト

アンカープリセットとコンテナーノードで、ほとんどの処理を行えます。size_flags_horizontal／vertical（FILL、EXPAND、SHRINK_CENTER、SHRINK_END）を使って、子要素がコンテナーのスペースをどのように使用するかを制御します。実行時の解像度変更は get_viewport().size_changed で検出できます。

アンカーとコンテナーを組み合わせた方法、解像度変更の検出、size_flags の全リファレンスについては、references/adaptive-layouts.md を参照してください。

---

8. 複数の解像度でのテスト

エディターのプレビューサイズ

エディターのビューポートでは、Editor > Editor Settings > Run > Window Placement を使って、特定のサイズでゲームを起動できます。または、2D エディターのツールバーにあるビューポートサイズセレクターを使います。

Project > Project Settings > Display > Window > Size > Window Width/Height Override でテスト用のウィンドウサイズを設定します。ベースのビューポートサイズはそのままに、ゲームウィンドウがそのサイズで開きます。

--resolution CLI フラグ

コマンドラインから解像度を指定して起動します。

# Windows
godot.exe --path "C:/projects/mygame" --resolution 1280x720

# Linux / macOS
godot --path /projects/mygame --resolution 1280x720

# Run an exported binary at a specific size
./mygame.x86_64 --resolution 375x812

一般的なテスト解像度

解像度	アスペクト比	一般的な用途
1920×1080	16:9	標準的な1080pのデスクトップ／テレビ
2560×1440	16:9	1440pの高DPIデスクトップ
1280×720	16:9	ローエンドのデスクトップ／最低目標
640×360	16:9	ピクセルアートの基準解像度（320×180の2倍）
2732×2048	4:3	iPad Pro — 16:9以外のアスペクト比をテスト
390×844	~19.5:9	iPhone 14の縦向き
844×390	~19.5:9	iPhone 14の横向き
1080×2400	20:9	Androidの縦長ポートレート
360×800	~20:9	Androidローエンド端末の縦向き

戦略： 常に基準デザイン解像度、16:9より横幅が広い解像度（例：21:9のウルトラワイド）、そして縦幅が長い解像度（例：モバイルの縦向き）でテストします。この3つのケースで、レイアウトの不具合の大半を検出できます。

---

9. チェックリスト

• 基準ビューポートサイズ（viewport_width／viewport_height）がエディターのデザインキャンバスと一致している
• ストレッチモードを意図的に選択している：ほとんどのゲームではcanvas_items、ピクセルアートではviewport
• アスペクト比モードを選択している：固定レイアウトのコンテンツでkeepが必要な場合を除き、expand
• ピクセルアートゲームでは、viewportストレッチ＋Nearestテクスチャフィルター＋integerストレッチスケールモードを使用している
• すべてのHUD Controlノードで、固定のposition値ではなく、最も近い端にアンカーを設定している
• ボタンや操作可能な要素にcustom_minimum_sizeを設定し、タップ対象のサイズを下回って縮小しないようにしている（モバイルでは最低44×44 pxを推奨）
• スペースを埋める要素のsize_flags_horizontal／size_flags_verticalをSIZE_EXPAND_FILLに設定している
• ウィンドウのサイズ変更にレイアウトを対応させる必要がある箇所で、get_viewport().size_changedシグナルを接続している
• DisplayServer.get_display_safe_area()からセーフエリアのインセットを取得し、ルートのMarginContainerに適用している
• 高DPI／Retinaディスプレイ向けに、起動時にDisplayServer.screen_get_dpi()を基にcontent_scale_factorを設定している
• タッチ入力はマウスイベントだけでなく、InputEventScreenTouch／InputEventScreenDragで処理している
• 画面の向きを正しいモード（SCREEN_LANDSCAPE／SCREEN_PORTRAIT）にロックしている。回転させる場合はSCREEN_SENSORを使用している
• モバイルでは、仮想キーボードの表示後に高さを取得し、UIコンテンツを上に移動させている
• 最低限、デザイン解像度、ウルトラワイド（21:9）1つ、モバイルの縦向き解像度1つでテストしている
• 複数解像度でのスモークテストを自動化するため、CIまたはプレイテストのスクリプトで--resolutionフラグを使用している