itch.io

In my experience Godot's UI system can be both extremely powerful but at times also extremely frustrating--especially when starting out. The primary reasons for the frustrating part are:

• The system relies on multiple concepts working together & it's not always obvious (conceptually) how they impact each other.
• The UI doesn't always provide an intuitive way to configure the various aspects. (e.g. flags that are mutually exclusive in effect but can still be enabled at the same time in the UI.)
• Some UI controls (especially less commonly used ones) can be quite buggy.

Suggested starting UI Node layout

My recommendation for a starting point is to create your UI with the following node setup:

• `MarginContainer` (Use the "Layout" button on the toolbar below the scene tabs to select "Full Rect". Set the margin sizes with the properties under the "Custom Constants" section *not* the, err, "Margin" section. Leave the "Size Flags" for both "Horizontal" & "Vertical" on "Fill".)
  • `VBoxContainer` (Leave the "Size Flags" for both "Horizontal" & "Vertical" on "Fill".)
    • `VBoxContainer` (Leave the "Size Flags" for both "Horizontal" & "Vertical" on "Fill". Have one of these per "vertical sub-section" (i.e. a subsection that spans the entire width of the screen) of UI, so you might want to have a "header" & "footer", so you'll want two `VBoxContainer` nodes at this level.)
      • `HBoxContainer` is probably what you want at this level which allows you to place controls next to each other horizontally.
        • Your `Button`s, `Label`s, `LineEdit`s etc controls go at this level.
      • (Maybe) `HBoxContainer` etc.
    • `VBoxContainer` (This would be for the "footer" part of the UI.)
      • `HBoxContainer` etc etc
    • (etc)

Let's say you then wanted the "footer" section to really stretch all the way from the "natural height" (my term) of the components, all the way to the bottom of the window, in this case you would change the "Size Flags" as follows:

• "Size Flag" > "Vertical"
  • (Keep enabled) "Fill"
  • (Newly enable) "Expand" (this "theoretically" stretches the area of the "footer" `VBoxContainer` to the bottom of the screen *but* this is only visible if "Fill" flag is *also* enabled. But read on...)

But what you *probably*/may want is for the UI controls in the footer to *also* be at the bottom of the screen--not just the enclosing container. In which case, you want:

• "Size Flag" > "Vertical"
  • (Newly disabled) "Fill"
  • (Newly enable) "Expand"
  • (Newly enable) "Shrink End" (Or "Shrink Center" if you want it vertically centered.)

So, essentially, "Fill" on its own sort of means "Shrink Beginning".

But, it's essential to realise that "Expand" can only expand if its parent container (in this case the `VBoxContainer` immediate under the `MarginContainer`) has extra space for the child to expand into--so that means e.g. "Fill" is also set on it and its parent also has space to expand into (which the `MarginContainer` does because we forced its anchors to be at the four extreme corners of the screen.

Yeah, it gets confusing and text isn't the greatest way to communicate these nuances. :) (And I may not have this 100%. :D )

My recommendation for getting an understanding of this would be to start with just the `MarginContainer` and its child `VBoxContainer` and play with the "Size Flags" one at a time to try to understand what effect each one has.

Other UI Control aspects to consider

The "Stretch Ratio" enables you to have split an area into a different ratio for e.g. two controls. By default when "Expand" is enabled two controls will split the area available in two (i.e. half each a.k.a 50% each a.k.a. a ratio of 1:1) and three controls will split into thirds etc. But if you want one control to be "greedy" then set its "Stretch Ratio" to say, 3 or 4 or 10 to force the other control(s) to take up less room.

Most Containers manage their size in such a way that you don't have to think about it too much. But in certain situations, with certain Containers, you might find that a particular Container gets "squashed" and its child controls become invisible. In this case you may need to provide a value for "Min Size" in the "Rect" section.

Grid-like Containers

In my experience, if you want a "grid" of UI controls, at first it is best to:

• Avoid the `GridContainer` control.
• Avoid the `ItemList` control.
• Avoid the `Tree` control.
• And, if you must, try something like a `VBoxContainer` containing `HBoxContainer`s.

Yeah, it's not very satisfactory... :/

So, if you must, still skip `GridContainer` & `ItemList` and go directly to `Tree` control but if you want to use keyboard for movement, be aware it is very very very broken! (Which brings with it major accessibility issues.)

Thus I recommend looking at the code in this related Godot Tree control issue comment and consider adapting the workaround for your own code and/or read the overview of issues discussed in the issue.

Conclusion

Despite the frustration I've experienced with Godot's UI controls/containers along the way, I do think Godot's UI system is powerful vs (theoretical) effort required and has the potential to be a very compelling part of Godot--but one which currently has a lot of unnecessary confusion occurring while learning it due to UI/UX, bug & documentation issues.

I recommend you stick with `MarginContainer`, `VBoxContainer` & `HBoxContainer`, the standard UI controls like `Button` & `Label` and take a bit of time to understand the effect of the different "Size Flags" (and you generally want to set them for the parent container first & work down the node tree) and you'll hopefully get it working enough for your purpose of a 2-day jam game. :)

Hope this helps you on your journey!