⚙️ BetterSettings

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

!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

• Discord
• GitHub issues
• Source and documentation