> For the complete documentation index, see [llms.txt](https://docs.otherside.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otherside.xyz/odk-docs/odk-plugin/odk-widget/odk-base-ui.md).

# ODK Base UI

**ODK Base UI** is a flexible UI framework designed for building reusable and dynamic widget controls. It simplifies logic binding, value syncing, and visibility control by pairing each control with an **Executor**.

Controls are placed into UI layouts like any other widgets, but their functionality is entirely **data-driven** via executors.

This keeps consistency thoughout the Otherside platform, allowing for devs to reuse existing designed controls.

***

### 🔁 How It Works

Each control can be paired with:

* A **Value Executor** (handles functionality and state)
* An optional **Visibility Executor** (handles when to show/hide the control)
* An optional **Registered Control Name** (for simple runtime access via the UI system)

<figure><img src="/files/eDa6RJdE0IeMUhSkZEeB" alt=""><figcaption></figcaption></figure>

***

#### 🎮 Control Executors

The Executor is a Blueprint class that drives the behaviour of a control. Every executor supports the following functions:

| Function                | Description                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`Initialise`**        | Called on setup. Used for binding events or caching references, much like the Begin Play event.                                                                           |
| **`GetCurrentValue`**   | Returns the control’s current state (e.g. current volume or mouse sensitivity).                                                                                           |
| **`HandleValueUpdate`** | Called when the user changes the control through the UI. Developers should implement functionality here (e.g. setting the mouse sensitivity to the current slider value). |

This system makes each control **self-contained** and keeps your UI logic clean and reusable.

***

#### 👁️ Visibility Executors (Optional)

A Visibility Executor is a separate class that defines when a control should be visible.

It implements:

* **`GetVisibility`** → Returns a visibility state (`Visible`, `Collapsed`, etc.)

Use cases include:

* Hiding the **player roles dropdown** unless the user is an admin
* Only showing Gamepad settings when a controller is connected.

***

#### 🏷️ Registered Control Name

Every control has an optional **`RegisteredControlName`**.

This name:

* Registers the control with the `BP_WorldService_ODKUI`
* Allows it to be found or replaced dynamically at runtime (See function library below)

***

### 🧰 Runtime Editing

The Blueprint Function Library `BPFL_ODKBaseUI` gives you helpers for modifying UI areas at runtime.

Notable functions:

| Function                               | Purpose                                                                                      |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| `ODKBaseUI_GetRegisteredAreaByName`    | Find a control or UI area by searching for the Registered Name                               |
| `ODKBaseUI_ReplaceWidget`              | Replace a widget or control at runtime                                                       |
| `ODKBaseUI_ReplaceWidgetByClass`       | Find a widget that matches the supplied class and replace it with a newly contructed widget. |
| `ODKBaseUI_AddControlToRegisteredArea` | Finds an area by name and adds a newly constructed widget to it.                             |
| `ODKBaseUI_AddTabToNamedTabList`       | Add tabs dynamically to a tab group                                                          |

This system is especially useful in:

* Hot-swapping controls during a session
* Extending shared base widgets without making duplicates

***

## Examples

### 🧪 Example: Roles selector

* **Control Type**: Dropdown
* **Executor**: `BP_SettingsExecutor_PlayerRoles`
  * `GetCurrentValue` → returns a string array of available roles
  * `HandleValueUpdate` → sets the players new role
* **Visibility Executor**: `BP_ODK_UIControlVisibility_UserHasSpecificRole`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.otherside.xyz/odk-docs/odk-plugin/odk-widget/odk-base-ui.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.