The following sections explain how each Thing works and where they are supported. For class items that are not supported by the item syntax, check out Class Chests.

Items

Syntax: <id> or <id>:<amount> or <id>:<data>:<amount>
Use in: Class items/armor, rewards, upgrade waves, supply waves, boss waves, entry fees

Items are denoted by their item IDs as defined in the Material enum of the Bukkit API. The item names are case-insensitive, i.e. dirt is the same as DIRT, but the underscores are significant, i.e. cookedbeef is NOT the same as cooked_beef.

The different syntax forms work as follows:

Use <id> if you just want a single item (without data value)
Use <id>:<amount> if you want to give more than one of an item (without data value)
Use <id>:<data>:<amount> if you want to give an item with a data value, even if you just want one.

Data values are necessary for certain types of items and vary quite a bit:

Potions and tipped arrows use the PotionType enum of the Bukkit API as data values. Prefix potion types with strong_ to get level II potions or long_ to get extended duration potions.
Wool and dyes use the DyeColor enum of the Bukkit API.

Enchantments can be added to items that support them. The syntax is an extension of the normal item syntax, where we add a space, and then a semicolon-separated list of pairs of namespaced enchantment ID and a level:

Use <item> <ench>:<lvl> if you want to add a single enchantment to an item.
Use <item> <ench>:<lvl>;<ench>:<lvl> if you want to add two enchantments to an item.
Use <item> <ench>:<lvl>;<ench>:<lvl>;<ench>:<lvl> for three enchantments, and so on...

The <item> portion is just normal item syntax as described above, i.e. <id> or <id>:<amount>, etc. The <ench> portion is a namespaced ID, e.g. bane_of_arthropods for Bane of Arthropods or fire_protection for Fire Protection. A list of enchantments can be found here. To find the namespaced ID for an enchantment, follow the link to the details page for the enchantment and look in the Data values section. As an example, the namespaced ID for Sweeping Edge is sweeping according to its details page. It is simpler than it sounds. Check out the examples below.

By adding enchantments to an enchanted book item, the enchantments are stored in the book rather than the book itself getting enchanted.

Examples

Syntax	Result
`dirt`	1x block of dirt
`dirt:5`	5x block of dirt
`wool:blue:1`	1x block of blue wool
`splash_potion:speed:2`	2x splash potions of Speed I
`potion:long_speed:1`	1x extended duration potion of Speed I
`potion:strong_speed:3`	3x potion of Speed II
`tipped_arrow:poison:10`	10x poison arrows
`diamond_sword knockback:1`	1x diamond sword with Knockback I
`bow infinity:1;power:5`	1x bow with Infinity and Power V
`enchanted_book flame:2`	1x enchanted book with Flame II in it

Notes

Different Minecraft versions may have different names for the same thing. For example, an iron shovel is called iron_shovel in Minecraft 1.13, but in versions prior to 1.13 it was called iron_spade.
In Minecraft versions prior to 1.13, enchantment names come from the Enchantment constants in the Bukkit API, e.g. protection_fire instead of fire_protection.
In Minecraft 1.8, potion data values are numeric IDs.
The potion prefixes long_ and strong_ are not supported on Minecraft versions prior to 1.13.
Splash potions are always called splash_potion in MobArena, even in builds for Minecraft 1.8.

Saved Items

Syntax: <identifier> or <identifier>:<amount>
Use in: Class items/armor, rewards, upgrade waves, boss waves (reward only), entry fees

For more complex items with lore and NBTs, it might be easier to just save an in-game item to disk and reference it. To save the currently held item, use /ma save-item <identifier>, where <identifier> is a unique name (note that this command will overwrite existing saved items if the names clash). Use the /ma load-item <identifier> command to load an already saved item (overwrites whatever is currently held), and the /ma delete-item <identifier> command to delete saved items.

Saved items are denoted by their identifier as defined by the /ma save-item command, and the identifiers follow the same naming convention as normal Minecraft item names. It is possible to override the amount of a saved item in the same way amounts are denoted on normal Minecraft items.

Examples

Syntax	Result
`cool_shield`	The item held when running `/ma save-item cool_shield`
`bad_sword`	The item held when running `/ma save-item bad_sword`

Notes

Saved items rely on the ConfigurationSerializable functionality in the Bukkit API, which means it inherits all of its features and limitations.
Saved items take precedence over normal Minecraft items, which means it is possible to override the meaning of dirt in the config-file. With great power comes great responsibility.

Chest Items

Syntax: inv(w x y z i) or inv(w x y z i-j) or inv(w x y z all)
Use in: Class items/armor, rewards, upgrade waves, boss waves (reward only), entry fees

If access to the config-file is limited or cumbersome, it might be easier to use in-game chests to store items. Items from chests and other containers can be referenced in the config-file by the world name and coordinates of the container as well as the container index or indices.

The different syntax forms work as follows:

inv(w x y z i) references the item at index i in the container located at x, y, z in world w
inv(w x y z i-j) references all the items from index i to index j (both inclusive) in the container located at x, y, z in world w
inv(w x y z all) references all the items in the container located at x, y, z in world w

Examples

Syntax	Result
`inv(games 1 2 3 8)`	the item at index 8 in the chest at coordinates (1,2,3) in world `games`
`inv(world 31 5 17 6-9)`	the four items at index 6 to 9 in the chest at coordinates (31,5,17) in world `world`
`inv(ma 50 42 123 all)`	all items in the chest at coordinates (50,42,123) in world `ma`

Notes

Chest items that reference multiple items (i-j and all) are internally transformed to groups, which means they behave in the same way, e.g. when presented as rewards.

Economy Money

Syntax: $<amount> or money:<amount>
Use in: Rewards, entry fees, class fees

If you have Vault installed alongside an economy plugin, you can use the currency from the economy plugin as entry fees, class fees, and rewards in MobArena.

Examples

Syntax	Result
`$5`	5 currency units
`$3.14`	3.14 currency units
`$0.01`	0.01 currency units

Notes

Even if you use a different currency symbol in your economy plugin, e.g. € or £, you still have to use the dollar sign $ in your MobArena config-file.

Commands

Syntax: cmd:/<command> or command:/<command>
Use in: Class items/armor, rewards, upgrade waves

You can have the server run a command that targets a given player denoted by the token <player>. This can be useful for granting persistent permissions via your permissions plugin, or integrating with rewards from other plugins, like rewarding tokens or special items with lore.

When using commands as rewards, MobArena will try to display the command in the chat like any other reward. By default, commands just show in their somewhat raw format, for example:

[MobArena] You just earned a reward: /give <player> dirt

You can use the extended syntax cmd(<name>):/<command> for a prettier name for your command reward. With this syntax, you can replace <name> with whatever you want displayed:

[MobArena] You just earned a reward: some dirt

Examples

(assuming the player is "Bob")

Syntax	Result
`cmd:/say <player> is cool`	runs `/say Bob is cool`
`cmd:/op <player>`	runs `/op Bob` (please don't actually do this)
`cmd(a very nice thing):/give <player> dirt`	runs `/give Bob dirt` and displays as "a very nice thing"

Notes

Commands and command names can't contain commas , because this symbol is used as a separator in item lists.

Permissions

Syntax: perm:<permission> or perm:[-|^]<permission>
Use in: Class items/armor, class permissions, rewards, upgrade waves

It is possible to temporarily grant or revoke permissions. MobArena uses Bukkit's PermissionAttachment API, which only keeps permissions around until the player logs out (or until MobArena removes it).

The syntax forms work as follows:

Use the form perm:<permission> to grant a permission
Use the forms perm:-<permission> or perm:^<permission> to revoke a permission

Temporary permissions can be useful if you want to allow your classes to use spells and abilities from plugins like Magic, MagicSpells, mcMMO, etc. It is also possible to revoke the mobarena.use.leave permission from classes, such that as soon as players have joined an arena and selected a class, they must complete it or die to leave (very sneaky and kinda evil).

Examples

Syntax	Result
`perm:mobarena.admin.kick`	Temporarily grants the `mobarena.admin.kick` permission
`perm:-mobarena.use.leave`	Temporarily revokes the `mobarena.use.leave` permission
`perm:^mobarena.use.leave`	Same as above

Notes

If you want to grant persistent permissions to players as rewards, use Commands to grant the permissions via your permissions plugin instead.
Permissions can be used in classes and upgrade waves without the perm: prefix by putting them in their designated permissions node. Check Setting up the config-file and Setting up the waves for examples.

Potion Effects

Syntax: effect:<effect> or effect:<effect>:<amplifier> or effect:<effect>:<amplifier>:<duration>
Use in: Class items/armor, class effects, rewards, all waves

Potion effects can be used in classes and waves, as well as in rewards (although that is kind of unorthodox). Unlike the data value for potion items, potion effect names come from the PotionEffectType constants in the Bukkit API, not from the PotionType enum.

Unlike with potion items, potion effects are much more flexible. We use an optional <amplifier> to specify how "strong" the effect should be (it is zero-indexed, so 0 means level I, 1 means level II, etc.), as well as an optional <duration> (in seconds) to specify how long the effect should last. By default, the amplification is 0 (level I), and the duration is "infinite" (2,147,483,647 ticks to be exact, or about 3.4 years).

The syntax forms work as follows:

Use effect:<effect> for an "infinite duration", level I version of the potion effect
Use effect:<effect>:<amplifier> for an "infinite duration" version of the potion effect with the given amplification level
Use effect:<effect>:<amplifier>:<duration> for a potion effect with the given amplification level that lasts for the given duration (in seconds)

Examples

Syntax	Result
`effect:speed`	Infinite duration Speed I
`effect:speed:1`	Infinite duration Speed II (amplifiers are zero-indexed)
`effect:speed:0:30`	Speed I that lasts 30 seconds
`effect:increase_damage`	Infinite duration Strength I

Notes

Potion effects can be used in classes and all waves without the effect: prefix by putting them in their designated effects node. Check Setting up the config-file and Setting up the waves for examples.

Advanced features

Use in: Rewards

When it comes to rewards, MobArena has support for a few extra tricks in the form of grouping, randomization, and "nothing". The individual usefulness of these features is limited at best, but when combined, they provide a powerful and expressive mechanism for spicing up and balancing rewards.

The following sections explain each individual feature in brief, but make sure to check out the Examples section below for concrete demonstrations of how they mesh together.

Thing grouping

Syntax: all(<thing>, <thing>, ...)

Combine a list of two or more Things into one unit.

A group consists of multiple Things, but it behaves like a single Thing when granted. This can be useful for rewarding item sets, e.g. full iron armor, a bow and some arrows, or a collection of potions.

Thing randomization

Syntax: random(<thing>, <thing>, ...)

Pick a random entry from a list of two or more Things.

Randomization always results in exactly one Thing from the given list. This is the default, internal mechanism used to treat bare lists of Things.

Nothing

Syntax: nothing

The nothing keyword is an "empty operation" in that it doesn't do anything. If a player is rewarded nothing, that player will not get anything, not even a message saying they didn't get anything. They get nothing.

While this feature may seem useless in and of itself, it can be combined with randomization to create "gaps" in reward lists so that a reward isn't guaranteed, or so that a grouping of rewards can be more varied.

Examples

Syntax	Result
`all(dirt, bone)`	a dirt block and a bone
`random(dirt, bone)`	a dirt block or a bone
`nothing`	nothing
`random(all(dirt, bone), all(stick, stone))`	either dirt + bone or stick + stone
`all(random(dirt, bone), random(stick, stone))`	a dirt block or a bone, and a stick or a stone
`random(all(dirt, bone), nothing)`	either a dirt block and a bone, or nothing
`all(random(nothing, bone), random(nothing, stone))`	maybe a bone, and maybe a stone
`random(bone, nothing, nothing, nothing)`	25 % chance to get a bone, 75 % chance to get nothing