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
committed by
garbagemule
garbagemule
parent
e85696138c
commit
c80b76e732
+111
-146
@@ -2,185 +2,150 @@
|
|||||||
Item and reward syntax
|
Item and reward syntax
|
||||||
######################
|
######################
|
||||||
|
|
||||||
**On this page:** \* `Overview <./Item-and-Reward-Syntax#an-overview>`__
|
This page explains the syntax for items and rewards for completing MobArena
|
||||||
\* `Single Items <./Item-and-Reward-Syntax#1-single-items>`__ \*
|
waves.
|
||||||
`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>`__
|
|
||||||
|
|
||||||
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
|
Item types
|
||||||
details, because if you aren't, there will be consequences.
|
**********
|
||||||
|
|
||||||
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>]
|
Single items
|
||||||
Multiple: [<id>|<name>]:<amount>
|
============
|
||||||
Sub-types: [<id>|<name>]:<data>:<amount>
|
|
||||||
|
|
||||||
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
|
.. code-block:: yaml
|
||||||
(``<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.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**Make sure to read `the important note on item
|
|
||||||
IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!**
|
|
||||||
|
|
||||||
Examples: ``diamond_sword``, ``stone``, ``42`` (iron block), ``322``
|
|
||||||
(snowball)
|
|
||||||
|
|
||||||
2. Multiple Items
|
|
||||||
~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
[<id>|<name>]:<amount>
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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>`__.
|
|
||||||
|
|
||||||
**Make sure to read `the important note on item
|
|
||||||
IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!**
|
|
||||||
|
|
||||||
Examples: ``arrow:64``, ``grilled_pork:4``, ``46:10`` (10x TNT),
|
|
||||||
``142:5`` (5x potato)
|
|
||||||
|
|
||||||
3. Item Sub-Types (potions, wool, dyes etc.)
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
[<id>|<name>]:<data>:<amount>
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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>`__.
|
|
||||||
|
|
||||||
**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:
|
classes:
|
||||||
Barbarian:
|
barbarian:
|
||||||
items: '373:8197:2'
|
items: bow
|
||||||
armor: '300'
|
armor: leather_leggings
|
||||||
|
|
||||||
In other words, you have to put ``'300'`` in the ``armor``-node, *not
|
.. [#] Each item ID number must be wrapped in apostrophes (``''``) to work
|
||||||
just* ``300``, and you have to put ``'373:8197:2'`` in the
|
correctly.
|
||||||
``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.
|
|
||||||
|
|
||||||
|
Multiple items
|
||||||
|
==============
|
||||||
|
|
||||||
|
``[<id>|<name>]:<amount>``
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
classes:
|
||||||
|
barbarian:
|
||||||
|
items: bow, arrow:64, grilled_pork:4
|
||||||
|
armor: leather_leggings
|
||||||
|
|
||||||
|
Item sub-types
|
||||||
|
==============
|
||||||
|
|
||||||
|
``[<id>|<name>]:<data>:<amount>``
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
classes:
|
||||||
|
barbarian:
|
||||||
|
items: bow, arrow:64, grilled_pork:4, potion:increase_damage:1,
|
||||||
|
wool:purple:1
|
||||||
|
armor: leather_leggings
|
||||||
|
|
||||||
|
|
||||||
|
************
|
||||||
Enchantments
|
Enchantments
|
||||||
~~~~~~~~~~~~
|
************
|
||||||
|
|
||||||
Enchantments can be added to items by appending a space, followed by a
|
``<item> <eid>:<level>;<eid>:<level>;...``
|
||||||
*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.:
|
|
||||||
|
|
||||||
::
|
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
|
.. code-block:: yaml
|
||||||
above. Here is an example:
|
|
||||||
|
|
||||||
::
|
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
|
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
|
Since v0.96, floating point numbers are also supported.
|
||||||
economy plugins. This feature *requires Vault*. The format quite simply
|
|
||||||
means that you type in a dollar sign followed by a valid monetary value.
|
|
||||||
|
|
||||||
Examples: ``$1``, ``$5``, ``$3.14`` (v0.96+), ``$0.99`` (v0.96+)
|
Examples:
|
||||||
|
|
||||||
|
- ``$1``
|
||||||
|
- ``$5``
|
||||||
|
- ``$3.14``
|
||||||
|
- ``$0.99``
|
||||||
|
|
||||||
|
|
||||||
|
***************
|
||||||
Command Rewards
|
Command Rewards
|
||||||
~~~~~~~~~~~~~~~
|
***************
|
||||||
|
|
||||||
Since v0.99, MobArena supports commands as rewards. This means that you
|
.. code-block:: yaml
|
||||||
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:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
cmd:/give <player> dirt
|
cmd:/give <player> dirt
|
||||||
|
cmd(description of reward):/give <player> dirt
|
||||||
|
|
||||||
If the player is "garbagemule", this setting will run the command "/give
|
You can run a command to give a special reward to a player. Command rewards are
|
||||||
garbagemule dirt" when the arena session ends. Note that this syntax
|
supported since v0.99. Useful examples might be to give a permission (maybe
|
||||||
will display as
|
unlocking a new arena) or integrating with other plugins.
|
||||||
``[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.
|
||||||
|
|
||||||
cmd(a very nice thing):/give <player> dirt
|
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!``.
|
||||||
|
|
||||||
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
|
||||||
|
|||||||
Reference in New Issue
Block a user