PlayerSettings

Version 1.0.0 · Paper/Purpur 1.21.x · Java 21

A central hub for per-player preferences. PlayerSettings gives players one clean GUI to pick their language and toggle preferences, and gives developers a simple API so every plugin can register its own settings in the same menu instead of scattering commands across the server.

Features

• One settings menu — /settings opens a paginated GUI. No more one command per preference.
• Language selection — players choose their locale (English, Portuguese, French out of the box) from a sub-menu; other plugins can honour that choice for their own messages.
• Auto-detection — a player's client language is detected on join and used as their default until they choose otherwise.
• Developer API — registered via Bukkit's ServicesManager. Plugins can register toggle, enum and numeric settings, group them into categories, and read per-player values by UUID.
• Fast reads — values are cached in memory with write-through persistence, so lookups from consumer plugins are cheap.
• SQLite storage — preferences are persisted per player with prepared statements.
• Safe by design — every write path operates on the player's own UUID; there is no command or path for a player to edit another player's settings.

Commands

Aliases: /prefs, /options.

Permissions

Configuration

# Default language for new players / players who haven't chosen.
# Ships as pt_PT — set en_US here for English-speaking servers.
default-language: pt_PT

# Languages players can choose from in the GUI.
languages:
  en_US:
    display-name: "<white>English"
    material: PAPER
  pt_PT:
    display-name: "<white>Português"
    material: PAPER
  fr_FR:
    display-name: "<white>Français"
    material: PAPER

storage:
  type: sqlite   # sqlite only for now
  file: "settings.db"

gui:
  title: "<dark_gray>Settings"
  language-title: "<dark_gray>Select Language"
  toggle-on-material: LIME_WOOL
  toggle-off-material: RED_WOOL
  filler-material: BLACK_STAINED_GLASS_PANE
  close-material: BARRIER

sounds:
  open-menu: "minecraft:ui.button.click"
  toggle: "minecraft:ui.button.click"
  select-language: "minecraft:entity.experience_orb.pickup"

Notable keys:

• languages — the locales offered in the GUI. Each consumer plugin should ship its own lang files for these locales; PlayerSettings only needs lang files for its own GUI messages.
• gui.* — display names and item materials used to render the menus (MiniMessage format).

For developers

PlayerSettings exposes PlayerSettingsApi through the Bukkit ServicesManager. Other plugins can register categories and toggle/enum/numeric settings, and read the current value for any player by UUID (getBoolean, getString, getLanguage, set). This lets a whole plugin suite share a single settings menu and a single per-player language choice.

Installation

1. Requires Paper or Purpur 1.21.x and Java 21.
2. Drop PlayerSettings-1.0.0.jar into your server's plugins/ folder.
3. Start the server and edit plugins/PlayerSettings/config.yml as needed, then /settings reload.

No external dependencies are required.

Support / Source

Source code: https://github.com/henriquescrrrr/carrageis-playersettings