godot-modernize-ui

name	godot-modernize-ui
version	1.0.0
displayName	Godot UI Modernization
description	Modernize Godot 3.x UI to 4.x best practices with theme extraction, responsive layouts, hiDPI support, and RichTextLabel BBCode patterns
author	Godot Superpowers
license	MIT
category	ui
type	tool
difficulty	beginner
audience	["developers","ui-designers"]
keywords	["godot","ui","theme","responsive","hidpi","bbcode","anchoring","layout","control","modernize"]
platforms	["linux","macos","windows"]
repository	https://github.com/asreonn/godot-superpowers
homepage	https://github.com/asreonn/godot-superpowers#readme

Godot UI Modernization

Modernizes Godot 3.x UI scenes and scripts to Godot 4.x best practices.

When to Use

• Migrating Godot 3.x projects to 4.x with UI scenes
• UI doesn't scale properly on hiDPI displays
• Hardcoded styles scattered across Control nodes
• Manual positioning instead of responsive anchoring
• RichTextLabel using deprecated BBCode tags
• Creating reusable custom controls

Core Patterns

1. Theme Resource Extraction

Before (Godot 3.x):

# Hardcoded in each Control node
$Button.modulate = Color.red
$Button.get("custom_styles/normal").bg_color = Color.blue
$Label.add_font_override("font", preload("res://fonts/big.tres"))

After (Godot 4.x):

# Centralized in Theme resource
# Create: res://ui/themes/main_theme.tres
# Assign to root Control or project settings

Theme.tres structure:

Theme
├── Button/styles/normal (StyleBoxFlat)
├── Button/colors/font_color = Color(1, 1, 1, 1)
├── Button/fonts/font = preload("res://fonts/button_font.tres")
├── Label/fonts/font = preload("res://fonts/label_font.tres")
└── Panel/styles/panel (StyleBoxFlat)

2. Control Anchoring Standardization

Before:

# Manual positioning
$Panel.position = Vector2(100, 100)
$Panel.size = Vector2(400, 300)

After:

Control (root)
├── Layout Mode: Anchors
├── Anchor Left: 0.5, Anchor Top: 0.5
├── Anchor Right: 0.5, Anchor Bottom: 0.5
├── Grow Horizontal: Center
├── Grow Vertical: Center
└── Custom Minimum Size: (400, 300)

Anchor Presets for Common Layouts:

Layout	Anchors	Offsets	Grow
Fullscreen	0,0 to 1,1	0 all sides	Both
Top Bar	0,0 to 1,0	Bottom: 60	Horizontal
Bottom Bar	0,1 to 1,1	Top: 60	Horizontal
Center Panel	0.5,0.5	Size defined	Both
Left Sidebar	0,0 to 0,1	Right: 250	Vertical
Right Sidebar	1,0 to 1,1	Left: 250	Vertical

3. UI Scaling (hiDPI Support)

Project Settings:

Display > Window > Stretch
├── Mode: canvas_items (or viewport)
├── Aspect: expand
└── Scale: 1.0 (auto-detected)

Script for Dynamic Scaling:

func _ready():
    # Handle hiDPI on different displays
    var screen_dpi = DisplayServer.screen_get_dpi()
    if screen_dpi > 150:
        get_tree().root.content_scale_factor = 2.0

Responsive Sizing:

@export var base_width: float = 1920.0
@export var base_height: float = 1080.0

func _on_viewport_size_changed():
    var viewport_size = get_viewport().get_visible_rect().size
    var scale_x = viewport_size.x / base_width
    var scale_y = viewport_size.y / base_height
    scale = Vector2(min(scale_x, scale_y), min(scale_x, scale_y))

4. RichTextLabel BBCode Patterns

Deprecated Godot 3.x:

[color=red]Warning[/color]
[url=https://example.com]Link[/url]
[img]res://icon.png[/img]

Godot 4.x BBCode:

[color=ff0000]Warning[/color]
[color=#ff0000]Hex Color[/color]
[url=https://example.com]Link[/url]
[img=64x64]res://icon.png[/img]
[font=res://fonts/custom.tres]Custom font[/font]
[wave amp=50 freq=5]Animated text[/wave]
[tornado radius=5 freq=2]Spinning text[/tornado]
[shake rate=5 level=10]Shaking text[/shake]
[fgcolor=00ff00 bgcolor=000000]Background[/fgcolor]
[outline_color=ffffff]Outlined[/outline_color]

Script Integration:

@onready var rich_label: RichTextLabel = $RichTextLabel

func append_colored_text(text: String, color: Color):
    rich_label.append_text("[color=%s]%s[/color]" % [color.to_html(), text])

func append_url(text: String, url: String):
    rich_label.append_text("[url=%s]%s[/url]" % [url, text])
    
func _on_meta_clicked(meta):
    OS.shell_open(str(meta))

5. Custom Control Creation

Custom Button with Built-in Theme:

@tool
class_name ModernButton
extends Button

@export var button_style: ButtonStyle = ButtonStyle.PRIMARY:
    set(value):
        button_style = value
        _update_style()

enum ButtonStyle { PRIMARY, SECONDARY, DANGER }

func _ready():
    _update_style()

func _update_style():
    match button_style:
        ButtonStyle.PRIMARY:
            add_theme_color_override("font_color", Color(1, 1, 1))
            add_theme_stylebox_override("normal", preload("res://ui/styles/primary_normal.tres"))
        ButtonStyle.SECONDARY:
            add_theme_color_override("font_color", Color(0.2, 0.2, 0.2))
            add_theme_stylebox_override("normal", preload("res://ui/styles/secondary_normal.tres"))
        ButtonStyle.DANGER:
            add_theme_color_override("font_color", Color(1, 1, 1))
            add_theme_stylebox_override("normal", preload("res://ui/styles/danger_normal.tres"))

Responsive Design Patterns

Container Hierarchy

CanvasLayer (UI Layer)
└── Control (Full Rect anchor, Fullscreen preset)
    ├── MarginContainer (padding)
    │   ├── VBoxContainer (vertical layout)
    │   │   ├── HBoxContainer (top bar)
    │   │   │   ├── Label (title)
    │   │   │   └── Button (close)
    │   │   └── ScrollContainer (scrollable content)
    │   │       └── VBoxContainer
    │   │           └── (dynamic content)
    │   └── HBoxContainer (bottom bar)
    │       └── Button (action)
    └── Panel (overlay/popup)

Safe Area Handling (Mobile)

func _ready():
    # Apply safe area insets for notched devices
    var safe_area = DisplayServer.get_display_safe_area()
    var window_size = DisplayServer.window_get_size()
    
    $MarginContainer.add_theme_constant_override("margin_left", safe_area.position.x)
    $MarginContainer.add_theme_constant_override("margin_top", safe_area.position.y)
    $MarginContainer.add_theme_constant_override("margin_right", 
        window_size.x - safe_area.end.x)
    $MarginContainer.add_theme_constant_override("margin_bottom", 
        window_size.y - safe_area.end.y)

Common Mistakes

Using RectPosition/RectSize directly:

# ❌ Bad - breaks with different resolutions
$Control.rect_position = Vector2(100, 100)
$Control.rect_size = Vector2(200, 150)

# ✅ Good - use anchors and layout containers
# Set anchors in editor or use custom_minimum_size
$Control.custom_minimum_size = Vector2(200, 150)

Hardcoding pixel values without scaling:

# ❌ Bad - too small on hiDPI
var padding = 10

# ✅ Good - scale with content_scale_factor
var padding = 10 * get_tree().root.content_scale_factor

Manual font size calculations:

# ❌ Bad - inconsistent across displays
label.add_theme_font_size_override("font_size", 24)

# ✅ Good - use theme with dynamic fonts
# Set in Theme resource with multiple sizes

Forgetting to handle window resize:

# ✅ Good - subscribe to resize signal
func _ready():
    get_viewport().size_changed.connect(_on_viewport_size_changed)
    _on_viewport_size_changed()

func _on_viewport_size_changed():
    # Recalculate responsive layout
    pass

Quick Reference

Task	Godot 3.x	Godot 4.x
Theme override	add_stylebox_override()	add_theme_stylebox_override()
Font override	add_font_override()	add_theme_font_override()
Color override	add_color_override()	add_theme_color_override()
Constant override	add_constant_override()	add_theme_constant_override()
Size override	rect_min_size	custom_minimum_size
Position	rect_position	position
Size	rect_size	size
Global position	rect_global_position	global_position
BBCode color	[color=red]	[color=ff0000] or [color=#ff0000]
BBCode image	[img]path[/img]	[img=widthxheight]path[/img]
hiDPI setting	ProjectSettings.display/window/dpi/allow_hidpi	Display > Window > Stretch > Mode

Migration Checklist

• Extract all hardcoded styles to Theme resources
• Replace rect_* properties with position/size
• Update BBCode syntax (colors, images)
• Configure hiDPI in project settings
• Convert manual positioning to anchor/layout system
• Test on multiple resolutions and DPIs
• Add viewport resize handling
• Create custom controls for repeated patterns