votersrights

votersrights

Let eligible players approve server actions together. One proposal at a time, clear thresholds, configurable voter lists, and optional custom vote actions.

Built for Paper 26.3 / Java 25. No runtime dependencies.

In game: use /help votersrights for the full guide. Players see voting help; users with votersrights.admin also see the admin commands and settings. The guide ends with clickable links to GitHub and the issue tracker.

Contents

• Quick start
• Voting rules
• Built-in actions
• Commands
• Permissions and eligibility
• Admin settings
• Custom vote actions
• Saved actions and limitations
• Install
• Links and support

Quick start

1. Ensure the required number of eligible players is online (default: 3).
2. A player runs /vote setTimeNight or another enabled action. The proposer automatically casts a yes ballot.
3. Other eligible players run /vote yes or /vote no, or click the vote buttons in chat.
4. The action runs as soon as yes votes reach the configured threshold. If it does not pass in 60 seconds, the vote fails.

Use /vote at any time to see the current tally or, when no vote is active, the enabled actions.

Voting rules

• Only one server-wide vote can be active. It lasts 60 seconds.
• The eligible online players at the start form a fixed electorate. Joining later does not add a voter; leaving does not remove a ballot. A voter who reconnects can still cast a ballot if they have not voted already.
• The default threshold is 50% of the electorate, rounded up. For example, 2 yes votes are needed out of 3 or 4, and 3 out of 5. Abstentions are not yes votes.
• Each eligible voter can submit one ballot. Votes cannot be changed. The proposal creator automatically votes yes.
• Votes are checked once per second as well as on ballot changes; a vote ends immediately when it passes, otherwise at expiry.
• A passed restart or timeout enters a warning period. No new vote can start until that pending action begins.
• Successful admin edits and reloads cancel an active vote. Passed delayed actions remain saved.

Built-in actions

Names are case-insensitive. Tab completion lists currently enabled actions.

Distance votes change current world settings, not server.properties or Paper configuration files; server settings can restore distances after a restart. Per-player/client limits may still reduce what a player sees. A distance proposal is rejected if no world would change. If a world's current distance is outside the configured range, the next vote clamps it into range, potentially moving farther than two chunks or correcting in the opposite direction.

Commands

Admin commands require votersrights.admin when run by a player. Configuration changes are validated before saving and applying; failed saves or invalid settings leave active settings unchanged and errors are reported. show prints the full configuration, including action toggles and custom commands.

Permissions and eligibility

Blacklist always takes precedence. When whitelist-enabled: true, a player must also be in the whitelist. The votersrights.vote permission is still required even when listed. Both lists store UUIDs; admin commands accept an online name, a locally cached name, or a UUID. There is no remote name lookup.

Admin settings

Admin commands write to plugins/votersrights/config.yml and apply immediately. Manual edits require /votersrights reload. Configuration must use the correct types and values; invalid startup configuration prevents the plugin from enabling, while a failed reload keeps the previous active settings.

Distance lower and upper bounds must be coordinated: raise the maximum before raising the minimum above it; lower the minimum before lowering the maximum below it. Successful setting changes cancel an in-progress vote. Existing timeout durations and protection windows are not retroactively changed; a queued restart uses the cooldown setting in effect when it executes.

Custom vote actions

Administrators may expose fixed console commands as player-votable actions. For example:

/votersrights action add announcement say The players have voted!
/vote announcement
/votersrights allow announcement false
/votersrights action remove announcement

The first command makes an enabled announcement action. A passing proposal executes the command as the console. Repeating action add appends another command and all commands run in order. The equivalent configuration is:

custom-actions:
  announcement:
    enabled: true
    commands:
      - "say The players have voted!"

Names must start with a lowercase letter, use only lowercase letters, digits, _ or -, and be at most 32 characters. Built-in action names and yes/no are reserved. Commands must be fixed text, without a leading slash, line breaks, braces/placeholders, or player-supplied arguments. Only add trusted commands: these run with console privileges and can intentionally bypass built-in safeguards. If a command is unhandled, execution stops with an explicit failure; already-run commands are not rolled back. A command handler that reports success is responsible for its actual outcome.

Saved actions and limitations

Restart warnings, cooldown timestamps, and timeout/protection records are saved atomically in plugins/votersrights/state.yml and survive server restarts. They use wall-clock time. A pending warning resumes from its original deadline; an overdue restart executes on the next scheduler tick. The restart cooldown is saved before dispatching the native console restart command. Configure and test your Paper restart script or host first: an unhandled restart is reported, but this plugin cannot make a host restart if its setup does not support the command, and the cooldown remains in place.

Timeouts use UUID state and do not change or overwrite the server ban list. Logging out during the 30-second warning does not avoid the timeout. The target must still be online when the vote passes; the timeout prevents login for its duration. Protection starts at the end of the timeout, whether or not the player reconnects. There is no automatic immunity for admins.

Install

1. Download votersrights from Hangar.
2. Put votersrights-0.2.0.jar into the Paper server's plugins/ directory and restart.
3. Java 25 is required by the server. Grant votersrights.admin only to trusted administrators; review custom console commands carefully.

Links and support

• Source and full guide: GitHub repository
• Download: Hangar project
• Report a bug or request a feature: GitHub issues

./gradlew build --console=plain

./gradlew build publishPluginPublicationToHangar syncAllPluginPublicationPagesToHangar \
  -PhangarChangelog="Describe this release"