Item and Reward Syntax - Chew/MobArena GitHub Wiki

Overview

Internally, MobArena works with what it calls Things. Things can essentially be anything, but the core plugin supports the following Things:

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:

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 enchantment names 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 enchantment names must be all lowercase and with underscores instead of spaces, e.g. bane_of_arthropods for Bane of Arthropods and fire_protection for Fire Protection. 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
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.

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

⚠️ **GitHub.com Fallback** ⚠️