mc-voting-polls

Testet only on mc version 1.21.11

flexible in-game voting and polling system for Bukkit/Spigot/Paper servers.
Admins can create command-based polls, while regular players can create restricted, silent polls from admin-approved templates. Polls are displayed in a GUI, support repetition, reminders, persistence, and multilingual messages.

---

Features

• In-game YES / NO voting
• Admin-controlled polls with full configuration
• Player-created polls limited to whitelisted templates
• Optional repeating polls
• Silent polls (no broadcast or reminders)
• GUI-based poll list and detailed view
• Persistent storage (survives restarts)
• Configurable reminders
• Language and message customization
• Vote history tracking

---

Installation

1. Place the plugin JAR into the plugins/ folder

2. Start the server once to generate config files

3. Configure:

   • config.yml
   • lang.yml
   • polls.yml
   • history.yml

4. Reload configuration with:

   /votepoll reload
   

---

Core Concepts

Poll

A poll represents a vote with the following properties:

• Unique ID (random or specified)
• Display name
• Description
• Console command to execute on success
• Duration (seconds)
• Minimum YES / NO votes
• Optional repeat interval
• Silent flag
• Creator (player, admin, or console)

Supported command placeholders:

• {target}
• {creator}

---

Templates (customCommands)

Poll templates defined in config.yml.
They are reusable and safe predefined commands.

Only templates listed in playerAllowedCommands can be used by non-admin players.

---

Player-Created Polls

• Can only be created from allowed templates
• Always receive a random poll ID
• Always silent
• No global notifications or reminders
• Visible only via GUI

Example:

/votepoll add example_ban --target=RareHuman

---

Admin-Created Polls

• Full control over all poll parameters
• Can broadcast to players
• Can send reminders
• Can be repeating or silent
• Can specify custom IDs

---

Commands

Player Commands

Open poll GUI:

/votepoll

Preview the poll info:

/preview <id>

Create a poll from an allowed template:

/votepoll add <templateId> [--target=PLAYER]

Vote on a poll:

/vote <pollId> yes
/vote <pollId> no

Toggle reminders:

/votepoll notify on
/votepoll notify off

Set language:

/votelang <languageCode>

---

Admin Commands (votepoll.admin or OP)

Create a poll:

/votepoll add [id] <duration> <minYes> <minNo> "<display>" <command> [flags]

Supported flags:

• --target=PLAYER
• --repeat
• --repeat=SECONDS
• --interval=SECONDS
• --silent
• --display=NAME

Examples:

/votepoll add banVote 300 5 3 "Ban toxic player" ban {target} --target=BadPlayer
/votepoll add 600 4 2 "Restart server?" restart --silent

Other admin commands:

/votepoll cancel <id>
/votepoll reload
/votepoll preview <id>

---

GUI

Active Votes GUI

• Lists all active polls

• Displays full poll information:

  • Name
  • Description
  • Command
  • End date
  • Creator
  • Required YES / NO votes
  • Poll ID
  • Time remaining
  • Vote command

Poll Detail GUI

• Shows the same information as notifications
• Includes YES and NO voting buttons

---

Notifications and Reminders

• Admin-created polls:

  • Broadcast on creation
  • Periodic reminders based on reminderIntervalSeconds

• Player-created polls:

  • Never broadcast
  • Never send reminders

• Players can opt out of reminders individually

---

Persistence

• polls.yml stores active polls
• history.yml stores completed polls
• Polls resume correctly after server restart

---

Configuration Example

reminderIntervalSeconds: 1800
defaultRepeatIntervalSeconds: 60

playerAllowedCommands:
  - "example_ban"

customCommands:
  - id: "example_ban"
    display: "Ban example player"
    description: "Ban a player for breaking rules"
    command: "ban {target} Breaking server rules"
    durationSeconds: 300
    minYes: 5
    minNo: 3
    repeat: false
    repeatIntervalSeconds: 0

messages:
  usage_votepoll: "&cUsage: /votepoll add|cancel|list|reload|notify"
  no_permission: "&cYou don't have permission to do that."
  usage_cancel: "&cUsage: /votepoll cancel <id>"
  unknown_subcommand: "&cUnknown subcommand."
  vote_failed: "&cUnable to vote."
  poll_canceled: "&cVote canceled: &6{display} (id: {id})"
  broadcast_new_poll: "&aNew vote created: &6{display} &f(id: {id})"
  vote_passed: "&aVote passed: &6{display}"
  vote_failed: "&cVote failed: &6{display}"
  vote_passed_majority: "&aVote passed (majority): &6{display}"
  vote_failed_majority: "&cVote failed (majority): &6{display}"

---

Permissions

Permission	Description
votepoll.admin	Full administrative access
none	Required for voting and allowed templates

---

Important Behavior

• Players receive a permission error if the template is not listed in playerAllowedCommands
• Player-created polls are silent by design
• If a repeating poll has no valid interval, defaultRepeatIntervalSeconds is used

---