Repository navigation
GUI Themes
Documentation for 1.5.0. Validate custom themes on your server before applying them to production.
Role rules share a paginated list (14 rules per page, currently two pages). Action items are descriptive and non-interactive. The control underneath shows the effective allow/block state and toggles it directly. State indicators show the effective state and next action, without a source/origin line. Reset, with confirmation, removes the role's overrides.
gui-style.default-heads enables bundled decorative heads; repeated decorative
head textures within a menu fall back to the original material in slot order.
State heads intentionally reuse green/red to communicate a consistent state.
state-heads, allowed-head, denied-head and clean-background configure the
indicators and filler. The rules layout uses previous-page, next-page,
info-0..13 and state-0..13 controls. Toggling a rule preserves the current page.
With clean-background: false (default), gui-style.border-material sets the
outer glass color (cyan) and fill-material sets the interior (gray). Both accept
stained glass pane materials. An explicit menu background overrides these global glass defaults.
The main protection menu contains information, area, management and a public-profile
button. The new main-public menu groups visibility, description, visits, favorites
and public settings. Private/admin protection lists and the information item always
display the configured stone block, even when a theme specifies a head. Curated heads
remain available for profiles in the public directory.
Resource packs are optional and supplied by the server administrator. LP ships and sends none. See external pack setup. Heads are disabled by default; enable them explicitly or configure individual icons in menus.yml.
Public icons accept public-protections.icons.heads.<id>: "<64-character hash>"
and optional head-names.<id> labels. The total curated catalogue has 28 slots,
including materials. Invalid heads and heads beyond the limit are logged and
ignored. Stored head:<id> values resolve only through this administrator list;
removing an entry makes affected profiles use the default material.
Detected Bedrock users receive ordinary titles/items, never the Java resource pack. See compatibility for backend API setup and testing limitations.
LP creates plugins/LederProtections/menus.yml once. Obsolete rule/category panels,
the old main menu and stock tiled confirmation panels migrate with a
menus.pre-layout-*.yml backup; other customizations
are preserved. schema-version: 1 is required. Missing menus/fields inherit the bundled
layout; existing config.yml, language customizations, category IDs and public
profiles remain in use. Make a backup before editing an existing theme.
All 22 menu definitions are covered: protection/main management, player/admin lists, public directory/settings/icon picker, members/blocked players, role/action rules, environment, co-owner settings, legacy WG flags, shop and confirmations.
Slots start at 0, left to right, top to bottom. rows accepts 1–6. Buttons use
stable names such as management, rules, members, back, close and
previous-page. Use the generated file as the full list of IDs for each menu.
An ID is a built-in action, not an arbitrary command or a permission grant.
schema-version: 1
pack-aware: false
menus:
main:
rows: 5
# Empty title uses lang/en.yml or lang/es.yml.
title: "&8{name}"
buttons:
management:
slots: [10]
icon:
material: ANVIL
hdb: "7129" # Example ID from the official HDB API; choose your own design.
info:
slots: [41] # Swap BOTH buttons so they do not overlap.
background:
material: BLACK_STAINED_GLASS_PANE
name: " "Changing a slot or skin does not change its action. A button hidden because of permissions/feature settings remains hidden. Normal clicks retain existing permission checks. Decorations have no action; neither names nor the visible item's metadata authorize an operation.
/lep reload validates the complete theme before activation. Duplicate/out-of-range
slots, unknown keys/actions, invalid types and malformed textures reject the
candidate. LP reports the menu/key and keeps the last valid theme. At first startup,
an invalid custom theme falls back to bundled menus. A successful reload closes
open LP menus; old sessions cannot execute against the new layout.
Player/admin protection lists, members, blocked players and the directory accept
1–28 content-slots; their page size adapts to the number configured. The directory
also respects the smaller public-protections.directory.page-size limit in config.yml.
List order maps to displayed entries. Example for the player protection list:
menus:
protection-list:
content-slots: [10, 12, 14, 16, 28, 30, 32, 34]The shop, public icon picker and legacy WG flag menus currently have no pagination:
they must retain the bundled number of content slots, although all those slots can
be moved. This prevents a smaller layout from silently hiding existing options.
content-icon changes the shared appearance of list entries; their original text
and action targets are preserved unless explicitly overridden.
Confirmation panels can become individual buttons: set buttons.confirm.slots: [11] and buttons.cancel.slots: [15] on a member/remove or rules/reset confirmation.
Required buttons cannot be removed or overlap. Multiple slots may trigger the same
named button; unrelated buttons cannot share a slot.
decorations.<name> accepts slots and icon, and cannot cover controls/content.
background.material: AIR clears filler items, useful for resource-pack backgrounds.
AIR is only accepted for backgrounds/decorations, not actionable buttons.
Icon fields are optional:
| Field | Meaning |
|---|---|
material |
Vanilla item; also fallback if a head is unavailable. Omit to keep the original. |
texture |
64-character Minecraft texture hash. |
base64 |
Base64 skin JSON containing an official Minecraft texture URL; max 4096 characters. |
hdb |
Quoted Head Database ID, e.g. "7129". |
custom-model-data |
Nonnegative integer for a resource-pack model. |
item-model |
Namespaced model key, e.g. lp:menu/members, on servers exposing that API. |
name, lore
|
Optional text overrides; otherwise retain translated/dynamic text. |
Choose one of texture, base64 or hdb. LP rejects arbitrary hosts, ports,
credentials, query strings and non-texture paths in Base64 URLs. Textures are
handled through public Bukkit profiles; LP does not make its own HTTP requests
when opening a menu. Clients still download Minecraft skin textures normally.
Head Database by Arcaniax is optional. Install the runtime plugin on the server, then restart. Its API library alone is not the runtime plugin. HeadDB products by other authors are not interchangeable. LP does not bundle HDB or require players to install a mod/resource pack for heads.
Missing/loading HDB, unknown IDs or an incompatible API use the material/original
icon and log a bounded warning. Icon templates (including failed lookups) use a bounded 2048-entry LRU cache;
each button receives a clone. /lep reload and HDB's DatabaseLoadEvent invalidate
the cache. Existing open inventories keep their snapshot until reopened. Installing
or hot-reloading plugins in a running server is not a supported deployment workflow.
Override category icons in menus.yml:
category-icons:
other:
material: COMPASS
hdb: "7129"Use your real category ID. This takes precedence over the existing category
head-texture in config.yml; without an override, the original texture/material
continues working. No category or saved public profile is renamed.
Titles accept literal Unicode glyphs (or YAML Unicode escapes), so a pack can draw a custom visual background through its font. The inventory still has real slots: a picture cannot change hitboxes or add an arbitrary button outside the grid. An author must align the glyph, row count and configured controls together.
pack-aware: true
menus:
main:
title: "&f\uE001"
fallback-title: "&8{name}"
buttons:
management:
icon:
material: PAPER
custom-model-data: 1001
item-model: "lp:menu/management"LP does not send/create a resource pack. Configure its delivery in the server or
your pack plugin. With pack-aware: true, model overrides and the custom title are
used only after a successful status for the exact UUID configured in
resource-pack.external.pack-id, with resource-pack.mode: external. Unrelated
packs do not activate the theme. Failure or rejection returns to the material and
fallback-title (or original translated title). LP checks load status, not whether
the pack actually contains your assets. Reconnect after enabling tracking or changing
its UUID. See setup and integration limits.
Legacy integer CustomModelData remains available on the Spigot baseline. item-model
uses a capability check and falls back on older servers; no NMS/Paper-only dependency
is introduced. Pack formats/model definitions still need to target your client version.
Text supports & colors, {user} (viewer), {title} (original menu title),
{plain_title} (original title without color/format codes, useful for dark pack backgrounds), and on
protection-context menus {name}, {owner}, {id}. Substitution is one-pass.
There is no new PlaceholderAPI polling loop in themes. Existing hologram/PAPI
features are unaffected. Keep status/value lore when replacing icons for rule toggles.
Integrations with ItemsAdder/Oraxen/Nexo item registries, automatic pack building, and per-player drag-and-drop layout editors remain future work. This update provides server-managed themes, not player-editable layouts.
Edita menus.yml para mover botones, cambiar filas, fondo e iconos. Las posiciones
empiezan en 0. Usa los IDs del archivo generado; cada ID conserva su función y sus
permisos aunque cambies la cabeza o el nombre. Si intercambias dos botones, cambia
las dos posiciones para evitar solapamientos.
Aplica con /lep reload. Si el tema es inválido se conserva el último válido; si
es correcto se cierran las GUIs antiguas. HDB es opcional; hdb: "7129" es solo un
ejemplo. También puedes usar texture, base64 o materiales normales. Las texturas
de categoría existentes siguen funcionando. Los modelos/glyphs necesitan un pack
compatible entregado por el servidor; LP no lo genera ni lo envía.
Las listas paginadas permiten cambiar la cantidad de entradas. Los selectores sin paginación conservan su cantidad de casillas. Esta versión configura el tema del servidor; la edición individual de menús por cada jugador queda para otra etapa.
- Head Database API
- DeluxeMenus icon providers
- Minecraft-Heads catalogue
- Oraxen glyph documentation
- Spigot ItemMeta API
Private-list pages and public-directory filters/sorting/pages are retained during the player session and cleared on disconnect. Main-menu Back returns to the private list, public directory or administrative view used to enter; the admin return checks permission again. Pages are clamped when the number of entries changes.
Empty private lists show a single explanation instead of repeating empty slots. The information item uses the protection name, owner, world, size and coordinates. Rule controls include a textual check/cross state and the exact next-click action. Confirmation descriptions identify the affected protection. Long lore is wrapped at 48 visible Unicode code points, retaining legacy colors; names remain intact.
Bundled English/Spanish defaults update through the existing config updater. User-customized text is preserved and may need the new placeholders added manually.
gui-style now belongs to menus.yml, alongside layouts and icons. Existing values
from config.yml migrate with backups; explicit values already in menus.yml win.
Missing fields inherit defaults. Invalid style values reject the menu reload and
retain the last valid theme. Old config values remain a fallback if file migration fails.