VoteMe

# Changelog All notable changes to VoteMe will be documented here. --- ## [1.0.2] — 2025-03-05 ### Added - Support for **8 vote sites**: Minecraft Pocket Servers, Minecraft-MP, Minecraft-Server.net, Craftlist, TopG, Planet Minecraft, Minecraft-Servers.org, ServerPact - Craftlist timestamp-based vote tracking — stores last claimed vote per player in `data.yml` - `PlayerJoinListener` — async join reminder showing how many unclaimed votes a player has - `/vote list` subcommand — lists all enabled vote site names and links in chat - Tab completion for `/vote list` - `join-reminder` toggle in `config.yml` - `checkStatus()` in `VoteAPIClient` for read-only join reminder checks - `ConfigManager` fully dynamic — reads all site data via `APIType` enum - `GUIListener` uses `EnumMap<Material, APIType>` for clean click routing - `VoteGUI` dynamically assigns slots based on active sites - Saweria support link added to top of `config.yml` ### Changed - Config structure changed from flat keys to nested blocks per site: ```yaml minecraft-pocket: api-key: "" name: "Minecraft Pocket Servers" url: "..." ``` - `VoteAPIClient` restructured with clear per-site handlers and shared HTTP helpers - `VoteGUI` slot layout redesigned to accommodate up to 8 sites in a 27-slot chest ### Notes - If upgrading from 1.0.0, delete the old `config.yml` and let the plugin regenerate it --- ## [1.0.0] — 2025-03-03 ### Initial Release - `/vote` command opens a 27-slot chest GUI - Support for **Minecraft Pocket Servers** and **Minecraft-MP** - Pure HTTP API — no port forwarding, no listener daemon required - All API calls run asynchronously (non-blocking main thread) - Fully configurable rewards via console commands (`{player}` variable) - Configurable messages and broadcast with `{player}` and `{link}` variables - Vote party system — fires server-wide rewards at vote milestones - Sound feedback: `VILLAGER_YES` + `XP_ORB` sequence on success, `VILLAGER_NO` on failure - Vote party sound sequence for all online players - PlaceholderAPI support with 4 placeholders: - `%voteme_total_votes%` - `%voteme_party_progress%` - `%voteme_party_target%` - `%voteme_party_needed%` - `/votereload` command for hot config reload - `data.yml` for persistent vote counter across restarts - MIT License

<div align="center"> ``` __ __ _ _ __ __ \ \ / /__ | |_ ___| |\/| | \/ | ___ \ V / _ \| __/ _ \ |\/| | |\/| |/ _ \ \_/ \___/\__\___/_| |_||_| |_|\___/ ``` **Turn every vote into a reward. No ports. No daemons. Just a clean API.** [](LICENSE) []() []() [](https://github.com/herzonly/VoteMe) </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**. ```bash git clone https://github.com/herza/VoteMe.git cd VoteMe mvn clean package ``` Output: `target/VoteMe.jar` --- ## 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](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 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. --- ## 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`: ```java MY_SITE("my-site", "https://mysite.com/api/"); ``` **2.** Add a claim handler in `VoteAPIClient.java`: ```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`: ```yaml 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 ```java 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](https://github.com/herzonly/VoteMe) ## 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. ```