We've implemented the UI part of the new API, so we can finally share more information about it. Please let us know if you're interested in a preview version of the API (specifically for the UI).
If you have any questions or feedback, don't hesitate to post here
The new version internally uses Unitys new UI Toolkit (formerly known as "UI Elements"), which is inspired by CSS. This means the new API no longer maintains a UI based on absolute and relative coordinates, instead they will use a flex layout. You can update the Style of a UI element directly - it determines the visual appearance and position of the element and is mostly based on Unitys IStyle class. However, you can still work with absolute and relative coordinates if you like.
The new API has two workflows, and both can be combined. The main workflow is the Style-based workflow, while all UIElements also offer some simplified helper methods (like setPosition(), setSize(), setPivot() etc). The latter resembles the old GUI workflow, but internally these methods just update the underlying style.
When using absolute coordinates, the reference resolution is always FullHD (1920x1080). The positions will be identical on other 16:9 resolutions, so if you place an element at the center using absolute coordinates (X: 960 Y: 560), it will be also centered on 1280x720 or 3840x2160 (4K) (and other 16:9 resolutions). The size will also be identical on all screens, i.e. if the element has an absolute width and height of 128 pixels, the game will resize the element on other resolutions as well.
The initial API release will provide at least a base UIElement class, a UILabel and a UITextField.
UIElement is the base class for all UI elements (similar to the old GuiElement class). You can use it as a container or panel. You can also add a background image to them, so they automatically replace the old "GuiImage" class. In other words, the UIElement class is now a combination of the old GuiElement, GuiPanel and GuiImage classes. UILabel is very much like the old GuiLabel class, while UITextField is very much like the old GuiTextField class.
Note: When using the simplified workflow methods, the origin of the screen (0, 0) will be in the top left corner (unlike the Java version, where the screen origin was in the lower left corner). When working with the style, however, that doesn't matter, because you set the top, left, right and bottom distance on the style directly.
When using relative values (percent values), the game now uses values between 0-100 instead of 0-1. So if you were using 0.5 in the Java version, this now becomes 50.
Style and HoverStyle
In addition to the regular style, all UI elements also have an additional, optional hoverStyle field: It determines the style of the element when it gets hovered with the mouse cursor. This way you could change properties like the color, size etc (e.g. when hovering the element, the color may change to blue or the font size of of the label may become bigger to achieve a hover effect).
The game handles this automatically under the hood, so when the mouse enters the element, it automatically sets the hoverStyle, and when the mouse leaves the element, it automatically sets the original style.
The hoverStyle is only used if the element is marked as "clickable" (so the element reacts to the mouse and mouse input). This is done through the setClickable() method (similar to how it worked in the Java version). In addition to the "clickable" flag, there is also a "pickable" flag: It determines if an element should "block" mouse clicks (irrespective of the clickable flag). If "picakble" is set to false, the mouse cursor will ignore the element, so you could click on another element which is behind the panel. If set to true, the panel will block the mouse input, so you couldn't click on elements behind it.
Childs and Parents
The new UI also supports childs and parents, like the old GuiElements. You can attach a UIElement to any other UIElement (which then becomes the new parent). The style (position, size etc) of a child then depends on the parent style. Childs also inherit certain style properties (like the font size) - unless they explicitly set them on their style. Moving a parent moves all childs automatically.
Unlike the Java version, you no longer have to call Player.addUIElement() for all childs - you only have to call it for the parent now, and the game handles all childs (and childs of childs) automatically.
Modify Game UI
The Internals class will provide a way to modify the Style of any game UI element. E.g. change the color of the health bar or the background color or image of any game menus. However, you have to use this with caution.
The new UI will also provide a simple way to show message boxes to the player. The Player class will provide various showMessageBox() methods for this, where you could provide a callback to get the user selection. There are also similar methods to bring up a color picker or an input dialog, for example.
This is a basic example which creates a black panel centered on the screen with a size of 500x300 pixels containing a centered label. It uses the simplified workflow, which resembles UI creation in the Java version:
With the new UI, we have a lot more control over our UI elements. We could have round edges on our panels, for example, or rotate elements. The next example uses almost the same code as above, but modifies some style properties (to have rounded upper left corner on the panel and also to rotate the label by 90 degree):
The next example uses the new flex layout: We want 10 panels to be evenly positioned around the center. We first create an invisible container (we call it "screen") which covers the whole screen. We set "pickable" to false, so it does not block our mouse clicks. We set absolute coordinates, and set top, left, right and bottom to 0 (in other words: the distance to the top, left, right and bottom will be 0 px, so the element covers the whole screen).
We set the alignItems property to "Center" (because we want our child elements to be centered), justifyContent will be set to "SpaceAround" (so the elements will be evenly positioned in the panel) and flexDirection will be set to "Row" (so they're aligned vertically instead of horizontally).
For the child elements, there is not much we have to change: We set the width and height to 128 pixels, set a random background color (using a util method) and add them as childs to the "screen" parent. That's it!
We're thinking about providing a plugin which brings back the old GuiElements from the Java version. They will be based on UIElements. This is mostly for reasons of compatibility (so if you have a big complex UI, you don't have to recreate it from scratch). Please let us know if this is important for you.