> For the complete documentation index, see [llms.txt](https://pintux.gitbook.io/pintux-support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pintux.gitbook.io/pintux-support/getting-started/download-and-installation.md).

# Download & Installation

### Requirements

* **Server:** Paper 1.20.6 or newer, or a fork. Folia is supported.
* **Proxy (optional):** Velocity 4, or BungeeCord / Waterfall.
* **Floodgate:** required — it is how BedrockGUI knows who is a Bedrock player. [Download Floodgate](https://github.com/GeyserMC/Floodgate).
* **Java 21** or later on Paper and BungeeCord. Velocity 4 needs **Java 25**.
* **PlaceholderAPI** (optional): needed for other plugins' `%…%` placeholders. BedrockGUI's own `%bgui_…%` placeholders work without it.
* **Vault** (optional): needed for the `economy` action.
* **LuckPerms** (optional): permission checks work with any permission plugin; LuckPerms is simply the common choice.

### Where to download

| Source          | Link                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------- |
| GitHub Releases | [github.com/pintux98/BedrockGUI/releases](https://github.com/pintux98/BedrockGUI/releases/latest) |
| Modrinth        | [modrinth.com/plugin/bedrockgui](https://modrinth.com/plugin/bedrockgui)                          |
| SpigotMC        | [spigotmc.org/resources/bedrockgui.119592](https://www.spigotmc.org/resources/bedrockgui.119592/) |

Pick the JAR for your platform:

| Platform               | JAR                       |
| ---------------------- | ------------------------- |
| Paper / Folia          | `BedrockGUI-Paper.jar`    |
| Velocity               | `BedrockGUI-Velocity.jar` |
| BungeeCord / Waterfall | `BedrockGUI-Bungee.jar`   |

### Paper, Velocity or BungeeCord?

BedrockGUI runs on all three, but a proxy has no world, inventory or economy of its own, so not everything is available there. Pick the JAR by what your menus need.

| Feature                                                                                | Paper / Folia | Velocity | BungeeCord |
| -------------------------------------------------------------------------------------- | ------------- | -------- | ---------- |
| SIMPLE, MODAL and CUSTOM forms, button images, cooldowns, `open_condition`, `on_close` | Yes           | Yes      | Yes        |
| Form `command:`, guarded by the form's `permission:`                                   | Yes           | Yes      | Yes        |
| Console opens a form for a player (`shop Steve`)                                       | Yes           | Yes      | Yes        |
| `command_intercept:`                                                                   | Yes           | No       | No         |
| Conditions (`permission:`, `placeholder:`, `plugin:`)                                  | Yes           | Yes      | Yes        |
| Built-in `{player}` placeholders and `%bgui_…%`                                        | Yes           | Yes      | Yes        |
| PlaceholderAPI `%…%` placeholders                                                      | Yes           | No       | No         |
| `%bgui_server%` (the player's backend server)                                          | No            | Yes      | Yes        |
| Addons                                                                                 | Yes           | No       | No         |

| Action                                                                    | Paper / Folia                    | Velocity                                                             | BungeeCord                                                    |
| ------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
| `message`, `actionbar`, `title`, `open`, `delay`, `conditional`, `random` | Yes                              | Yes                                                                  | Yes                                                           |
| `broadcast`                                                               | All filters; `world:` is a world | `permission:`, and `world:` is a backend server; no `radius:`        | `permission:`, and `world:` is a backend server; no `radius:` |
| `sound`                                                                   | Yes                              | Yes, by namespaced id                                                | No                                                            |
| `command` (as the player)                                                 | Any command                      | Proxy commands; anything else is sent to the player's backend server | Proxy commands only                                           |
| `server` (as console)                                                     | Server console                   | Proxy console                                                        | Proxy console                                                 |
| `economy`                                                                 | Yes, with Vault                  | No                                                                   | No                                                            |
| `inventory`                                                               | Yes                              | No                                                                   | No                                                            |
| `bungee`                                                                  | Sends the message to the proxy   | `Connect`, `ConnectOther`, `Message`, `KickPlayer`                   | `Connect`, `ConnectOther`, `Message`, `KickPlayer`            |

A step whose action the platform does not have fails with "The … action is not available on this server." and stops the rest of its sequence. At startup the console lists every such step as a warning, so you see them before players do.

On Velocity, commands with signed chat arguments, such as `/msg` or `/me`, cannot be sent to the backend for a player. BungeeCord cannot send any command to the backend for a player.

{% hint style="info" %}
You can install BedrockGUI on the proxy and on the backend servers at the same time. Keep network menus (server selector, hub) on the proxy and economy, inventory or intercept menus on the backend, and give the forms on each side different `command:` names, because the proxy sees a command first.
{% endhint %}

### Installation

1. Install **Floodgate** — on the backend server, and on the proxy too if you run one.

{% hint style="warning" %}
**On a network**, set `send-floodgate-data: true` in the Floodgate config (or Geyser config) **on the proxy**. Without it the backend never learns who is a Bedrock player, so BedrockGUI cannot open forms for them. Restart the proxy after changing it.
{% endhint %}

2. Download the JAR for your platform.
3. Drop it into `plugins/`.
4. Start the server. This generates `config.yml`, `messages.yml` and a set of example forms in `forms/`.
5. Open the tour in game to check everything works:

```
/bedrockgui open main_menu
```

6. Edit or replace the forms in `plugins/BedrockGUI/forms/`, then apply your changes:

```
/bedrockgui reload
```

{% hint style="info" %}
The bundled examples are a working reference for every feature — actions, button images, custom forms, conditions, cooldowns. Read them next to Config Layout, then delete the ones you do not want.
{% endhint %}

### Upgrading from an older version

If your menus still live inline in `config.yml`, or under a `menu:` root, migrate them:

```
/bedrockgui convert
```

Your `config.yml` is backed up first, each form becomes its own file under `forms/`, and legacy action strings are rewritten to the current syntax. Details in Config Layout.

`config.yml` and `messages.yml` are upgraded for you on startup. When the bundled `config-version` is newer than yours, new keys are added, obsolete ones are removed, and every value you set is kept. The `forms:` section of `config.yml` is never touched.

{% hint style="info" %}
Example forms are only written on a fresh install, so an update never adds new ones to an existing `forms/` folder. To try a newer example such as `pay_player.yml`, copy it from the `forms/` folder inside the JAR into `plugins/BedrockGUI/forms/` and list it under `forms:` in `config.yml`.
{% endhint %}

### Verifying the install

* Console logs the registered action handlers and the loaded form ids on startup. If a form is missing from that list, it failed to parse — the warning above it says why.
* `/bedrockgui reload` re-reads everything, so you never need a restart for a config change.
* A Bedrock player is required to actually see a form. Java players get the `menu.noJava` message instead.

### Addons

Optional addons turn other plugins' GUIs into native Bedrock forms, with no menu design on your part:

| Addon                  | Covers                                           |
| ---------------------- | ------------------------------------------------ |
| **Essentials Addon**   | Warps, kits, homes, TPA, shops, pets, death menu |
| **Bedwars Addon**      | Shop, upgrades, arena, stats, spectator, party   |
| **Homestead Addon**    | Homestead's region and claim GUIs                |
| **PhoenixDuels Addon** | Duel, queue, party and spectate menus            |

All four are on [GitHub Releases](https://github.com/pintux98/BedrockGUI/releases/latest). Setup is in the [Addons](/pintux-support/addons.md) section.