Skip to content

GUI Themes

alexisleder edited this page Nov 8, 2026 · 2 revisions

GUI themes — 1.5.0

Documentation for 1.5.0. Validate custom themes on your server before applying them to production.

Configuration

Rule layout and optional head styling

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.

Lists and confirmations

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.

Icons and Head Database

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.

Resource packs

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.

Español — uso rápido

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.

Sources

Navigation and readability

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.

Configuration cleanup

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.

Clone this wiki locally