VoteLedger

v1.0.0 // Spigot · Paper 1.18.2 – 26.3 // Java 17+

requires: nothing

VoteLedger lets your staff, and your players through proposals, put a question to the whole server and close it with a counted, announced result. It is made for survival, roleplay and community servers that want their players to take part in decisions. Each poll has its own quorum, majority and eligibility rules, every ballot is written to a timestamped ledger, and the winning option can run console commands.

Spoiler: Features, text version

• Polls created in game — /vote create takes a duration, a question and 2 to 6 options (up to 28 in config.yml).
• Rules per poll — quorum, simple or qualified majority (50 to 100%), final or changeable ballots, live or hidden count.
• Eligibility — an extra permission, a minimum play time read from the vanilla statistics and a minimum time since the first join.
• One ballot per account — a changeable ballot can be changed 3 times by default, each change is recorded.
• Timestamped ledger — /vote ledger lists every ballot cast or changed, with its time, paged and filterable by player.
• Ballot box signs — a sign with [Urn] and a poll number opens the ballot on right click and shows the question, time left and ballots cast.
• Protected boxes — ballot box signs resist players, explosions, pistons and fire; staff remove them while sneaking.
• Menus — /vote opens a menu of the open polls; the polls still waiting for your ballot shine.
• Automatic closing — polls close at their end date, even after a restart, and the result is announced with a bar per option.
• Console command sets — commands for the winner, for one option, for no decision, for every voter and for the winning voters.
• Offline voters — their commands are queued until they join, run at once or skipped, as you choose.
• Player proposals — players propose a poll, staff approve or deny it, with limits per player, in total and a cooldown.
• Staff tools — close, cancel, extend and reopen a poll; ballots are kept and console commands never run twice.
• Archives — /vote results lists the closed polls with their verdict and shows the full count of each.
• Reminders — every 15 minutes and on join, players get the list of the polls they can still vote in.
• Translatable — English and French files included, every text editable, hex colour codes supported.
• No dependency — polls and ballot boxes are stored in YAML files, saved off the main thread.

Code (Text):

/vote                       voteledger.use            Menu of the open polls

/vote <id>                  voteledger.use            Ballot of a poll

/vote list                  voteledger.use            Open polls in chat

/vote info <id>             voteledger.use            Details, rules or result of a poll

/vote results [page|#id]    voteledger.results        Archives of the closed polls

/vote propose <...>         voteledger.propose        Propose a poll to the staff

/vote create <...>          voteledger.create         Open a poll

/vote close <id>            voteledger.admin.close    Close a poll now

/vote ledger <id>           voteledger.admin.ledger   Every ballot of a poll

/vote reload                voteledger.admin.reload   Reload config and messages

Create and propose share one syntax:
/vote create 3d quorum:20 majority:67 change:yes Reset the End? | Yes | No

// Aliases: /votes, /poll, /polls, /scrutin, /voteledger.

Spoiler: All commands

Code (Text):

/vote                                     voteledger.use              Menu of the open polls

/vote menu [page]                         voteledger.use              Menu of the open polls, at a page

/vote <id>                                voteledger.use              Ballot of a poll

/vote list                                voteledger.use              Open polls in chat

/vote info <id>                           voteledger.use              Details and rules of a poll, or its result once closed

/vote help                                voteledger.help             Help, limited to what you may run

/vote results [page]                      voteledger.results          Closed polls, most recent first, with their verdict

/vote results #<id>                       voteledger.results          Full count of a closed poll

/vote propose <duration> [rule:value ...] <question> | <option> | <option> ...

                                          voteledger.propose          Propose a poll to the staff

/vote create <duration> [rule:value ...] <question> | <option> | <option> ...

                                          voteledger.create           Open a poll

/vote proposals [page]                    voteledger.admin.proposals  Proposals waiting for a decision

/vote approve <n> [actions:<set>]         voteledger.admin.proposals  Open a proposed poll

/vote deny <n> [reason]                   voteledger.admin.proposals  Refuse a proposed poll

/vote close <id>                          voteledger.admin.close      Close a poll now and announce its result

/vote cancel <id>                         voteledger.admin.cancel     Cancel a poll, without result or command

/vote extend <id> <duration>              voteledger.admin.extend     Push back the end of a poll

/vote reopen <id> <duration>              voteledger.admin.reopen     Open a closed poll again, its ballots kept

/vote ledger <id> [player] [page]         voteledger.admin.ledger     Every ballot of a poll, with its time

/vote reload                              voteledger.admin.reload     Reload config.yml and the messages

Rule flags, between the duration and the question:

quorum:<n>                 ballots needed for the result to count (0 to 100000)

majority:simple|<50-100>   simple majority or share the winner must reach

change:yes|no              ballots can be changed, or are final

results:live|hidden        count shown before the closing, or not

permission:<node>|none     only players with this permission vote

playtime:<duration>|none   minimum play time on the server

seniority:<duration>|none  minimum time since the first join

actions:<set>              console command set of config.yml (voteledger.admin.actions, create only)

Durations: 30m, 12h, 7d, 1w, 1d12h. Ballot box: [Urn] on line 1 of a sign, the poll number on line 2.

Players have voteledger.use, voteledger.vote, voteledger.help, voteledger.results and voteledger.propose by default. Give voteledger.create to the staff who open polls, and voteledger.admin (or each voteledger.admin.* node) to the staff who manage them.

Spoiler: All permissions

Code (Text):

voteledger.*                 op     Every VoteLedger command

voteledger.use               true   /vote menu, list, info and the announcements

voteledger.vote              true   Cast a ballot, within the eligibility rules of the poll

voteledger.help              true   /vote help

voteledger.results           true   /vote results

voteledger.propose           true   /vote propose

voteledger.create            op     /vote create

voteledger.admin             op     Every voteledger.admin.* node below

voteledger.admin.close       op     /vote close

voteledger.admin.cancel      op     /vote cancel

voteledger.admin.extend      op     /vote extend

voteledger.admin.reopen      op     /vote reopen

voteledger.admin.proposals   op     /vote proposals, approve, deny, and notice of new proposals

voteledger.admin.actions     op     actions:<set> flag of /vote create and /vote approve

voteledger.admin.ledger      op     /vote ledger

voteledger.admin.reload      op     /vote reload

voteledger.admin.urn         op     Place and remove ballot box signs

• rules.defaults — the rules of a poll created without flags: no quorum, simple majority, final ballots, live count.
• actions.sets — named sets of console commands, chosen per poll with actions:<set>; the "example" set shows every list.
• polls — 1m to 30d per poll, 6 options, 20 open polls at the same time.
• proposals — on by default, 1 waiting proposal per player, 20 in total, 1h between two proposals.
• reminders.interval — 15m between two reminders, 0 to turn them off.
• urns.tags — the first lines that turn a sign into a ballot box: [Urn], [Urne] and [Vote].

// Menu items and sounds are read by name; a name unknown to your server version is reported in the console and replaced.

Spoiler: config.yml

Code (Text):

============================================================

 VoteLedger - community polls, voted in game

============================================================

This file is only ever READ by the plugin: your comments and your layout are

never rewritten. Apply your changes in game with /vote reload.

#

What the plugin stores lives next to this file:

  polls.yml - every poll, open or closed, with its rules, one ballot per

              player (who, which option, when) and its ledger, plus the

              proposals waiting for the staff and the console commands

              waiting for an offline voter

  urns.yml  - the ballot box signs placed in the worlds

Do not edit these files while the server is running.

Language of every message and menu shown to players.

"en" and "fr" are provided: messages_en.yml and messages_fr.yml are created in

this folder on first start, edit them freely. For another language, copy

messages_en.yml to messages_xx.yml, translate it and put "xx" here.

Keys added by a future version are appended to your file automatically.

language: en

How dates are written in messages (end of a poll, closing date).

Java SimpleDateFormat pattern: dd/MM/yyyy HH:mm, MM/dd/yyyy hh:mm a...

date-format: "yyyy-MM-dd HH:mm"

polls:

  # Durations are written like 30m, 12h, 7d, 1w or 1d12h (s, m, h, d, w).

  # A plain number is a number of minutes.

  # The shortest and the longest duration /vote create accepts.

  min-duration: 1m

  max-duration: 30d

  # Options a single poll may offer, from 2 to 28.

  max-options: 6

  # Longest question (10 to 256 characters) and longest option (1 to 64).

  # Colour codes typed by the creator are removed.

  max-question-length: 100

  max-option-length: 32

  # How many polls may be open at the same time, from 1 to 500.

  max-open: 20

  # How often the end dates are checked, in seconds (1 to 60). A poll closes at

  # most this long after its end date. The check does nothing while no poll

  # exists. Time counts on the real clock: a poll that ended while the server

  # was off is closed and announced at the first check after the start.

  check-interval-seconds: 5

The rules of a poll are fixed when it opens. The creator sets them with flags

written between the duration and the question, for example:

  /vote create 3d quorum:20 majority:67 change:yes results:hidden playtime:5h

    seniority:7d permission:group.member Reset the End? | Yes | No

Every flag left out takes the default below. Changing a default later does not

change the polls already open.

rules:

  defaults:

    # Ballots needed for the result to count (0 to 100000, 0 = no quorum). Under

    # the quorum the poll decides nothing and the closing says so.

    quorum: 0

    # "simple": the option with the most ballots wins (a tie decides nothing).

    # A percentage from 50 to 100: qualified majority, the leading option must

    # reach this share of the ballots cast (67 for two thirds).

    majority: simple

    # true: a voter may change their ballot until the closing. false: the first

    # ballot is final.

    changeable: false

    # live: the count per option is shown while the poll is open (/vote info and

    # the ballot). hidden: only the number of ballots is shown until the closing.

    results: live

    # Extra permission a voter needs, on top of voteledger.vote ("" = none).

    # Any node works, for example group.member: give it with your permission plugin.

    permission: ""

    # Minimum play t