Prison Events

PrisonEvents runs timed events on your prison server. Players race to mine the most blocks, earn the most currency or reach a shared goal together, and the plugin pays rewards to the winners and to everyone who took part. Events start on their own on a timer, or you can start them by hand.

The short version

Upload the PrisonEvents jar to your plugins folder and restart the server. Then, as an operator, run:

/events list
/events start mining-frenzy 2m
/events
/events top
/events stop mining-frenzy
/events next

1. /events list shows every event that loaded, with its id. Out of the box that's community-mine, mining-frenzy, ore-rush and race-to-1000.
2. /events start mining-frenzy 2m starts Mining Frenzy for two minutes instead of its usual ten. Everyone online gets a start message and title, and a boss bar and action bar appear. Now mine a few blocks in a PinnaPrison mine.
3. /events shows the time left, your score, your position and the leader.
4. /events top shows the leaderboard.
5. /events stop mining-frenzy ends the event now. Rewards are still paid when you stop an event by hand, so you'll see the winner announcement and get the first-place reward.
6. /events next shows which event the scheduler will start next, and when. By default a random event starts every 45 minutes to 1 hour 15 minutes.

What you need

How an event works

Every event is one file in plugins/PrisonEvents/events/. The file name is the event's id, so ore-rush.yml is the event ore-rush. You can sort files into subfolders; the id is still the file name.

An event's type decides how it's won:

Its objective.type decides what counts as score:

An event doesn't change what players earn while it runs. It keeps score, then pays rewards when it ends. The set-up comes with six events:

Adding or changing an event

Anything an event file doesn't set comes from event-defaults at the bottom of config.yml. Change a key there to change every event; set the same key in one event file to change only that event.

To add an event, copy a file in events/, rename it (the new name is the id), edit it and run /events reload. Here's mining-frenzy.yml, trimmed:

name: "&6&lMining Frenzy"
description: ["&7Mine as many blocks as you can!"]
duration: 10m
type: LEADERBOARD
objective:
  type: BLOCKS_MINED
  name: "Blocks"
milestones: [1000, 5000, 10000, 25000]
rewards:
  placements:
    1:
      - "[GIVE-ECO] tokens 25k"
      - "[FIREWORK] GOLD YELLOW"
    2: ["[GIVE-ECO] tokens 10k"]
    3: ["[GIVE-ECO] tokens 5k"]

• name and description take colour codes: &a and &#RRGGBB. objective.name is the word shown after scores, such as "Blocks".
• duration takes 90s, 5m, 1h30m or 2d.
• objective.goal is the target for FIRST_TO_GOAL and COMMUNITY events. On a LEADERBOARD event it only feeds the progress bars and percentages.
• milestones are scores that trigger a message. In a COMMUNITY event everyone hears when the shared total passes one; in other events each player gets a private message when their own score does.
• permission limits scoring to players with that permission node, and enabled: false keeps the file but doesn't load the event.

To narrow down what counts, use the keys under objective.filter. All of them are optional:

A blocks filter stops enchant, bomb, drill and autominer blocks counting, even with count-enchant-blocks: true, because those breaks don't report which blocks they were.

Scheduling events

The scheduler section of config.yml starts events on its own:

scheduler:
  enabled: true
  mode: INTERVAL              # INTERVAL (random event every interval-min..interval-max) or TIMES
  interval-min: 45m
  interval-max: 1h15m
  times: ["12:00", "18:00", "21:00"]   # TIMES mode, HH:mm
  timezone: system            # e.g. Europe/London
  min-players: 1              # online players required (events may require more)
  retry-interval: 5m          # when an event cannot start, try again after this
  avoid-repeat: true          # never pick the same event twice in a row
  announce-before: [300, 60, 10]   # seconds before the start: messages.yml -> scheduler.starting-soon
  events: []                  # only pick from these ids (empty = every event with scheduler.enabled: true)

In INTERVAL mode the wait is a random time between interval-min and interval-max, counted from when the last automatic event started (or from server start). In TIMES mode an event starts at each listed time; if times is empty, the scheduler falls back to INTERVAL. If an event can't start when it's due, the scheduler tries again after retry-interval.

The scheduler picks at random from the eligible events, using each event's own scheduler section (enabled: true, weight: 10, min-players: 1 and cooldown: 0s in event-defaults). A higher weight makes an event more likely to be picked. enabled: false or weight: 0 keeps it out of the schedule, but you can still start it with /events start. min-players is how many players must be online for this event, and cooldown is how long after the scheduler last started it before it can be picked again.

/events pause stops the countdown until /events resume. A pause lasts until you resume or restart the server. /events reload and a restart both reset the countdown to the next automatic event.

Rewards

Rewards are lists of actions under rewards in an event file or in event-defaults:

event-defaults gives 500 tokens to anyone who scores at least 100. Every bundled event keeps that participation reward except Community Mine and Vote Party, which turn it off with actions: [].

Rewards aren't paid when an event is cancelled by /events reload or a restart, or when you stop it with /events stop and rewards-on-manual-stop is false. If a COMMUNITY event misses its goal, placements and community rewards are skipped; set community-placements-when-failed: true in config.yml to pay placements anyway.

offline-rewards decides what happens to players who left before the end. queue (the default) saves their rewards and gives them when they next join. true pays now, but only currency, console and broadcast actions work for an offline player. false skips them.

Placeholders such as {player}, {event}, {position} and {value_formatted} work in actions. To give crate keys, use [CONSOLE] prisoncrates give {player} <crate> <amount> (see PrisonCrates).

What players see

Each event file (or event-defaults) controls the displays:

• Boss bar (bossbar): the text, color and style, and what the bar shows with progress: TIME drains as time runs out, TIME_ELAPSED fills, GOAL shows the shared total (or the leader's score) against the goal, and PLAYER shows the player's own progress. It flashes flash-color in the last flash-seconds.
• Action bar (actionbar): added after PinnaPrison's own action bar text, using the actionbar.addon-separator from PinnaPrison's display.yml, and shown alone when PinnaPrison has nothing to show.
• Chat, titles and sounds (messages, titles, sounds): start, countdown (at each second in countdown-at), milestones, end, no winner, cancelled, goal reached, community goal failed, and join-info for players who join mid-event. An empty string turns one off.
• Winner announcement (winner-announcement): the top placements players are announced in chat. Every line containing {head} gets one row of the winner's face. Faces of offline players come from Mojang's servers (the chat-head section of config.yml); if one can't be fetched, Steve is drawn instead.

Players can hide these with /events toggle bossbar, actionbar, messages or all. Turning off messages also hides event titles and sounds. The choice is saved.

Commands

The main command is /prisonevents, with the aliases /events, /ev, /prisonevent and /miningevents. Players can use these:

Admin commands:

Permissions

The permission keys in event files take any node you choose; give it to players with your permissions plugin.

Files

/events reload applies changes to all three kinds of YAML file, except the storage section of config.yml, which needs a restart. The six example events are only written when the events folder doesn't exist, so a deleted example doesn't come back. To get them all back, rename the folder, run /events reload, then move your own event files back. PrisonEvents has no menus.

Placeholders

These need PlaceholderAPI:

Inside event files, and as <key> above, you can use {event}, {description}, {objective}, {duration}, {time_left}, {time_left_short}, {goal_formatted}, {total_formatted}, {percent}, {bar}, {time_bar}, {participants}, {leader_name}, {leader_value_formatted}, {top_1_name} and {top_1_value_formatted} (up to leaderboard-size, 10 by default). For the player there's {player}, {progress_formatted}, {position}, {position_suffix}, {player_percent}, {player_bar}, {remaining_formatted} and {behind_leader_formatted}. Rewards and winner lines add {value_formatted} (the player's final score), and placement rewards and winner lines also have {winner}. Formatted numbers use PinnaPrison's number format, so they match the rest of your server.

Troubleshooting

No events start on their own. Run /events next. If automatic events are disabled, set scheduler.enabled: true and run /events reload; if they're paused, run /events resume. Otherwise check that enough players are online for scheduler.min-players and the events' own min-players, that no event is still running, and that scheduler.events (if you filled it in) lists real ids.

Winners didn't get their rewards. Look in the console for Unknown currency or Invalid amount warnings: the currency in [GIVE-ECO] must match a currency id from PinnaPrison's currencies folder. Events cancelled by a reload or restart pay nothing, and a COMMUNITY event that missed its goal skips placements. Players who were offline get queued rewards when they next join.

Enchant, bomb or autominer blocks don't count. Set objective.count-enchant-blocks: true in the event file. Only Community Mine has it on out of the box. Events with a blocks filter, like Ore Rush, never count these blocks.

An event is missing from /events list. Check the console after /events reload. Could not load events/... means a YAML mistake, and Duplicate event id means two files share a name in different subfolders. Files with enabled: false, like Money Maker and Vote Party, are skipped on purpose. To use Money Maker, set objective.filter.currencies to the currency id players earn, remove enabled: false and reload. Only earnings made while the player is online count.

Vote Party doesn't give keys. The bundled reward line [CONSOLE] crate givekey {player} vote 1 isn't a PrisonCrates command. Change it to [CONSOLE] prisoncrates give {player} <crate> 1, using a crate id from plugins/PrisonCrates/crates/. Vote Party also ships turned off, so remove the top-level enabled: false from vote-party.yml and run /events reload. Votes only count while the event runs, so start it with /events start vote-party and have your vote plugin run events progress <player> vote-party 1. While it runs (an hour by default), no automatic event starts.