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
This commit is contained in:
Justin W. Flory
garbagemule
parent
e85696138c
commit
c80b76e732
|
|
@ -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**: ``[<id>|<name>]``
|
||||
- **Multiple**: ``[<id>|<name>]:<amount>``
|
||||
- **Sub-types**: ``[<id>|<name>]:<data>:<amount>``
|
||||
|
||||
Single: [<id>|<name>]
|
||||
Multiple: [<id>|<name>]:<amount>
|
||||
Sub-types: [<id>|<name>]:<data>:<amount>
|
||||
Single items
|
||||
============
|
||||
|
||||
Confusing? Let's break them down one by one.
|
||||
``[<id>|<name>]``
|
||||
|
||||
1. Single Items
|
||||
~~~~~~~~~~~~~~~
|
||||
*Either* an item ID number [#]_ (``<id>``) or item name (``<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.
|
||||
|
||||
[<id>|<name>]
|
||||
This example gives the ``barbarian`` class a bow and leather leggings.
|
||||
|
||||
This means you can use either the item ID (``<id>``), or the item name
|
||||
(``<name>``) as defined in the `Material enum of the Bukkit
|
||||
API <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>`__.
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~
|
||||
``[<id>|<name>]:<amount>``
|
||||
|
||||
::
|
||||
This method lets you add an amount to an item. This is useful for items like
|
||||
arrows or potions.
|
||||
|
||||
[<id>|<name>]:<amount>
|
||||
Now, our example also gives 64 arrows and four pieces of cooked porkchops.
|
||||
|
||||
This way, you append an ``<amount>`` 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)
|
||||
``[<id>|<name>]:<data>:<amount>``
|
||||
|
||||
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`_
|
||||
|
||||
[<id>|<name>]:<data>:<amount>
|
||||
Now, our example gives one Potion of Strength I and one piece of purple wool.
|
||||
|
||||
This way, you append **BOTH** a ``<data>`` value (the sub-type) and an
|
||||
``<amount>``, 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 <http://www.minecraftwiki.net/wiki/Potions#Primary_potions>`__ 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 <http://jd.bukkit.org/rb/apidocs/src-html/org/bukkit/DyeColor.html#line.10>`__.
|
||||
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 ``<eid>:<level>``, where ``<eid>``
|
||||
is an enchantment ID as defined by the `Enchantment Wrappers in the
|
||||
Bukkit
|
||||
API <http://jd.bukkit.org/rb/apidocs/src-html/org/bukkit/enchantments/Enchantment.html#line.12>`__
|
||||
(the numbers in the parentheses at the end of each line), i.e.:
|
||||
``<item> <eid>:<level>;<eid>:<level>;...``
|
||||
|
||||
::
|
||||
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.
|
||||
|
||||
<item> <eid>:<level>;<eid>:<level>;...
|
||||
Now, our example adds Power II and Flame I to the bow and a diamond sword with
|
||||
Sharpness I and Knockback II.
|
||||
|
||||
The ``<item>`` 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
|
||||
~~~~~~~~~~~~~
|
||||
*************
|
||||
|
||||
::
|
||||
``$<amount>``
|
||||
|
||||
$<amount>
|
||||
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 <player> dirt
|
||||
cmd(description of reward):/give <player> dirt
|
||||
|
||||
cmd:/give <player> 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 <player> 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 <player> <permission>``
|
||||
appears to the player as ``You just earned a reward: New arena to play!``.
|
||||
|
||||
cmd(a very nice thing):/give <player> 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue