VoteMe

---

What is VoteMe?

VoteMe is a lightweight, pure API-based voting plugin for Java Edition servers. Players open a clean chest GUI, click a site, and their reward lands in their inventory — no port forwarding, no external listener, no daemon process needed.

It supports two of the biggest Minecraft server listing sites out of the box, and every single piece of behavior — sounds, messages, rewards, GUI title, vote party threshold — is configurable down to the last character.

---

Feature Overview

``` /vote Opens a 27-slot chest GUI /vote list Lists all vote site links in chat Join Reminder Tells players how many votes they haven't claimed yet Dual API Support Minecraft Pocket Servers + Minecraft-MP, one or both Fully Async Zero impact on main thread — all API calls are non-blocking Reward System Any console command as a reward (items, money, permissions) Vote Party Server-wide reward event when a vote milestone is hit Sound Feedback Villager + XP Orb sounds for every vote outcome PlaceholderAPI 4 ready-to-use placeholders for scoreboards Hot Reload /votereload — no restart needed after config changes ```

---

Requirements

| Requirement | Version | Notes | |---|---|---| | Java | 21+ | | | Paper or Spigot | 1.21.1 | Also runs on Purpur, Pufferfish, and other forks | | PlaceholderAPI | Any | Optional — unlocks `%voteme_*%` placeholders |

---

Installation

Step 1. Drop `VoteMe.jar` into your `/plugins` folder.

Step 2. Start the server once to generate the config file at `plugins/VoteMe/config.yml`.

Step 3. Open the config and fill in your API key(s) and server page URL(s).

Step 4. Run `/votereload` in-game or from console. Done.

---

Configuration

```yaml

╔══════════════════════════════════════════════════════════╗

VoteMe Configuration — by Herza

╚══════════════════════════════════════════════════════════╝

── Vote Sites ─────────────────────────────────────────────

Set api-key to "" to disable that site.

You can run one site, or both at the same time.

minecraft-pocket: api-key: "" name: "Minecraft Pocket Servers" url: "https://minecraftpocket-servers.com/server/YOUR_ID"

minecraft-mp: api-key: "" name: "Minecraft-MP" url: "https://minecraft-mp.com/server/YOUR_ID"

── Join Reminder ──────────────────────────────────────────

When a player joins, VoteMe checks all enabled sites.

If unclaimed votes exist, the player gets a private message.

Set to false to disable.

join-reminder: true

── Rewards ────────────────────────────────────────────────

Console commands executed when a player claims a vote.

Variable: {player}

rewards: - "give {player} diamond 1" - "eco give {player} 500"

── Messages ───────────────────────────────────────────────

Supports & color codes. Variables: {player}, {link}

Set any value to "" to disable that message.

messages: success: "&a[Vote] &fThank you for voting, &e{player}&f! Rewards sent." already-claimed: "&e[Vote] &fYou already claimed your reward today." not-voted: "&c[Vote] &fYou haven't voted yet. Head to: &e{link}" error: "&c[Vote] &fCould not reach the voting API. Try again later."

── Broadcast ──────────────────────────────────────────────

Sent to ALL online players when someone claims a vote.

Variables: {player}, {link}. Set to [] to disable entirely.

broadcast: - "&6[Vote] &e{player} &fjust claimed their vote rewards! Vote at &e{link}&f."

── Vote Party ─────────────────────────────────────────────

Fires every time total votes hit a multiple of this number.

Set to 0 to disable vote party entirely.

vote-party: 50

Console commands run for EVERY online player when the party fires.

Variable: {player}

vote-party-rewards: - "give {player} diamond 5"

── GUI ────────────────────────────────────────────────────

gui: title: "&8» &6&lVoteMe &8«"

╔══════════════════════════════════════════════════════════╗

PlaceholderAPI — requires PlaceholderAPI plugin

#

%voteme_total_votes% All-time total votes recorded

%voteme_party_progress% Votes in the current party cycle

%voteme_party_target% Target to trigger a party (N/A if off)

%voteme_party_needed% Remaining votes until next party (N/A if off)

#

Scoreboard examples:

"&fTotal Votes &e%voteme_total_votes%"

"&fParty &e%voteme_party_progress%&7/&6%voteme_party_target%"

"&fNext Party In &e%voteme_party_needed% &fvotes"

╚══════════════════════════════════════════════════════════╝

```

Where to get your API key

Minecraft Pocket Servers — Log into your dashboard at `minecraftpocket-servers.com`, open your server settings, and copy the API key from the voting section.

Minecraft-MP — Log into `minecraft-mp.com`, go to your server panel, and find the API key under the voting/API tab.

---

Commands

| Command | What it does | Permission | |---|---|---| | `/vote` | Opens the vote chest GUI | `voteme.vote` | | `/vote list` | Lists all vote site names and links in chat | `voteme.vote` | | `/votereload` | Reloads config without restarting the server | `voteme.admin` |

---

Permissions

| Node | Default | Description | |---|---|---| | `voteme.vote` | All players | Access to `/vote` and `/vote list` | | `voteme.admin` | OP only | Access to `/votereload` |

---

PlaceholderAPI

Install PlaceholderAPI and VoteMe registers its expansion automatically on startup — no extra commands needed.

| Placeholder | Returns | |---|---| | `%voteme_total_votes%` | All-time total votes recorded by the plugin | | `%voteme_party_progress%` | Votes counted in the current party cycle | | `%voteme_party_target%` | Vote count target to fire a party (`N/A` if disabled) | | `%voteme_party_needed%` | Votes remaining until the next party (`N/A` if disabled) |

Works with any scoreboard plugin that supports PlaceholderAPI — CMI, FeatherBoard, AnimatedScoreboard, etc.

``` &fTotal Votes &e%voteme_total_votes% &fParty &e%voteme_party_progress%&7/&6%voteme_party_target% &fNext Party &e%voteme_party_needed% &fvotes ```

---

How the Vote API Works

VoteMe talks directly to each site's HTTP API. There is no listener port, no webhook server, and no firewall rules to configure.

Minecraft Pocket Servers — two-step flow

``` Step 1 GET /api/?object=votes&element=claim&key=KEY&username=PLAYER Response: "1" = unclaimed | "2" = already claimed | "0" = not voted

Step 2 (only if step 1 returns "1") GET /api/?action=post&object=votes&element=claim&key=KEY&username=PLAYER Response: "1" = success ```

Minecraft-MP — single-step flow

``` GET /api/?action=post&object=votes&element=claim&key=KEY&username=PLAYER Response: "1" = claimed | "2" = already claimed | "0" = not voted ```

All requests run on a separate async thread. The main server thread is never touched.

---

Sound Feedback

Every vote outcome plays a distinct sound sequence so players always know what happened without even reading the chat.

| Event | Sound Sequence | |---|---| | Vote claimed | `VILLAGER_YES` → `XP_ORB` pitch 1.2 → `XP_ORB` pitch 1.5 → `VILLAGER_CELEBRATE` | | Not voted / already claimed / error | `VILLAGER_NO` | | Vote party fires | `VILLAGER_CELEBRATE` → `XP_ORB` x3 rising → `VILLAGER_YES` (all online players) |

---

Vote Party

Every time a vote is claimed, the server-wide counter goes up by one. When it hits a clean multiple of your configured `vote-party` number, every player currently online receives the `vote-party-rewards` commands and a full sound sequence.

Between milestones, a broadcast keeps everyone in the loop:

``` [VoteParty] 23/50 votes reached! 27 more needed. ```

Set `vote-party: 0` to turn it off entirely.

---

Join Reminder

Two seconds after a player joins (delayed to not overlap with other join messages), VoteMe checks all enabled vote sites in the background. If any site has an unclaimed vote waiting for that player, they get a private message:

``` [VoteMe] You still have 2 votes on our voting service. Use /vote list [VoteMe] You still have 1 vote on our voting service. Use /vote list ```

The count reflects exactly how many sites have an unclaimed vote — not how many times they voted. Set `join-reminder: false` to disable.

---

Adding a New Vote Site

Feel free to request an more Vote Service Contact me at [email protected]

License

``` MIT License — Copyright (c) 2025 Herza Free to use, fork, modify, and redistribute with attribution. See LICENSE for full text. ```