Animations / Rolls

A roll is the animation a player watches while a crate decides what they win. Each crate picks one roll by ID, and the rolls themselves are tuned globally. By the end of this page you'll know which rolls exist and how rerolls fit in.

What are rolls?

A roll is the animation that plays when a crate opens, before the reward is revealed. You choose one per crate with the roll option in the crate config, and you tune each roll's behaviour in the rolls section of Plugin Config.

Roll IDWhat it doesVideo
csgoScrolls a row of items in a GUI, easing to a stop on the winnerVideo
slot_machineSpins reels in a GUI, stopping them one at a timeVideo
eliminationKnocks candidates out of a GUI one by one until the winner is the last leftVideo
pickFace-down boxes in a GUI; the player clicks one to open itVideo
chooseEvery reward the player can win is shown in a GUI; they click the one they wantVideo
matchA scratchcard: the player scratches cards until enough of them matchVideo
encircleRings the player with items that spin, then reveal the winnerVideo
flashBlinds the player while an item flies toward their faceVideo
orbit_collapseOrbits items around the player, then collapses them into the winnerVideo
vortexSpirals items inwards and upwards, flinging out a loser on every passVideo
rouletteA glowing cursor runs a ring of items and slows to a stop on the winnerVideo
cycleFloats an item at the crate, swapping it every few ticksVideo
hologramNo items at all: a hologram cycles reward names and locks onto the winnerVideo
sky_dropThrows items out of the crate and drops the winner from aboveVideo
strikeThe item rises, hangs, and a lightning strike reveals the winnerVideo
deliveryAn entity carries the reward from the crate to the playerVideo
quickRises a single item out of the crateVideo
instantNo animation, the reward is given straight awayVideo
semi_instantThrows the item out of the crate for a momentVideo

Hiding the placed crate

Rolls that play out in the world can sit on top of a placed crate's hologram and preview item. Each of those rolls has a hide-placed-crate option in config.yml:

rolls:
  cycle:
    hide-placed-crate: true

When enabled, the hologram and floating preview item are hidden from the player opening the crate for as long as the roll runs, then restored when it finishes. Only that player is affected - everyone else still sees the crate as normal.

RollDefault
cycletrue
deliveryfalse
encirclefalse
flashfalse
hologramtrue
orbit_collapsefalse
quickfalse
roulettefalse
semi_instantfalse
sky_dropfalse
strikefalse
vortexfalse

The two that default to true are the ones that take over the crate's own space: cycle swaps the preview item for a cycling one, and hologram replaces the crate's hologram with its own. The rest leave the crate alone unless you turn the option on.

csgo, slot_machine, elimination, pick, choose, and instant have no hide-placed-crate option, because they play out in a GUI or don't animate at all - the crate's hologram never gets in their way. Adding the option to their config section does nothing.

The option is also inert when there's no placed crate to hide, such as opening with /ecocrates open or a virtual key.

The scratchcard

match deals a card of face-down rewards. The player scratches them off one at a time, and the first reward they turn up to-match copies of is what they win.

There's no card size to set. A losing reward is dealt at most to-match - 1 copies, so it can tease a set the player can't finish but never become a second winner, and the card is then dealt as large as the crate's own rewards can fill, up to 21. With to-match: 2 every loser is unique, since a repeat would be a winning pair, so the card is as big as the crate has distinct rewards. Raising to-match allows duplicates and so deals a bigger card: a crate with six rewards deals seven cards at to-match: 2, and thirteen at to-match: 3.

The winner is decided before the roll starts, as it is for every roll except choose, so the card is dealt around it. What the player finds is genuinely on the card, though: the reveal at the end flips the rest face-up and those near misses are the cards they didn't scratch, not invented afterwards.

min-scratches stops an anticlimactic instant win. If the set would complete too early, the winner is quietly moved under a card that hasn't been scratched yet - unscratched cards give nothing away, and past the floor the card behaves exactly as dealt. If the player stops scratching, auto-scratch scratches for them so the roll always finishes.

Choosing your own reward

choose is the one roll where the winner isn't decided beforehand. It opens a GUI listing every reward the player is currently eligible to win (the same eligibility every other roll's weighted pick respects - permission-gated rewards that a player can't win never appear), paginated if there are more than fit on one page. Whichever one they click is what they win.

With several rewards the player makes one choice per reward, the first reward plus each bonus reward. Bonus choices hide rewards that are bonus-eligible: false, and rewards already chosen max-per-open times. A bonus choice with nothing left to offer is dropped: it isn't given and isn't counted in %reward_amount%. The number of choices comes from bonus-chances, and any entry under 100 makes the number of choices random, so a crate that must be fully non-random uses only 100 entries.

If the player doesn't click anything, auto-pick ticks pass and a random eligible reward is chosen for them so the roll can't hang open forever. reveal-time is how long the GUI stays open showing the pick before the crate finishes.

Multiple rewards

A crate or pouch with bonus-chances can give several rewards per open; see How to Make a Crate. Every reward in an open is independent: it is picked, rerolled, counted and runs its effects on its own. Every built-in roll shows several rewards natively, up to its capacity. Every pick is decided when the open starts, so the number of rewards never changes during the animation. The one exception is choose: a bonus choice with nothing left to offer is dropped, so that open gives one reward fewer.

RollWith several rewardsCapacity
instantEvery reward is given at once.Unlimited
semi_instantOne item is thrown out per reward.Unlimited
deliveryOne courier carries every item and hands them over one after another.Unlimited
quickThe items rise side by side around the crate.5
flash, cycle, strikeOne item per reward side by side, each cycling. They lock on in turn, left to right.5
sky_dropOne launch per reward, landing in turn.5
hologramOne block of lines per reward, locking in turn.5
encircle, orbit_collapse, vortexThe roll ends with the last few items left, and each one is a winner.items - 1
rouletteThe cursor stops once per reward, and each stop stays lit.items - 1
csgoOne scrolling lane per reward, stacked. The lanes stop in turn.4
slot_machineOne payline per reward.3
eliminationCandidates are knocked out until as many are left as there are rewards.candidates - 1
pickThe player opens one box per reward. The number of boxes is raised to at least one more than the rewards, up to 7.6
matchThe card holds one set per reward and grows to fit. The player scratches until every set is found.28 divided by to-match
chooseThe player makes one choice per reward. See Choosing your own reward.Unlimited

items, candidates and to-match are the settings of that roll in Plugin Config, so changing them changes the capacity. A roll that needs room for the winners, such as encircle or pick, raises its item or box count automatically when there are more rewards.

If an open has more rewards than the roll's capacity, they play in batches: the roll plays once for the first batch of up to its capacity, then again for the next, in order, until every reward has been shown.

pick and match give the rewards the crate decided in advance, the same as with one reward. The player's clicks only decide where each reward is revealed.

Rolls from other plugins

A roll registered by another plugin that doesn't support several rewards uses multi-reward.fallback, set in Plugin Config or per crate. sequential plays the roll once per reward, one after another. primary plays it for the first reward only and gives the bonus rewards straight after, with no animation.

Rerolls

A reroll lets a player swap a won reward for a fresh roll. After winning, the player is offered the choice to accept the reward or reroll. You can watch a video on rerolls here.

Rerolls are configured per crate with the rerolls: block:

  • enabled: whether rerolling is offered.

  • max-rerolls: how many rerolls in a row before the player is forced to accept. The count resets once a reward is accepted (or forced).

  • price: the cost of each reroll, using the standard price system (currencies or items). The %reroll% placeholder (1-based) lets the price scale per reroll, e.g. value: "%reroll%*2" charges 2, then 4, then 6. If the player can't afford the next reroll, the reward is given automatically.

rerolls:
  enabled: true
  max-rerolls: 3
  price:
    type: emerald
    value: "%reroll%*2"
    display: "&e%value% &7Emeralds"

Each reward in an open is rerolled on its own. max-rerolls and the %reroll% price count per reward. A reward can be rerolled only if the crate's rerolls allow it and the reward isn't set to rerollable: false. Bonus rewards can also be switched off from rerolling with bonus-rerollable. Pouches never offer rerolls.

When a roll shows several rewards at once, a menu lists every reward after the animation. Click a reward to reroll only that one, and the menu reopens with its replacement. Accepting, or closing the menu, gives every reward. Rolls using the sequential fallback offer the normal reroll GUI after each reward instead, and the primary fallback only offers a reroll for the first reward. The menu is configured under reroll.multi in Plugin Config.

A reroll replaces its reward in place, so it can't change how many rewards the open gives. Rerolling a choose reward means choosing it again.

By default every player can reroll where it's enabled. To stop certain groups or players, negate the ecocrates.reroll.<crate> permission. The reroll GUI itself is configured in Plugin Config.


Where to go next

  • Use a roll: set the roll option in How to Make a Crate.

  • Tune a roll: adjust each animation in Plugin Config.

  • Permissions: control who can reroll in Commands and Permissions.