ThemeDB in Godot – Complete Guide

Creating visually appealing and user-friendly interfaces is a crucial part of game development. The appearance of buttons, menus, and other UI elements can significantly impact player engagement and the overall gaming experience. This is where Godot’s ThemeDB class comes into play.

The ThemeDB class in Godot 4 is a powerful singleton that grants you access to a treasure trove of static information regarding theme resources. These resources are the backbone of your game’s visual identity, providing a consistent look and feel across all UI components.

What is ThemeDB?

ThemeDB is a class in Godot 4 that acts as a repository for theme-related data. It inherits from Object, perhaps the most fundamental class in Godot’s scripting API, which provides a broad range of features, from memory management to message passing. As a singleton, ThemeDB is globally accessible, ensuring that your theme resources are consistently manageable across your entire project.

What is it for?

The purpose of ThemeDB is to centralize control over theme properties and assets such as fonts, icons, styleboxes, and scaling factors. This centralization ensures that when you change a theme property, it gets updated instantly across all elements in your game, which can be a massive time saver. It also handles fallbacks for these properties, so you never have to worry about UI elements appearing unthemed or out of place.

Why should I learn it?

Understanding the ThemeDB class is essential for Godot developers who aim to create polished and scalable game interfaces. Whether you’re working on a small indie title or a large-scale project, learning how to use ThemeDB allows you to:

– Easily maintain a consistent aesthetic throughout your game.
– Quickly adjust the UI’s appearance by modifying theme resources in one location.
– Provide fallbacks to avoid unstyled UI elements, which can break immersion.

By mastering ThemeDB, you’ll take a big step towards making UIs that not only look great but are also maintainable and extendable, which is a hallmark of professional game development.

CTA Small Image

Basic Usage of ThemeDB

To start working with ThemeDB in Godot 4, you’ll want to understand how you can access theme properties for your UI elements. Here’s how you can do just that:

var button_theme = ThemeDB.get_icon("icon_name", "Button")

In the code snippet above, we’re retrieving an icon called “icon_name” that’s associated with the Button class using ThemeDB’s get_icon method. The returned icon can then be applied to Button nodes to ensure a consistent look throughout the game’s UI.

Changing Theme Properties Globally

One of the main advantages of using ThemeDB is the ability to change theme properties across all instances. If you want all buttons to have a new texture for their hovered state, you only need to make one change:

ThemeDB.set_icon("new_icon_name", "Button", new_icon_texture)

Here, we use the set_icon method to replace the existing icon for the hovered state of all Button nodes in our game with “new_icon_name”. This change automatically applies wherever the Button theme is used.

Accessing and Modifying StyleBoxes

StyleBoxes define the borders and backgrounds of UI elements in Godot. With ThemeDB, you can easily fetch and modify them:

var stylebox_normal = ThemeDB.get_stylebox("normal", "Button")
stylebox_normal.bg_color = Color(1, 0, 0, 1)  # Red background
ThemeDB.set_stylebox("normal", "Button", stylebox_normal)

In the code above, we are fetching the “normal” StyleBox for Button nodes, changing its background color to red, and then using set_stylebox to apply this modified StyleBox globally.

Adjusting Font Data

Fonts are crucial for UI legibility and style. ThemeDB lets you control font properties across your UI:

var default_font = ThemeDB.get_font("default_font", "Label")
default_font.size = 18  # Change font size
ThemeDB.set_font("default_font", "Label", default_font)

This example demonstrates how to get the default font for the Label class, change its size, and update it globally using ThemeDB’s set_font method.

Working with Theme Data Types

In addition to icons and StyleBoxes, ThemeDB can handle different data types, such as Colors and Constants:

# Get and set colors
var font_color = ThemeDB.get_color("font_color", "Label")
ThemeDB.set_color("font_color", "Label", Color(0.5, 0.5, 0.5, 1))  # Set to Grey

# Get and set constants
var hseparation = ThemeDB.get_constant("hseparation", "HBoxContainer")
ThemeDB.set_constant("hseparation", "HBoxContainer", 12)

The first example changes the font color for all Labels to grey, while the second modifies the horizontal separation in HBoxContainer.

Remember, any changes made with ThemeDB are project-wide. This ensures that your UI remains consistent and any modification or update to the theme is straightforward and efficient.Managing theme resources in your Godot game can be a breeze with the ThemeDB class. Let’s explore more advanced usage of this tool with some practical examples, so you can get a taste of its power and flexibility.

Advanced ThemeDB Examples

Adding New Themes
Adding new themes to your project is straightforward with ThemeDB. You can create a new theme resource and then set it globally:

var new_theme =

This snippet creates a new theme and then sets it as the default theme for the project using set_default_theme. Now, all UI elements will use this theme unless specified otherwise.

Retrieving and Modifying Scalability
Handling different display sizes and resolutions is critical, and ThemeDB helps you manage the scalability of your UI:

var default_scale = ThemeDB.get_default_font("Label").outline_size
default_scale = 2.0  # Doubles the outline size for better visibility
ThemeDB.get_default_font("Label").outline_size = default_scale

In the code, we’re adjusting the outline size of the default font for labels to make it more visible on various display sizes.

Streamlining Theme Asset Management
If you’re working with a lot of icons and other assets, ThemeDB can help keep things organized. Use its methods to streamline asset management:

# Load an icon texture
var icon_texture = preload("res://path_to_icon.png")

# Set the icon for all CheckButtons
ThemeDB.set_icon("checked", "CheckButton", icon_texture)

This example shows how to preload an icon texture and set it for all CheckButton instances in your game, ensuring they all display the same checked state icon.

Customizing Specific UI Elements
Sometimes, you might need to change the theme for a specific UI element rather than globally. This can also be done using ThemeDB:

var button_theme = ThemeDB.get_theme_from_view("Button", button_instance)
button_theme.set_icon("icon_name", "Button", new_icon_texture)

Here, we retrieve the theme from a specific Button instance and change its icon. This won’t affect other buttons in the game.

Applying Styles to Specific States
It’s common to have different styles for various button states, like “pressed” or “hover”. ThemeDB can handle this as well:

var hover_stylebox =
hover_stylebox.bg_color = Color(1, 1, 0, 1)  # Yellow background for hover state
ThemeDB.set_stylebox("hover", "Button", hover_stylebox)

In this snippet, we’re creating a new StyleBox specifically for the hover state of buttons and giving it a yellow background color.

Adjusting Theme Constants Globally
Constants in Godot themes can represent values like margins or spacing, which you might need to tweak for your entire game. This can be done easily using ThemeDB:

ThemeDB.set_constant("vseparation", "VBoxContainer", 20)

By executing this line of code, you’re setting the vertical separation in all VBoxContainer nodes to 20 pixels.

Creating a Responsive UI
A responsive UI is pivotal in game development. Use ThemeDB to adjust your styles based on the game’s environment:

if OS.window_size.x > 1920:  # Assume 4K
    ThemeDB.set_default_font_size(24)  # Set larger font size for 4K resolution
    ThemeDB.set_default_font_size(14)  # Set smaller font size otherwise

This conditional statement changes the default font size based on the window size, which can help create a UI that is adaptive and looks good on multiple screen resolutions.

Using ThemeDB effectively means your UI will not only be more cohesive and flexible but you’ll save a tremendous amount of time when making project-wide style changes. By leveraging the power of ThemeDB, we, at Zenva, encourage you to create games with interfaces that are as polished and engaging as the gameplay itself.ThemeDB can do much more than handle the basics. By now, you might have a good grip on how to control and modify the visuals of your game’s UI effortlessly on a global scale. Let’s dive deeper into the rabbit hole and explore further what ThemeDB can accomplish with more creative and precise adjustments.

Dynamic Color Adjustments
Colors can dictate the mood and tone of your game’s UI. Here’s how you can add a dynamic touch to it:

// Define a function to adjust button text color based on the time of day
func update_button_text_color(is_daytime: bool):
    var color = is_daytime ? Color(0, 0, 0, 1) : Color(1, 1, 1, 1)  // Black for day, White for night
    ThemeDB.set_color("font_color", "Button", color)

// Call this function with a boolean value to change all button text colors
update_button_text_color(true) // Use false for nighttime

In this example, we define a function that changes all Button text colors based on whether it’s daytime or nighttime in your game.

Icons for Different Game States
Highlighting different game states with icons can vastly improve user experience. Below is a strategy to swap icons based on game status:

func update_health_icon(player_health: int):
    var icon_name = "heart_full"
    if player_health < 20:
        icon_name = "heart_empty"
    var health_icon = preload("res://icons/" + icon_name + ".png")
    ThemeDB.set_icon("icon", "HealthBar", health_icon)

// Update the health icon based on the player's health value
update_health_icon(  // Assuming is an existing variable

This snippet dynamically changes the HealthBar icon depending on the player’s health.

Switching Themes for Different Levels or Contexts
Sometimes, different parts of your game may require completely distinct themes. Here’s how you can switch them on the fly:

# Assuming 'desert_theme_res' and 'arctic_theme_res' are paths to .tres files
var desert_theme = preload(desert_theme_res)
var arctic_theme = preload(arctic_theme_res)

func set_level_theme(level_type: String):
    match level_type:

// Call this when switching levels
set_level_theme(current_level.type)  // Assuming 'current_level.type' is a String that has the level type

This code shows a function that switches the entire game theme based on the current level type.

Customizing Tooltips
Having informative tooltips is a great way to enhance gameplay. Make sure they look the part with ThemeDB:

// Customize tooltip style
var tooltip_stylebox =
tooltip_stylebox.bg_color = Color(0, 0, 0, 0.8)
tooltip_stylebox.border_color = Color(1, 1, 0, 1)
ThemeDB.set_stylebox("panel", "TooltipPanel", tooltip_stylebox)

// Set the font for the tooltips
var tooltip_font =
tooltip_font.size = 14
ThemeDB.set_font("font", "TooltipLabel", tooltip_font)

Here, we tailor the style and font of tooltips to fit the theme of the game while making sure they are clearly readable.

Implementing these advanced techniques with ThemeDB will not only result in a more visually consistent and engaging game but also show the level of detail and care put into its development. Remember, with ThemeDB, your creativity is your only limit when it comes to styling your game’s UI!

Continuing Your Godot Journey

Embarking on a journey of learning game development with Godot 4 is an adventure that pays off in the ability to bring creative ideas to life. After getting familiar with ThemeDB and the exciting ways you can customize your game’s UI, it’s natural to wonder, “Where to go next?”

We, at Zenva Academy, invite you to further your learning with our Godot Game Development Mini-Degree. This comprehensive collection of courses is tailored to guide you through the art of creating cross-platform games using the powerful yet easy-to-grasp tools provided by Godot 4.

Whether you’re just starting out or looking to level up your existing skills, our courses cover a spectrum of topics, from fundamental principles to advanced techniques in both 2D and 3D game development. Learn at your own pace, reinforce knowledge with practical exercises, and build a portfolio that showcases your prowess in game creation.

And if you’re keen on exploring an even broader array of Godot courses, visit our extensive Godot course category. With our hands-on approach to teaching, you can go from beginner to professional in no time. Keep learning, keep creating, and turn those game ideas into reality with Zenva!


It’s thrilling to uncover the intricacies of game development and particularly rewarding to give life to your own unique user interfaces with Godot 4’s ThemeDB. With the capabilities and techniques we’ve explored, you are now equipped with the knowledge to create truly immersive and visually consistent experiences for your players.

Remember, every great game stands out with its attention to detail and its user experience, so we encourage you to refine your skills with ThemeDB and take advantage of all the possibilities it offers. Dive deeper into the world of Godot with our Godot Game Development Mini-Degree and carry on forging the path to becoming a masterful game developer. The journey doesn’t end here – it’s just another level completed in the grand game of learning. Happy coding!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.