From 0aac85ff5c27e98564243a9f43ae58685bd18ff2 Mon Sep 17 00:00:00 2001 From: LMBishop <13875753+LMBishop@users.noreply.github.com> Date: Thu, 6 Jul 2023 14:10:24 +0100 Subject: Migrate docs to GitHub pages --- docs/configuration/defining-items.md | 318 +++++++++++++++++++++++++++++++++++ 1 file changed, 318 insertions(+) create mode 100644 docs/configuration/defining-items.md (limited to 'docs/configuration/defining-items.md') diff --git a/docs/configuration/defining-items.md b/docs/configuration/defining-items.md new file mode 100644 index 00000000..a32bb689 --- /dev/null +++ b/docs/configuration/defining-items.md @@ -0,0 +1,318 @@ +--- +title: Defining items +parent: Configuration +nav_order: 5 +--- + +# Defining items +{: .no_toc } + +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. + +{: .note } +The information on this page describes how to define items across every +configuration file. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Layout + +``` yaml +item: + name: "&6&lSuper Cool Stick" + item: STICK + lore: + - "&7Really cool lore." + # field4: value4 + # etc. +``` + +## Options + +| Field | Optional | Minecraft Version | More Information | +|----------------------|-----------------|-------------------|------------------------------| +| `item` | ❌ | \- | [Jump](#item) | +| `name` | ✅ \* | \- | [Jump](#name) | +| `lore` | ✅ | \- | [Jump](#lore) | +| `enchantments` | ✅ | \- | [Jump](#enchantments) | +| `itemflags` | ✅ | 1.8+ | [Jump](#item-flags) | +| `unbreakable` | ✅ | 1.13+ | [Jump](#unbreakable) | +| `attributemodifiers` | ✅ | 1.13+ | [Jump](#attribute-modifiers) | +| `custommodeldata` | ✅ | 1.14+ | [Jump](#custom-model-data) | +| `owner-[...]` | ✅ | 1.8+ | [Jump](#owner) | + +\*: The name must be defined for the display item of Quests. + +### Item + + +*`item` or `type` or `material`* + +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 `:`. + +``` 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: +. 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 `, where `` is the desired name of the +item. Your item will be saved to file items/\.yml, **with the type +'raw**'. + + + + + +### 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 [§ options](#options). + + 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" +``` -- cgit v1.2.3-70-g09d2