PopupPanel in Godot – Complete Guide

Welcome to the world of Godot 4, an open-source game engine that’s winning hearts with its versatility and ease of use! Today, we’re diving into the PopupPanel class—a nifty little tool that can add a professional touch to your game’s user interface. Think of a pause menu that pops up in the middle of the action, a settings control that slides into view, or an in-game notification system. All of these could leverage the PopupPanel to create engaging player experiences. So whether you’re a budding game developer or a seasoned pro looking for a refresher, this tutorial is for you.

What is PopupPanel?

PopupPanel is a class in Godot 4 that derives its functionality from a rich lineage of classes: Popup, Window, Viewport, Node, and Object. It’s essentially a special type of popup that is backed by a panel. This panel acts as a canvas for any child controls you might add, automatically scaling them to fit within its bounds. It’s like a versatile container that keeps all your UI elements snug and responsive.

What is it for?

PopupPanel is for developers who need a quick and effective way to implement popups with a configurable background. Unlike basic popups, PopupPanel gives you the added advantage of theming through its StyleBox property, allowing for a greater degree of customization. This is particularly handy when you’re striving for a consistent aesthetic throughout your game’s UI.

Why Should I Learn It?

Understanding PopupPanel opens doors to a broad array of UI design possibilities within Godot 4.

– With it, you can create menus, dialogs, and hideable UI components that don’t interfere with the game’s main action.
– It’s integral to creating a user experience that feels polished and professional.
– Learning to use this class will equip you with the skills to manage in-game storytelling, player feedback, and interactive elements seamlessly.

Plus, mastering PopupPanel can be your stepping stone to a broader understanding of Godot’s UI system—a critical part of game development. Let’s jump into how to use this powerful UI tool with some hands-on examples!

CTA Small Image

Creating a Basic PopupPanel

The first step to harness the power of PopupPanel is to create a simple one. Let’s start by adding a PopupPanel to the scene and showing it on screen.

var popup_panel = PopupPanel.new()
popup_panel.popup_centered(Vector2(200, 200))  # Sets the size of the popup

This piece of code creates a new PopupPanel, adds it as a child to the current node, and then displays it centered with a size of 200×200 pixels.

Customizing with StyleBoxes

A basic popup might feel a little bland. That’s where StyleBoxes come in to give your PopupPanel some visual flair. Let’s add a StyleBox to our PopupPanel to change its background.

var style_box = StyleBoxFlat.new()
style_box.set_bg_color(Color(0.2, 0.25, 0.3))  # Set a nice dark background color
popup_panel.add_stylebox_override("panel", style_box)

Here we’ve created a new StyleBoxFlat, set its background color to a dark shade, and then applied it to our popup panel. This will override the default look with our new styling.

Adding Interactive Elements

Interactivity is key in game UI. Let’s add a button to our PopupPanel that closes it when clicked.

var button = Button.new()
button.text = "Close"
button.connect("pressed", popup_panel, "hide")
button.rect_min_size = Vector2(100, 40)  # Gives the button a minimum size

This script creates a new Button, sets its text to “Close”, connects its “pressed” signal to the panel’s “hide” function (which will close the panel when the button is pressed), then adds it as a child to the PopupPanel.

Positioning Elements Inside PopupPanel

To keep UI elements well-organized within your PopupPanel, you should position them correctly. Here is how you can place that Close button at the bottom of the panel.

button.anchor_bottom = 1.0
button.margin_bottom = -20  # Pushes the button 20 pixels up from the bottom margin

Setting the button’s anchor_bottom to 1.0 ensures that it’s aligned to the bottom of the PopupPanel. The negative margin_bottom then moves it up from the absolute bottom by 20 pixels, ensuring it’s not flush with the edge.

Stick with us as we dive deeper into the wonders of PopupPanel in Godot 4 in the next part of our tutorial. As we go, remember that each snippet is a building block to creating a rich user interface that can make your game stand out in a crowded marketplace.Great! Now that we’ve added a basic interactive element to our PopupPanel, we’ll delve into more advanced features and customization options that can really make your UI pop.

Let’s add some flair to the PopupPanel by including a title bar to indicate what the panel is for. We’ll create a Label node for this purpose and place it at the top of the PopupPanel.

var title_label = Label.new()
title_label.text = "Options"
title_label.anchor_top = 0.0
title_label.margin_top = 20  # Gives a top margin to push it down from the very top

Here, our title “Options” will appear at the top center of the PopupPanel, giving users a clear indication of the panel’s purpose.

Now, suppose we want to include a variety of settings in our PopupPanel, such as volume control. We can use HSlider nodes for a user-friendly experience.

var volume_slider = HSlider.new()
volume_slider.anchor_left = 0.5
volume_slider.anchor_top = 0.3
volume_slider.margin_top = 5  # Small margin to separate it from elements above
volume_slider.rect_min_size = Vector2(150, 20)  # Sets a minimum size for the slider

We’ve now provided the user a way to control the volume, centering it horizontally in the panel and placing it a bit below the title.

Maybe we want to allow our players to toggle fullscreen mode. We can add a CheckBox to change the game’s display settings.

var fullscreen_toggle = CheckBox.new()
fullscreen_toggle.text = "Fullscreen"
fullscreen_toggle.anchor_left = 0.5
fullscreen_toggle.anchor_top = 0.4
fullscreen_toggle.rect_min_size = Vector2(150, 20)  # Ensures the CheckBox is properly sized

Now, the player has a CheckBox to toggle fullscreen mode. Place it below the volume slider for an orderly appearance.

For our final touch, let’s add a way for users to save their settings with a Save Button at the bottom of the PopupPanel.

var save_button = Button.new()
save_button.text = "Save Settings"
save_button.anchor_bottom= 1.0
save_button.margin_bottom = -50  # Pushes the button up from the bottom
save_button.rect_min_size = Vector2(150, 40)  # Gives the button a clear, clickable size
save_button.connect("pressed", self, "_on_SaveButton_pressed")  # Make sure to define this function!

With this Save Button, players can commit their settings, and it’s placed conveniently at the bottom of the panel.

As you can see, the PopupPanel class in Godot Engine allows for a great deal of flexibility. You can create a user interface that not only looks good but also enhances the player’s experience. Use PopupPanel to create any type of popup you need, from quick notifications to complex settings menus. Customize them with various controls and stylize them to match your game’s theme, offering a cohesive and engaging user experience.

When designing your UI, remember to place your interactive elements strategically and ensure that they’re user-friendly—this helps to keep your players immersed in the game without pulling their focus away unnecessarily.

In our next section, we will see how we can integrate our PopupPanel to react to in-game events and actions. Stay tuned to take your UI skills to even greater heights!Moving forward, let’s integrate our PopupPanel into the game environment to make it react dynamically to in-game events. Imagine a situation where your game needs to pause and present the PopupPanel when the player presses the ‘Escape’ key. Here’s how we can set this up:

To detect the ‘Escape’ key press, we need to overwrite the `_input()` function in our main game node:

func _input(event):
    if event is InputEventKey and event.pressed and event.scancode == KEY_ESCAPE:
        popup_panel.popup_centered(Vector2(300, 400))  # Adjust the size as needed
        get_tree().paused = true  # Pause the game

When the player presses the ‘Escape’ key, the PopupPanel will appear, and the game will pause. To unpause the game when the PopupPanel is hidden, we can connect to the ‘about_to_hide’ signal:

popup_panel.connect("about_to_hide", self, "_on_PopupPanel_hide")

func _on_PopupPanel_hide():
    get_tree().paused = false  # Unpause the game

Next, we should ensure that our settings like volume control and fullscreen toggle have an effect. To make the volume slider work, we can connect to its ‘value_changed’ signal and adjust the game’s volume accordingly:

volume_slider.connect("value_changed", self, "_on_VolumeSlider_value_changed")

func _on_VolumeSlider_value_changed(value):
    AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), value)

For the fullscreen toggle, we would want to change the window’s fullscreen mode whenever the CheckBox is toggled:

fullscreen_toggle.connect("toggled", self, "_on_FullscreenToggle_toggled")

func _on_FullscreenToggle_toggled(button_pressed):
    OS.window_fullscreen = button_pressed

Lastly, you may want the settings to be saved even after the game closes. For that, we can write the current settings to a file when the ‘Save’ button is clicked:

func _on_SaveButton_pressed():
    var settings = File.new()
    settings.open("user://settings.cfg", File.WRITE)
    settings.store_line("fullscreen=" + String(OS.window_fullscreen))
    settings.store_line("volume=" + String(AudioServer.get_bus_volume_db(AudioServer.get_bus_index("Master"))))

Remember, handling user settings and preferences requires attention to detail, input validation, and sometimes a bit of creativity. Always keep in mind the player’s comfort and ease of use when designing these systems.

As you practice with the PopupPanel, keep experimenting with different controls and their properties to find the perfect setup for your game. As you do so, you’ll not only make your game’s UI more engaging but also enhance the overall gameplay experience. Now is the time to innovate, code, and create the game interfaces of your dreams with Godot 4—a tool that bestows upon you both the canvas and the paints to bring your visions to life.

Continuing Your Game Development Journey with Godot

Embarking on your game development journey can be as thrilling as the games you’re dreaming of creating. If you’re ready to level up from understanding the basics of PopupPanel in Godot 4 to building full-featured games, then it’s time to expand your horizons. At Zenva, we offer the Godot Game Development Mini-Degree where you can turn that enthusiasm into tangible skills.

This comprehensive series of courses will guide you through creating cross-platform games using Godot 4. Covering everything from 2D and 3D development to animation and advanced scripting, these courses are fit for both green novices and seasoned developers alike. You’ll emerge with a robust portfolio of projects that showcase your ability to harness Godot’s potential.

Interested in broadening the scope of your learning further? Take a peek at our wide range of Godot courses to find topics that pique your curiosity and meet your learning goals. Whether you’re looking to sharpen your existing skills or delve into new areas of the Godot Engine, Zenva has a course for you. From bite-sized tutorials to in-depth training, let us be a part of your journey to becoming a skilled game developer with the power of Godot.


As you’ve seen, the PopupPanel in Godot 4 offers a flexible and powerful way to add professional-looking UI elements to your games. Whether you’re creating a pause menu, an options panel, or an in-game notification system, the skills you’ve learned here will elevate your games to new heights of interactivity. But remember, this is just one piece of the vast world of game development with Godot.

Are you eager to transform your creative visions into playable realities? We invite you to join our Godot Game Development Mini-Degree, where we’ll take you step-by-step through the entire game development process. Let’s craft amazing experiences together with Godot, your free and open canvas for game creation. At Zenva, we can’t wait to see the incredible games you’ll build!

Python Blog Image

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