diff options
Diffstat (limited to 'docs/Defining-items.md')
| -rw-r--r-- | docs/Defining-items.md | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/docs/Defining-items.md b/docs/Defining-items.md new file mode 100644 index 00000000..cad57de9 --- /dev/null +++ b/docs/Defining-items.md @@ -0,0 +1,329 @@ +\_\_NOTOC\_\_ + +An **ItemStack** is a **representation of an item** in an inventory. +Every configured ItemStack in Quests is parsed the exact same way. This +page gives guidance on how to define items with specific attributes. + +## Table of contents + +- [Configurable options](Defining_items#Configurable_options "wikilink") + - [Configuration + layout](Defining_items#Configuration_layout "wikilink") + - [Examples](Defining_items#Examples "wikilink") + - [Name](Defining_items#Name "wikilink") + - [Item](Defining_items#Item "wikilink") + - [Lore](Defining_items#Lore "wikilink") + - [Enchantments](Defining_items#Enchantments "wikilink") + - [Item flags](Defining_items#Item_flags "wikilink") + - [Unbreakable](Defining_items#Unbreakable "wikilink") + - [Attribute + modifiers](Defining_items#Attribute_modifiers "wikilink") + - [Custom model data](Defining_items#Custom_model_data "wikilink") + - [Owner](Defining_items#Owner "wikilink") +- [Quest items](Defining_items#Quest_items "wikilink") + - [Importing items](Defining_items#Importing_items "wikilink") + - [Manually defined + items](Defining_items#Manually_defined_items "wikilink") + - [Defined](Defining_items#Defined "wikilink") + - [MMOItems](Defining_items#MMOItems "wikilink") + - [Slimefun](Defining_items#Slimefun "wikilink") + - [ExecutableItems](Defining_items#ExecutableItems "wikilink") + - [Referencing a quest + item](Defining_items#Referencing_a_quest_item "wikilink") + +## Configurable options + +| Field | Optional | Minecraft Version | More Information | +|----------------------|------------------|-------------------|-------------------------------------------------------| +| `item` | ❌ | \- | [Jump](Defining_items#Item "wikilink") | +| `name` | ✅ <sup>\*</sup> | \- | [Jump](Defining_items#Name "wikilink") | +| `lore` | ✅ | \- | [Jump](Defining_items#Lore "wikilink") | +| `enchantments` | ✅ | \- | [Jump](Defining_items#Enchantments "wikilink") | +| `itemflags` | ✅ | 1.8+ | [Jump](Defining_items#Item_flags "wikilink") | +| `unbreakable` | ✅ | 1.13+ | [Jump](Defining_items#Unbreakable "wikilink") | +| `attributemodifiers` | ✅ | 1.13+ | [Jump](Defining_items#Attribute_modifiers "wikilink") | +| `custommodeldata` | ✅ | 1.14+ | [Jump](Defining_items#Custom_model_data "wikilink") | +| `owner-[...]` | ✅ | 1.8+ | [Jump](Defining_items#Owner_(skulls) "wikilink") | + +<sup>\*: The name must be defined for the display item of Quests.</sup> + +### Configuration layout + +``` yaml +item: + name: "&6&lSuper Cool Stick" + item: STICK + lore: + - "&7Really cool lore." + # field4: value4 + # etc. +``` + +### Examples + +#### Item + + +*`item` or `type`material</code>* + +The item is the material the itemstack is made out of. Please see the +[latest +javadocs](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) +(1.13+) or the [1.12 +javadocs](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) +(1.8-1.12) for item names. For 1.8-1.12, data codes can be added on at +the end with a colon `:<code>`. + +``` yaml +item: + item: "WHEAT" + ... +``` + +#### Name + + +*`name`* + +The name is displayed at the top of the item when hovered over, or just +above the hotbar when selected. + +``` yaml +item: + name: "&2&lSuper Cool Name" + ... +``` + +#### Lore + + +*`lore`* + +The lore is the description of the item seen when hovering over it. You +can remove this omit entirely if a lore is not desired. + +``` yaml +item: + lore: + - "Line 1" + - "Line 2" + ... +``` + +#### Enchantments + +The format of enchantments depends on your Minecraft version. + + +**Pre-1.13**: Use [spigot +names](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html) +-\> format "{enchantment}:{level}" + +**1.13+**: Use Vanilla names -\> namespace for vanilla enchantments is +"minecraft" -\> format "{namespace}:{enchantment}:{level}" + +``` yaml +item: + enchantments: + - "minecraft:infinity:1" + ... +``` + +#### Item flags + +Item flags can be added to hide enchantment names, etc. A full list of +itemflags is available on the [Spigot +javadocs](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html). + +``` yaml +item: + itemflags: + - "HIDE_ATTRIBUTES" + ... +``` + +#### Unbreakable + +- *1.13+*' + +``` yaml +item: + unbreakable: true + ... +``` + +#### Attribute modifiers + +**1.13+** Adds specific attribute modifiers to the items. The UUID +should always be specified otherwise the server will randomly generate +one on each restart. Full list of attributes is available on the [Spigot +javadocs](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html), +along with full list of +[operations](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/AttributeModifier.Operation.html). + +``` yaml +item: + attributemodifiers: + - attribute: GENERIC_MOVEMENT_SPEED + modifier: + uuid: "49dc07dc-bfdb-4dc7-85d3-66ef52b51858" + name: "generic.movementSpeed" + operation: ADD_NUMBER + amount: 0.03 + equipmentslot: HAND + - attribute: GENERIC_MOVEMENT_SPEED + modifier: + uuid: "e22513cf-b15f-4443-9e2f-103c0ff9731b" + name: "generic.movementSpeed" + operation: ADD_NUMBER + amount: 0.01 + equipmentslot: OFF_HAND + ... +``` + +#### Custom model data + +**1.14+** + +``` yaml +item: + custommodeldata: 12345 + ... +``` + +#### Owner + +This only applies if you have a skull item stack (`PLAYER_HEAD` 1.13+, +`SKULL_ITEM` 1.8-1.12). There are three ways to define the player for +the skull: by **username**; **uuid**; or, **base64 encoded string**. + +The **preferred method** is to **explicitly specify a base64 encoded +string**. Using any of the other two methods require that the player has +joined the server before, and may possibly make a request to Mojang +(locking the server thread) depending on which server software you use. + +You can get the base64 encoded representation of a player skin here: +<https://mineskin.org/>. It will look like the following (may be +referred to as 'texture data'): + + ewogICJ0aW1lc3RhbXAiIDogMTYyNTgzNjU0OTAxNCwKICAicHJvZmlsZUlkIiA6ICJlMmNlNzA0ZWVjNGE0YjE4YTNlYjA4MTRiMzdmYTFkNCIsCiAgInByb2ZpbGVOYW1lIiA6ICJmYXRwaWdzYXJlZmF0IiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzJiMTIzMWEyZjNkYTQ2OTQxZDY1OWI4NDNjZWZhNDljOGE1NTA0ZjE4MzNlOTA3YzY3YmJiMTQ2NTE0OTlhNyIKICAgIH0KICB9Cn0= + +You can specify each type by the following: + +``` yaml +item: + owner-base64: "base64 encoded string" + ... +``` + +``` yaml +item: + owner-username: "username" + ... +``` + +``` yaml +item: + owner-uuid: "uuid" + ... +``` + +## Quest items + +**Quest items** can help simplify your configuration by putting +individual itemstacks inside a named file (under directory items/), to +allow for easy referencing from a task configuration and reducing +configuration duplication across your quests. + +The types of quest items are as follows: + +- `raw` (items imported using /q a items import) +- `defined` (items manually written following the format above) +- `mmoitems` (items from MMOItems) +- `slimefun` (items from Slimefun) +- `executableitems` (items from ExecutableItems) + +### Importing items + +**Importing** an item means creating a new quest item **from the item +you are holding** in game. To do this, simply hold the desired item and +run `/q a items import <id>`, where `<id>` is the desired name of the +item. Your item will be saved to file items/\<id\>.yml, **with the type +'raw**'. + +<https://i.imgur.com/6lsld61.png> <https://i.imgur.com/Pg2eO9a.png> + +### Manually defining items + +You can manually define an item by creating a new `yml` file within the +items/ directory. You must specify a `type` and the item itself under +`item`. + +#### Defined + +**Defined quest items** are regular ItemStacks and follow the format +defined under [§ Configurable +options](Defined_items#Configurable_options "wikilink"). + + items/testitem.yml + +``` yaml +type: "defined" +item: + name: "Cool item" + type: DIAMOND_SWORD + lore: + - "Really cool lore" +``` + +#### MMOItems + +**MMOItems quest items** are ItemStacks which belong to the MMOItems +plugin. + + items/testitem.yml + +``` yaml +type: "mmoitems" +item: + type: "BOW" #mmoitems type + id: "HELL_BOW" #mmoitems id +``` + +#### Slimefun + +**Slimefun quest items** are ItemStacks which belong to the Slimefun +plugin. + + items/testitem.yml + +``` yaml +type: "slimefun" +item: + id: "slimefun_item_id" #slimefun id +``` + +#### ExecutableItems + +**ExecutableItems quest items** are ItemStacks which belong to the +ExecutableItems plugin. + + items/testitem.yml + +``` yaml +type: "executableitems" +item: + id: "executableitems_id" #executableitems id +``` + +### Referencing a quest item + +In most cases where an ItemStack is accepted in Quests, you can simply +provide the ID of the quest item under the key `quest-item`. + +``` yaml +# Within a task +type: "inventory" +item: + quest-item: "testitem" +``` |