This plugin provides a few functions to add/remove text into/from the screen using the Label Control widget. Those are added into a panel that expands/shrinks according to the contents. This panel is, by default, black with some transparency set just so text is more easily readable. This color (and transparency) can be changed.
By default, the release build of this plugin makes all functions empty. This means that those functions can be called but will do nothing in the exported project. This can be useful to keep debugging code in place while making sure none of it will appear in the release builds. Note that custom builds of the extension pack can still change this behavior if so desired.
I found myself constantly creating temporary Label controls to display some rapidly changing values, specially to debug networking code. To make things easier this plugin deals with the creation of such widgets.
The functionality is accessed through its single class, OverlayInfo, which is provided as a singleton.
Visibility of the panel can be controlled by several ways. To hide it, call hide(). To show it again, call show(). Alternatively, call set_visible(visible) or even directly access its visible property. And there is even a toggle_visibility(). Like so:
# Show the label panel
OverlayInfo.show()
# Hide it
OverlayInfo.hide()
# Make it visible again
OverlayInfo.set_visible(true)
# Hiding it again
OverlayInfo.visible = false
# Since it's currently hidden, this will make it visible again
OverlayInfo.toggle_visibility()
To add a label into the panel, there is the set_label() function, which requires two arguments. The first one is an identification for the label to be created. The second is the text to be assigned. Suppose we want to display the position of a character. We can then call this every time the position is changed:
OverlayInfo.set_label("character_position", character.get_position())
In this example the label is identified by the character_position. This is important in order to properly update the label if so desired. But then, what if we want to remove this label? There is the remove_label() function, which requires the identification used in the set_label() function. So, to remove the character position:
OverlayInfo.remove_label("character_position")
There is another way to add labels to screen, using add_timed_label(). This functions adds the provided text to the panel and auto removes it after the specified amount of seconds. Suppose we have a "plant object" that holds a grow_stage property which isn't updated too frequently. We then want to display this value for 2 seconds:
OverlayInfo.add_timed_label("Grow Stage: %s" % plant.grow_stage, 2.0)
All non timed labels can be removed at once by calling clear_labels():
OverlayInfo.clear_labels()
It's also possible to easily anchor the panel to any of the window sides:
# Place the panel on the left side of the window
OverlayInfo.set_horizontal_align_left()
# Place the panel on the center (horizontally) of the window
OverlayInfo.set_horizontal_align_center()
# Place the panel on the right side of the window
OverlayInfo.set_horizontal_align_right()
# Place the panel on the top section of the window
OverlayInfo.set_vertical_align_top()
# Place the panel on the center (vertically) of the window
OverlayInfo.set_vertical_align_center()
# Place the panel on the bottom section of the window
OverlayInfo.set_vertical_align_bottom()
So, suppose we want the panel on the bottom right corner of the window. We can then call the following two functions in sequence:
OverlayInfo.set_horizontal_align_right()
OverlayInfo.set_vertical_align_bottom()
It's possible to change the styling of the panel and labels. There are actually two ways to achieve this. Both are based on the creation of a Theme resource and properly styling both the Label and PanelContainer controls.
Theme resource in your Project Settings. When this is done, the entire project will use that theme, including the Controls created by the OverlayInfo.OverlayInfo contains a theme property. Assigning to it will affect only the controls handled by the OverlayInfo.When you use (1) the only thing to keep in mind is that OverlayInfo will look exactly like any other PanelContainer/Label that you might use in your game's UI. If you want the appearance to be different then you might prefer to use (2), ideally with a dedicated theme resource.
It's possible to automatically hide the panel when all labels are removed from it. This can be done by enabling the auto_hide setting in the Project Settings -> Keh Extension Pack -> Overlay Info.
It's also possible to automatically show the panel when a label is added into the panel. This can be done by enabling the auto_show setting in the Project Settings -> Keh Extension Pack -> Overlay Info.
You query if there is at least one label in the panel by calling OverlayInfo.has_any_label().
This plugin uses internal processing to deal with timed labels. If you are not new to Godot then you know tha it offers _process() and _physics_process() to perform processing. If you are new, I have written about it here . Nevertheless, this plugins allows you to choose which processing will be used to deal with the timed labels. To do that, open Project Settings -> Keh Extension Pack -> Overlay Info. There is a single boolean in there, named Use Physics Process. If it's checked it will "tell" the plugin to use physics iterations to update the timed labels. By default that will be done using the "idle frame" (or, in other words, this options is not checked).
As I have mentioned in the introduction of this plugin, by default the release build makes the OverlayInfo empty. Explicitly setting its visibility to true will do nothing because the functions contain no code in such case. Yet, if you decide to use a custom build of the extension pack where this debugging class is not empty in release builds, you still can hide the panel, sort of "disabling" its functionality through code. This might be useful to track errors that appear only in release builds.