Government

Government is a Paper 1.21.11 plugin for Java 21 that provides LuckPerms-backed jobs, supervised government departments, configurable entrance exams, salary policy, terms of office, and secret-ballot elections. LuckPerms is the authority for every current job and rank. SQLite stores workflow and historical data without duplicating current membership.

Highlights

• One ordinary job in each configured category (white_collar, blue_collar, and the combined government/criminal restricted category)
• Configured exempt appointments, such as city council, which do not consume a category slot
• Employment offers with expiration; acceptance rechecks and atomically replaces the prior non-exempt job in that category
• Track-scoped management requiring both government.manage.track.<track> and a configured rank scope
• Promotion, demotion, dismissal, employee lists, individual and rank salary policy, and complete audit history
• Sign-bound multiple-choice exams with configurable answers, pass scores, cooldowns, job awards, and pass commands
• /quitjob <job> and /about; players may select the job used for their display prefix
• Lectern polling stations and player-head ballot GUIs
• FPTP, approval, two-round, IRV, fractional-transfer STV using the Droop quota, and referendum voting
• Declaration stages with permission and active-playtime requirements
• Secret, UUID-unique, optionally revisable ballots; election staff see anonymous ballots and administrators can perform restricted correlations
• Quorum, referendum approval thresholds, deterministic tie resolution, recountable round records, terms, vacancies, succession, recall petitions, recall referenda, and automatic LuckPerms certification
• SQLite WAL, prepared statements, foreign keys, startup integrity checks, backups, and serialized database work
• PlaceholderAPI and a Bukkit services API for chat/economy integrations

Install

1. Run Paper 1.21.11 on Java 21.
2. Install LuckPerms. It is required.
3. Optionally install PlaceholderAPI if Carbon or another chat plugin should display the player-selected job.
4. Copy the current build/libs/MCSkylines-Government-*.jar to the server's plugins folder.
5. Start and stop the server once, then configure plugins/Government/.
6. Create every group named in jobs.yml and elections.yml in LuckPerms.
7. Grant only the dynamic track, salary, election, and station permissions that each role needs.

Configuration

• config.yml — storage, offers, job limits, prefix behavior, salary schedule metadata, election scheduling, recall timing, and security limits
• jobs.yml — categories, tracks, rank order, management scopes, LuckPerms groups, salaries, prefixes, exemptions, and exams
• elections.yml — offices, groups, seat counts, methods, terms, candidacy requirements, voting permissions, succession, and referendum defaults
• guis.yml — reserved GUI presentation settings
• messages.yml — MiniMessage user-facing text
• data.db — offers, salary overrides, display selections, exams, stations, elections, candidates, ballots, terms, recalls, vacancies, and audits

Configuration reload is all-or-nothing. A database path change requires a restart. Keys must be lowercase-safe identifiers; durations support s, m, h, d, w, mo, and y, including compounds such as 1d12h.

Job rules

Each job maps to one LuckPerms group. A player may hold one non-exempt job per configured category. Assigning a new non-exempt job removes only configured, non-exempt groups in the same category. Unrelated LuckPerms groups and nodes are never touched.

limit-exempt: true makes a configured appointment not count against its category. The inherited permission government.jobs.limit-exempt provides a personal bypass when a server needs a broader exception.

Management requires:

1. government.manage.track.<target-track> (or government.admin), and
2. at least one current job whose configured management scope contains the target rank.

This permits a mayor rank to manage a police commissioner while preventing the mayor from directly managing ordinary police ranks unless the configuration explicitly allows it.

Exams and stations

Define an exam under exams in jobs.yml, look at a sign, and run:

/government station exam <exam>

Right-clicking that sign opens the exam. Correct-answer indexes are zero-based. Passing assigns pass-job and may execute the configured console commands after replacing <player> and <uuid>.

Look at a lectern and run:

/government station poll

Right-clicking that lectern lists open elections. Ordinary voters do not receive a remote voting command.

Election workflow

/government election create <key> <office> <method> <declarations-in> <opens-in> <duration> <seats> [revisions]
/government election declare <key> [statement]
/government election candidate add <key> <player> [statement]
/government election close <key>
/government election count <key>
/government election certify <key>

Two-round elections that lack a first-round majority report two finalists. Create their second round with:

/government election runoff <original> <new-key> <opens-in> <duration>

Referenda use:

/government election referendum <key> <opens-in> <duration> <quorum%> <approval%> <revisions> <question>

Certification grants winner groups, removes outgoing certified officeholders, creates terms, and enforces normal job-category replacement for non-exempt office groups. A failed quorum is not certifiable. A tied referendum resolves to the status-quo NO result.

Recall petitions are created with /government election recall <term-id> <required-signatures> <duration> <reason> and signed with /government election recall-sign <recall-id>. Reaching the configured threshold schedules a secret recall referendum; certification of YES vacates the term and applies succession.

Ballot privacy

The current voter ledger and ballot payloads are separate tables. Election staff may use /government election ballots <key> and /government election count <key> to inspect anonymous ballots and aggregates. Only government.election.audit may correlate a random ballot UUID with its voter through /government election audit-ballot <key> <ballot-uuid>. Replaced ballot revisions remain in the administrator audit mapping but are marked superseded and never counted.

As with any server-side voting system, a person with direct filesystem/database access is ultimately trusted.

Chat prefix selection

Players use /about display <job> or click one of their own jobs in /about. With PlaceholderAPI installed, Carbon can use:

%government_job_prefix%%player_name%: %message%

Available values are job, job_key, job_prefix, job_category, job_track, and job_rank. LUCKPERMS_PERSONAL prefix mode is also available but should be used only when the existing LuckPerms meta stack is understood; the plugin removes only exact configured prefixes at its configured priority.

Economy integration

When Economy is installed and salary payments are enabled, payroll runs once per configured real-world day. Salary calculation follows: individual override, then database rank override, then the configured job salary. Each job may map to a treasury or department account. Economy enforces the prior-24-hour attendance threshold, tax/debt withholding, idempotency, and arrears. Without an economy adapter, Government continues operating but does not pay salaries. Other plugins can obtain GovernmentApi from Bukkit's services manager.

Build

..\gradlew.bat -p . clean test jar

See docs/PERMISSIONS.md and SECURITY.md before granting management or election powers.

Launch a job department

1. Define the category, track, rank order, LuckPerms group, salary, prefix, and management scopes in jobs.yml.
2. Create every referenced LuckPerms group before assigning players. Government treats LuckPerms as current membership authority and does not mirror membership into SQLite.
3. Grant managers both the dynamic government.manage.track.<track> node and a job whose configured scope reaches the target rank. Permission alone is not enough unless government.admin is used.
4. Test an offer from creation through acceptance and expiry. Acceptance rechecks the player's current groups and replaces only configured, non-exempt jobs in the same category.
5. Map salary funding to the correct treasury or department account and verify the Economy attendance requirement and budget before relying on payroll.

Use exemptions for appointments that should coexist with an ordinary category job. A personal government.jobs.limit-exempt permission is broader than a configured exempt job and should be reserved for deliberate exceptions.

Build and test an entrance exam

Define the exam questions, zero-based correct answers, pass score, cooldown, awarded job, and optional completion commands in jobs.yml. Look at the sign that should become the station and run /government station exam <exam>. Players right-click that bound sign to begin; passing applies the configured job and then executes approved console commands with player placeholders.

Test every answer index, the exact pass boundary, cooldown behavior, a player whose current category job must be replaced, and a player who no longer qualifies at completion time.

Run an election from declaration to certification

1. Define the office in elections.yml, including its LuckPerms group, seats, voting permission, method, term, candidacy requirements, succession, and referendum defaults.
2. Register at least one lectern poll station with /government station poll. Ordinary voters vote through a station, not a remote command.
3. Create the election with its declaration, opening, duration, seat, and ballot-revision settings.
4. Let candidates declare or have staff add them. Eligibility and configured active-play requirements are checked.
5. Open a poll station as multiple eligible test voters. Confirm one UUID-unique ballot per voter and, when enabled, that a revision supersedes rather than double-counts the prior ballot.
6. Close and count the election. Inspect anonymous ballot output and recorded rounds before certification.
7. Certify only after quorum and result checks. Certification changes office groups, creates terms, removes outgoing certified holders, and applies normal category replacement rules.

For two-round voting, create the runoff from the reported finalists. For IRV and STV, retain the round records so recounts are explainable. A referendum tied exactly at the threshold resolves to the status quo NO. A failed-quorum election cannot be certified.

Recalls, vacancies, and succession

Create a recall against an active term, collect the configured number of unique signatures before expiry, and allow Government to schedule the secret recall referendum. Certifying YES vacates the term and applies the office's configured succession. Test ordinary term expiry and manual vacancy handling on staging as well; election groups should never be managed by ad-hoc LuckPerms commands during an active certification workflow.

Privacy and audit boundaries

Election staff can inspect anonymous ballots and aggregates. Only government.election.audit can correlate a random ballot UUID with a voter, including superseded revisions. Limit that permission to the smallest trusted group. Direct database/filesystem administrators remain part of the system's trust boundary.

Government testing checklist

1. Offer, accept, replace, promote, demote, dismiss, and voluntarily quit representative jobs in every category.
2. Verify exempt appointments and manager rank scopes.
3. Pass and fail each configured entrance exam.
4. Test FPTP, approval, runoff, IRV, STV, and referendum counts with ties and failed quorum.
5. Test ballot revision, anonymous inspection, restricted audit correlation, certification, term expiry, succession, and recall.
6. Verify display-job selection and PlaceholderAPI output for players with multiple jobs.
7. Fund and underfund payroll accounts and confirm eligible, ineligible, and arrears outcomes.