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

```yaml 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

---