Prison Momentum

PrisonMomentum rewards players for mining without a break. The longer they keep mining in their mine, the higher they climb a ladder of momentum levels, and each level boosts their currency income and enchant proc chances. Stop mining and the momentum drains away, level by level.

The short version

Upload the prisonmomentum jar to your plugins folder and restart the server. Before you test, read the console: if it says a currency booster "is not a PinnaPrison currency", fix the ids first (see The ladder and its boosts). Then join as an operator and run:

/momentum setlevel <your name> 5
/boosters
/momentum
/momentum levels
/momentum toggle
/momentum reset <your name>

1. setlevel puts you straight on level V of the default ladder, with its title, sound and purple boss bar. Players get there by mining; this just skips the wait.
2. /boosters is PinnaPrison's boosters menu. Momentum shows there next to your other boosters, for example ⛏ Momentum V 1.25x for tokens.
3. /momentum opens the momentum menu: your level, progress, streak, active boosts and best-ever records, plus switches for the boss bar and titles.
4. /momentum levels opens the ladder, showing what each level takes and what it boosts.
5. /momentum toggle hides your boss bar. Run it again to bring it back.
6. reset puts your momentum back to zero. While you were in the menus, you'll probably have seen the bar turn red and drain. That's what happens when a player stops mining for more than 10 seconds.

What you need

How momentum builds and drains

Every block a player mines by hand in their mine adds to their momentum bar. Fill the bar and they reach the next level, and the bar starts again towards the level after. Each level's blocks value is what it takes to get there from the level below, so the default ladder needs 40 blocks for level I, 80 more for II, and 6,190 in all to reach X.

If a player stops mining for longer than the grace period (10 seconds), momentum starts draining at 4 blocks a second. When the bar is empty they drop a level, land on a full bar for that level, and keep draining until they reach zero. In other words, draining walks the climb back down. Mining a single block stops the drain straight away.

At the top level the bar keeps filling up to that level's own requirement (1,800 blocks by default). This works as a buffer: a full bar at the top lets a player take a longer break before they drop.

grace-period: 10s

decay:
  blocks-per-second: 4.0

gain:
  sources:
    - MANUAL
  afk-block: false
  block-weights:
    default: 1.0
    # DIAMOND_ORE: 2.0

• grace-period takes 10s, 1m, 1h30m or plain seconds.
• decay.blocks-per-second is the drain speed. Give a level its own speed with decay-blocks-per-second under that level.
• gain.sources decides what counts. MANUAL is blocks mined by hand. Add ENCHANT, BOMB, DRILL, AUTOMINER or OTHER to count blocks broken those ways too; they always use the default weight.
• afk-block: true lets blocks from a player's AFK block session count. It's off so momentum rewards players who are actually there.
• block-weights makes some blocks worth more than others. Anything not listed uses default.

Death, teleports and logging out

What happens when a player dies or teleports is set under loss:

loss:
  death:
    mode: RESET
  teleport:
    mode: DECAY
    only-outside-mine: true

• RESET wipes momentum on the spot. It's the default for dying.
• DECAY doesn't drain any faster. It only changes the reason the boss bar shows (such as "Teleported out of the mine"); the usual grace period and drain still apply. It's the default for teleports.
• NONE ignores it.
• With only-outside-mine: true, only teleports that land outside every mine count. Teleporting around or into a mine, including visiting someone else's, keeps the streak going.

Logging out depends on save-momentum. It's false by default, so momentum only lasts while the player's online: logging out or a server restart puts them back to zero. Set it to true and their level, progress and streak are saved and come back on their next join with a fresh grace period. You can then also turn on offline-decay, which drains momentum for time spent offline. The comments above it in config.yml explain the settings.

Each player's best-ever records (highest level, longest streak and most blocks in one streak) are always saved, whatever these are set to.

The ladder and its boosts

The ladder lives under levels in config.yml. Number the levels 1, 2, 3 and so on without gaps; you can have as many as you like. This is level 3 from the default ladder, trimmed:

levels:
  3:
    icon: YELLOW_DYE
    blocks: 140
    boosters:
      - type: currency
        currency: tokens
        multiplier: 0.15
      - type: currency
        currency: gems
        multiplier: 0.05
    multiplier-display: '&#FFDE59+15% Tokens &8│ &#7EE8FA+5% Gems'

Each level can have:

• blocks (required): the blocks needed to reach it from the level below.
• boosters: the boosts held while on this level. multiplier is the bonus, so 0.15 means +15%.
• multiplier-display: the text players see for this level's boosts in the boss bar, titles and menus. It's only text, so update it whenever you change boosters.
• bossbar: a name and color for the boss bar on this level.
• effects: the title, subtitle, sound, particles and console commands for reaching this level.
• aura: particles around the player for as long as they hold the level. The default ladder gives one to level X.
• decay-blocks-per-second: a drain speed for this level only.
• icon: the item shown for this level in the ladder menu.

There are three types of booster:

Boosts switch on the moment a player reaches a level and off the moment they lose it. They stack with the player's other PinnaPrison boosters, and /boosters lists them under the name set in boosters.name. Blank that name to hide the line; the boost still applies.

By default each level lists its full set of boosts, and only the current level's boosts apply. Set boosters.stack-levels: true and each level adds to all the levels below it instead. If you switch that on, cut each level down to just its increase, or the default ladder adds up to +290% tokens at level X.

Boss bar, titles and effects

The boss bar shows the player's level and progress while they have momentum. While momentum is draining it turns red and shows the reason and the drain speed. Each level can set its own boss bar name and colour; the defaults and the draining style are under bossbar in config.yml. Colours are PINK, BLUE, RED, GREEN, YELLOW, PURPLE and WHITE. Set bossbar.enabled: false to turn it off for everyone, or show-while-building: false to hide it until a player reaches level I.

Reaching a level shows a title, plays a sound and sends particles, all set under visuals.level-up. Any level can override these under its own effects; the default ladder does this for V and X. Dropping a level plays the visuals.level-down sound. Other players in the same mine see the particles too.

Sounds and particles follow each player's PinnaPrison sound and particle settings. Players can also hide the boss bar and level-up titles for themselves with /momentum toggle or the switches in the menu, and that choice is saved.

Commands

/prisonmomentum and /pmom work in place of /momentum. Add -s as the last word of an admin command to run it without the confirmation message, which is handy for crates, vote rewards and command blocks: /momentum addblocks Steve 100 -s. Error messages still show.

Permissions

Building momentum and getting its boosts doesn't need a permission.

Files

/momentum reload applies changes to config.yml and messages.yml, except the storage section, which needs a restart.

The two menu files use PinnaPrison's own GUI format and reload with /pinna reload. They're written on first start and never overwritten, so your edits survive updates. To get a default back, delete the file and restart the server. The comment at the top of each file lists the tokens you can use. The boss bar and title switches (momentum-toggle items) also work in other PinnaPrison menus, such as its settings menu. See the PinnaPrison docs for the GUI format.

Placeholders

Use any key below as %prisonmomentum_<key>% with PlaceholderAPI, or as %pinnaprison_variable_momentum_<key>% in PinnaPrison without it.

PlaceholderAPI also accepts multiplier_<enchant id>, progress_bar, next_level_roman, record_level_roman, reason and rate. PinnaPrison only gets multiplier_<currency> variables for the currencies that exist when the server starts.

Troubleshooting

Players level up, but their income doesn't change or momentum is missing from /boosters. The booster ids don't match your PinnaPrison currencies. Look in the console for "is not a PinnaPrison currency": that line lists the ids PinnaPrison knows. Put the right ones in each level's boosters, then run /momentum reload.

Mining doesn't build any momentum. Only blocks mined by hand count by default. Blocks broken by enchants, bombs, drills and autominers don't, and nor do AFK block sessions. Add the sources you want under gain.sources, or set afk-block: true, then run /momentum reload. Also check block-weights hasn't set default to 0.

/momentum says "The momentum menu isn't loaded" and shows chat stats instead. The menu file is missing or PinnaPrison couldn't load it. If you deleted it, restart the server to put the default back. If you edited it, check it for YAML mistakes and run /pinna reload.

Everyone's momentum resets when they log out or the server restarts. That's the default. Set save-momentum: true in config.yml and run /momentum reload to keep it.

The ladder stops before your last level. The console says why: a level number is missing (levels must run 1, 2, 3 without gaps) or a level has no blocks value above 0. Every level after that point is ignored until you fix it and reload.

After a reload, the ladder and boosts are back to the defaults. config.yml has a YAML mistake, so the plugin is running on its built-in defaults. The reload message still says it worked, but the console shows "config.yml could not be read" with the problem line. Fix it and run /momentum reload again.