Index of every page on this site: llms.txt
All skills
jame581 avatar

/responsive-ui

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when handling multiple resolutions — stretch modes, aspect ratios, DPI scaling, and mobile/desktop adaptation

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/responsive-ui

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈33 tokens for metadata: the name and description. ≈2.4k when used: this file. ≈3k more on demand in 4 files.

Description uses 1.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈129 characters, or 1.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

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:

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

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:

# 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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts29d3 checks · Risk SAFE
  • Gen Agent Trust Hub29d

    The skill provides comprehensive documentation and code snippets for creating responsive user interfaces in Godot 4.3+. It covers project settings, DPI scaling, mobile safe areas, and pixel art configurations. No security issues were detected.

  • Socket29d

    No alerts

  • Snyk29d

    Risk: LOW · No issues

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last month

README badge

README badge for jame581/godotprompter/responsive-ui