From c80b76e7329e15aad164d030b66001d086d2ee69 Mon Sep 17 00:00:00 2001 From: "Justin W. Flory" Date: Tue, 12 Dec 2017 20:12:04 -0500 Subject: [PATCH] Update "Item and reward syntax" documentation (see full commit) This commit updates the "Item and reward syntax" documentation. * Follows RST document style guide * Uses active voice / minor edits * Reorganize structure / flow --- docs/user/item-reward-syntax.rst | 231 +++++++++++++------------------ 1 file changed, 98 insertions(+), 133 deletions(-) diff --git a/docs/user/item-reward-syntax.rst b/docs/user/item-reward-syntax.rst index eca7298..fb48dc8 100644 --- a/docs/user/item-reward-syntax.rst +++ b/docs/user/item-reward-syntax.rst @@ -2,185 +2,150 @@ Item and reward syntax ###################### -**On this page:** \* `Overview <./Item-and-Reward-Syntax#an-overview>`__ -\* `Single Items <./Item-and-Reward-Syntax#1-single-items>`__ \* -`Multiple Items <./Item-and-Reward-Syntax#2-multiple-items>`__ \* `Item -Sub-Types <./Item-and-Reward-Syntax#3-item-sub-types-potions-wool-dyes-etc>`__ -\* `Note about item -IDs <./Item-and-Reward-Syntax#an-important-note-on-using-item-ids>`__ \* -`Enchantments <./Item-and-Reward-Syntax#enchantments>`__ \* `Economy -Money <./Item-and-Reward-Syntax#economy-money>`__ \* `Command -Rewards <./Item-and-Reward-Syntax#command-rewards>`__ +This page explains the syntax for items and rewards for completing MobArena +waves. -An Overview -~~~~~~~~~~~ -Items in MobArena follow a very specific syntax that you **must** obey, -or you will experience missing items or errors. Be attentive to the -details, because if you aren't, there will be consequences. +********** +Item types +********** -MobArena allows these three different ways of defining items: +MobArena items must use a specific syntax to work as expected. The plugin allows +three different ways of defining items: -:: +- **Single**: ``[|]`` +- **Multiple**: ``[|]:`` +- **Sub-types**: ``[|]::`` - Single: [|] - Multiple: [|]: - Sub-types: [|]:: +Single items +============ -Confusing? Let's break them down one by one. +``[|]`` -1. Single Items -~~~~~~~~~~~~~~~ +*Either* an item ID number [#]_ (````) or item name (````) can be used. +Item names are defined in the `Material enum`_ of the Bukkit API. Item names are +case-insensitive. -:: +The Material enum changes when items are added, changed, or reworked. The +Minecraft server version determines what items are available. Check the +documentation for what item names are available. - [|] +This example gives the ``barbarian`` class a bow and leather leggings. -This means you can use either the item ID (````), or the item name -(````) as defined in the `Material enum of the Bukkit -API `__. -The item names are case-insensitive. +.. code-block:: yaml -Note that the Material enum changes when there are new items or -sometimes if items were reworked. As an example, the ``SPLASH_POTION`` -enum value is not available in versions prior to Minecraft 1.9. Before -then, splash potions were simply ``POTION``\ s with a higher data value. + classes: + barbarian: + items: bow + armor: leather_leggings -**Make sure to read `the important note on item -IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!** +.. [#] Each item ID number must be wrapped in apostrophes (``''``) to work + correctly. -Examples: ``diamond_sword``, ``stone``, ``42`` (iron block), ``322`` -(snowball) +Multiple items +============== -2. Multiple Items -~~~~~~~~~~~~~~~~~ +``[|]:`` -:: +This method lets you add an amount to an item. This is useful for items like +arrows or potions. - [|]: +Now, our example also gives 64 arrows and four pieces of cooked porkchops. -This way, you append an ```` to the item, specifying how many of -the given item you want. This is useful for giving out stuff like arrows -or potions that you generally want to give more than one of. +.. code-block:: yaml -Note that if you use this syntax, it is indeed the *amount* you specify, -not the item sub-type. We go over sub-types in the `next -section <./Item-Syntax#3-item-sub-types-potions-wool-dyes-etc>`__. + classes: + barbarian: + items: bow, arrow:64, grilled_pork:4 + armor: leather_leggings -**Make sure to read `the important note on item -IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!** +Item sub-types +============== -Examples: ``arrow:64``, ``grilled_pork:4``, ``46:10`` (10x TNT), -``142:5`` (5x potato) +``[|]::`` -3. Item Sub-Types (potions, wool, dyes etc.) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To add an item sub-type, both the sub-type name and an amount must be specified. +This is helpful for items like potions, wool, and/or dyes. -:: +- `Potion effect types`_ +- `Color names`_ - [|]:: +Now, our example gives one Potion of Strength I and one piece of purple wool. -This way, you append **BOTH** a ```` value (the sub-type) and an -````, regardless of how many of the given item you want. This -syntax is mostly used with potions, which have special sub-type values -in the 8000's and 16000's. Check out `this -page `__ for -the potion sub-types. +.. code-block:: yaml -For wool and dyes (ink sacks), you don't have to use the numeric data -value. Instead, you can use the *color names* as defined in the -`DyeColor *enum* of the Bukkit -API `__. + classes: + barbarian: + items: bow, arrow:64, grilled_pork:4, potion:increase_damage:1, + wool:purple:1 + armor: leather_leggings -**Make sure to read `the important note on item -IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!** - -Examples: ``wool:blue:1`` (one blue wool), ``ink_sack:brown:10`` (ten -cocoa beans), ``potion:8201:1`` (one strength potion), ``373:8197:2`` -(two health potions) - -An important note on using item IDs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you choose to use item IDs, there is a catch. If an item is *alone* -in its node, it **MUST** be enclosed in apostrophes, or YAML will crap -itself. For example, if you decide to have a Barbarian class that only -has a pair of *lederhosen* as armor, and nothing put a couple of health -potions, you need to do it like this: - -:: - - classes: - Barbarian: - items: '373:8197:2' - armor: '300' - -In other words, you have to put ``'300'`` in the ``armor``-node, *not -just* ``300``, and you have to put ``'373:8197:2'`` in the -``items``-node, *not just* ``373:8197:2``. This requirement is removed -if you use the item names instead, or if you add -`enchantments <./Item-Syntax#enchantments>`__ to the given item. +************ Enchantments -~~~~~~~~~~~~ +************ -Enchantments can be added to items by appending a space, followed by a -*semi-colon separated list* of pairs ``:``, where ```` -is an enchantment ID as defined by the `Enchantment Wrappers in the -Bukkit -API `__ -(the numbers in the parentheses at the end of each line), i.e.: +`` :;:;...`` -:: +Add enchantments to an item by adding a space with a semi-colon separated list +with the enchantment name and the strength. Find valid enchantment names in the +`Enchantment class`_ in the Spigot API. - :;:;... +Now, our example adds Power II and Flame I to the bow and a diamond sword with +Sharpness I and Knockback II. -The ```` is any item following the normal item syntax as described -above. Here is an example: +.. code-block:: yaml -:: + classes: + barbarian: + items: bow arrow_damage:2;arrow_fire:1, arrow:64, grilled_pork:4, + potion:increase_damage:1, wool:purple:1, + diamond_sword damage_all:1;knockback:2 + armor: leather_leggings - diamond_sword 16:2;19:5 - -This line gives a diamond sword with sharpness (ID 16) level 2, and -knockback (ID 19) level 5. +************* Economy Money -~~~~~~~~~~~~~ +************* -:: +``$`` - $ +MobArena supports entry fees and rewards with economy plugins. You must use +`Vault`_ for this to work. -MobArena supports entry fees and rewards in the form of money from -economy plugins. This feature *requires Vault*. The format quite simply -means that you type in a dollar sign followed by a valid monetary value. +Since v0.96, floating point numbers are also supported. -Examples: ``$1``, ``$5``, ``$3.14`` (v0.96+), ``$0.99`` (v0.96+) +Examples: +- ``$1`` +- ``$5`` +- ``$3.14`` +- ``$0.99`` + + +*************** Command Rewards -~~~~~~~~~~~~~~~ +*************** -Since v0.99, MobArena supports commands as rewards. This means that you -can have the server run a command that targets the recipient player. -This is useful for granting persistent permissions via your permissions -plugin, or integrating with rewards from other plugins, like rewarding -tokens or special items with lore. The basic syntax is this: +.. code-block:: yaml -:: + cmd:/give dirt + cmd(description of reward):/give dirt - cmd:/give dirt +You can run a command to give a special reward to a player. Command rewards are +supported since v0.99. Useful examples might be to give a permission (maybe +unlocking a new arena) or integrating with other plugins. -If the player is "garbagemule", this setting will run the command "/give -garbagemule dirt" when the arena session ends. Note that this syntax -will display as -``[MobArena] You just earned a reward: /give dirt``, which -isn't very pretty. If you want the reward to have a title, simply expand -the ``cmd`` with the name in a parenthesis: +It is possible to customize the message a player receives when they receive a +command reward. By default, the plugin prints the command. You can specify a +more user-friendly message in the second format listed above. -:: +For example, ``cmd(New arena to play!)/perm add `` +appears to the player as ``You just earned a reward: New arena to play!``. - cmd(a very nice thing):/give dirt -This will display as -``[MobArena] You just earned a reward: a very nice thing`` +.. _`Material enum`: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html +.. _`Potion effect types`: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionEffectType.html +.. _`Color names`: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/DyeColor.html +.. _`Enchantment class`: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html +.. _`Vault`: https://dev.bukkit.org/projects/vault