VoteMe

<div align="center">

 __   __    _       _       __  __      
 \ \ / /__ | |_ ___| |\/|  |  \/  | ___
  \ V / _ \| __/ _ \ |\/| | |\/| |/ _ \
   \_/ \___/\__\___/_|  |_||_|  |_|\___/

Turn every vote into a reward. No ports. No daemons. Just a clean API. [](LICENSE) [](ht… </div> ---

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 |

Bedrock server software (PMMP, Nukkit, GeyserMC standalone) is not supported.

---

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. ---

Building from Source

Requires Maven and Java 21.

git clone https://github.com/herza/VoteMe.git
cd VoteMe
mvn clean package

Output: target/VoteMe.jar ---

Configuration

# ╔══════════════════════════════════════════════════════════╗
#   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](https://www.spigotmc.org/resources/placeholderapi.6245/) 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 ou