ModNVote

Privacy-first, GUI-driven community polling for PaperMC 1.21.x

ModNVote is a modern voting and polling plugin for Minecraft communities that want polls to be easy for players, practical for admins, and verifiable after the fact.

ModNVote 2.x replaces the original Yes/No-only workflow with a full poll lifecycle system supporting:

• Ranked single-winner polls
• Yes/No polls
• GUI-driven poll creation and editing
• Poll cloning for repeat or template-based polls
• Anonymous ballot storage
• Participation tracking separated from vote content
• Ballot proof-phrase verification
• Tamper-evident audit and integrity checks
• Optional external witness publication via Discord-compatible webhooks
• Manual and automatic integrity checkpoint publication
• Java/Bedrock-friendly inventory interfaces
• Mandatory vote confirmation before submission
• /poll as a short alias for /modnvote

Built for PaperMC 1.21.x and Java 21.

ModNVote is the spiritual successor to PineVote, rebuilt cleanly under the MODN METL brand with a stronger focus on privacy, transparency, and integrity.

---

Key Features

GUI Poll Builder

Admins can create and edit polls through an inventory GUI rather than a long sequence of setup commands.

Supported builder flows:

/modnvote create ranked_single_winner <optionCount>
/modnvote create yes_no
/modnvote edit <draftPollId>

The shorter alias can also be used:

/poll create ranked_single_winner <optionCount>
/poll create yes_no
/poll edit <draftPollId>

The builder lets admins configure:

• Poll title
• Poll description
• Option names
• Option descriptions
• Ranked poll partial-ranking behaviour
• Ranked poll maximum ranking count

Fields use clear red/green completion indicators:

• Red = still needs work
• Green = complete

When the poll is valid, the READY control turns green and the poll can be staged for opening.

---

Poll Cloning

Admins can clone an existing poll into a new editable draft:

/modnvote clone <sourcePollId>

This is useful for recurring polls where some options, wording, or settings are reused.

Cloning copies the poll definition and options, but does not copy ballots, participation records, lifecycle timestamps, proof phrases, or audit history.

---

Ranked Single-Winner Polls

Ranked polls let players order choices by preference.

Admins can create a ranked poll with:

/modnvote create ranked_single_winner 5

Players then vote through a GUI using:

/modnvote vote <pollId>

Ranked voting includes:

• Click-to-rank options
• Stable paper option icons
• Tooltip text showing current rank
• Optional partial-ranking support
• Configurable max rankings
• Mandatory review/confirmation before the ballot is cast

---

Yes/No Polls

Yes/No polls are still fully supported, now as part of the 2.x poll lifecycle.

Admins can create one with:

/modnvote create yes_no

The plugin uses protected canonical Yes and No options while still supporting the new GUI setup and lifecycle flow.

---

Anonymous Ballots

ModNVote is built around one core rule:

Anonymous ballots are the source of truth for vote content.

The plugin deliberately separates:

Data	Purpose
Anonymous ballots	Store vote content and drive results
Participation records	Track who participated and prevent duplicates
Audit records	Provide lifecycle and integrity evidence
Proof phrases	Let players verify ballots without exposing identity links

This means results are calculated from anonymous ballots only, not from identity-aware participation records.

---

Verification Without Revealing Vote Content

Players can verify participation:

/modnvote verify participation <pollId>

This confirms whether their participation was recorded without revealing how they voted.

Players can also verify a ballot proof phrase:

/modnvote verify ballot <pollId> <proofPhrase>

Proof phrases act like bearer tokens. Anyone with the phrase can verify that ballot reference, so players should keep them private.

---

Audit, Integrity Checks, and Witness Publication

ModNVote is designed to make tampering detectable.

Integrity features include:

• Anonymous ballot hash checks
• Ballot proof commitment checks
• Participation inclusion checks
• Poll lifecycle audit records
• Audit chain validation
• Result calculation from anonymous ballots only
• Optional witness checkpoint publication

ModNVote can publish privacy-safe witness events to configured Discord-compatible webhooks.

Supported witness events include:

• Poll opened
• Poll closed, including a public result summary
• Automatic integrity checkpoints every configured number of accepted ballots
• Manual integrity checkpoints via:

/modnvote checkpoint <pollId>

Witness publication does not publish player names, UUIDs, IP addresses, proof phrases, participation receipts, or per-player vote content.

Webhook delivery is best-effort and non-blocking. A failed webhook does not cancel voting, poll opening, poll closing, checkpointing, or persistence.

---

Java and Bedrock Friendly GUI

The GUI intentionally avoids decorative glass panes.

This keeps the interface simpler and more compatible with Bedrock players while still providing clear interaction cues through:

• Item names
• Item lore
• Wrapped multiline descriptions
• Red/green builder state
• Confirmation screens

---

Main Commands

All commands are rooted at:

/modnvote

The shorter alias is also available:

/poll

Admin workflow

/modnvote guide
/modnvote create ranked_single_winner <optionCount>
/modnvote create yes_no
/modnvote edit <draftPollId>
/modnvote clone <sourcePollId>
/modnvote list
/modnvote show <pollId>
/modnvote delete <pollId>
/modnvote open <pollId>
/modnvote close <pollId>
/modnvote result <pollId>
/modnvote checkpoint <pollId>

Player workflow

/modnvote vote <pollId>
/modnvote mypolls
/modnvote verify participation <pollId>
/modnvote verify ballot <pollId> <proofPhrase>

Utility

/modnvote status
/modnvote reload

All examples above can also be run with /poll instead of /modnvote.

Some older low-level setup commands may remain callable as recovery tools, but normal poll setup should use the GUI builder.

---

Privacy Model

ModNVote avoids storing voter identity and vote content together.

Participation records are identity-aware because the plugin needs to know who has already voted. Anonymous ballots store the vote content. These two systems are deliberately separate.

This allows the plugin to:

• Prevent duplicate voting
• Verify that a player participated
• Calculate results from ballot content
• Avoid exposing how a named player voted

/modnvote verify participation must not reveal vote content.

/modnvote result must use anonymous ballots only.

External witness publication is poll-level only and must not reveal player-specific vote data.

---

Poll Lifecycle

Polls move through explicit states:

DRAFT -> READY -> OPEN -> CLOSED

Typical flow:

create -> edit in builder -> mark READY -> open -> players vote -> close -> result

DRAFT polls can be edited in the Poll Builder. READY polls can be opened. OPEN polls accept votes. CLOSED polls can report results.

---

Webhook Configuration

Webhook publication is configured in plugins/ModNVote/config.yml.

A single webhook should be configured as a YAML list:

publication:
  discord_webhooks:
    - "https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN"
  publish_poll_opened: true
  publish_poll_closed: true
  publish_checkpoints: true

integrity:
  checkpoint_interval_ballots: 25

Use discord_webhooks: [] to disable webhook publication.

Multiple webhooks are supported by adding more - ... lines.

Never commit real webhook URLs to source control.

---

PlaceholderAPI

PlaceholderAPI support was part of the legacy 1.x plugin.

For ModNVote 2.x, please check the current release notes and repository documentation for the latest PlaceholderAPI status before relying on placeholders in production dashboards.

---

Requirements

• Server: PaperMC 1.21.x
• Java: 21
• Database: SQLite
• Optional: PlaceholderAPI, where supported by the current build

---

Installation

1. Download the latest modnvote-*.jar.
2. Drop it into your server's plugins folder.
3. Restart the server.
4. Configure permissions with your permissions plugin.
5. Create a test poll with:

/modnvote create yes_no

or:

/modnvote create ranked_single_winner 3

ModNVote 2.x is a clean-install release. Migration from legacy 1.x databases is not currently supported.

---

Permissions

Permissions are defined in plugin.yml.

Common permissions include:

modnvote.admin.poll.create
modnvote.admin.poll.list
modnvote.admin.poll.open
modnvote.admin.poll.close
modnvote.admin.reload
modnvote.verify
modnvote.testvote

Duplicate-prevention bypass support remains configurable through the plugin configuration.

---

Roadmap

Potential future 2.x work includes:

• Multi-winner STV
• Combined elections such as Mayor + Council
• Exportable signed audit snapshots
• Advanced reporting and dashboards
• Dedicated GUI delete confirmation flow
• Additional admin transparency tooling
• Multi-target witness publication beyond Discord-compatible webhooks

---

License & Credits

• License: MIT
• Copyright: MODN METL LTD
• Developed by Jamie E. Thompson (@jamjet3)
• Community testing: Pinecraft Equestrian SMP

If you use ModNVote on your server, a star on the GitHub repo is always appreciated.