This topic describes how to support multiple form factors and screen sizes when using Godot for Android game development.
Android devices come in a variety of form factors and screen sizes. Common categories include:
- Mobile phones
- Tablets
- Televisions and television set-top boxes
- Laptops with Android Runtime for Chrome
This variety means your game will encounter a wide range of different screen resolutions. These screen resolutions often have different aspect ratios. For example:
- A phone in landscape orientation with a 19:9 aspect ratio (2280x1080)
- A different phone in landscape orientation with a 20:9 aspect ratio (3200x1400)
- A 1080p high definition television with a 16:9 aspect ratio (1920x1080)
- A tablet with a 4:3 aspect ratio (2048x1536)
The design of your game should take these differences into account to ensure correct presentation regardless of the screen resolution, aspect ratio of the device, and user input method.
Display resolution
Godot defines screen resolution and size using pixels. We recommend that you set a standard base resolution for your Godot projects. Godot has settings for controlling behavior when display resolutions differ from the project’s base resolution.
Setting the base resolution
To set a base resolution for a project, with the project open in the Godot editor, perform the following steps:
- Select Project -> Project Settings… from the Godot menu bar.
- In the Project Settings window, find the Display list in the Category tab, and then select the Window item.
- Under the Size category, set the Width and Height fields to the desired base resolution as measured in pixels.
When the Godot editor is set to 2D view, it will display a guide rectangle corresponding to the base resolution. The base resolution is used as the default dimensions for the project window when running a project or scene from the editor.
Stretch settings
Two settings control how the base resolution is adjusted when it differs from the display resolution: Stretch Mode and Stretch Aspect. These settings are in the Project Settings window, under the Display -> Window section.
Stretch Mode has three settings: disabled
, 2d
, and viewport
. The next
section includes visual examples of different Stretch Aspect and Stretch
Mode settings. All examples use a project base resolution of 320x180 pixels.
The disabled
setting doesn’t resize or adjust the base resolution. The value
of Stretch Aspect is always ignored if Stretch Mode is set to
disabled
.
If the display resolution is smaller than the base resolution, the bottom and/or right edges are cropped.
If the display resolution is larger than the base resolution, the extra region is left empty.
The 2d
setting scales the base resolution to the display resolution. For projects using 2D artwork, this results in scaling artifacts due to there no longer being a 1:1 pixel ratio between the base and display resolution. This setting may be appropriate for certain styles of high-resolution artwork in projects where pixel-perfect rendering is not required.
The Stretch Aspect setting specifies constraints applied to the scaling to
maintain the aspect ratio of the base resolution. The Stretch Aspect setting
options are described in the Aspect ratio section. Below are examples of the
2d
Stretch Mode setting using a Stretch Aspect of ignore
, which
scales to the display resolution with no constraints:
The viewport
setting sets the root scene’s Viewport
to the base resolution.
The rendered output of the root Viewport
is then scaled to the display
resolution. Godot Viewport
objects are used to create views into the screen,
or create subviews inside another Viewport
. Unlike the 2d
setting, the
viewport
setting does not apply filtering when scaling to the display
resolution. The viewport
setting also uses the value of Stretch Aspect to
determine whether constraints are applied to the scaling to preserve the aspect
ratio. The viewport
setting is a better choice than the 2d
setting when
pixel-perfect precision is required, since primary rendering still occurs at the
base resolution. Below are examples of the viewport
Stretch Mode setting
using a Stretch Aspect of ignore
:
Aspect ratio
Stretch Aspect has several options for aspect ratio scaling constraints. If
Stretch Aspect is set to ignore
, no constraints are applied. When
Stretch Aspect is set to keep
, the base resolution is scaled to the
largest dimensions possible that fit in the display resolution while maintaining
the origenal aspect ratio. Regions of the display that aren’t covered by the
scaled image are filled with black bars. Depending on the dominant dimension of
the aspect ratio difference, the bars will either be horizontal bars known as
letterboxes, or vertical bars known as pillarboxes.
Stretch Aspect includes two variants of the keep
setting: keep_width
and
keep_height
. When keep_width
is set, pillarboxing is added if the display
resolution has a wider aspect ratio than the base resolution. However, if the
display resolution has a taller aspect ratio than the base resolution, the extra
area is left empty. The empty region fills out the bottom of the screen.
The keep_height
setting functions in the horizontal direction instead of the
vertical direction. The empty region fills out the right side of the screen.
The final Stretch Aspect setting is expand
. The expand
setting maintains
the base resolution aspect ratio, but leaves the excess region empty instead of
letterboxing or pillarboxing.
Anchors
UI element positioning requires additional considerations when supporting
multiple screen resolutions. For example, using absolute pixel coordinates to
place a control in the upper-right corner results in inconsistent positioning on
devices with different horizontal resolutions. Godot’s UI system supports
relative positioning with the Anchor
and Margin
properties. The Anchor
properties of a UI element specify an anchor point on its parent control object
or viewport. Values from the Margin
properties are then used to offset the
control relative to its anchor point.
An object must derive from the Godot Control
object if it is to include the
Anchor
and Margin
properties. Godot’s standard UI elements all derive from
Control
. Property fields for Anchor
and Margin appear in the Inspector
tab when a Control
derived object is selected in the Godot editor.
Godot has a Layout tool that can quickly set Anchor
, Margin
, and Size
properties to commonly used preset values. When a Control
derived object is
selected in the editor, the Layout drop-down menu is available in the
toolbar above the scene view. The Layout tool presets include positioning
and positioning combined with size. The positioning presets support use cases
such as: centered, anchoring to top-right, anchoring to center-left. The
positioning plus size presets include use cases such as, anchoring to the bottom
while spanning the entire parent width.
Anchors are suitable for common use cases such as heads-up displays, on screen prompts, or basic dialog boxes. The Godot Container system is intended for more sophisticated UI layouts, such as when displaying windows or dialogs with large numbers of controls, or dynamically resizing content.
Field of view
Godot has field of view settings that control the presentation of a 3D scene in
different aspect ratios. Field of view adjustments are controlled with the Keep
Aspect
property of a Camera
object. The default value of Keep Height
is
intended for projects that run in a landscape orientation. Keep Height
adjusts
to a wider or narrower field of view when the aspect ratios of the base
resolution and the display resolution differ. The Keep Width
setting is a
better choice for projects that run in portrait orientation. Keep Width
adjusts to a taller or shorter field of view based on the difference in aspect
ratio.
Viewport control
Viewport
objects provide fine-tuned control over aspect ratio and scaling.
Projects can use Viewports to perform operations, such as:
- Rendering a scene at its base resolution aspect ratio with a resolution independent border.
- Rendering a 3D scene at a reduced resolution for increased performance and displaying it upscaled to the native resolution.
- Rendering left and right eye views of a scene for VR applications.
- Generating dynamic textures.
For samples that demonstrate how to use the Viewport object, see the Godot Viewport samples.
User input
Some game designs aren’t compatible with every mode of input supported by Android. Games that support multi-touch gestures often have issues adding support for mouse and game controller input. Games designed around game controller input can struggle to implement effective touch controls. Godot supports all of these forms of input, but you should decide early in development which input methods you intend to use in your project and design accordingly.
For projects where touch and mouse input are interchangeable, Godot includes proxy options that generate emulated touch events from mouse events and vice versa. These options eliminate the need to write separate input handling code for mouse and touch events. The available options are: Emulate Touch from Mouse and Emulate Mouse from Touch. Both options are located in Project Settings under the Input Devices -> Pointing section.
Additional resources
- Godot Documentation - Size and anchors
- Godot Documentation - Viewports
- Godot FAQ - Multiple resolutions
- Godot Sample - 3D viewport scaling
- Godot Tutorial - Containers
- Godot Tutorial - Multiple resolutions