MayorSystem

MayorSystem is a Paper 1.21+ plugin that runs server elections, crowns a mayor, and lets that mayor pick server-wide perks. It includes optional displays (NPC or hologram), sell bonuses, and full admin tooling.

MIT License This project is licensed under the MIT License. See LICENSE for full terms.

At a Glance

• Scheduled terms with a configurable vote window (ISO-8601 durations)
• Candidate applications with playtime and cost requirements
• Perk catalog with sections, pick limits, and custom perk requests
• Bonus terms every N terms
• Public toggle and pause modes to selectively freeze systems
• Per-event broadcast configuration (election open, mayor elected, apply/vote activity) with CHAT/TITLE/BOTH modes
• Sell bonuses (SystemSellAddon integration)
• Skyblock-style perk mechanics via SystemSkyblockStyleAddon (optional)
• Mayor NPC statue and optional leaderboard hologram (DecentHolograms or FancyHolograms)
• Status screen election top-3 card with full ranking view, name search, and sorting
• Admin menus, audit log, health checks, and force-election tools
• Separate messages.yml and gui.yml customization files
• Missing config.yml, messages.yml, and gui.yml keys are restored automatically on startup/reload without overwriting custom values
• Robust LuckPerms integration with auto-group creation and async operations (see LuckPerms Setup Guide)
• MiniMessage formatting with optional PlaceholderAPI

Screenshots

How Elections Work (30-second overview)

• Terms run on a schedule starting at term.first_term_start.
• The vote window opens term.vote_window before a term starts.
• Players apply to be candidates if they meet playtime and cost requirements.
• Players vote, a mayor is elected, and the mayor picks perks for the term.
• Bonus terms can grant extra perks every N terms.

Display: Mayor NPC + Leaderboard Hologram

MayorSystem supports two optional displays that can be used together or in rotation.

Mayor NPC (Citizens or FancyNpcs)

• Spawn/move: /%title_command% admin npc spawn (fallback: /mayor admin npc spawn)
• Remove: /%title_command% admin npc remove (fallback: /mayor admin npc remove)
• Force update: /%title_command% admin npc update (fallback: /mayor admin npc update)

Leaderboard Hologram (DecentHolograms or FancyHolograms)

• Spawn/move: /%title_command% admin hologram spawn (fallback: /mayor admin hologram spawn)
• Remove: /%title_command% admin hologram remove (fallback: /mayor admin hologram remove)
• Force update: /%title_command% admin hologram update (fallback: /mayor admin hologram update)

The hologram backend can be pinned with hologram.leaderboard.provider or left on auto.

Showcase Mode

Set how displays behave in config.yml:

• showcase.mode: SWITCHING will show the hologram during elections and the NPC once a mayor is elected.
• showcase.mode: INDIVIDUAL keeps each display active at its own location.

In SWITCHING mode, if no mayor is elected yet, the hologram stays active. The hologram uses the NPC location in this mode.

You can also switch mode in-game:

• /%title_command% admin display mode <switching|individual> (fallback: /mayor admin display mode <switching|individual>)

SystemSellAddon Integration (Recommended)

SystemSellAddon applies MayorSystem sell bonuses directly to /sell payouts.

• Bonuses stack on top of SystemSellAddon payouts
• Category and total bonuses are passed through cleanly
• Bonus messages are pulled from messages.yml (key: public.sell_bonus)

On first start with SystemSellAddon installed, MayorSystem imports mayor-perks into perks.sections.economy in its own config.yml so menus read from a single source. Delete that section to re-sync from SystemSellAddon.

SystemSkyblockStyleAddon Integration

MayorSystem can drive the Skyblock-style perk mechanics provided by SystemSkyblockStyleAddon (also referred to as SystemSkyblockStyleSystem). Enable the skyblock_style section in config.yml, elect a mayor, and the addon will apply mechanics for any active perks.

On first start with SystemSkyblockStyleAddon installed, MayorSystem imports perk display data into perks.sections.skyblock_style in its own config.yml so menus read from a single source. Delete that section to re-sync from the addon.

Requirements

• Paper 1.21+ (API 1.21)
• Java 21

Quick Start

1. Drop the jar into plugins/ and start the server once.
2. Set the first term start from the admin UI or command before the first term begins. Example: /%title_command% admin settings first_term_start 2026-03-01T00:00:00-05:00 (fallback: /mayor admin settings first_term_start 2026-03-01T00:00:00-05:00).
3. (Optional) If using LuckPerms (recommended for mayor prefix/group management), see LuckPerms Setup Guide for quick configuration.
4. (Optional) Adjust term.length, term.vote_window, term.perks_per_term, and election.broadcast settings.
5. (Optional) Install integrations (Vault + a compatible economy plugin, Citizens/FancyNpcs, LuckPerms, SystemSellAddon, SystemSkyblockStyleAddon, PlaceholderAPI, DecentHolograms or FancyHolograms).
6. Join in-game and run /%title_command% (fallback: /mayor).
7. Use admin menus/commands for common settings. Edit config.yml, messages.yml, and gui.yml only for advanced customization.

If you install SystemSellAddon or SystemSkyblockStyleAddon, MayorSystem will import those perk definitions into plugins/MayorSystem/config.yml on first start. Edit them there afterward, or delete the section to re-sync.

Configuration Auto-Sync:

• On startup and reload, MayorSystem automatically adds any missing keys from config.yml, messages.yml, and gui.yml defaults without overwriting your custom values.
• This means updates adding new config options won't require manual edits to your existing files.

Tips:

• The default term.first_term_start is set far in the future so nothing starts until you set it.
• term.first_term_start is locked once the server has reached term #1. Resetting election data moves it back to the far-future default so it cannot immediately restart.
• Use /%title_command% admin reload to test config changes immediately (config.yml sync runs on reload).
• If missing config keys are added during reload, check the server console for "Config sync" messages.

Commands

Public / Player

/%title_command%   # fallback: /mayor
/%title_command% status   # fallback: /mayor status
/%title_command% apply   # fallback: /mayor apply
/%title_command% vote <candidate>   # fallback: /mayor vote <candidate>
/%title_command% vote   # fallback: /mayor vote; opens the vote menu
/%title_command% candidate   # fallback: /mayor candidate
/%title_command% stepdown   # fallback: /mayor stepdown

Admin: Core

/%title_command% admin   # fallback: /mayor admin
/%title_command% admin system   # fallback: /mayor admin system
/%title_command% admin system toggle   # fallback: /mayor admin system toggle
/%title_command% admin system refresh_offline_cache   # fallback: /mayor admin system refresh_offline_cache

Admin: Display

/%title_command% admin display   # fallback: /mayor admin display
/%title_command% admin display mode <switching|individual>   # fallback: /mayor admin display mode <switching|individual>

Admin: Display Reward

/%title_command% admin reward   # fallback: /mayor admin reward
/%title_command% admin reward tracks   # fallback: /mayor admin reward tracks
/%title_command% admin reward groups   # fallback: /mayor admin reward groups
/%title_command% admin reward users   # fallback: /mayor admin reward users
/%title_command% admin reward tag_icon   # fallback: /mayor admin reward tag_icon
/%title_command% admin reward open <main|tracks|groups|users|tag|tag_icon|health>   # fallback: /mayor admin reward open <main|tracks|groups|users|tag|tag_icon|health>
/%title_command% admin reward health   # fallback: /mayor admin reward health
/%title_command% admin reward sync   # fallback: /mayor admin reward sync
/%title_command% admin reward default <RANK|TAG|BOTH>   # fallback: /mayor admin reward default <RANK|TAG|BOTH>
/%title_command% admin reward list   # fallback: /mayor admin reward list
/%title_command% admin reward list <track|group|user>   # fallback: /mayor admin reward list <track|group|user>
/%title_command% admin reward inspect <track|group|user> <target>   # fallback: /mayor admin reward inspect <track|group|user> <target>
/%title_command% admin reward add <track|group|user> <target> <RANK|TAG|BOTH>   # fallback: /mayor admin reward add <track|group|user> <target> <RANK|TAG|BOTH>
/%title_command% admin reward edit <track|group|user> <target> <RANK|TAG|BOTH>   # fallback: /mayor admin reward edit <track|group|user> <target> <RANK|TAG|BOTH>
/%title_command% admin reward remove <track|group|user> <target>   # fallback: /mayor admin reward remove <track|group|user> <target>
/%title_command% admin reward rank group <group>   # fallback: /mayor admin reward rank group <group>
/%title_command% admin reward tag id <id>   # fallback: /mayor admin reward tag id <id>
/%title_command% admin reward tag display <text>   # fallback: /mayor admin reward tag display <text>
/%title_command% admin reward tag description <text>   # fallback: /mayor admin reward tag description <text>
/%title_command% admin reward tag before_rank <true|false>   # fallback: /mayor admin reward tag before_rank <true|false>
/%title_command% admin reward tag icon   # fallback: /mayor admin reward tag icon
/%title_command% admin reward tag icon material <material>   # fallback: /mayor admin reward tag icon material <material>
/%title_command% admin reward tag icon reset   # fallback: /mayor admin reward tag icon reset
/%title_command% admin reward tag icon custom_model_data <clear|reset|0|number>   # fallback: /mayor admin reward tag icon custom_model_data <clear|reset|0|number>
/%title_command% admin reward tag icon glint   # fallback: /mayor admin reward tag icon glint

Admin: NPC

/%title_command% admin npc spawn   # fallback: /mayor admin npc spawn
/%title_command% admin npc remove   # fallback: /mayor admin npc remove
/%title_command% admin npc update   # fallback: /mayor admin npc update

Admin: Hologram (DecentHolograms or FancyHolograms)

/%title_command% admin hologram spawn   # fallback: /mayor admin hologram spawn
/%title_command% admin hologram remove   # fallback: /mayor admin hologram remove
/%title_command% admin hologram update   # fallback: /mayor admin hologram update

Admin: Governance

/%title_command% admin governance   # fallback: /mayor admin governance

Admin: Fake Votes

/%title_command% admin election fakevotes   # fallback: /mayor admin election fakevotes

Admin: Messaging

/%title_command% admin messaging   # fallback: /mayor admin messaging

Admin: Monitoring

/%title_command% admin monitoring   # fallback: /mayor admin monitoring
/%title_command% admin audit   # fallback: /mayor admin audit
/%title_command% admin health   # fallback: /mayor admin health

Admin: Maintenance

/%title_command% admin maintenance   # fallback: /mayor admin maintenance
/%title_command% admin debug   # fallback: /mayor admin debug
/%title_command% admin reload   # fallback: /mayor admin reload
/%title_command% admin settings reload   # fallback: /mayor admin settings reload

Admin: Candidates

/%title_command% admin candidates   # fallback: /mayor admin candidates
/%title_command% admin candidates remove <player>   # fallback: /mayor admin candidates remove <player>
/%title_command% admin candidates restore <player>   # fallback: /mayor admin candidates restore <player>
/%title_command% admin candidates process <player>   # fallback: /mayor admin candidates process <player>
/%title_command% admin candidates applyban   # fallback: /mayor admin candidates applyban
/%title_command% admin candidates applyban perm <player>   # fallback: /mayor admin candidates applyban perm <player>
/%title_command% admin candidates applyban temp <player> <days>   # fallback: /mayor admin candidates applyban temp <player> <days>
/%title_command% admin candidates applyban clear <player>   # fallback: /mayor admin candidates applyban clear <player>

Admin: Perks

/%title_command% admin perks   # fallback: /mayor admin perks
/%title_command% admin perks refresh   # fallback: /mayor admin perks refresh
/%title_command% admin perks refresh <player|--all|all>   # fallback: /mayor admin perks refresh <player|--all|all>
/%title_command% admin perks requests   # fallback: /mayor admin perks requests
/%title_command% admin perks requests approve <id>   # fallback: /mayor admin perks requests approve <id>
/%title_command% admin perks requests deny <id>   # fallback: /mayor admin perks requests deny <id>
/%title_command% admin customperk <id> <approve|deny>   # fallback: /mayor admin customperk <id> <approve|deny>
/%title_command% admin perks catalog   # fallback: /mayor admin perks catalog
/%title_command% admin perks catalog section <section> <toggle|on|off>   # fallback: /mayor admin perks catalog section <section> <toggle|on|off>
/%title_command% admin perks catalog perk <section> <perk> <toggle|on|off>   # fallback: /mayor admin perks catalog perk <section> <perk> <toggle|on|off>

Admin: Election

/%title_command% admin election   # fallback: /mayor admin election
/%title_command% admin election start   # fallback: /mayor admin election start
/%title_command% admin election end   # fallback: /mayor admin election end
/%title_command% admin election clear   # fallback: /mayor admin election clear
/%title_command% admin election elect   # fallback: /mayor admin election elect
/%title_command% admin election elect set <player>   # fallback: /mayor admin election elect set <player>
/%title_command% admin election elect clear   # fallback: /mayor admin election elect clear
/%title_command% admin election elect now <player>   # fallback: /mayor admin election elect now <player>

Admin: Settings (menu shortcuts)

/%title_command% admin settings   # fallback: /mayor admin settings
/%title_command% admin settings enabled   # fallback: /mayor admin settings enabled
/%title_command% admin settings public_enabled   # fallback: /mayor admin settings public_enabled
/%title_command% admin settings pause_enabled   # fallback: /mayor admin settings pause_enabled
/%title_command% admin settings mayor_group   # fallback: /mayor admin settings mayor_group
/%title_command% admin settings enable_options   # fallback: /mayor admin settings enable_options
/%title_command% admin settings pause_options   # fallback: /mayor admin settings pause_options
/%title_command% admin settings display   # fallback: /mayor admin settings display
/%title_command% admin settings display_reward   # fallback: /mayor admin settings display_reward
/%title_command% admin settings term_length   # fallback: /mayor admin settings term_length
/%title_command% admin settings vote_window   # fallback: /mayor admin settings vote_window
/%title_command% admin settings first_term_start   # fallback: /mayor admin settings first_term_start
/%title_command% admin settings perks_per_term   # fallback: /mayor admin settings perks_per_term
/%title_command% admin settings election   # fallback: /mayor admin settings election
/%title_command% admin settings term_extras   # fallback: /mayor admin settings term_extras
/%title_command% admin settings bonus_enabled   # fallback: /mayor admin settings bonus_enabled
/%title_command% admin settings bonus_every   # fallback: /mayor admin settings bonus_every
/%title_command% admin settings bonus_perks   # fallback: /mayor admin settings bonus_perks
/%title_command% admin settings playtime_minutes   # fallback: /mayor admin settings playtime_minutes
/%title_command% admin settings apply_cost   # fallback: /mayor admin settings apply_cost
/%title_command% admin settings custom_limit   # fallback: /mayor admin settings custom_limit
/%title_command% admin settings custom_condition   # fallback: /mayor admin settings custom_condition
/%title_command% admin settings chat_prompts   # fallback: /mayor admin settings chat_prompts
/%title_command% admin settings broadcasts   # fallback: /mayor admin settings broadcasts

Admin: Settings (direct commands)

/%title_command% admin settings enabled <true|false>   # fallback: /mayor admin settings enabled <true|false>
/%title_command% admin settings public_enabled <true|false>   # fallback: /mayor admin settings public_enabled <true|false>
/%title_command% admin settings pause_enabled <true|false>   # fallback: /mayor admin settings pause_enabled <true|false>
/%title_command% admin settings mayor_group_enabled <true|false>   # fallback: /mayor admin settings mayor_group_enabled <true|false>
/%title_command% admin settings mayor_group <group>   # fallback: /mayor admin settings mayor_group <group>
/%title_command% admin settings enable_options <option>   # fallback: /mayor admin settings enable_options <option>
/%title_command% admin settings pause_options <option>   # fallback: /mayor admin settings pause_options <option>
/%title_command% admin settings term_length <ISO-8601 duration>   # fallback: /mayor admin settings term_length <ISO-8601 duration>
/%title_command% admin settings vote_window <ISO-8601 duration>   # fallback: /mayor admin settings vote_window <ISO-8601 duration>
/%title_command% admin settings first_term_start <OffsetDateTime>   # fallback: /mayor admin settings first_term_start <OffsetDateTime>
/%title_command% admin settings perks_per_term <int>   # fallback: /mayor admin settings perks_per_term <int>
/%title_command% admin settings election_timing <while_term|after_term>   # fallback: /mayor admin settings election_timing <while_term|after_term>
/%title_command% admin settings bonus_enabled <true|false>   # fallback: /mayor admin settings bonus_enabled <true|false>
/%title_command% admin settings bonus_every <int>   # fallback: /mayor admin settings bonus_every <int>
/%title_command% admin settings bonus_perks <int>   # fallback: /mayor admin settings bonus_perks <int>
/%title_command% admin settings playtime_minutes <int>   # fallback: /mayor admin settings playtime_minutes <int>
/%title_command% admin settings apply_cost <number>   # fallback: /mayor admin settings apply_cost <number>
/%title_command% admin settings custom_limit <int>   # fallback: /mayor admin settings custom_limit <int>
/%title_command% admin settings custom_condition <NONE|ELECTED_ONCE|APPLY_REQUIREMENTS>   # fallback: /mayor admin settings custom_condition <NONE|ELECTED_ONCE|APPLY_REQUIREMENTS>
/%title_command% admin settings chat_prompts <bio|title|description> <int>   # fallback: /mayor admin settings chat_prompts <bio|title|description> <int>
/%title_command% admin settings chat_prompt_timeout <int>   # fallback: /mayor admin settings chat_prompt_timeout <int>
/%title_command% admin settings broadcasts enabled <true|false>   # fallback: /mayor admin settings broadcasts enabled <true|false>
/%title_command% admin settings broadcasts mode <chat|title|both>   # fallback: /mayor admin settings broadcasts mode <chat|title|both>
/%title_command% admin settings broadcasts event <vote|apply> <disabled|chat|title|both>   # fallback: /mayor admin settings broadcasts event <vote|apply> <disabled|chat|title|both>
/%title_command% admin settings allow_vote_change <true|false>   # fallback: /mayor admin settings allow_vote_change <true|false>
/%title_command% admin settings tie_policy <SEEDED_RANDOM|INCUMBENT|EARLIEST_APPLICATION|ALPHABETICAL>   # fallback: /mayor admin settings tie_policy <SEEDED_RANDOM|INCUMBENT|EARLIEST_APPLICATION|ALPHABETICAL>
/%title_command% admin settings mayor_stepdown <OFF|NO_MAYOR|KEEP_MAYOR>   # fallback: /mayor admin settings mayor_stepdown <OFF|NO_MAYOR|KEEP_MAYOR>
/%title_command% admin settings stepdown_reapply <true|false>   # fallback: /mayor admin settings stepdown_reapply <true|false>
/%title_command% admin settings reload   # fallback: /mayor admin settings reload

Permissions

Wildcards / Aggregates

Player

Admin

Admin panel access is feature-permission driven now. A staff member can open /%title_command% admin if they have mayor.admin.access or any admin action node, but they will only see and be able to open the sections/actions they actually have permission for.

Menus (GUI)

Public / Player

• MainMenu: entry point + quick status
• StatusMenu: term timeline + election window + clickable top-3 election card
• ElectionRankingMenu: full election ranking with vote-count sorting and name filtering
• VoteMenu / VoteConfirmMenu: pick + confirm a vote
• CandidateMenu: candidate hub
• CandidatePerkCatalogMenu / CandidatePerkSectionMenu / CandidatePerksViewMenu
• CandidateCustomPerksMenu: request custom perks
• ApplySectionsMenu / ApplyPerksMenu / ApplyConfirmMenu
• StepDownConfirmMenu
• MayorProfileMenu (opened from the Mayor NPC)

Admin

• AdminMenu: staff home
• AdminDebugMenu (reload, offline cache, reset)
• AdminMonitoringMenu / AdminAuditMenu / AdminHealthMenu
• AdminCandidatesMenu / ConfirmRemoveCandidateMenu
• AdminApplyBanSearchMenu / AdminApplyBanTypeMenu / AdminApplyBanDurationMenu
• AdminPerksMenu / AdminPerkCatalogMenu / AdminPerkSectionMenu / AdminPerkRequestsMenu / AdminPerkRefreshMenu
• AdminElectionMenu / AdminElectionSettingsMenu / AdminFakeVotesMenu / AdminFakeVoteAdjustMenu
• AdminForceElectMenu / AdminForceElectSectionsMenu / AdminForceElectPerksMenu / AdminForceElectConfirmMenu
• AdminSettingsMenu / AdminSettingsGeneralMenu / AdminSettingsEnableOptionsMenu / AdminSettingsPauseOptionsMenu
• AdminSettingsTermMenu / AdminBonusTermMenu / GovernanceSettingsMenu
• AdminSettingsApplyMenu / AdminSettingsCustomRequestsMenu / AdminSettingsChatPromptsMenu / AdminBroadcastSettingsMenu
• AdminSettingsMayorGroupMenu / AdminDisplayRewardTargetsMenu / AdminDisplayRewardTargetRemoveConfirmMenu / AdminDisplayRewardTagIconMenu
• AdminMessagingMenu
• AdminDisplayMenu (NPC + hologram controls)
• AdminResetElectionConfirmMenu

Configuration Highlights

• enabled: Master switch for the plugin.
• public_enabled: Toggle the system for regular players while keeping admin access.
• title.name: Role display name used across menus/messages (example: Mayor -> King).
• title.command_alias_enabled: Enables dynamic alias routing from /<sanitized title.name> to /mayor. Sanitization compatibility-normalizes unusual Unicode letter forms (such as fullwidth/circled letters and small-cap variants), keeps lowercase a-z only, and removes other characters. /mayor always remains available.
• title.player_prefix, title.chat_prefix: MiniMessage templates with %title_name% / %title_command% tokens.
• title.username_group_enabled, title.username_group: Assign the elected player to a LuckPerms group. MayorSystem auto-creates the group if missing; usually the only external setup is LuckPerms meta-formatting plus any prefix/meta you want on that group.
• display_reward.*: Display Reward settings for Rank, Tag, or Rank + Tag mayor rewards. Rank uses LuckPerms group membership; Tag uses DeluxeTags with DeluxeTags.Tag.<tagId> granted through LuckPerms.
• display_reward.targets.tracks, display_reward.targets.groups, display_reward.targets.users: Reward Mode overrides. Resolution order is user, group, track, then the global Reward Mode.
• Name tokens are split between compatibility-safe raw names and formatted display names: %mayor_name%, %player_name%, and %candidate_name% stay raw for older configs; %mayor_display_name%, %player_display_name%, and %candidate_display_name% include MayorSystem/LuckPerms display formatting when available, and the bundled defaults now use the display-name variants.
• enable_options: Select which subsystems are affected when enabled=false.
• pause.enabled: Pause scheduling without disabling the plugin.
• pause.options: Select which subsystems are affected when paused.
• term.length, term.vote_window, term.first_term_start, term.perks_per_term: Core term settings.
• term.first_term_start can be changed only before term #1; after that, use election/admin controls instead of rewriting history.
• term.bonus_term.*: Bonus term settings.
• apply.playtime_minutes, apply.cost: Candidate requirements.
• election.allow_vote_change, election.tie_policy, election.mayor_stepdown, election.stepdown.allow_reapply.
• Fake votes are stored separately from real votes and are added on top of real totals for ranking, displays, and winner selection.
• sell_bonus.*: Sell-bonus stacking rules (consumed by SystemSellAddon).
• custom_requests.*: Custom perk request limits and conditions.
• perks.command_execution.enable_console_commands: If false, non-effect perk commands are never dispatched from console.
• perks.command_execution.allow_roots: Allowlist for dangerous command roots that are blocked by default.
• showcase.*, npc.*, hologram.*: Display settings, including npc.mayor.provider and hologram.leaderboard.provider backend selection.
• data.store.*: SQLite or MySQL storage.
• Store startup fails closed. MayorSystem will not silently fall back from MySQL to SQLite if the configured backend cannot load.

Subsystem options for enable_options and pause.options: SCHEDULE, ACTIONS, PERKS, MAYOR_NPC, BROADCASTS.

Configuration Examples

• These files mirror the current shipped defaults in src/main/resources/.
• Example config.yml
• Example messages.yml
• Example gui.yml
• LuckPerms setup guide

Dependencies & Integrations

Required

• Paper 1.21+ (API 1.21)
• Java 21

Optional (auto-detected)

• Vault (economy bridge + optional NPC chat-prefix lookup)
• Vault-compatible economy plugin (economy provider, e.g., EssentialsX Economy)
• Citizens or FancyNpcs (Mayor NPC)
• SystemSellAddon (sell bonus integration)
• SystemSkyblockStyleAddon (Skyblock-style perk mechanics)
• PlaceholderAPI (placeholders in messages + broadcasts)
• LuckPerms (elected-player group integration)
• DecentHolograms or FancyHolograms (leaderboard hologram)

For the recommended additive rank/tag setup with MayorSystem, see docs/LUCKPERMS_SETUP.md.

Data Storage

• data.store.type = sqlite or mysql
• SQLite file: elections.db
• MySQL settings live under data.store.mysql in config.yml
• New configs ship MySQL user and password as CHANGE_ME. If MySQL is selected with blank or placeholder credentials, MayorSystem stops during startup instead of accepting production data into the wrong backend.
• Backend load failures are fail-closed by design. Fix the configured backend rather than expecting automatic fallback.
• Do not edit SQLite/MySQL data directly for normal operation. Use admin commands/menus for election changes, and back up data before switching storage backends.

PlaceholderAPI

If PlaceholderAPI is installed, MayorSystem registers these placeholders:

• %mayorsystem_title_name% -> configured title name
• %mayorsystem_title_name_lower% -> lowercase configured title name
• %mayorsystem_title_display% -> legacy-color formatted title display/prefix
• %mayorsystem_title_tag% -> legacy &6[Title] tag
• %mayorsystem_leaderboard_term% -> current election term number (1-based)
• %mayorsystem_leaderboard_<pos>_name% -> raw candidate name at position <pos> (legacy-safe)
• %mayorsystem_leaderboard_<pos>_display_name% -> formatted candidate display name at position <pos> (used by the bundled defaults)
• %mayorsystem_leaderboard_<pos>_votes% -> vote count at position <pos>
• %mayorsystem_leaderboard_<pos>_uuid% -> candidate UUID at position <pos>

<pos> starts at 1. If there is no candidate at that position, the placeholder returns an empty string.

Support & Troubleshooting

• Use /%title_command% admin maintenance (fallback: /mayor admin maintenance) or /%title_command% admin debug (fallback: /mayor admin debug) for maintenance tools.
• Reload requires mayor.admin.maintenance.reload (or mayor.admin.settings.reload).
• Offline cache refresh / reset election requires mayor.admin.maintenance.debug.
• Use /%title_command% admin monitoring (fallback: /mayor admin monitoring) or /%title_command% admin health (fallback: /mayor admin health) for a full environment check.
• Health includes LuckPerms integration checks: plugin enabled, API service available, configured group exists, and elected mayor group node state.
• Admin menus and direct admin-open routes are permission-filtered. Staff only see sections they can access, and direct submenu opens are revalidated against the same feature permissions.
• Menu clicks are permission-revalidated; if a player's relevant perms change while a menu is open, actions are denied and the menu is closed.
• Use /%title_command% admin audit (fallback: /mayor admin audit) to see who changed what.
• Check config.yml and messages.yml for customization.
• Check gui.yml for menu titles, buttons, lore, and layout text customization.
• Use messages.yml -> styles.* to retheme warning/error/success colors from one place.
• Missing keys in messages.yml and gui.yml are restored automatically during startup/reload without overwriting your existing custom entries.
• If NPCs or holograms do not show, confirm the integration plugin is installed and enabled, then run /%title_command% admin health (fallback: /mayor admin health).

Build (for developers)

./gradlew clean jar

This produces the thin upload jar in build/libs/ (no shaded dependencies). Runtime dependencies are downloaded by Paper/Spigot from plugin.yml -> libraries at server startup. Use MayorSystem-<version>.jar for server installs and Spigot uploads.

Optional local fat jar (not for upload):

./gradlew shadowJar

This produces MayorSystem-<version>-all.jar for local/offline testing only.

License

This project is licensed under the MIT License.

Copyright (c) 2026 L1cked

See LICENSE for the full text.