Bukkit

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.

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

1. Download the latest version of the plugin and put it into your plugins folder
2. Restart the server
3. Check out the config file and fill it out
4. Restart the server again
5. Create your lottery boxes ingame
6. 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.