| name | responsive-ui |
| description | Use when handling multiple resolutions — stretch modes, aspect ratios, DPI scaling, and mobile/desktop adaptation |
Responsive UI in Godot 4.3+
All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.
Related skills: godot-ui for Control node layout and themes, export-pipeline for platform-specific export settings, godot-project-setup for initial project resolution settings, input-handling for touch vs desktop input adaptation, localization for layout adjustments per locale, mobile-development for safe-area and notch handling.
1. Project Settings for Resolution
Configure base resolution and stretch behaviour in Project > Project Settings > Display > Window.
Key settings and their .godot/project.godot keys:
| Setting | project.godot key | Recommended value |
|---|
| Viewport width | window/size/viewport_width | 1920 (or your base design width) |
| Viewport height | window/size/viewport_height | 1080 (or your base design height) |
| Stretch mode | window/stretch/mode | canvas_items (most games) |
| Stretch aspect | window/stretch/aspect | expand (fill screen) or keep (letterbox) |
| Scale factor | window/stretch/scale | 1 (adjust for pixel art integer scaling) |
Godot 4.7+: Projects newly created in Godot 4.7 already default display/window/stretch/mode to canvas_items and display/window/stretch/aspect to expand (previously disabled / keep) — the recommendations above are now the out-of-the-box values. Projects created on older versions are unchanged (the property default is still disabled), so set both explicitly when upgrading. See the 4.7 migration guide.
These can also be set at runtime:
GDScript:
# Read current viewport size
var viewport_size: Vector2 = get_viewport().get_visible_rect().size
# Change stretch mode at runtime
ProjectSettings.set_setting("display/window/stretch/mode", "canvas_items")
C#:
Vector2I viewportSize = GetViewport().GetVisibleRect().Size;
ProjectSettings.SetSetting("display/window/stretch/mode", "canvas_items");
2. Stretch Mode Comparison
| Mode | project.godot value | Rendering | Best For |
|---|
canvas_items | "canvas_items" | Viewport rendered at design resolution, then upscaled — UI and 2D nodes scale smoothly | Most 2D and UI-heavy games |
viewport | "viewport" | Entire viewport is rendered at design resolution and stretched; no sub-pixel blending | Pixel art games needing pixel-perfect output |
disabled | "disabled" | No automatic scaling; every Control node must handle its own layout | Complex custom scaling, 3D games with a Control HUD |
When to choose each:
canvas_items — Default recommendation. Smooth scaling at any resolution. UI built with Control nodes and anchors responds naturally. Text and icons stay crisp at high DPI when combined with content_scale_factor.viewport — Locks rendering to the design resolution. Combined with integer scaling and nearest-neighbour filtering it gives a classic pixel-perfect look. Avoid for high-DPI displays unless you intentionally want chunky pixels.disabled — Use when you need full manual control, e.g. a 3D game where the UI must adapt to safe areas or unusual aspect ratios without Godot scaling it.
3. Aspect Ratio Handling
Set via Project > Project Settings > Display > Window > Stretch > Aspect or the window/stretch/aspect key.
| Mode | Visual Result | When to Use |
|---|
keep | Letterbox (black bars top/bottom) or pillarbox (bars left/right) — design rect is preserved exactly | Games with a fixed layout that must not be cropped (e.g. score-based arcade, puzzle) |
expand | Screen is fully filled; the visible game area grows on wider or taller displays | Action games, platformers — more visible play area is a bonus, not a problem |
keep_width | Width is fixed; height expands on taller screens (mobile portrait) | Portrait mobile games where horizontal alignment is strict |
keep_height | Height is fixed; width expands on wider screens (landscape) | Landscape games where vertical alignment is strict (e.g. side-scroller HUD) |
expand with adaptive UI is the most versatile choice for games targeting both desktop and mobile. Anchor your HUD elements to screen edges so they follow the expanded visible area.
4. Pixel Art Setup
For crisp pixel-art games: Project Settings → Display → Window → Stretch → Mode = viewport, base resolution at native pixel size (e.g., 320×180), Window Size Override = 4× for editor preview. Use integer scaling to avoid sub-pixel blur.
See references/pixel-art-setup.md for full project settings, integer-scaling script, nearest-neighbour filter overrides.
5. DPI Scaling
For retina / high-DPI displays: set content_scale_factor to scale the entire UI proportionally. Query DisplayServer.screen_get_dpi() at runtime for adaptive scaling per device.
See references/dpi-scaling.md for the content_scale_factor recipe and DPI-querying patterns.
6. Mobile Considerations
Four mobile-specific concerns: touch input (tap, swipe, multi-touch), safe-area insets (notch / dynamic island avoidance), orientation lock (portrait/landscape pinning), virtual keyboard (handle show/hide to avoid covering UI).
See references/mobile.md for full GDScript on each concern, plus iOS / Android nuances.
7. Adaptive Layouts
Anchor presets + Container nodes do most of the work. Use size_flags_horizontal/vertical (FILL, EXPAND, SHRINK_CENTER, SHRINK_END) to control how children consume container space. Detect runtime resolution changes via get_viewport().size_changed.
See references/adaptive-layouts.md for the anchor + container strategy, resolution-change detection, and the full size_flags reference.
8. Testing Multiple Resolutions
Editor Preview Sizes
In the editor viewport, use Editor > Editor Settings > Run > Window Placement to start the game at specific sizes, or use the viewport size selector in the 2D editor toolbar.
Add common test sizes under Project > Project Settings > Display > Window > Size > Test Width/Height to preview in the editor.
--resolution CLI Flag
Launch from the command line with an override resolution:
godot.exe --path "C:/projects/mygame" --resolution 1280x720
godot --path /projects/mygame --resolution 1280x720
./mygame.x86_64 --resolution 375x812
Common Test Resolutions
| Resolution | Aspect | Common Use |
|---|
1920×1080 | 16:9 | Standard 1080p desktop / TV |
2560×1440 | 16:9 | 1440p high-DPI desktop |
1280×720 | 16:9 | Low-end desktop / minimum target |
640×360 | 16:9 | Pixel art base resolution (2× of 320×180) |
2732×2048 | 4:3 | iPad Pro — tests non-16:9 aspect ratios |
390×844 | ~19.5:9 | iPhone 14 portrait |
844×390 | ~19.5:9 | iPhone 14 landscape |
1080×2400 | 20:9 | Android tall portrait |
360×800 | ~20:9 | Android low-end portrait |
Strategy: Always test at your base design resolution, one resolution wider than 16:9 (e.g. 21:9 ultrawide), and one taller (e.g. mobile portrait). These three cases catch the most layout bugs.
9. Checklist
