---
name: responsive-ui
description: Use when handling multiple resolutions — stretch modes, aspect ratios, DPI scaling, and mobile/desktop adaptation
title: responsive-ui
canonical_url: https://skilld.dev/gh/jame581/godotprompter/responsive-ui
last_updated: 2026-10-23T04:19:05.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/adaptive-layouts.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/references/adaptive-layouts.md), [references/dpi-scaling.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/references/dpi-scaling.md), [references/mobile.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/references/mobile.md), [references/pixel-art-setup.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/references/pixel-art-setup.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/responsive-ui`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/responsive-ui`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/responsive-ui) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/responsive-ui`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/responsive-ui --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/responsive-ui --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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 keys in the `[display]` section of `project.godot`:

| 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` |
| Scale mode | `window/stretch/scale_mode` | `fractional`; `integer` for pixel art |

> **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](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

The engine reads these settings once at startup; changing them with `ProjectSettings.set_setting()` later has no effect. At runtime, set the matching `Window` properties instead:

**GDScript:**

```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#:**

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

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

---

## 2. Stretch Mode Comparison

| Mode | `project.godot` value | Rendering | Best For |
|---|---|---|---|
| `canvas_items` | `"canvas_items"` | Rendered at the window's resolution; 2D nodes and UI are scaled from the design resolution, so text stays sharp | 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; the viewport is the window size, so a bigger window shows more at the same pixel size (anchors and containers still lay out) | 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 Width/Height Override` (e.g. 1280×720) for a larger window when testing. Use integer scaling (`Stretch → Scale Mode = integer`) to avoid uneven pixels.

> See [references/pixel-art-setup.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/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](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/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](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/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](https://skilld.dev/api/skills-raw/jame581/godotprompter/responsive-ui/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.

Set a test window size under **Project > Project Settings > Display > Window > Size > Window Width/Height Override** — the game window opens at that size while the base viewport size stays the same.

### `--resolution` CLI Flag

Launch from the command line with an override resolution:

```bash
# 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
```

### 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

- [ ] Base viewport size (`viewport_width` / `viewport_height`) matches the design canvas in the editor
- [ ] Stretch mode chosen deliberately: `canvas_items` for most games, `viewport` for pixel art
- [ ] Aspect ratio mode chosen: `expand` unless fixed-layout content requires `keep`
- [ ] Pixel art games use `viewport` stretch + `Nearest` texture filter + `integer` stretch scale mode
- [ ] All HUD `Control` nodes use anchors anchored to the nearest edge, not fixed `position` values
- [ ] `custom_minimum_size` set on buttons and interactive elements to prevent collapse below tap target size (minimum 44×44 px recommended for mobile)
- [ ] `size_flags_horizontal` / `size_flags_vertical` set to `SIZE_EXPAND_FILL` on elements that should fill space
- [ ] `get_viewport().size_changed` signal connected where layout must respond to window resize
- [ ] Safe area insets read from `DisplayServer.get_display_safe_area()` and applied to a root `MarginContainer`
- [ ] `content_scale_factor` set at startup based on `DisplayServer.screen_get_dpi()` for high-DPI / Retina displays
- [ ] Touch input handled via `InputEventScreenTouch` / `InputEventScreenDrag`, not mouse events alone
- [ ] Orientation locked to the correct mode (`SCREEN_LANDSCAPE` / `SCREEN_PORTRAIT`) or `SCREEN_SENSOR` where rotation is intended
- [ ] Virtual keyboard height queried after show and used to shift UI content upward on mobile
- [ ] Tested at minimum: design resolution, one ultra-wide (21:9), and one mobile portrait resolution
- [ ] `--resolution` flag used in CI or playtest scripts to automate multi-resolution smoke tests
