VoteMe

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

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

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

Permissions

PlaceholderAPI

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

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.

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.

For Developers

Project Structure

src/main/java/id/herza/voteme/
├── VoteMe.java                      Entry point, registers all components
├── api/
│   ├── APIType.java                 Enum: MINECRAFT_POCKET, MINECRAFT_MP
│   ├── VoteAPIClient.java           HTTP client — checkStatus() and checkAndClaim()
│   └── VoteResult.java              Enum: SUCCESS, ALREADY_CLAIMED, NOT_VOTED, ERROR
├── command/
│   ├── VoteCommand.java             /vote and /vote list, with tab completion
│   └── VoteReloadCommand.java       /votereload
├── gui/
│   ├── VoteGUI.java                 27-slot chest GUI builder
│   └── VoteGUIHolder.java           InventoryHolder tag to identify the GUI
├── listener/
│   ├── GUIListener.java             Inventory click handler
│   └── PlayerJoinListener.java      Async join vote reminder
├── manager/
│   ├── ConfigManager.java           Single source of truth for all config values
│   ├── RewardManager.java           Dispatches console reward commands
│   └── VoteManager.java             Core logic: processing, party, data persistence
└── placeholder/
    └── VoteMePlaceholder.java       PlaceholderAPI expansion (auto-registers)

Adding a New Vote Site

1. Add the site to APIType.java:

MY_SITE("my-site", "https://mysite.com/api/");

2. Add a claim handler in VoteAPIClient.java:

private static VoteResult handleMySite(String apiKey, String username, String base) throws IOException {
    String result = fetch(base + "?action=post&key=" + apiKey + "&username=" + username);
    return "1".equals(result) ? VoteResult.SUCCESS : VoteResult.NOT_VOTED;
}

3. Add a config block in config.yml:

my-site:
  api-key: ""
  name: "My Site"
  url: "https://mysite.com/server/YOUR_ID"

4. Add a GUI slot in VoteGUI.java and wire up the click in GUIListener.java.

Accessing VoteManager from Another Plugin

Plugin raw = Bukkit.getPluginManager().getPlugin("VoteMe");
if (raw instanceof VoteMe voteme) {
    int total    = voteme.getVoteManager().getTotalVotes();
    int needed   = voteme.getVoteManager().getVotesUntilParty();
    int progress = voteme.getVoteManager().getPartyProgress();
}

Click Here for source code

Support Indonesian creator 🇮🇩

• https://saweria.co/herza

License

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