From 50a9b09f5e181390345ca55bf6443ed3a57d0231 Mon Sep 17 00:00:00 2001 From: tastybento Date: Thu, 24 Sep 2026 21:12:06 +0100 Subject: [PATCH] Document the template-driven settings panels Covers BentoBoxWorld/BentoBox#3081: the settings_panel.yml and admin_settings_panel.yml templates, their button types, the separate panel title, the [ranks] and [tooltips] lore placeholders, button fallbacks, and the list of customizable core panels. Co-Authored-By: Claude Fable 5.1 --- .../Island-Protection,-Flags-&-Ranks.md | 24 ++++++++++++++ docs/Tutorials/generic/Customizable-GUI.md | 31 +++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md b/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md index 95a28630..ad1796ee 100644 --- a/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md +++ b/docs/BentoBox/Island-Protection,-Flags-&-Ranks.md @@ -69,6 +69,27 @@ Admins can later unhide the Flag by reiterating the same procedure. *Player's view of all the basic Flags being allowed to be displayed.* +### Customizing the Settings Panel + +!!! new "Added in BentoBox 3.23.0" + The Settings Panel is laid out by a template file, like the other [customizable GUIs](/en/latest/Tutorials/generic/Customizable-GUI/). + +The layout of the Settings Panel comes from `plugins/BentoBox/panels/settings_panel.yml`, which BentoBox writes on first start. A game mode addon can ship its own copy in its `panels` folder (for example `plugins/BentoBox/addons/BSkyBlock/panels/settings_panel.yml`), and that one is used for that game mode instead. The default file reproduces the panel exactly as it looked before, so nothing changes until you edit it. If the file cannot be read, BentoBox logs an error and shows the built-in panel. + +Every button is placed with a `data.type`: + +| Type | What it shows | +| --- | --- | +| `TAB` | A tab button. `data.tab` is `PROTECTION`, `SETTING`, or `WORLD_PROTECTION` (the read-only view a player gets when not standing on an island). A tab that does not apply is not shown and the button's `fallback` is used instead. | +| `FLAG` | One slot of the paged flag list. Put as many of these as you want flags per page. With `data.flag: ` the slot always shows that flag instead, and the flag leaves the paged list; this is how the lock and change-settings icons are placed. | +| `MODE` | The display mode switch. Icons can be set per mode with `basic-icon`, `advanced-icon` and `expert-icon` in `data`. | +| `RESET` | Reset every flag to its default. Only the island owner sees it. | +| `NEXT`, `PREVIOUS` | Paging. Only shown when there is a page to go to. | + +**Title and tab names are separate.** The panel title is the template's `title`, by default the locale entry `panels.settings.title`, which is translated with `[tab]` (the name of the tab being shown) and `[world_name]`. The default is just `[tab]`. Each tab button has its own `title` and `description`, by default the `protection.panel.PROTECTION.title` and similar entries. So you can style the title one way and the tab buttons another, in either the template or the locale. + +**Lore layout.** A flag's lore is built from `protection.panel.flag-item.description-layout` (protection flags), `setting-layout` (settings) or `menu-layout` (flags that open a sub-panel) in the locale. As of 3.23.0 these layouts may contain `[ranks]`, where the rank list of a protection flag is inserted, and `[tooltips]`, where the tooltips of the flag button's `actions` in the template are inserted. Without `[ranks]` the rank list is appended after the layout, as before; without `[tooltips]` any tooltips are appended after an empty line. To move the click hints under the rank list, remove them from the layout, put `[ranks]` and `[tooltips]` where you want them, and declare the hints as tooltips on the `flag_button` in the template. A flag button's own `title` and `description` in the template may name a different locale entry to use as the name and lore layout for that panel only. + ![Curse of Vanishing](https://user-images.githubusercontent.com/20014332/80591692-6799b500-8a1e-11ea-9ab8-e076f47d2220.png) *The "Curse of Vanishing" being applied to one of the Flag.* @@ -151,6 +172,9 @@ Command cooldowns and teleport warm-up delays can be skipped with: The **Admin Settings Panel** is accessible via `/[admin_command] settings` (with no arguments). It contains three tabs: +!!! new "Added in BentoBox 3.23.0" + The Admin Settings Panel is laid out by `plugins/BentoBox/panels/admin_settings_panel.yml`, in the same way as the [player's Settings Panel](#customizing-the-settings-panel). Its tab types are `WORLD_SETTING`, `WORLD_DEFAULTS` and `ISLAND_DEFAULTS`; the last two need the `[gamemode].admin.set-world-defaults` permission and are hidden without it. The same file lays out `/[admin_command] settings `: each world tab names an island tab (`PROTECTION`, `SETTING`) as its `fallback`, which is what is shown when there is an island. + ### World Settings Toggles world-level setting flags that apply across the entire game world. diff --git a/docs/Tutorials/generic/Customizable-GUI.md b/docs/Tutorials/generic/Customizable-GUI.md index 5a058e58..ee433a4e 100644 --- a/docs/Tutorials/generic/Customizable-GUI.md +++ b/docs/Tutorials/generic/Customizable-GUI.md @@ -207,3 +207,34 @@ panel_name: Be aware, not all options are usable by players. `action` supports tooltip generation. Tooltips will be always added at the end of the button description and will be in the order of actions. + +??? question "What is `fallback` for buttons?" + A button may carry a `fallback`: another button definition (or the name of a `reusable`) that is shown when the button itself cannot be, for example a tab that does not apply in the current situation, or a paged slot with nothing left to show. A fallback is a full button, so it may have its own `data` and `actions`, and even its own `fallback`. The settings panels use this to put the tab shown off-island in the same slot as the tab shown on an island. + ```yaml + 2: + icon: SHIELD + title: protection.panel.PROTECTION.title + data: + type: TAB + tab: PROTECTION + fallback: + icon: STONE_BRICKS + title: protection.panel.WORLD_DEFAULTS.title + data: + type: TAB + tab: WORLD_PROTECTION + ``` + Fallbacks work as of BentoBox 3.23.0; earlier versions skipped the fallback and showed its own fallback instead. + +??? question "Which BentoBox panels are customizable?" + BentoBox writes these templates to `plugins/BentoBox/panels/` on first start. A game mode addon may ship its own copy of any of them in its own `panels` folder, which is then used for that game mode. + + | File | Panel | + | --- | --- | + | `island_creation_panel.yml` | Blueprint bundle choice when creating an island | + | `island_homes_panel.yml` | `/[player_command] homes` | + | `language_panel.yml` | `/[player_command] language` | + | `team_panel.yml` and `team_invite_panel.yml` | `/[player_command] team` and its invite screen | + | `settings_panel.yml` | `/[player_command] settings`, see [Customizing the Settings Panel](/en/latest/BentoBox/Island-Protection,-Flags-&-Ranks/#customizing-the-settings-panel) | + | `admin_settings_panel.yml` | `/[admin_command] settings` | + | `placeholder_panel.yml` and `placeholder_list_panel.yml` | The placeholder browser |