Add customizable crates to your server.
Command aliases: /magiccrates
, /mc
Command | Description | Permission | Default |
---|---|---|---|
/magiccrates |
MagicCrates Command | magiccrates.cmd | True |
/magiccrates receive |
Receive all your unreceived rewards | magiccrates.cmd.receive | True |
/magiccrates receive show |
Show all rewards you have not yet received | magiccrates.cmd.receive.show | True |
/magiccrates create |
Toggle crate Create mode | magiccrates.cmd.create | OP |
/magiccrates remove |
Toggle crate Remove mode | magiccrates.cmd.remove | OP |
/magiccrates key <crate_type> [amount] [player] |
Give a crate key to a player | magiccrates.cmd.key | OP |
/magiccrates key all <crate_type> [amount] |
Give a crate key to all the online players | magiccrates.cmd.key.all | OP |
/magiccrates reward set <crate_type> <player> <reward> <amount> |
Set the amount of times a reward is received | magiccrates.cmd.reward.set | OP |
/magiccrates reward reset crate <crate_type> |
Reset the amount of times all rewards from the crate are received | magiccrates.cmd.reward.reset | OP |
/magiccrates reward reset reward <crate_type> <reward> |
Reset the amount of times a reward is received from a crate type | magiccrates.cmd.reward.reset | OP |
/magiccrates reward reset player <player> [crate_type] [reward] |
Reset the amount of times a player has received rewards from crates | magiccrates.cmd.reward.reset | OP |
/mc create
You can remove crates with a command:
/mc remove
You can also remove crates by breaking the crate:
You can only open crates by using a crate key. Each crate type has its own key.
You can create keys using the command /mc key <crate_type> [amount] [player]
When you have a crate key, you can open the matching crate by clicking on the crate.
All crates from the same Crate Type have the exact same content, and when opening a crate of a certain type, a random reward will be given to the player.
You can customize or add your own crates in crate_types.json.
In a crate type, you can specify multiple rewards. However, not every reward will behave the same.
Normal rewards have a static amount of them in the crate which results in a fixed probability of getting the item.
However, you can also create Dynamic rewards.
The probability and amount of getting these rewards depends on the amount
of times the reward has been received by the
player or all players.
Crate rewards have to be added in crate_types.json, and there you can find more information about
creating the rewards.
version
- [DO NOT TOUCH] The version of the config filedelay
- The delay in ticks before the crate-opening animation startsprefix
- The prefix in front of all messages the plugin sendskey
- The item that should be used for the key.show-crate-info
- If players are able to see the contents of a crate, when clicking on a crate without a keyshow-reward-info
- If players are able to see the detailed information of a crate reward, when clicking on a reward
in the crate info form.database
- Settings for the libasynql databaseThe key follows the same structure as the crate reward items.
The only difference is that the name
of the item supports some parameters to distinguish keys for different crate
types
prefix
- The prefix defined in prefix
in the config.ymlcrate
- The name of the crate typecrate_id
- The ID of the crate type
Further information about parameters can be found here.version: 1
delay: 20
prefix: §r[§6Magic§cCrates§r]
key:
id: minecraft:paper
name: §r[§6Crate §cKey§r] §e{crate}
lore:
- §r[§6Magic§cCrates§r]
enchantments:
- name: unbreaking
level: 1
show-crate-info: true
show-reward-info: true
database:
type: sqlite
sqlite:
file: data.sqlite
mysql:
host: 127.0.0.1
username: root
password: ""
schema: your_schema
worker-limit: 1
List of the most important changes in v3.x
crates.json
and rewarded_players.json
to the database tables Crates and
Rewards respectivelyMigrator
to migrate all old JSON files to the databasekeyall
commandPermission | Description | Default |
---|---|---|
magiccrates.cmd |
Access to the /magiccrates command |
OP |
magiccrates.cmd.create |
Access to the /magiccrates create command |
OP |
magiccrates.cmd.remove |
Access to the /magiccrates remove command |
OP |
magiccrates.cmd.key |
Access to the /magiccrates key command |
OP |
magiccrates.cmd.key.all |
Access to the /magiccrates keyall command |
OP |
magiccrates.break.remove |
Permission to remove a crate by breaking it | OP |
The crate_types.json
file contains all crate types, including the rewards.
You can find all the specifications about how to create your own custom crate types below.
If there is something wrong with the file (e.g. invalid json, a type is missing required values, or invalid data values are given) the plugin will notify you in the server console on startup indicating what went wrong, so that you can fix the error.
The basic structure in crate_types.json
is defined like the following:
{
"<type_id>": "CrateType",
...
}
You can add as many crate types (<type_id>: CrateType
) to this file as you need, but every CrateType
needs an ID!
{
// the name shown above the crate
"name": "string",
// the crate rewards
"rewards": "CrateReward[]",
// commands executed after a player opened the crate
"commands": "Command[]",
// [optional] a reward or reward id that should be used as the replacement reward
"replacement": "CrateReward|string"
}
The replacement defined in the CrateType
is used as a global replacer for all DynamicCrateReward
's (unless there is
a replacement specified in the DynamicCrateReward
).
Since v3.0.0, it is possible to register crate rewards with unique ID's. It is recommended to use unique ID's as those
will prevent issues which can occur when renaming dynamic rewards without ID.
But because all versions before 3.0.0 do not make use of this system, I decided to make it backwards compatible until
v4.0.0 releases.
Recommended:
{
"rewards": {
"<reward_id>": "CrateReward",
...
}
}
Deprecated: (will be removed in v4.0.0)
{
"rewards": [
"CrateReward",
...
]
}
A command is a string representing the command you want the CONSOLE to execute, but it is possible to include some parameters in the command.
to use the parameter, include {<parameter>}
in the string.
parameter | description |
---|---|
prefix | The prefix defined in the config.yml |
player | The name of the player that opened the crate |
crate | The name of the crate type that was opened |
crate_id | The ID of the crate type that was opened |
reward | The name of the reward the player received |
reward_id | The id of the reward the player received |
A Command will look something like this: "say {player} received {reward} from a {crate}"
.
Executing this command will result
in say Hebbinkpro received Unique Diamond from a Rare Crate
when Hebbinkpro
opened
a Rare Crate
and won a Unique Diamond
.
This is the data structure of a CrateReward
{
// name of the reward
"name": "string",
// amount of this reward inside the crate.
"amount": "int",
// the item(s) the player gets
"items": "Item[]",
// commands executed when the player wins this reward
"commands": "string[]",
// [optional] path/url to an image that will be displayed in the crate UI
"icon": "string"
}
At least one item or command should be given
This is the data structure of a DynamicCrateReward
{
// name of the reward
"name": "string",
// [optional] amount of this reward inside the crate.
"amount": "int",
// [optional] maximum amount of this reward the player can get
"player_max": "int",
// [optional] maximum amount of this reward that can be awarded server wide
"global_max": "int",
// [optional] amount of the replacement reward inside the crate
"replace_amount": "int",
// [optional] if the reward should be replaced by a replacment reward when the maximum is reached
"replace": "bool",
// the item(s) the player gets
"items": "Item[]",
// commands executed when the player wins this reward
"commands": "string[]",
// [optional] path/url to an image that will be displayed in the crate UI
"icon": "string",
// [optional] a reward or reward id that should be used as the replacement reward
"replacement": "CrateReward|string"
}
The dynamic reward is a more complex version of the default reward.
player_max
AND/OR global_max
should be specified (>0
), otherwise it is a normal CrateReward
amount
is given, the amount will be used for the reward distribution, otherwise the amount of times the player is
allowed to get the reward will be used.replace_amount
is given, this is used for the max amount of replacementsreplace
is false
, the reward will not be replacedreplacement
is given, this will be used as the replacement for the rewardamount
is specified, there will be some of the replacement
reward inside the crate based upon the amount of
times the player has received the reward.WARNING You can only use a normal CrateReward
as a replacement reward.
Icons are used for the UI when you interact with a crate without a key. In this UI, all items available in the chest are
displayed with their icon.
By default, the icon of the rewarded item will be displayed, but you can customize this by providing an url.
You can use minecraft textures, in this case you only have to provide the path that points to a texture inside
the texture pack (e.g. textures/items/diamond
or textures/blocks/dirt
)
This is the data structure of an Item
inside a CrateReward
.
Items registered using Customies are also supported, but make sure you identify them correctly.
{
// id of the item (e.g. minecraft:dirt or customies:example)
"id": "string",
// [optional] custom name of the item
"name": "string",
// [optional] amount of the item the player will receive
"amount": "int",
// [optional] add one or more lines of lore to the item
"lore": "string | string[]",
// [optional] list of enchantments applied to the item
"enchantments": "Enchantment | Enchantment[]"
}
This is the data structure of an Enchantment
inside an Item
{
// name of the enchantment
"name": "string",
// level of the enchantment
"level": "int"
}
Note: The enchantment name should be registered in PMMP, otherwise the crate type will not be loaded
{
"common": {
"name": "§cCommon §6Crate",
"rewards": {
"iron": {
"name": "Common Iron",
"amount": 5,
"item": {
"id": "iron_ingot"
}
},
"dirt": {
"name": "Dirt",
"amount": 15,
"item": {
"id": "dirt",
"amount": 2
}
}
}
}
}
If a player opens this crate:
iron
and 15x dirt
iron
is 5/20 * 100% = 25%
{
"rare": {
"name": "§bRare §6Crate",
"rewards": {
"diamond": {
"name": "Unique Diamond",
"global_max": 1,
"replacement": "dirt",
"item": {
"id": "diamond",
"name": "Unique Diamond",
"amount": 1,
"lore": "The only Unique Diamond available in the server",
"enchantments": [
{
"name": "efficiency",
"level": 1
}
]
},
"commands": [
"msg {player} you are the only player in the server with this diamond."
]
},
"dirt": {
"name": "Dirt",
"amount": 9,
"item": {
"id": "dirt",
"amount": 2
}
}
},
"commands": [
"say {player} won {reward} from a {crate} crate"
]
}
}
If a player opens this crate:
diamond
and 9x dirt
diamond
, replace the diamond
by 1x dirt
amount
, or replacement_amount
given, global_max
or player_max
is useddirt
{
"magic": {
"name": "§cMagic §6Crate",
"replacement": "dirt",
"rewards": {
"shard": {
"name": "Magic Shard",
"player_max": 1,
"amount": 5,
"replace_amount": 10,
"item": {
"id": "amethyst_shard",
"name": "Magic Amethyst",
"amount": 1,
"lore": "A Shard full of Magic"
},
"commands": [
"msg {player} you have received your only magic shared."
]
},
"dirt": {
"name": "Dirt",
"amount": 40,
"item": {
"id": "dirt",
"amount": 2
}
}
},
"commands": [
"say {player} won {reward} from a {crate} crate"
]
}
}
If a player opens this crate:
shard
and 40x dirt
shard
, the shard is replaced by 10x dirt
(replace_amount
x replacement
)
dirt
and no shards