🏷️ Codes

On this page, you will find how to configure voucher codes.

#Codes

Every code lives under vouchers in vouchers.yml.

generated-code-alphabet: ABCDEFGHJKLMNPQRSTUVWXYZ23456789
generated-code-length: 8
vouchers:
  '0':
    code: SUMMER25
    enabled: true
    display-name: '&6Summer Giveaway'
    display-item:
      material: PAPER
      display-name: '&aVoucher'
      amount: 1
    key-rewards:
      '0':
        key: vote
        amount: 5
    win-items: {}
    win-commands: []
    redeem-message:
    - '&aYou redeemed the code &f%code%&a!'
    broadcast-message:
    - '&e%player% &aredeemed the code &f%code%&a!'
    broadcast: false
    max-uses: 100
    max-uses-per-player: 1
    expires-at: -1
    permission: ''
    uses: 0
    max-win-item-amount: -1
    max-win-command-amount: -1

Codes and their key rewards are stored as numbered sections rather than YAML lists, the same shape the crate rewards use. The numbers are positions only and have to stay unique inside their section.

#Options

Option	What it does
`code`	What the player types. Matched without regard to casing, so `summer25` and `SUMMER25` are the same code.
`enabled`	Switches the code off without deleting it or losing its usage count.
`display-name`	A friendly name used in messages. Falls back to the code itself when empty.
`display-item`	The icon the reward pipeline uses when the items are handed over.
`key-rewards`	The keys the code gives, as a list of `key` and `amount` pairs.
`win-items`	Items the code gives.
`win-commands`	Commands run when the code is redeemed. Prefix a command with `*` to run it as the player instead of the console.
`redeem-message`	Sent to the player who redeemed the code.
`broadcast-message`	Sent to every online player, only when `broadcast` is on.
`broadcast`	Announces the redemption to the whole server.
`max-uses`	Redemptions allowed across the whole server, `-1` for unlimited.
`max-uses-per-player`	Redemptions allowed per player, `-1` for unlimited. Defaults to `1`.
`expires-at`	Epoch milliseconds after which the code stops working, `-1` for never.
`permission`	The player needs this to redeem the code. Leave empty for everyone.
`uses`	How many times the code has been redeemed. Maintained by the plugin.
`max-win-item-amount`	How many of the win items are given, `-1` for all of them.
`max-win-command-amount`	How many of the win commands are run, `-1` for all of them.

uses is written by the plugin. Editing it by hand changes how many redemptions are left on a code with a max-uses cap, and setting it back to 0 reopens a code that had run out.

#Limits

The two caps do different jobs and are usually combined. max-uses-per-player stops one player redeeming the same code repeatedly, and max-uses caps the giveaway as a whole.

Both are enforced at the moment of redemption rather than on a timer, so two players redeeming the last remaining use at the same instant cannot both get through — one of them is told the code is exhausted.

#Generated codes

generated-code-alphabet and generated-code-length control the codes produced by /crate createVoucher when it is asked to generate one.

The default alphabet leaves out I, O, 0 and 1, so a code read off a screenshot or a Discord message cannot be mistyped into a different valid code. Generated codes are always checked against the existing ones before being used.

#Message placeholders

redeem-message and broadcast-message accept:

Placeholder	Value
`%player%`	The player who redeemed the code.
`%code%`	The code itself.
`%voucher%`	The display name, falling back to the code.

Last updated 9 days ago