Prison Perks

PrisonPerks lets players spend Perk Tickets to roll a random perk onto their PinnaPrison pickaxe. A perk is a set of permanent boosts, such as extra money, tokens or enchant procs, at a level from I to V. The rarer the perk, the harder it is to land.

The short version

Upload the prisonperks jar to your plugins folder and restart the server. The console should say prisonperks enabled (20 perks, ...). Then join as an operator, put your prison pickaxe in your inventory and run:

/pinna reload
/prisonperks tickets give <your name> 5
/perks
/prisonperks info

1. /pinna reload loads the "Perk:" line that PrisonPerks added to PinnaPrison's pickaxe lore on its first start. You only need to do this once.
2. tickets give gives you five Perk Tickets. Every roll costs one.
3. /perks opens the Pickaxe Perks menu. Click Roll a Perk: the ring spins for three seconds, then the perk lands on your pickaxe and the result shows in chat.
4. /prisonperks info shows your perk, its boosts, your tickets and your pity progress. Hold the pickaxe and the boosts apply.

What you need

How perks work

Each player has one perk at most. Rolling again replaces it, whatever it was. The perk is saved against the player, not the item, so it stays if their pickaxe is replaced. It shows in the pickaxe lore as a "Perk:" line.

A perk only boosts while the prison pickaxe is in the player's main hand. That's boosts.require-held: true in config.yml. If your players earn a lot without holding the pickaxe, from autominers, robots or the AFK block, set it to false so the perk always counts.

Perk boosts aren't timed boosters. PinnaPrison counts them every time it works out income or enchant chance, so they stack with boosters, crystals and rebirth upgrades. While a perk is active it also shows in PinnaPrison's /boosters menu as a line like "Pickaxe Perk (Fortune Perk V)". Change that wording with booster.name in messages.yml.

Rolling, odds and pity

A roll costs one ticket and needs the player's prison pickaxe somewhere in their inventory. PrisonPerks then picks:

1. The perk, weighted by each perk's chance. Weights are relative: a perk with chance: 5 is twice as likely as one with 2.5, however many perks there are.
2. The level, weighted by roll.level-weights in config.yml. The default [50, 25, 15, 7, 3] gives level I half the time and level V 3% of the time. A perk file can set its own level-weights.

The result is decided before the spin starts, so closing the menu or logging out mid-spin never loses it: the perk is applied straight away. The spin only plays when the roll is made from the menu. Its length and sounds are under roll.animation, and enabled: false makes every roll instant.

Pity luck. Every 500th roll is guaranteed to come from the EPIC tier, which the messages call a "Purple Perk". Its level is rolled as normal. The counter only resets on that guaranteed roll, so landing an Epic perk by luck doesn't reset it. Change the count and the tier under pity: in config.yml.

The bundled perks and their odds:

/prisonperks list prints the real chance of every loaded perk, so run it after you change anything.

Editing perks

Each perk is one file in plugins/prisonperks/perks/. The file name is the perk's id, which /prisonperks setperk uses. The comment block at the top of money.yml explains every key. Trimmed, the Money Perk looks like this:

display-name: '&a&lMoney Perk'
tier: COMMON
material: EMERALD
chance: 12.5
lore:
  - '&8ᴘɪᴄᴋᴀxᴇ ᴘᴇʀᴋ &8• {tier-color}{tier}'
  - '{levels}'
  - '&7Roll chance: &f{chance}% &8({chance-real}% of all rolls)'
levels:
  '1': { lore: ' &a┃ &fI &8» &aMoney &7+5%',   boosts: { money: 0.05 } }
  '5': { lore: ' &a┃ &fV &8» &aMoney &7+25%',  boosts: { money: 0.25 } }

• tier is COMMON, UNCOMMON, RARE, EPIC or LEGENDARY. It sets the tier name and colour in the lore, the grouping in the index and which perks pity can give. It doesn't change the odds; chance does.
• material takes a Bukkit material, player-<name> or texture-<base64> for a custom head.
• lore is the text on the perk's icon in the menus. {levels} expands to every level's lore line.
• Each level's boosts sets a bonus per stat as a decimal: 0.25 is +25%. The level's lore line is only text, so update it when you change a number.

The boost keys you can use:

A key PinnaPrison doesn't recognise does nothing, and the console warns about it at startup and on reload.

To add a perk, copy a file, rename it (the new name is the id), edit it and run /prisonperks reload. To remove one, delete the file or rename it so it no longer ends in .yml. Anyone who had it loses its boosts. Setting chance: 0 doesn't remove a perk: it's treated as 1.

The 20 bundled perks are only written when the perks folder doesn't exist, so a perk you delete stays deleted. To get them all back, delete the whole folder and run /prisonperks reload.

Perk Tickets

Tickets are the only way to roll. New players start with tickets.starting from config.yml (0 by default). Changing it later doesn't affect players who've already joined. There are three ways to hand tickets out:

• The ticket store in /perks. Three buttons sell 1, 10 and 25 tickets for 5,000, 45,000 and 100,000 tokens. Change them in plugins/PinnaPrison/guis/prisonperks/tool-perks.yml, then run /pinna reload:
  yamlCopy

  buy-1:
    custom-item:
      type: 'perks-buy-tickets'
      amount: 1
      cost: 5000
      currency: 'tokens'

  currency can be any PinnaPrison currency id. The amount: outside custom-item only sets the stack size of the icon.
• A console command, for crates, votes or anything else that runs commands: prisonperks tickets give <player> 5 -s. It works for offline players who've joined before.
• The PinnaPrison currency perktickets. Anywhere PinnaPrison takes actions, give-eco perktickets 5 gives five tickets. The PrisonPass rewards perk-tickets-1, perk-tickets-3 and perk-tickets-5 already use it.

So PinnaPrison shows a proper name instead of perktickets, add this to plugins/PinnaPrison/external-currencies.yml:

currencies:
  perktickets:
    display-name: 'Perk Tickets'
    color:
      primary: '&d'
      secondary: '&5'

The menus

/perks opens Pickaxe Perks: pity progress at the top, a Perk Index button, the player's pickaxe in the middle with the spin ring around it, the Roll button and the ticket store. PinnaPrison's token and gem enchant menus already have a PERKS button that runs /perks. On its first start PrisonPerks changes that button's lore from "sword perks" to "pickaxe perks". Closing Pickaxe Perks takes players back to the token enchant menu; change or blank main-menu: 'token-enchants' in tool-perks.yml to change that.

Perk Index (/perks index, or the book in Pickaxe Perks) lists every perk grouped by tier, with its levels and boosts. The perk the player has glows and shows its level.

Both are PinnaPrison menu files, so you edit them like any other PinnaPrison menu. The comment block at the top of tool-perks.yml lists the PrisonPerks item types and the {tokens} you can use.

Commands

Player commands:

Admin commands (alias /pperks):

tickets, setperk, removeperk and info also work on offline players who've joined before. Add -s as the last argument to run a command without sending you any feedback, for example /prisonperks tickets give Steve 5 -s. The player still gets their own message, such as "You received 5 Perk Tickets".

Permissions

Files

PrisonPerks writes the two menu files at startup only if they're missing, and never overwrites them, so your edits are safe. To get a default back, delete the file and restart; /pinna reload alone won't bring it back.

On its first start PrisonPerks also edits three PinnaPrison files once: it adds the perk line to plugins/PinnaPrison/pickaxe/config.yml and rewords the PERKS button in guis/token-enchants.yml and guis/gem-enchants.yml. It keeps a copy of each original, ending in .prisonperks.bak. Set hooks.pinnaprison.pickaxe-lore.auto-patch: false before the first start if you'd rather make these changes yourself.

Placeholders

PinnaPrison's own variables need no extra plugin and work in the pickaxe lore and PinnaPrison menus and messages: %pinnaprison_variable_perk_<key>%, plus %pinnaprison_variable_perk% for the current perk. With PlaceholderAPI the same values are %prisonperks_<key>%.

For the boost keys the PinnaPrison form is %pinnaprison_variable_perk_boost_money%, without a second perk_, and it only exists for keys at least one perk uses. Write tool-exp as pickaxexp here. Values are only filled in for online players; offline players show 0 or blank.

With PlaceholderAPI installed and EdPerks not installed, %edperks_<key>% returns the same values, so scoreboard lines written for EdPerks keep working. Turn this off with hooks.placeholderapi.edperks-compat: false.

Troubleshooting

The pickaxe lore doesn't show a "Perk:" line. Run /pinna reload after the first start. If it's still missing, check the console from that start. If it says it "Could not find where to insert the perk line", add the line from hooks.pinnaprison.pickaxe-lore.line to the lore in plugins/PinnaPrison/pickaxe/config.yml yourself. To make PrisonPerks try again, delete plugins/prisonperks/.pickaxe-lore-patched and restart.

"You must be holding your prison pickaxe to roll a perk!" PrisonPerks couldn't find the player's PinnaPrison pickaxe anywhere in their inventory. An ordinary pickaxe doesn't count. Get the prison pickaxe back into their inventory and roll again.

A player has a perk but earns no more than before. By default the perk only boosts while the prison pickaxe is in their main hand. If most of their income comes from autominers or other things that run while they hold something else, set boosts.require-held: false and run /prisonperks reload. Also check the console for "which is neither a PinnaPrison currency nor an enchant": that perk uses a boost key your server doesn't have, so fix the key in its file.

give-eco perktickets does nothing, or tickets show as "perktickets". The console should say "Registered Perk Tickets as PinnaPrison currency 'perktickets'" at startup. If it doesn't, set hooks.pinnaprison.external-currency: true and restart; a reload won't change it. For a proper name, add the external-currencies.yml entry from Perk Tickets.

/perks says "The perks menu isn't loaded". tool-perks.yml is missing from plugins/PinnaPrison/guis/prisonperks/. Restart the server and PrisonPerks writes the default again.

A perk you added or edited doesn't show up. Run /prisonperks reload, then check the console. A YAML mistake ("could not be read") or a file with no levels ("no 'levels' defined") means the perk is skipped. An unknown tier falls back to COMMON. Run /prisonperks list to see what loaded.