Gui Resizer

d954mas · December 27, 2025, 5:50am

Defold GUI Resizer

Project for automatic GUI scaling for portrait and landscape orientations with safe area support.

Screenshots

Features

Recompute GUI scale based on screen aspect ratio.
Automatic selection of gui.ADJUST_FIT / gui.ADJUST_ZOOM.
Safe area offsets for UI elements (notch/system bars).

Setup

You can use this project as a Defold library dependency. Open game.project and add:

https://github.com/d954mas/defold-gui-resizer/archive/master.zip

For safe area support, use the official extension:

https://github.com/defold/extension-safearea

Logic: FIT in landscape, ZOOM in portrait

On resize, the system uses gui.ADJUST_FIT for landscape and gui.ADJUST_ZOOM for portrait.
This allows the same layout to work across both orientations. Landscape behaves like the standard
Defold GUI setup, while portrait uses gui.ADJUST_ZOOM plus an automatic scale selected from the
predefined list of aspect presets.

Quick start

Initialize scale presets and size checks:

-- main/main.script
local GUI_RESIZER = require "gui_resizer.gui_resizer"

function init(self)
	GUI_RESIZER.init_scales({
		{ scale = vmath.vector3(1), aspect = 10 / 16 },
		{ scale = vmath.vector3(1), aspect = (3 / 4) },
		{ scale = vmath.vector3(1), aspect = (3.5 / 4) },
		{ scale = vmath.vector3(1), aspect = (4 / 4) },
	})
end

function update(self, dt)
	GUI_RESIZER:check_size()
end

Use the resizer in a GUI script and register nodes:

-- main/gui.gui_script
local GUI_RESIZER = require "gui_resizer.gui_resizer"

function init(self)
	self.resizer = GUI_RESIZER.new()
	self.resizer:add_node(gui.get_node("top"), 2, { top = 0 })
	self.resizer:add_node(gui.get_node("modal"), 3, {})
end

function update(self, dt)
	self.resizer:update()
end

Safe area

The module gui_resizer/safearea_helper.lua expects safearea.get_insets().
On PC there is a test implementation. Uncomment if you need it. In production, replace it with safearea extension.

API

`gui_resizer.gui_resizer`

GUI_RESIZER.init_scales(scales) initializes scale presets.
- scales is an array of { scale = vmath.vector3, aspect = number }.
- Must be called once before use.
GUI_RESIZER:check_size() recalculates screen size, aspect, and scales. Call every frame or on resize.
GUI_RESIZER.new() creates a new resizer instance.
GuiResizer:add_node(node, scale_idx, safe_area_config) registers a GUI node.
- node is a gui node.
- scale_idx is the index in scales (defaults to 2, the aspect = 3/4 preset, which fits most cases well).
- safe_area_config is a table with optional numeric offsets top, bottom, left, right.
  The value is added to the corresponding safe area inset (extra movement in GUI units).
GuiResizer:remove_node(node) unregisters a node from the resizer.
GuiResizer:update() applies current scale, adjust mode, and safe area offsets to all nodes.
GuiResizer.get_scale(idx) returns the scale preset by index.
GuiResizer.get_mode() returns the current adjust mode (gui.ADJUST_FIT or gui.ADJUST_ZOOM).

Scale presets

init_scales() takes a list of presets with aspect and base scale.
The calculations use display.width/height from game.project, so make sure those values match
your reference layout.