This Godot plugin provides a custom CanvasLayer that scales the viewport contents to always cover the full window with no black bars, no content reveal, and no distortions. Child CanvasItem nodes (i.e., UI) can also be scaled, independently of the content.
As noted in the Godot docs, scaling content for multiple resolutions is typically an issue that needs to be addressed in 2D games. Godot has built-in options to scale 2D content under Project Settings > General > Display > Window > Stretch, but the only way to scale with both no black bars and no content reveal is to use Aspect: ignore, which distorts content.
Godot's built-in stretch modes for scaling 2D content.
Black bars are not aesthetic, and prematurely revealing content outside of the viewport might be undesirable for gameplay. Scaling CanvasLayer presents one possible solution, which is always adjusting the zoom such that all black bars and content reveal areas are outside of the viewport's bounds.
Scaling CanvasLayer stretches with no black bars, no content reveal, and no distortions.
Download or clone this project and copy addons/scaling_canvas_layer/ to your project's addons/ folder. Alternatively you can install using the AssetLib from the Godot editor. Search for this plugin and then click Download followed by Install.
Open your project in Godot and enable Scaling CanvasLayer under Project Settings > Plugins.
Script settings.
Add a ScalingCanvasLayer to your scene and then review the settings below.
- Stretch Shrink - Sets Godot's Stretch Shrink factor. It is an overall scaling factor applied on top of everything. This affects both content and UI.
- Scale Content - Toggle content scaling on/off. "Content" is defined as objects that are not CanvasItem children of this CanvasLayer.
- Content Desired Resolution - Specify the ideal resolution of the content here. It determines when to scale up or down. If set to 0x0, the project's window size is used instead.
- Camera Path - A camera is required for content scaling. Godot currently doesn't support getting the active 2D camera by script, so you must assign it here manually.
- Scale Ui - Toggle UI scaling on/off. "UI" is defined as CanvasItem objects that are children of this CanvasLayer.
- Ui Desired Resolution - Specify the ideal resolution of the UI here. It determines when to scale up or down. If set to 0x0, the project's window size is used instead.
- Ui Width Height Factor - Weight factor that determines how much to scale the UI according to width and how much according to height (0.0 = width, 1.0 = height).
Content scaling affects objects in the viewport that are not child CanvasItem objects. To illustrate how content scaling works, we will be using:
- This 16x9 image:
. - An initial window size of 16x9, set in Project Settings > General > Display > Window > Size.
Content scaling is achieved by scaling the assigned camera's zoom. The resulting effect mimics Godot's 2d stretch mode, so antialiasing will occur when we scale up.
Antialiased content scaling.
You can avoid antialiasing by disabling Filter and Mipmaps on the Import tab of each asset and then reimporting. Now the results are similar to Godot's viewport stretch mode.
Disable Filter and Mipmaps on assets to remove antialiasing.
However, scaled pixels are not guaranteed to stay square because camera zooming allows pixel fractions in calculations, which occur when the scaled window's aspect ratio is not equal to the desired resolution's aspect ratio. This means that scaled pixels will not align correctly with the pixel grid.
Scaling content by camera zoom does not respect the pixel grid.
If you need pixel-perfect scaling, consider this solution by sysharm or this plugin by Yukitty, which scale the viewport instead of the camera zoom.
UI scaling affects objects that are child CanvasItem objects (i.e., buttons, text, controls) of this CanvasLayer. Because UI scaling has its own desired resolution setting, UI objects are scaled independently of the content. In addition, it uses the Ui Width Height Factor to determine how much influence the width and height should each have on the final scale. Setting it to 0.0 means only the difference in width (i.e., current resolution vs. desired resolution) will be considered. Setting it to 1.0 means only the difference in height is. A value of 0.5 factors in both width and height equally.
Scaling the UI with different Ui Width Height Factor values.
- This plugin overrides the settings under Project Settings > General > Display > Window > Stretch.
- Integer scaling (i.e., pixel-perfect scaling) is being discussed in Godot proposals.
- Original content scaling code is based on a gist by BarelyAliveMau5.
- "16:9" animations of built-in stretch modes are from the Godot docs. 16x9 image used in the content scaling examples was recreated based on these animations.
- Icon is a modified version of
CanvasLayer.svgfrom Godot's editor icons.
Copyright © 2021 Nicholas Yang
Copyright © 2021 BarelyAliveMau5
Unless otherwise specified, files in this repository are licensed under the MIT license. See LICENSE.md for more information.