Chance-based key-and-chest rewards system, with more to come.

This plugin requires Java 7 or later

LotteryBoxes allows you to assign chests as "lottery boxes" - Locked boxes that have a chance of being opened by an item assigned as a key. If the box is opened successfully, then a configured reward is picked randomly from within, with regard to their configured weighted chances.

Purity rating

Origin

This plugin was inspired by this plugin request thread. Many thanks to Jduffygames for the idea!

Features

Ingame configuration and easily-editable JSON data file
Item, command and economy/soft-currency (using Vault) rewards
Any item can be assigned as a key; the key will be used up when you attempt to open a box with it
Boxes can require keys named specifically for them, or can use a generic key, but will always refuse to open to a key from another box
Almost all messages in the plugin are configurable, as well as having a configurable prefix

Installation

Download the latest version of the plugin and put it into your plugins folder
Restart the server
Check out the config file and fill it out
Restart the server again
Create your lottery boxes ingame
Done!

Changelog

0.0.1: Closed beta release

0.0.2: Initial release, including customization of most messages

0.0.3: /givekey command, for giving keys to players directly

Configuration

Most of the messages in the plugin are fully configurable. Take a look at the config.yml file generated by the plugin, and edit it to your liking.

Note, the prefix and messages all support colour codes beginning with the ampersand symbol (&).

prefix - A prefix applied to every message from the plugin, aside from stack traces. Set this to two double quotes ("") to disable it.
messages - A set of most of the messages in the plugin. Disable any of them by setting it to two double quotes ("").
version - Don't edit this! It's used to update the configuration when the plugin is updated and I add new things to it.

Permissions

Note, these will be changed when I refactor the commands system.

lotterybox.chbox - Access to the /chbox command
lotterybox.givekey - Access to the /givekey command
lotterybox.lsbox - Access to the /lsbox command
lotterybox.mkbox - Access to the /mkbox command
lockbox.mkkey - Access to the /mkkey command
lotterybox.open - Access to open the lottery boxes
lotterybox.rmbox - Access to the /rmbox command

lotterybox.admin - All of the permissions, except for lotterybox.open
lotterybox.* - All of the permissions

Commands

Note, these will be changed when I refactor the commands system.

/chbox <name> <operation> [params] - Change the settings and rewards for a given lottery box
- Operation: help - A help system for this specific command
  - Use on its own for basic help, or supply one of the operations for more information.
- Operation: reward - Rewards management
  - Syntax: /chbox <name> reward <operation> [value]
  - Operation: add <reward name> <type> - Add a new reward to the box. Type can be item, command or money
    - Rewards will be added in a default state of emptiness, with 0 chance
  - Operation: remove <reward name> - Remove a reward from a box
  - Operation: chance <reward name> <value> - Set the relative chance of this reward being picked
  - Operation: set <reward name> <value> - Set the end result of this reward being picked
    - If the reward type is money, this should be a number representing how much money to give
    - If the reward type is item, this can be one of two things..
      - ItemName:Amount - For example, DIAMOND:3
      - hand, if you're doing this ingame, for the stack of items you're currently holding
    - If the reward type is command, this should be the command to run. It will be run as the console and supports the following tokens..
      - {NAME} - The player's name
      - {WORLD} - The current world
      - {X} - The player's current X position (as an integer)
      - {Y} - The player's current Y position (as an integer)
      - {Z} - The player's current Z position (as an integer)
      - {BOX} - The name of the box being opened
      - {REWARD} - The name of the reward being given
- Operation: set - Management of box-specific options
  - Syntax: /chbox <name> set <option> <value>
    - Option: chance - The one-in-x chance of this box opening successfully.
    - Option: keys - Whether to use named keys, or named and generic keys. Set to named for the former, all for the latter.
    - Option: uses - How many rewards this box can dispense, or infinite to remove the limit.
/givekey <player> [item] [box name] - Give a box key directly to a player - it'll be dropped on the ground if their inventory is full
/lsbox [name] ["rewards"] - List lottery boxes and get information on them
/mkbox <name> [world] [x] [y] [z] - Look at a chest and run this to designate it as a lottery box, or manually specify the location
/mkkey [name] - Create a key (optionally for a specific box)
/rmbox <name> - Remove a lottery box that already exists

Usage

First, create some lottery boxes.
Then, create some keys. You can use any item you want for this.
Using the commands above, set up your lottery boxes with their options and rewards.
Hide your keys, make them available in chest shops, or whatever you plan to do to distribute them.
When someone has a key, they should simply hold the key and right-click on the box they want to open.

Planned additions and changes

Redo the commands and permissions systems so they're more user-friendly and less messy
Add support for chest keys being generated in dungeon
Consideration of supporting plugins such as HolographicDisplays and Prism (this is a long way down the line, though)

How are you using this plugin?

I'd love to know! If you've found an interesting or novel use for this plugin, then please leave a comment - it'll help me gauge both interest and what to work on with this plugin next.

Development releases

Development builds of this project can be acquired at the provided 
continuous integration server. These builds have not been approved 
by the BukkitDev staff. Use them at your own risk.

There's an automated build server here: Bamboo. As the above disclaimer says, these builds aren't approved by the Bukkit team, so take backups!

Please note

This plugin was created specifically for my community, The Archives. Therefore, some of the features for this plugin will reflect our own personal needs from it. However, I am more than happy to take suggestions!

Remember, you need to be using Java 7 or later to use this plugin. If you aren't already using Java 7, you should take the time to upgrade as it contains many speed, security and stability improvements.

The source is available on GitHub.