The problem of multiple resolutions

Developers often have trouble understanding how to best support multiple resolutions in their games. For desktop and console games, this is more or less straightforward, as most screen aspect ratios are 16:9 and resolutions are standard (720p, 1080p, 1440p, 4K, …).

For mobile games, at first, it was easy. For many years, the iPhone and iPad used the same resolution. When Retina was implemented, they just doubled the pixel density; most developers had to supply assets in default and double resolutions.

Nowadays, this is no longer the case, as there are plenty of different screen sizes, densities, and aspect ratios. Non-conventional sizes are also becoming increasingly popular, such as ultrawide displays.

For 3D games, there is not much of a need to support multiple resolutions (from the aesthetic point of view). The 3D geometry will just fill the screen based on the field of view, disregarding the aspect ratio. The main reason one may want to support this, in this case, is for performance reasons (running in lower resolution to increase frames per second).

For 2D and game UIs, this is a different matter, as art needs to be created using specific pixel sizes in software such as Photoshop, GIMP or Krita.

Since layouts, aspect ratios, resolutions, and pixel densities can change so much, it is no longer possible to design UIs for every specific screen. Another method must be used.


The most common approach is to use a single base resolution and then fit it to everything else. This resolution is how most players are expected to play the game (given their hardware). For mobile, Google has useful stats online, and for desktop, Steam also does.

As an example, Steam shows that the most common primary display resolution is 1920×1080, so a sensible approach is to develop a game for this resolution, then handle scaling for different sizes and aspect ratios.

Godot provides several useful tools to do this easily.


A base size for the window can be specified in the Project Settings under Display → Window.


然而,它的作用并不完全明显; 引擎将 尝试将显示器切换到此分辨率。 相反,将此设置视为“设计大小”,即您在编辑器中使用的区域的大小。 此设置直接对应于2D编辑器中蓝色矩形的大小。

通常需要支持具有与该基本大小不同的屏幕和窗口大小的设备。 Godot提供了许多方法来控制视区的大小调整和拉伸到不同的屏幕大小。


Godot follows a modern approach to multiple resolutions. The engine will never change the monitor's resolution on its own. While changing the monitor's resolution is the most efficient approach, it's also the least reliable approach as it can leave the monitor stuck on a low resolution if the game crashes. This is especially common on macOS or Linux which don't handle resolution changes as well as Windows.

Changing the monitor's resolution also removes any control from the game developer over filtering and aspect ratio stretching, which can be important to ensure correct display for pixel art games.

On top of that, changing the monitor's resolution makes alt-tabbing in and out of a game much slower since the monitor has to change resolutions every time this is done.


市面上有着各种各样的设备, 拥有各种类型的屏幕, 依次有着不同的像素密度和分辨率。处理所有的类型工作量巨大, 所以Godot试图让开发者的生活变得更简单。 Viewport 节点提供了几个处理大小调整的函数, 而场景树的根节点始终是一个Viewport (场景将作为它的子节点被实例化, 并且始终可以通过调用``get_tree().get_root()`` 或``get_node("/root")`` 来访问它。

在任何情况下, 虽然更改``根视区``的参数可能是解决问题的最灵活方法, 但这样做的可能包含大量工作、大量代码和大量推测过程, 因此Godot在``项目设置``中提供了一组简单的参数来处理多分辨率问题。


Stretch settings are located in the project settings and provide several options:


拉伸模式 (Stretch mode)

The Stretch Mode setting defines how the base size is stretched to fit the resolution of the window or screen.


下面的动画使用仅16×9像素的“基本大小”来演示不同拉伸模式的效果。 单个精灵,大小也是16×9像素,覆盖整个视区,并在其上添加一个对角线 Line2D :

  • Stretch Mode = Disabled (default): No stretching happens. One unit in the scene corresponds to one pixel on the screen. In this mode, the Stretch Aspect setting has no effect.


  • Stretch Mode = 2D: In this mode, the size specified in display/width and display/height in the project settings is stretched to cover the whole screen (taking the Stretch Aspect setting into account). This means that everything is rendered directly at the target resolution. 3D is largely unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts.

    如果您的2D图稿具有足够高的分辨率并且不需要像素完美渲染,那么这是一个不错的选择。 考虑在2D纹理和字体上启用纹理过滤和mipmapping。

  • Stretch Mode = Viewport: Viewport scaling means that the size of the root Viewport is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking the Stretch Aspect setting into account).

    This mode is useful when working with pixel-precise games, or for the sake of rendering to a lower resolution to improve performance.


拉伸比例(Stretch aspect)

The second setting is the stretch aspect. Note that this only takes effect if Stretch Mode is set to something other than Disabled.

在下面的动画中,您会注意到灰色和黑色区域。 黑色区域由引擎添加,无法绘制。 灰色区域是场景的一部分,可以绘制。 灰色区域对应于您在2D编辑器中看到的蓝色框架外的区域。

  • Stretch Aspect = Ignore: Ignore the aspect ratio when stretching the screen. This means that the original resolution will be stretched to exactly fill the screen, even if it's wider or narrower. This may result in nonuniform stretching: things looking wider or taller than designed.

  • Stretch Aspect = Keep: Keep aspect ratio when stretching the screen. This means that the viewport retains its original size regardless of the screen resolution, and black bars will be added to the top/bottom of the screen ("letterboxing") or the sides ("pillarboxing").


  • Stretch Aspect = Keep Width: Keep aspect ratio when stretching the screen. If the screen is wider than the base size, black bars are added at the left and right (pillarboxing). But if the screen is taller than the base resolution, the viewport will be grown in the vertical direction (and more content will be visible to the bottom). You can also think of this as "Expand Vertically".

    这通常是创建可扩展的GUI或HUD的最佳选择,因此一些控件可以锚定到底部( 大小和锚定点)。

  • Stretch Aspect = Keep Height: Keep aspect ratio when stretching the screen. If the screen is taller than the base size, black bars are added at the top and bottom (letterboxing). But if the screen is wider than the base resolution, the viewport will be grown in the horizontal direction (and more content will be visible to the right). You can also think of this as "Expand Horizontally".


  • Stretch Aspect = Expand: Keep aspect ratio when stretching the screen, but keep neither the base width nor height. Depending on the screen aspect ratio, the viewport will either be larger in the horizontal direction (if the screen is wider than the base size) or in the vertical direction (if the screen is taller than the original size).



The Shrink setting allows you to add an extra scaling factor on top of what the Stretch options above already provide. The default value of 1 means that no scaling occurs.

If, for example, you set Shrink to 4 and leave Stretch Mode on Disabled, each unit in your scene will correspond to 4×4 pixels on the screen.

If Stretch Mode is set to something other than Disabled, the size of the root viewport is scaled down by the Shrink factor, and pixels in the output are scaled up by the same amount. This is rarely useful for 2D games, but can be used to increase performance in 3D games by rendering them at a lower resolution.


To configure stretching at runtime from a script, use the get_tree().set_screen_stretch() method (see SceneTree.set_screen_stretch()).


If the game has a very high base resolution (e.g. 3840×2160), aliasing might appear when downsampling to something considerably lower like 1280×720. Aliasing can be made less visible by shrinking all images by a factor of 2 upon loading. This can be done by calling the method below before the game data is loaded:


Alternatively, you can also enable mipmaps on all your 2D textures. However, enabling mipmaps will increase memory usage which may be problematic on low-end mobile devices.

Handling aspect ratios

Once scaling for different resolutions is accounted for, make sure that your user interface also scales for different aspect ratios. This can be done using anchors and/or containers.

视场角(Field of view)缩放

The 3D Camera node's Keep Aspect property defaults to the Keep Height scaling mode (also called Hor+). This is usually the best value for desktop games and mobile games in landscape mode, as widescreen displays will automatically use a wider field of view.

However, if your 3D game is intended to be played in portrait mode, it may make more sense to use Keep Width instead (also called Vert-). This way, smartphones with an aspect ratio taller than 16:9 (e.g. 19:9) will use a taller field of view, which is more logical here.

Scaling 2D and 3D elements differently using Viewports

Using multiple Viewport nodes, you can have different scales for various elements. For instance, you can use this to render the 3D world at a low resolution while keeping 2D elements at the native resolution. This can improve performance significantly while keeping the HUD and other 2D elements crisp.

This is done by using the root Viewport node only for 2D elements, then creating a Viewport node to display the 3D world and displaying it using a ViewportContainer or TextureRect node. There will effectively be two viewports in the final project. One upside of using TextureRect over ViewportContainer is that it allows enable linear filtering. This makes scaled 3D viewports look better in many cases.

See the 3D viewport scaling demo for examples.