?
Host a serverModrinth App
Sign in
ModsResource PacksData PacksShadersModpacksPluginsServers
Settings
BetterSettings

BetterSettings

Reliable Paper player settings with custom YAML, toggle and choice values, safe reloads, and Classic or Donut-inspired GUIs.

613downloads
1follower
613downloads
1follower

Compatibility

Minecraft: Java Edition

26.2
26.1.x
1.21.x
1.20.5–1.20.6

Platforms

Links

View source Join Discord server
Donate on Ko-fiDonate on PayPal

Tags

Creators

Details

Licensed MIT
Published 10 months ago
Updated 2 weeks ago

⚙️ BetterSettings

Reliable player settings for Paper — one GUI, custom definitions, choice values, and safe reloads.

Discord GitHub bStats

BetterSettings 1.1 Chat choices

One settings menu, two layouts

BetterSettings gives players one place to manage server preferences while giving owners and plugin developers a stable extension point.

  • Classic preset: preserves the existing category-menu workflow.
  • Donut-inspired preset: an opt-in 54-slot tabbed inventory with Chat, Notifications, PvP, Visuals, Privacy, Scoreboard, and General tabs.
  • Clear controls: left-click toggles or advances, right-click selects the previous choice, and shift-click restores the configured default.
  • Capability-aware: provider-backed entries stay hidden until the plugin that implements them registers a behavior. Empty tabs are hidden too.

BetterSettings 1.1 tab tour

The Donut-inspired preset recreates the useful settings organization inside a normal Paper inventory. It is not affiliated with DonutSMP and does not copy its pause-screen interface.

Toggle and choice settings

Version 1.1 adds typed values without breaking the original boolean API.

  • Toggles remain YAML booleans.
  • Choices persist as strings and can be cycled in either direction.
  • Invalid stored choices safely resolve to the configured default.
  • Boolean changes continue to fire the legacy events as well as the new typed value event.

Choice setting cycle

The choice shown above is a custom demonstration definition, not a bundled server feature.

Custom settings that survive reloads

Custom YAML accepts:

  • a single setting at the root of settings/*.yml;
  • several named settings in one file; or
  • a named block such as Test: with an optional explicit id.

Unknown categories appear under Uncategorized with a warning. Invalid materials fall back to PAPER and are reported by validation. Duplicate IDs and invalid definitions fail validation instead of silently replacing another setting.

Reloads are atomic: a bad candidate keeps the current live menu running. Settings and behaviors registered by other plugins survive YAML reloads.

Actions and integrations

Custom settings can run validated post-commit actions:

  • send a player message;
  • run a player command; or
  • run a console command.

Command effects are best-effort because the destination plugin owns their behavior.

The Donut-inspired catalog includes generic provider-backed entries for auction alerts, bounty alerts, payment policy, item-worth lore, display rank, fast crystals, and scoreboard lines. BetterSettings only shows them after a provider registers the matching behavior.

Native behavior

BetterSettings-owned behavior includes chat and player visibility, personal time and weather, protection preferences, movement and potion-style modes, auto-respawn, item pickup, collision, and related Paper-native controls. The active catalog and availability counts are derived from the definitions loaded on your server rather than a fixed marketing number.

Commands

Command Purpose Permission
/settings Open the settings menu bettersettings.use
/settings reload Validate and atomically reload bettersettings.reload
/settings info Show the active preset and registry counts bettersettings.info
/settings validate Show loaded, unavailable, skipped, duplicate, and invalid counts bettersettings.validate

Developer API

The original Setting, SettingsRegistry.registerSetting(...), boolean data methods, and boolean events remain available. Version 1.1 adds ValueSetting, SettingType, SettingOption, SettingBehavior, string value methods, typed registration, and PlayerSettingValueChangeEvent.

SettingsRegistry.getInstance().registerSetting(new MyCustomSetting());

Requirements and compatibility

  • Java 21 or newer
  • Paper 1.20.5 or newer
  • No required third-party plugins

The same Java 21 artifact was exercised on Paper 1.20.5 with Java 21 and stable Paper 26.2 with Java 25. Folia is not advertised for 1.1 because its complete runtime journey has not been verified. Paper 26.3 remains an experimental smoke target rather than advertised stable support.

Upgrade from 1.0

  1. Back up plugins/BetterSettings/ as normal operational hygiene.
  2. Replace the old JAR with BetterSettings-1.1.0.jar.
  3. Keep the existing configuration and player-data files in place.
  4. Restart the server and run /settings validate.

Existing files are not overwritten. Existing boolean player values remain booleans, the active preset defaults to classic, and newly bundled files are copied only when missing.

Support