CommonerVote turns guests into Commoners. Team members vote for guests whose building they have seen; each vote is
worth a share of a promotion, and when a guest reaches 100 % the plugin promotes them through LuckPerms, welcomes them
and announces it to the network. Votes last a limited time, and a staff vote can count for more than a team vote.
Everything players see is a Paper dialog, the action bar or chat. This page describes 2.0.0, the latest release
on master (tag v2.0.0), a rewrite for Paper 26.2 and Java 25. The source is public at
MCME/CommonerVote.

At a glance

How the code is organised

Everything lives under com.mcmiddleearth.commonervote. The services talk to small interfaces, so the tests can swap
the outside world (database, LuckPerms, dialogs, proxy) for fakes.

Two things to know before you change code:

• Threads. Database work never runs on the main thread, and LuckPerms answers arrive on LuckPerms' threads. Any
  code that touches the Bukkit API after either hops back to the main thread first (the services get a main-thread
  Executor for that).
• Settings refresh. The settings live in the database and are shared by every server on it. Each server reads them
  again every minute (1,200 ticks); until the first read succeeds, nobody is promoted and /vote config does not open.
  If the database is down at start-up, the table set-up is retried on the same timer.

Building and testing

You need JDK 25 and Maven.

mvn -B verify

This compiles, runs the tests and writes the jar to target/. The tests use JUnit, Mockito and MockBukkit
(mockbukkit-v26.2), with H2 in MariaDB mode standing in for the database. TestCommonerVotePlugin overrides the
protected create… methods of the main class to plug in the in-memory database, inline executors and fakes.
LegacyCompatibilityTest keeps the votes table readable by the old 1.2.9 plugin, and PluginDescriptorTest checks
plugin.yml.

The jar name follows MCME's convention, CommonerVote-<version>-<DEV|SNAPSHOT|RELEASE>-<commit id>.jar:

• the kind defaults to DEV; pass -Dbuild.type=RELEASE for a release build;
• the commit id is the current HEAD's, so build after committing;
• in a linked git worktree the commit-id plugin reads the wrong commit, so pass
  -Dgit.commit.id.abbrev=$(git rev-parse --short=7 HEAD) yourself.

GitHub Actions (.github/workflows/build.yml) runs mvn -B verify on pushes to master, development and
revision/**, and on pull requests. It does not publish anything. Releases are on the repository's
Releases page, as the RELEASE jar plus its .sha256.

Configuration

plugins/CommonerVote/config.yml holds only the database connection and the proxy switch. Everything else is a
shared setting in the database.

The keys of 1.2.9 that moved into the database (validityPeriod, votesNeeded, useXpBar and others) are ignored;
the start-up log names any your file still has.

Shared settings (database)

Edited in game with /vote config and stored in the commonervote_settings table. Another server picks up a change
within about a minute.

Database tables

The plugin creates these with CREATE TABLE IF NOT EXISTS:

Commands and permissions

/vote is registered with Brigadier (there is no commands: block in plugin.yml); /commonervote:vote works too.

Dialog buttons check the permission again when clicked, so removing a permission takes effect at once.

APIs and extension points

CommonerVote offers no Java API and fires no events for other plugins, and it is not published to the
Maven repository. What other software can rely on:

• The database tables above. The votes table layout is a compatibility promise towards 1.2.9; keep it unchanged.
• The promotion command. Promotions run a configurable console command, so a network can promote through
  something other than lp user … parent set if it needs to.

Inside the plugin, RankService, Messenger, DialogPresenter and CommandRunner are the seams: a new rank plugin or
transport means a new implementation of one interface, not changes to the services.

How it talks to other plugins and systems

Proxy messages. A vote for a guest on another server goes out as ForwardToPlayer to that guest's name, subchannel
CommonerVote, with the payload Voted (new in 2.0) or Update (votes changed: refresh the XP bar and check for a
promotion; 1.2.9 understands this one too). The promotion announcement is MessageRaw to ALL, carrying the message as
JSON. Plugin messages need a player online on the sending server; when nobody is, the guest is brought up to date at
their next join.

The promotion guard. lp user <player> parent set <group> replaces all of a player's groups. So the plugin promotes
only a player whose direct groups are default plus the groups in promotableGroups; anyone else is listed as
"Auto-promotion blocked" in the review, and "Promote now" names the group that blocks it.

flowchart LR
  T[Team member: /vote] --> V[VoteService]
  V --> DB[(commonervote_* tables)]
  V --> P[PromotionService]
  P -->|direct groups, exempt| LP[LuckPerms API]
  P -->|console: promotionCommand| LP
  V -->|ForwardToPlayer, subchannel CommonerVote| PX[Velocity proxy]
  P -->|MessageRaw ALL| PX
  PX --> O[Guest's server: XP bar, action bar, promotion check]

Further reading

• README and
  CHANGELOG on master, including the upgrade notes
  from 1.x
• Setting up for JDK 25, Maven and MockBukkit