[Feat] Admin GUI: Runtime Config Editor

[derrickmehaffy]

Summary

The AdminConfigPage currently displays a "Coming Soon" placeholder. Implement a runtime configuration editor GUI that allows admins to view and modify plugin settings without editing files manually.

Features

Config Display

• 8 tabbed sections (General, Power, Claims, Combat, Chat, Modules, World Map, Protection) covering ~130 settings across 9 config files
• Show setting descriptions and default values
• Indicate which settings require a reload vs. take effect immediately

Editing

• Boolean toggles, int/double increment/decrement, text fields, dropdowns as appropriate
• Input validation (numeric ranges, string patterns, enum values)
• Highlight modified values that differ from defaults
• World list editor with server world picker
• Faction permissions matrix with role selector

Actions

• Save — Write changes to config file
• Revert — Discard in-memory changes back to saved state
• Reset to Default — Reset individual settings or entire sections (two-click confirm)
• In-memory change tracking with save/revert/reset workflow

Scope

• Main config.json settings
• Module-specific configuration sections
• Zone flag defaults
• Economy settings (currency, tax rates, upkeep)
• World Map conditional sections based on refresh mode
• Protection tab role selector and permission default/lock toggles

Test Plan

• Open /f admin and navigate to Config tab
• Verify all 8 tabs load and switch correctly
• Test boolean toggles, int/double increment/decrement, text fields, dropdowns
• Test world whitelist/blacklist add/remove with server world picker
• Test Protection tab role selector and permission default/lock toggles
• Test World Map tab conditional sections based on refresh mode
• Test Save, Revert, and Reset Defaults (two-click confirm)
• Verify saved config persists after /f reload

Existing Infrastructure

• AdminConfigPage.java — Placeholder page exists
• ConfigManager — Handles config loading/saving
• Admin GUI framework — Fully functional for other admin pages

Origin

Roadmap Phase B.3 ("Coming Soon" admin page placeholder).

[derrickmehaffy]

Updated Design: Nested Sub-Navigation per Config File

Navigation Architecture

Introduce a secondary nav bar nested below the existing admin nav bar — a new pattern for the project. When an admin clicks the "Config" tab in the top admin nav, they see:

┌──────────────────────────────────────────────────────────────────────┐
│ Admin Panel │ Dashboard │ Actions │ Factions │ ... │ Config │ ... │ ← existing admin nav (red, 45px)
├──────────────────────────────────────────────────────────────────────┤
│ Factions │ Server │ Chat │ Economy │ Map │ Perms │ Worlds │ ... │ ← NEW config sub-nav (cyan/teal, ~34px)
├──────────────────────────────────────────────────────────────────────┤
│ │
│ [scrollable config settings for selected sub-tab] │
│ │
└──────────────────────────────────────────────────────────────────────┘

Sub-Tab → Config File Mapping

Each sub-tab maps directly to one config file in config/:

Sub-Tab	Config File	Config Class	Key Settings
Factions	factions.json	FactionsConfig	Faction limits, names, colors, power, claims, combat, spawn protection, relations, invites, stuck, claim protection overrides (~50+ settings, largest file)
Server	server.json	ServerConfig	Teleport warmup/cooldown, updates, auto-save, mob clearing, messages/prefix, GUI title, terrain map, language/i18n, admin permissions
Chat	chat.json	ChatConfig	Chat formatting, tag display, relation colors, faction/ally chat colors/prefix, chat history settings
Economy	economy.json	EconomyConfig	Treasury enable, currency names/symbol, starting balance, deposit/withdraw/transfer fees, upkeep (cost, interval, grace, scaling tiers)
World Map	worldmap.json	WorldMapConfig	Territory map markers, refresh mode, conditional sections
Permissions	faction-permissions.json	FactionPermissionsConfig	Territory permission defaults per role, permission lock toggles
Worlds	worlds.json	WorldsConfig	Per-world settings, claiming allowed, power loss, friendly fire overrides
Announcements	announcements.json	AnnouncementConfig	Territory enter/leave notifications, wilderness messages
Gravestones	gravestones.json	GravestoneConfig	Gravestone integration settings
Backup	backup.json	BackupConfig	Backup scheduling, hourly/daily/weekly/manual/shutdown retention
Debug	debug.json	DebugConfig	Per-subsystem debug flags (power, claim, combat, protection, relation, territory, worldmap, integration)

Total: 11 sub-tabs, 11 config files, ~130+ settings

Implementation Details

New UI Template: Config Sub-Nav Bar

Create config_sub_nav_bar.ui following the existing MenuItem nav bar pattern but with:

• Smaller height (~34px vs 45px for admin nav)
• Different color scheme — lighter background (e.g., #1a2736) with a distinct active color (e.g., cyan #00CCCC or teal) to visually differentiate from the red admin nav
• Same MenuItem element type with SelectedStyle for active state
• Dynamic button container (#ConfigSubNavButtons) populated from a ConfigSubPageRegistry

admin_config.ui layout:
 $Nav.@HyperFactionsAdminNavBar ← existing top nav (Config tab selected)
 $ConfigNav.@ConfigSubNavBar ← NEW secondary nav
 $C.@Container ← content area (scrollable, swapped per sub-tab)

New Java Components

1. ConfigSubPageRegistry — Registry of config sub-pages (similar to AdminPageRegistry)

   • Each entry: id, displayName, configClass, order
   • 11 entries, one per config file

2. ConfigSubNavHelper — Builds the sub-nav bar and handles sub-tab click events

   • Follows AdminNavBarHelper pattern exactly
   • Event data key: "configSubNav" (to distinguish from "adminNavBar")

3. AdminConfigPage refactor — Becomes a container/router that:

   • Sets up the admin nav bar (Config tab active)
   • Sets up the config sub-nav bar (default to "Factions" tab)
   • Delegates content rendering to the selected sub-page

4. Per-config sub-pages — One class per config file (or a generic ConfigSectionPage with config-driven field rendering):

   • ConfigFactionsSubPage — sections for faction limits, power, claims, combat, spawn protection, relations, invites, stuck, protection overrides (this is the big one, likely needs internal section headers)
   • ConfigServerSubPage — teleport, updates, auto-save, mob clearing, messages, GUI, language, permissions
   • ConfigChatSubPage, ConfigEconomySubPage, etc.
   • Each sub-page reads from its ModuleConfig/ConfigFile class and writes back via ConfigManager

Factions Tab Internal Layout (Largest Config)

Since factions.json has ~50+ settings across many categories, use section headers within the scrollable area (NOT additional nested tabs):

┌─ Factions ──────────────────────────────────────────┐
│ │
│ ── General ── │
│ Max Members: [50] Max Name Length: [24] ... │
│ │
│ ── Power ── │
│ Max Player Power: [20.0] Starting: [10.0] ... │
│ │
│ ── Claims ── │
│ Max Claims: [100] Adjacent Only: [✗] ... │
│ │
│ ── Combat ── │
│ Tag Duration: [15s] Ally Damage: [✗] ... │
│ │
│ ── Spawn Protection ── │
│ ... │
│ ── Relations ── │
│ ── Invites ── │
│ ── Stuck ── │
│ ── Claim Protection Overrides ── │
│ │
│ [Save] [Revert] [Reset to Default] │
└──────────────────────────────────────────────────────┘

Action Bar (Bottom of Each Sub-Tab)

Each sub-tab content area includes a pinned bottom action bar:

• Save — Writes changes to that config file via ConfigManager
• Revert — Discards unsaved in-memory edits
• Reset to Default — Two-click confirm, resets individual settings or entire section

Data Flow

User clicks sub-tab → ConfigSubNavHelper.handleNavEvent()
 → Reads "configSubNav" from event data
 → Opens new AdminConfigPage with selected sub-tab ID
 → AdminConfigPage.build() renders admin nav + sub-nav + selected sub-page content

User edits a setting → In-memory change tracked (highlight modified values)
User clicks Save → ConfigManager.get().chat().save() (or whichever config)
User clicks Revert → Reload from ConfigManager.get().chat().reload()

Config Manager Integration Points

Each config class already has load(), save(), reload(), and validateAndLog(). The sub-pages call:

• ConfigManager.get().factions() → FactionsConfig (getter/setter pairs)
• ConfigManager.get().server() → ServerConfig
• ConfigManager.get().chat() → ChatConfig
• etc.

All module configs extend ModuleConfig which has isEnabled()/setEnabled() — so the enabled toggle can be a universal first field on applicable sub-tabs.

Test Plan Update

• Open /f admin → Config tab → verify sub-nav bar appears below admin nav
• Click each of the 11 sub-tabs → verify correct settings load
• Verify Factions tab internal section headers render correctly with scrolling
• Test each input type: boolean toggles, int/double fields, text fields, dropdowns
• Test Worlds tab: world list add/remove with server world picker
• Test Permissions tab: role selector + permission default/lock toggles
• Test Economy tab: upkeep scaling tier editor
• Test Save → verify changes persist after /f reload
• Test Revert → verify unsaved changes are discarded
• Test Reset to Default → verify two-click confirm, values reset
• Verify modified values are visually highlighted before saving
• Test navigation: switch between sub-tabs with unsaved changes → warn or auto-revert

[derrickmehaffy]

Config Input Type Catalog — CustomUI Implementation Details

Every setting across all 11 config files mapped to its exact CustomUI element, event pattern, and implementation approach.

---

Input Type Summary

Input Type	Count	CustomUI Element	Config Fields
Boolean toggle	~80+	$C.@CheckBoxWithLabel	Most common — all on/off flags
Integer (bounded)	~25	$C.@SliderNumberField	maxMembers, maxClaims, tagDuration, retention counts, etc.
Integer (unbounded/special)	~5	$C.@TextField + validation	maxAllies/maxEnemies (-1 = unlimited)
Double (bounded)	~15	$C.@SliderNumberField	power values, penalties, regen rates
BigDecimal (currency)	~10	$C.@TextField + parse	economy amounts, fee percentages, upkeep costs
String (free text)	~15	$C.@TextField	prefix, format strings, chat tags, URLs
String (enum/select)	~5	Bare DropdownBox + DropdownEntry	tagDisplay, releaseChannel, priority, scalingMode, defaultPolicy
String (hex color)	~12	ColorPickerDropdownBox	all *Color fields in ServerConfig, ChatConfig
List<String>	~3	Dynamic list + add/remove	worldWhitelist, worldBlacklist, claimBlacklist
List<ScalingTier>	1	Dynamic list + dual fields	upkeepScalingTiers
Map<String, WorldSettings>	1	Dynamic list + per-world toggles	worlds map (with wildcard patterns)
EnumMap<FactionRole, String>	2	Fixed rows + $C.@TextField	roleDisplayNames, roleShortNames
Permission matrix	1	Role selector + checkbox grid	FactionPermissionsConfig defaults/locks
Boolean (nullable/tri-state)	4 per world	Bare DropdownBox (Inherit/Yes/No)	WorldSettings claiming, powerLoss, friendlyFire

---

1. Boolean Toggle (~80+ fields)

Element: $C.@CheckBoxWithLabel
Used by: Every config file

.ui template (config_toggle_entry.ui):

Group {
 LayoutMode: Left;
 Anchor: (Height: 32, Bottom: 4);

 $C.@CheckBoxWithLabel #Toggle {
 @Text = "";
 @Checked = false;
 Anchor: (Width: 300);
 }

 Label #Description {
 Text: "";
 Anchor: (Left: 8);
 Style: (FontSize: 11, TextColor: $C.@ColorGrayCaption);
 }
}

Java pattern:

private void buildToggle(UICommandBuilder cmd, UIEventBuilder events,
 String containerId, int index,
 String label, boolean currentValue, String settingKey) {
 cmd.append("#" + containerId, UIPaths.CONFIG_TOGGLE_ENTRY);
 String idx = "#" + containerId + "[" + index + "]";

 cmd.set(idx + " #Toggle #CheckBox.Value", currentValue);
 // Label is set via template @Text or via child Label
 cmd.set(idx + " #Description.Text", label);

 events.addEventBinding(
 CustomUIEventBindingType.ValueChanged,
 idx + " #Toggle #CheckBox",
 EventData.of("Action", "ToggleBool").append("Key", settingKey),
 false // don't lock UI for toggles
 );
}

Event handling — toggle from server state (NOT reading @ value):

// In handleDataEvent:
if ("ToggleBool".equals(action)) {
 String key = data.key;
 boolean current = getConfigBoolean(key);
 setConfigBoolean(key, !current); // flip
 refreshPage();
}

Critical notes:

• Use child selector #id #CheckBox.Value — direct #id.Value crashes
• Use child selector #id #CheckBox.Disabled for disabled state
• Do NOT read checkbox value via @ in EventData — toggle from server state instead
• locksInterface: false to keep UI responsive for rapid toggling

Fields using this type:
FactionsConfig: allowColors, killRewardRequiresFaction, powerLossOnMobDeath, powerLossOnEnvironmentalDeath, regenWhenOffline, hardcoreMode, onlyAdjacent, preventDisconnect, decayEnabled, outsiderPickupAllowed, outsiderDropAllowed, factionlessExplosionsAllowed, enemyExplosionsAllowed, neutralExplosionsAllowed, fireSpreadAllowed, factionlessDamageAllowed, enemyDamageAllowed, neutralDamageAllowed, allyDamage, factionDamage, taggedLogoutPenalty, spawnProtectionEnabled, spawnProtectionBreakOnAttack, spawnProtectionBreakOnMove
ServerConfig: cancelOnMove, cancelOnDamage, autoSaveEnabled, terrainMapEnabled, adminRequiresOp, allowWithoutPermissionMod, updateCheckEnabled, mobClearEnabled, usePlayerLanguage, hyperProtectAutoDownload, hyperProtectAutoUpdate
ChatConfig: historyEnabled
DebugConfig: enabledByDefault, logToConsole, power, claim, combat, protection, relation, territory, worldmap, interaction, mixin, spawning, integration, economy, sentryEnabled, sentryDebug
EconomyConfig: disbandRefundToLeader, upkeepEnabled, upkeepAutoPayDefault
BackupConfig: onShutdown
AnnouncementConfig: factionCreated, factionDisbanded, leadershipTransfer, overclaim, warDeclared, allianceFormed, allianceBroken, territoryNotificationsEnabled, wildernessOnLeaveZoneEnabled, wildernessOnLeaveClaimEnabled
GravestoneConfig: protectInOwnTerritory, factionMembersCanAccess, alliesCanAccess, protectInSafeZone, protectInWarZone, protectInWilderness, announceDeathLocation, protectInEnemyTerritory, protectInNeutralTerritory, enemiesCanLootInOwnTerritory, allowLootDuringRaid, allowLootDuringWar

---

2. Integer (Bounded Range) (~25 fields)

Element: $C.@SliderNumberField
Used by: FactionsConfig, ServerConfig, BackupConfig, ChatConfig, EconomyConfig, WorldMapConfig

.ui template (config_slider_entry.ui):

Group {
 LayoutMode: Top;
 Anchor: (Height: 52, Bottom: 6);

 Label #SettingLabel {
 Text: "";
 Anchor: (Height: 18);
 Style: (FontSize: 12, TextColor: $C.@ColorDefaultLabel);
 }

 $C.@SliderNumberField #SliderInput {
 @Anchor = (Width: 380, Height: 28);
 Value: 0;
 Min: 0;
 Max: 100;
 NumberFieldStyle: $C.@DefaultInputFieldStyle;
 }
}

Java pattern:

private void buildSlider(UICommandBuilder cmd, UIEventBuilder events,
 String containerId, int index,
 String label, int currentValue,
 int min, int max, String settingKey) {
 cmd.append("#" + containerId, UIPaths.CONFIG_SLIDER_ENTRY);
 String idx = "#" + containerId + "[" + index + "]";

 cmd.set(idx + " #SettingLabel.Text", label);
 cmd.set(idx + " #SliderInput.Value", currentValue);
 cmd.set(idx + " #SliderInput.Min", min);
 cmd.set(idx + " #SliderInput.Max", max);

 events.addEventBinding(
 CustomUIEventBindingType.ValueChanged,
 idx + " #SliderInput",
 EventData.of("Action", "SliderChanged")
 .append("Key", settingKey)
 .append("@Val", idx + " #SliderInput.Value"),
 false
 );
}

Fields using this type (with ranges):

Config	Field	Default	Min	Max
FactionsConfig	maxMembers	50	1	500
FactionsConfig	maxNameLength	24	1	64
FactionsConfig	minNameLength	3	1	maxNameLength
FactionsConfig	maxMembershipHistory	10	1	100
FactionsConfig	maxClaims	100	0	10000
FactionsConfig	decayDaysInactive	30	1	365
FactionsConfig	decayClaimsPerCycle	5	1	100
FactionsConfig	tagDurationSeconds	15	0	300
FactionsConfig	spawnProtectionDurationSeconds	5	0	60
FactionsConfig	inviteExpirationMinutes	5	1	1440
FactionsConfig	joinRequestExpirationHours	24	1	720
FactionsConfig	stuckMinRadius	3	1	32
FactionsConfig	stuckRadiusIncrease	3	1	32
FactionsConfig	stuckMaxAttempts	10	1	50
FactionsConfig	stuckWarmupSeconds	30	0	600
FactionsConfig	stuckCooldownSeconds	300	0	3600
ServerConfig	warmupSeconds	5	0	300
ServerConfig	cooldownSeconds	300	0	3600
ServerConfig	autoSaveIntervalMinutes	5	1	60
ServerConfig	leaderboardKdRefreshSeconds	300	30	3600
ServerConfig	mobClearIntervalSeconds	10	5	300
BackupConfig	hourlyRetention	24	0	168
BackupConfig	dailyRetention	7	0	90
BackupConfig	weeklyRetention	4	0	52
BackupConfig	manualRetention	10	0	100
BackupConfig	shutdownRetention	5	0	50
ChatConfig	historyMaxMessages	200	10	1000
ChatConfig	historyRetentionDays	7	1	90
ChatConfig	historyCleanupIntervalMinutes	60	5	1440
EconomyConfig	defaultLimitPeriodHours	24	1	720
EconomyConfig	upkeepIntervalHours	24	1	168
EconomyConfig	upkeepGracePeriodHours	48	0	720
EconomyConfig	upkeepFreeChunks	3	0	100
EconomyConfig	upkeepClaimLossPerCycle	1	1	50
EconomyConfig	upkeepWarningHours	6	0	72
WorldMapConfig	proximityChunkRadius	32	1	128
WorldMapConfig	proximityBatchIntervalTicks	30	1	200
WorldMapConfig	proximityMaxChunksPerBatch	50	1	500
WorldMapConfig	incrementalBatchIntervalTicks	30	1	200
WorldMapConfig	incrementalMaxChunksPerBatch	50	1	500
WorldMapConfig	debouncedDelaySeconds	5	1	60
WorldMapConfig	factionWideRefreshThreshold	200	1	1000

---

3. Integer (Special: -1 = Unlimited) (~2 fields)

Element: $C.@TextField with label hint showing "-1 = unlimited"
Used by: FactionsConfig maxAllies, maxEnemies

SliderNumberField doesn't work here because -1 is a sentinel value. Use a text field with validation.

Java pattern:

cmd.append("#Container", UIPaths.CONFIG_TEXT_ENTRY);
cmd.set(idx + " #SettingLabel.Text", "Max Allies (-1 = unlimited)");
cmd.set(idx + " #TextInput.Value", String.valueOf(currentValue));

events.addEventBinding(
 CustomUIEventBindingType.ValueChanged,
 idx + " #TextInput",
 EventData.of("Action", "IntChanged")
 .append("Key", "maxAllies")
 .append("@Val", idx + " #TextInput.Value"),
 false
);

// Validation in handler:
int parsed = Integer.parseInt(value);
if (parsed < -1) parsed = -1; // clamp

---

4. Double (Bounded Range) (~15 fields)

Element: $C.@SliderNumberField (same as integer, but with decimal step)
Used by: FactionsConfig power/combat values, DebugConfig sentryTracesSampleRate

Note: SliderNumberField supports float values natively. For fields like regenPerMinute (0.1 default, range 0.0-10.0), set Min/Max as floats.

Fields using this type:

Config	Field	Default	Min	Max
FactionsConfig	maxPlayerPower	20.0	0.0	1000.0
FactionsConfig	startingPower	10.0	0.0	maxPlayerPower
FactionsConfig	powerPerClaim	2.0	0.0	100.0
FactionsConfig	deathPenalty	1.0	0.0	maxPlayerPower
FactionsConfig	killReward	0.0	0.0	maxPlayerPower
FactionsConfig	regenPerMinute	0.1	0.0	10.0
FactionsConfig	logoutPowerLoss	1.0	0.0	maxPlayerPower
FactionsConfig	neutralAttackPenalty	0.0	0.0	maxPlayerPower
DebugConfig	sentryTracesSampleRate	0.0	0.0	1.0

---

5. BigDecimal (Currency Amounts) (~10 fields)

Element: $C.@TextField with string input, parsed to BigDecimal server-side
Used by: EconomyConfig

SliderNumberField doesn't have the precision needed for currency. Use a text field.

.ui template (config_currency_entry.ui):

Group {
 LayoutMode: Top;
 Anchor: (Height: 52, Bottom: 6);

 Label #SettingLabel {
 Text: "";
 Anchor: (Height: 18);
 Style: (FontSize: 12, TextColor: $C.@ColorDefaultLabel);
 }

 Group {
 LayoutMode: Left;
 Anchor: (Height: 28);

 Label #CurrencySymbol {
 Text: "$";
 Anchor: (Width: 20, Height: 28);
 Style: (FontSize: 14, TextColor: $C.@ColorDefault);
 }

 $C.@TextField #CurrencyInput {
 @Anchor = (Width: 150, Height: 28);
 PlaceholderText: "0.00";
 }
 }
}

Java pattern:

cmd.set(idx + " #CurrencyInput.Value", currentValue.toPlainString());
cmd.set(idx + " #CurrencySymbol.Text", ConfigManager.get().getEconomyCurrencySymbol());

events.addEventBinding(
 CustomUIEventBindingType.FocusLost, // validate on blur, not every keystroke
 idx + " #CurrencyInput",
 EventData.of("Action", "CurrencyChanged")
 .append("Key", settingKey)
 .append("@Val", idx + " #CurrencyInput.Value"),
 false
);

// Validation in handler:
try {
 BigDecimal parsed = new BigDecimal(value);
 if (parsed.compareTo(BigDecimal.ZERO) < 0) parsed = BigDecimal.ZERO;
 setConfigBigDecimal(key, parsed);
} catch (NumberFormatException e) {
 // Revert to current value on next refresh
}

Fields: startingBalance, defaultMaxWithdrawAmount, defaultMaxWithdrawPerPeriod, defaultMaxTransferAmount, defaultMaxTransferPerPeriod, depositFeePercent (0-100), withdrawFeePercent (0-100), transferFeePercent (0-100), upkeepCostPerChunk, upkeepMaxCostCap

---

6. String (Free Text) (~15 fields)

Element: $C.@TextField
Used by: ServerConfig, ChatConfig, EconomyConfig, AnnouncementConfig

.ui template (config_text_entry.ui):

Group {
 LayoutMode: Top;
 Anchor: (Height: 52, Bottom: 6);

 Label #SettingLabel {
 Text: "";
 Anchor: (Height: 18);
 Style: (FontSize: 12, TextColor: $C.@ColorDefaultLabel);
 }

 $C.@TextField #TextInput {
 @Anchor = (Width: 380, Height: 28);
 PlaceholderText: "";
 }
}

Java pattern:

cmd.set(idx + " #TextInput.Value", currentValue); // .Value NOT .Text

events.addEventBinding(
 CustomUIEventBindingType.FocusLost, // commit on blur
 idx + " #TextInput",
 EventData.of("Action", "TextChanged")
 .append("Key", settingKey)
 .append("@Val", idx + " #TextInput.Value"),
 false
);

Critical: Use .Value NOT .Text — .Text on TextField crashes or has no effect.

Fields: ServerConfig prefixText, guiTitle, updateCheckUrl, defaultLanguage, hyperProtectUpdateUrl; ChatConfig format, tagFormat, noFactionTag, factionChatPrefix, allyChatPrefix; EconomyConfig currencyName, currencyNamePlural, currencySymbol; AnnouncementConfig wildernessOnLeaveZoneUpper/Lower, wildernessOnLeaveClaimUpper/Lower; DebugConfig sentryDsn, sentryEnvironment

---

7. String (Enum/Select) (~5 fields)

Element: Bare DropdownBox (NOT $C.@DropdownBox — the template opens sideways)
Used by: ChatConfig, ServerConfig, EconomyConfig, WorldMapConfig, WorldsConfig

.ui template (config_dropdown_entry.ui):

Group {
 LayoutMode: Top;
 Anchor: (Height: 52, Bottom: 6);

 Label #SettingLabel {
 Text: "";
 Anchor: (Height: 18);
 Style: (FontSize: 12, TextColor: $C.@ColorDefaultLabel);
 }

 Group {
 Background: (Color: #0d1520);
 Padding: (Left: 6, Right: 6);
 Anchor: (Height: 32);

 DropdownBox #Dropdown {
 Anchor: (Height: 26);
 }
 }
}

Java pattern:

// Build entries list
List<DropdownEntryInfo> entries = List.of(
 new DropdownEntryInfo(LocalizableString.fromString("Tag"), "tag"),
 new DropdownEntryInfo(LocalizableString.fromString("Name"), "name"),
 new DropdownEntryInfo(LocalizableString.fromString("None"), "none")
);
cmd.set(idx + " #Dropdown.Entries", entries);
cmd.set(idx + " #Dropdown.Value", currentValue);

events.addEventBinding(
 CustomUIEventBindingType.ValueChanged,
 idx + " #Dropdown",
 EventData.of("Action", "DropdownChanged")
 .append("Key", settingKey)
 .append("@Val", idx + " #Dropdown.Value"),
 false
);

Note: Use bare DropdownBox wrapped in a styled Group for visual chrome. The $C.@DropdownBox template opens sideways and its ValueChanged event doesn't fire on the wrapper element.

Fields and their options:

Config	Field	Options
ChatConfig	tagDisplay	tag, name, none
ChatConfig	priority	EARLIEST, EARLY, NORMAL, LATE, LATEST
ServerConfig	releaseChannel	stable, prerelease
EconomyConfig	upkeepScalingMode	flat, progressive
WorldsConfig	defaultPolicy	allow, deny
WorldMapConfig	refreshMode	proximity, incremental, debounced, immediate, manual

---

8. String (Hex Color) (~12 fields)

Element: ColorPickerDropdownBox with $C.@DefaultColorPickerDropdownBoxStyle
Used by: ServerConfig, ChatConfig

This is the compact color picker (swatch button that opens a dropdown picker). More space-efficient than the full ColorPicker for a settings page with many color fields.

.ui template (config_color_entry.ui):

Group {
 LayoutMode: Left;
 Anchor: (Height: 36, Bottom: 4);

 Label #SettingLabel {
 Text: "";
 Anchor: (Width: 200, Height: 28);
 Style: (FontSize: 12, TextColor: $C.@ColorDefaultLabel);
 }

 ColorPickerDropdownBox #ColorPicker {
 Color: "#FFFFFF";
 Style: $C.@DefaultColorPickerDropdownBoxStyle;
 }
}

Java pattern:

cmd.set(idx + " #ColorPicker.Color", currentHexColor);

events.addEventBinding(
 CustomUIEventBindingType.ValueChanged,
 idx + " #ColorPicker",
 EventData.of("Action", "ColorChanged")
 .append("Key", settingKey)
 .append("@Val", idx + " #ColorPicker.Color"),
 false
);

Fields: ServerConfig prefixColor, prefixBracketColor, primaryColor; ChatConfig noFactionTagColor, playerNameColor, relationColorOwn, relationColorAlly, relationColorNeutral, relationColorEnemy, factionChatColor, allyChatColor, senderNameColor, messageColor

---

9. List<String> — Dynamic Add/Remove List (~3 fields)

Element: Dynamic list with entry template + add button
Used by: FactionsConfig worldWhitelist, worldBlacklist; WorldsConfig claimBlacklist

Layout:

┌─ World Whitelist ──────────────────────────┐
│ ┌─────────────────────────────────────┐ │
│ │ world_alpha [x] │ │
│ │ world_beta [x] │ │
│ │ creative_realm [x] │ │
│ └─────────────────────────────────────┘ │
│ │
│ [ Enter world name... ] [+ Add] │
└────────────────────────────────────────────┘

.ui template (config_string_list.ui):

Group {
 LayoutMode: Top;
 Anchor: (Bottom: 8);

 Label #ListLabel {
 Text: "";
 Anchor: (Height: 20);
 Style: (FontSize: 12, TextColor: $C.@ColorDefaultLabel);
 }

 Group #ListContainer {
 LayoutMode: Top;
 Anchor: (Bottom: 4);
 // entries appended here
 }

 Group {
 LayoutMode: Left;
 Anchor: (Height: 32);

 $C.@TextField #AddInput {
 @Anchor = (Width: 280, Height: 28);
 PlaceholderText: "Enter world name...";
 }

 Group { Anchor: (Width: 8); }

 $C.@SecondaryTextButton #AddBtn {
 @Text = "+ Add";
 Anchor: (Width: 80, Height: 28);
 }
 }
}

.ui template (config_string_list_entry.ui):

Group {
 LayoutMode: Left;
 Anchor: (Height: 28, Bottom: 2);
 Background: (Color: #1a2736);
 Padding: (Left: 8, Right: 4);

 Label #EntryText {
 Text: "";
 Anchor: (Height: 28);
 Style: (FontSize: 12, TextColor: $C.@ColorDefault);
 }

 $C.@CancelTextButton #RemoveBtn {
 @Text = "x";
 Anchor: (Width: 28, Height: 24);
 }
}

Java pattern:

private void buildStringList(UICommandBuilder cmd, UIEventBuilder events,
 String listId, String label, List<String> items, String settingKey) {
 cmd.set("#" + listId + " #ListLabel.Text", label);
 cmd.clear("#" + listId + " #ListContainer");

 for (int i = 0; i < items.size(); i++) {
 cmd.append("#" + listId + " #ListContainer", UIPaths.CONFIG_STRING_LIST_ENTRY);
 String idx = "#" + listId + " #ListContainer[" + i + "]";

 cmd.set(idx + " #EntryText.Text", items.get(i));

 events.addEventBinding(
 CustomUIEventBindingType.Activating,
 idx + " #RemoveBtn",
 EventData.of("Action", "ListRemove")
 .append("Key", settingKey)
 .append("Value", items.get(i)),
 false
 );
 }

 // Add button
 events.addEventBinding(
 CustomUIEventBindingType.Activating,
 "#" + listId + " #AddBtn",
 EventData.of("Action", "ListAdd")
 .append("Key", settingKey)
 .append("@NewValue", "#" + listId + " #AddInput.Value"),
 false
 );
}

// Handler:
case "ListAdd" -> {
 String newValue = data.newValue;
 if (newValue != null && !newValue.isBlank()) {
 getConfigList(key).add(newValue.trim());
 refreshPage();
 }
}
case "ListRemove" -> {
 getConfigList(key).remove(data.value);
 refreshPage();
}

Enhancement: For world names, could add a dropdown picker populated from the server's actual world list alongside the text field.

---

10. List<ScalingTier> — Economy Upkeep Tiers (1 field)

Element: Dynamic list with dual fields per entry + add/remove
Used by: EconomyConfig upkeepScalingTiers

This is an ordered list of ScalingTier(int chunkCount, BigDecimal costPerChunk) records, where chunkCount = 0 means "all remaining" (catch-all).

Layout:

┌─ Upkeep Scaling Tiers ──────────────────────────────────┐
│ │
│ Tier 1: Chunks: [10] Cost/Chunk: [$2.00] [x] │
│ Tier 2: Chunks: [15] Cost/Chunk: [$3.00] [x] │
│ Tier 3: Chunks: [0*] Cost/Chunk: [$5.00] [x] │
│ (* 0 = all remaining) │
│ │
│ [+ Add Tier] │
└──────────────────────────────────────────────────────────┘

.ui template (config_tier_entry.ui):

Group {
 LayoutMode: Left;
 Anchor: (Height: 32, Bottom: 4);
 Background: (Color: #1a2736);
 Padding: (Left: 8, Right: 4, Full: 4);

 Label #TierLabel {
 Text: "Tier 1:";
 Anchor: (Width: 50, Height: 28);
 Style: (FontSize: 12, TextColor: $C.@ColorGrayCaption);
 }

 Label { Text: "Chunks:"; Anchor: (Width: 55, Height: 28); Style: (FontSize: 11, TextColor: $C.@ColorGrayCaption); }

 $C.@TextField #ChunkInput {
 @Anchor = (Width: 60, Height: 26);
 PlaceholderText: "0";
 }

 Group { Anchor: (Width: 12); }

 Label { Text: "Cost:"; Anchor: (Width: 40, Height: 28); Style: (FontSize: 11, TextColor: $C.@ColorGrayCaption); }

 $C.@TextField #CostInput {
 @Anchor = (Width: 80, Height: 26);
 PlaceholderText: "0.00";
 }

 Group { Anchor: (Width: 8); }

 $C.@CancelTextButton #RemoveTierBtn {
 @Text = "x";
 Anchor: (Width: 28, Height: 24);
 }
}

Java pattern: Same dynamic list approach as List<String>, but bind ValueChanged/FocusLost on both #ChunkInput and #CostInput with tier index in EventData. On save, rebuild the full List<ScalingTier> from current in-memory state.

---

11. Map<String, WorldSettings> — Per-World Settings (1 field)

Element: Dynamic list with per-world toggle columns
Used by: WorldsConfig worlds

Each world entry has 4 nullable booleans (tri-state: inherit/yes/no) plus a world name (which supports wildcard patterns like instance-%).

Layout:

┌─ Per-World Settings ─────────────────────────────────────────────────┐
│ │
│ World Claiming Power Loss FF Faction FF Ally │
│ ────────────────────────────────────────────────────────────────── │
│ instance-% [No v] [Inherit v] [Inherit v] [Inherit v] │ [x]
│ example-world-abc [Yes v] [Yes v] [No v] [No v] │ [x]
│ │
│ [ Enter world/pattern... ] [+ Add] │
└──────────────────────────────────────────────────────────────────────┘

Each cell is a bare DropdownBox with 3 entries:

List<DropdownEntryInfo> triStateEntries = List.of(
 new DropdownEntryInfo(LocalizableString.fromString("Inherit"), "inherit"),
 new DropdownEntryInfo(LocalizableString.fromString("Yes"), "true"),
 new DropdownEntryInfo(LocalizableString.fromString("No"), "false")
);

Null → "inherit" mapping: WorldSettings uses Boolean (nullable) — null = inherit global default, true = override yes, false = override no. Map "inherit" ↔ null in the handler.

---

12. EnumMap<FactionRole, String> — Role Names (2 fields)

Element: Fixed 3-row layout with $C.@TextField per role
Used by: FactionsConfig roleDisplayNames, roleShortNames

Layout:

┌─ Role Display Names ──────────────────────────────┐
│ │
│ Leader: [ Leader ] Short: [ LD ] │
│ Officer: [ Officer ] Short: [ OF ] │
│ Member: [ Member ] Short: [ MB ] │
│ │
└────────────────────────────────────────────────────┘

Fixed 3 rows (LEADER, OFFICER, MEMBER) — not a dynamic list. Each row has two text fields. Short names validated to 1-4 characters.

---

13. Permission Matrix — Defaults & Locks (1 config file)

Element: Role tab selector + checkbox grid (existing pattern from FactionSettingsPage/AdminFactionSettingsPage)
Used by: FactionPermissionsConfig

Layout:

┌─ Faction Permissions ────────────────────────────────────────────┐
│ │
│ [Outsider] [Ally] [Member] [Officer] ← role selector tabs │
│ │
│ Permission Default Locked │
│ ───────────────────────────────────── │
│ Break [ ] [ ] │
│ Place [ ] [ ] │
│ Interact [x ] [ ] │
│ Door Use [x ] [ ] ← indented child │
│ Container Use [ ] [ ] │
│ Bench Use [ ] [ ] │
│ Processing Use [ ] [ ] │
│ Seat Use [ ] [ ] │
│ Transport Use [ ] [ ] │
│ Crate Use [ ] [ ] │
│ NPC Tame [ ] [ ] │
│ PvE Damage [ ] [ ] │
│ │
│ ── Mob Spawning ── │
│ Enabled [x ] [ ] │
│ Hostile [x ] [ ] │
│ Passive [x ] [ ] │
│ Neutral [x ] [ ] │
│ │
│ ── Treasury ── │
│ Deposit [x ] [ ] │
│ Withdraw [ ] [ ] │
│ Transfer [ ] [ ] │
│ │
│ ── Global ── │
│ PvP Enabled [x ] [ ] │
│ Officers Can Edit [ ] [ ] │
└──────────────────────────────────────────────────────────────────┘

Uses the existing buildToggle() pattern from AdminFactionSettingsPage with parent-child disable logic. Two $C.@CheckBoxWithLabel per row (Default value + Locked toggle). When "Locked" is checked, factions cannot override that permission.

Role tabs use the Tab Navigation pattern (TextButtons with Disabled = true for active state).

---

14. Conditional Visibility — WorldMap Refresh Mode

Several WorldMapConfig fields are only relevant for specific refreshMode values. Use collapsible/conditional sections that show/hide based on the selected mode:

// After dropdown change or on build:
boolean isProximity = "proximity".equals(currentMode);
boolean isIncremental = "incremental".equals(currentMode);
boolean isDebounced = "debounced".equals(currentMode);

cmd.set("#ProximitySettings.Visible", isProximity);
cmd.set("#IncrementalSettings.Visible", isIncremental);
cmd.set("#DebouncedSettings.Visible", isDebounced);

Section	Visible When	Fields
Proximity Settings	refreshMode = proximity	proximityChunkRadius, proximityBatchIntervalTicks, proximityMaxChunksPerBatch
Incremental Settings	refreshMode = incremental	incrementalBatchIntervalTicks, incrementalMaxChunksPerBatch
Debounced Settings	refreshMode = debounced	debouncedDelaySeconds
(always visible)	any mode	showFactionTags, autoFallbackOnError, factionWideRefreshThreshold, all player visibility fields

---

Shared Helper Architecture

To avoid duplicating code across 11 sub-pages, implement a generic config field renderer:

public class ConfigFieldRenderer {
 // Dispatches to the correct builder based on field metadata
 public static int renderField(UICommandBuilder cmd, UIEventBuilder events,
 String containerId, int index,
 ConfigFieldMeta field, Object currentValue) {
 return switch (field.type()) {
 case BOOLEAN -> buildToggle(cmd, events, containerId, index, field, (boolean) currentValue);
 case INT_RANGE -> buildSlider(cmd, events, containerId, index, field, (int) currentValue);
 case DOUBLE_RANGE -> buildSliderDouble(cmd, events, containerId, index, field, (double) currentValue);
 case BIG_DECIMAL -> buildCurrency(cmd, events, containerId, index, field, (BigDecimal) currentValue);
 case STRING -> buildText(cmd, events, containerId, index, field, (String) currentValue);
 case ENUM_SELECT -> buildDropdown(cmd, events, containerId, index, field, (String) currentValue);
 case HEX_COLOR -> buildColorPicker(cmd, events, containerId, index, field, (String) currentValue);
 case STRING_LIST -> buildStringList(cmd, events, containerId, index, field, (List<String>) currentValue);
 // ...
 };
 }
}

Each config sub-page would define its fields as List<ConfigFieldMeta> with type, key, label, constraints, and call the shared renderer. This keeps the 11 sub-pages thin (field definitions only) while centralizing all the CustomUI wiring.

---

Modified Value Highlighting

Track in-memory changes in a Set<String> modifiedKeys. When rendering any field, if the key is in the modified set, add a visual indicator:

if (modifiedKeys.contains(settingKey)) {
 cmd.set(idx + " #SettingLabel.Style.TextColor", "#FFAA00"); // orange = modified
} else {
 cmd.set(idx + " #SettingLabel.Style.TextColor", "#" + ColorDefault); // normal
}

Reset the set on Save or Revert.