Skip to main content

Godot Extension

The godot extension is the easiest-to-use version of WUI. Both windows and linux versions of the extensions can be downloaded from the release page or directly from static.zweieuro.at.

There should be no functional difference between the two platforms, if you encounter any issues please report them.

This is a short Video showing the godot extension with both debuggers active for in game and editor debugging at the same time.

Installation​

Godot asset store:​

At the moment the asset store of godot is not used. This is because the extension is comparatively quite large (packed 120MB, unpacked ~200MB) as a godot extension. That means I can't just throw it onto a repo on github. Hopefully the extension will be available in the asset store soon, there is an issue for it.

Manual installation​

Step by step manual installation:

  • You can download the most up-to-date version from the release page.
  • Inside the archive you will find a 'Release' or 'Debug' folder
  • put libwui_godot.<OS>... into the res://addons/ folder of your godot project

The complete file-tree should look like this:

Linux:

├── addons
│   └── wui_godot
│       ├── libwui_godot.gdextension
│       ├── libwui_godot.*.release.so   # main godot extension
│       └── wui_resources/              # folder
├── project.godot
├── ...

Windows:

├── addons
│   └── wui_godot
│       ├── libwui_godot.gdextension
│       ├── libwui_godot.*.release.dll   # main godot extension
│       └── ... many other dlls
├── project.godot
├── ...

The exact name of the extension may be different depending on how many release versions for what system are available.

That's it. Should you want to uninstall the extension, simply remove the addons folder. The installed extension should auto-detect upon the next start of the godot editor.

Alternatively: The vivaci/bouncing objects godot projects have a helper script that will download and extract the extension for you, it can be found here

WuiTab​

The extension adds a new Element WuiTab as a node Internally this is a thin wrapper around the Control node in godot with rendering forwarded from WUIs Tab Wrapper Class and input forwarding from godot to WUI.

Screenshot from the editor with the WuiTab selected in the Vivaci Godot project.

Properties​

There is only one property that is exposed to the editor:

  • InitialPath: String is the initial path that is loaded into the tab. It may point anywhere, but it is recommended to point to a local file (e.g. res://index.html) or a local server (e.g. localhost:3000). Changing this in the editor will reload the page immediately. res:// or user:// are resolved automatically relative to the project root and may lead outside of the project folder.

All other systems are handled by the godot control node or internally forwarded.

Behavior​

In the Editor the tab will show the current page that initialPath but events/signals are not fired during editing mode (this is due to how signals are handled in godot). Click and input events are not processed in this mode (which doesn't make sense in the editor).

In the game the tab will show the current page that initialPath and will fire signals when events are received from the UI. Where the tab itself navigates is up to implementation.

Any mouse events are forwarded to WUI. The UI will only accept these events (meaning no other component inside godot will receive them) if and only if a pixel was clicked that is not fully transparent. Anything else is considered the 'background'.

Any keyboard input that is received during the game is forwarded to the UI if and only if the UI is in a 'focused' mode.

  • Relevant line of gode in the extension is here.
  • Focus of ui elements :focus and focus() There are several ways to get a focus on an element, it is up to the developer to implement this.

Signals​

The component provides signals:

  • event_received(eventName: String, eventPayload: Dictionary) which is emitted when an event is received from the UI
  • load_end(currentUrl; String, httpCode: int, error: Dictionary) which is emitted when the page has finished loading (either sccessfully (code = 200) or with an error (code != 200) in form of some error).
godot default behavior

When attaching a new script to a component, godot overwrites _ready function. Doing this will stop the component from initializing properly.

Project Settings​

The extension exposes a few settings inside godot for easier use, they can be found the the very bottom inside godot Project > Project Settings under WUI.

WUI:

  • Project:
    • Devtools Mode: Enable or disable the devloper tools during runtime.
    • Remote debugging port: The port that the UI will listen on for debugging
  • editor:
    • Devtools Mode: Enable or disable the devloper tools during editor mode.
    • Remote debugging port: The port that the UI will listen on for debugging
  • General:
    • locale: the locale that WUI and its internal browser will use for formatting (e.g. dates, numbers, etc.) default: en-US
    • Cache Directory Path: Keeping this empty will assign a new directory in your OSs temp directory, note: see warning. default: empty string
    • Wui Resource path: You can detach WUI from its resource folder, here you can write down wherever you put it. Note: the extension needs to find at least libwui by itself. By default the library searches in its own directory and wui_resources. Should you require a more specific setup you can compile the extension yourself and change RPATH in the CMakeLists.txt file.
Sensitive information

The setting Cache Directory Path is used as the browsers cache directory. This means that any information stored in the cache will be stored in this directory. This can include sensitive information like cookies, local storage, etc. It is recommended to keep this directory clean and secure. The directory is not automatically cleaned up by WUI.

It is assumed that whatever you are doing is:

  1. not sensitive
  2. you are aware of the implications of storing data in the cache directory.

If you plan on logging your user in it is recommended to do so in one go and ensure the cache is cleared afterwards.

Debugging UI​

Debugging works the same as the core library. You can point to the ports mentioned in the settings above and open the debug page in your browser.

note

If you run the game via the editor you will see two pages of your UI since WUI will be running twice. This is normal and expected behavior if both debug modes are enabled.