Items guide

source/guides/basics/custom-items.md

@@ -1,28 +1,208 @@
-Fancier Sticks: Making Custom Items (PLACEHOLDER ONLY)
+Fancier Sticks: Making Custom Items
 -----------------------------------
 
-**TODO: Write-up that introduces item script containers, and the general ideas of making custom items, mentioning recipes, name/lore, mechanisms, item flags, etc.**
-
-### Placeholder
+```eval_rst
+.. contents:: Table of Contents
+    :local:
+```
 
-Until this page is written, you can view the [old tutorial video here](https://one.denizenscript.com/denizen/vids/Custom%20Items).
+### What Are Custom Items
 
-### Sample Script
+Custom items are a way to store a various set of properties onto an item to create a new unique item in the game. Denizen provides the capabilities to save these unique items in item scripts so that they can be reused or uniquely referenced to in other scripts. These were briefly mentioned in [the mechanisms guide](/guides/basics/mechanisms) but this page will go into more detail.
 
-Here's a quick sample of a modern item script.
+### The Basic Structure
 
+To start off with, this is how a basic item script looks like:
 ```dscript_green
-my_item:
+fancy_stick:
     type: item
     material: stick
-    display name: <&[item]>Fancy stick!
+    display name: <&[item]><bold>Fancy stick!
     lore:
     - <&[lore]>So fancy.
+    - <&[lore]>Second line.
+```
+In [the script editor](/guides/first-steps/script-editor), you can simply type `item` and use tab completion to generate the basic template of an item script at any time.
+
+An item script container has the type set to `item`. You will need to give it a valid ItemTag for your item to be based off of; for example here we are using a stick.
+
+While not strictly required, most item script will also have a custom display name and custom lore. The display name works similarly to other container keys, the lore takes in a list as opposed to a single argument. Each line of lore is given on a new line prepended by a `-` <span class="parens">(similar to how a list of commands look in scripts)</span>.
+
+You can get this item in-game by typing `/ex give fancy_stick`
+
+Note that the above sample uses the `item` and `lore` custom color codes defined in your Denizen/config.yml
+
+![](images/fancy_stick-basic.png)
+
+### Adding More Properties
+
+There are several other properties that can be added to item scripts.
+
+As an example this would be how you would add enchantments:
+```dscript_green
+fancy_sword:
+    type: item
+    material: iron_sword
+    display name: <&[item]><bold>Fancy indestructible sword!
+    enchantments:
+    - smite:2
+    - unbreaking:3
+```
+
+You can get this item in-game by typing `/ex give fancy_sword`
+
+![](images/fancy_sword-basic.png)
+
+You can also add in custom data onto an item in the form of flags such as:
+```dscript_green
+special_hat_1:
+    type: item
+    material: iron_helmet
+    display name: <&[item]><bold>A Special Hat
+    flags:
+        hat_type: 1
+special_hat_2:
+    type: item
+    material: iron_helmet
+    display name: <&[item]><bold>A Special Hat 2.0
+    flags:
+        hat_type: 2
 ```
 
-You can get this item in-game by typing `/ex give my_item`
+You can test this out by giving yourself the 2 items `/ex give special_hat_1` and `/ex give special_hat_2` and using `/ex narrate <player.item_in_hand.flag[hat_type]>` while holding the item to see the flag value.
+
+
+As mentioned above [the mechanisms guide](/guides/basics/mechanisms) covers more on how properties work, but to reiterate you can apply mechanisms to items directly in the item script to add more unique properties that are not covered by other keys. For instance if you wanted the `fancy_sword` to be truly unbreakable you would do:
+```dscript_green
+fancy_sword:
+    type: item
+    material: iron_sword
+    display name: <&[item]><bold>Fancy indestructible sword!
+    enchantments:
+    - smite:2
+    mechanisms:
+        unbreakable: true
+```
+
+As a warning, changes to an item script do not get automatically applied to instances of the item that have been created. For instance, if you are now updating this sword, the old sword would still have the same original properties.
+
+### Using Items Elsewhere
+
+Since item scripts are effectively new items, any place that accepts ItemTags will also accept item scripts in addition to any vanilla minecraft item. As demonstrated previously, you can simply just provide the name of the item script into the give command and denizen will give you a copy of that item. This applies also to anywhere that specific items can be referenced. For instance, let's say we want an event to listen for when someone specifically uses the `fancy_sword` to hit something else, we can simply just do the following:
+```dscript_green
+fancy_sword_events:
+    type: world
+    events:
+        on player damages entity with:fancy_sword:
+        - narrate "You hit an <context.entity.name> with the fancy sword"
+```
+You can test this out by hitting an entity with the fancy_sword and again with a normal one. See that nothing happens when using the normal one and only when using the fancy_sword does the statement display.
 
-Note that the above sample uses the `item` and `lore` custom color codes defined in your `Denizen/config.yml`
+### Adding Crafting Recipes
+
+Custom items can also come with their own crafting recipes so that players can craft it in game. Let's add a crafting recipe to the fancy_sword:
+```dscript_green
+fancy_sword:
+    type: item
+    material: iron_sword
+    display name: <&[item]><bold>Fancy indestructible sword!
+    enchantments:
+    - smite:2
+    mechanisms:
+        unbreakable: true
+    recipes:
+        1:
+            type: shaped
+            input:
+            - obsidian|air|air
+            - air|obsidian|air
+            - air|air|iron_sword
+```
+A few things to note:
+- Each recipe needs a number, as an item can have multiple recipes. This should be increasing in numeric order
+- The recipe needs a type, there are many ways to craft items, shaped is the most basic/common which uses the crafting table
+- The shaped recipe goes in this 3\*3 or 2\*2 grid with air taking up where you would want a specific empty spot <span class="parens">if a 2\*2 shape is desired, simply adjust the input to match</span>
+- The recipe will not show up in the recipe book after crafting until you either reconnect or use the `resend_recipes` mechanism <span class="parens">(`/ex adjust <player> resend_recipes`)</span>
+
+You can try it out and see that you can now craft it:
+![](images/fancy_sword-crafting.png)
+
+As mentioned above, there are more kinds of crafting. To cover them briefly an example is given of how the input would look.
+
+shapeless - taking a list of items as input but doesn't care about shape:
+```dscript_blue
+type: shapeless
+input: obsidian|obsidian|iron_sword
+```
+
+stonecutting - takes in only a single item on the stonecutter
+```dscript_blue
+type: stonecutting
+input: iron_sword
+```
+
+furnace/blast/smoker/campfire - smelting an item in the relevant item from the script
+```dscript_blue
+type: furnace
+input: iron_sword
+```
+
+smithing - crafting an item on the smithing table, using 2 inputs (a base and an upgrade) as well as allowing to keep enchantments and display names
+```dscript_blue
+type: smithing
+base: iron_sword
+retains: enchantments|display
+upgrade: obsidian
+```
+
+brewing - use a brewing stand to convert and item with an ingredient into the item from the script. Note, neither the item in the script nor the input need to be a potion in any way.
+```dscript_blue
+type: brewing
+input: iron_sword
+ingredient: obsidian
+```
+
+### Custom Books
+
+On related topic to item scripts, there are also book scripts. While they serve similar purpose as item scripts, they are their own unique container.
+An example book script would be as follows:
+```dscript_green
+fancy_book:
+    type: book
+    title: The Fanciest of Books
+    author: Steve
+    signed: true
+    text:
+    - There once was a player named steve who ate a potato<n><n>He liked it
+    - The end
+```
+
+Things to note here:
+- The author does not have to be anyone real, you can put in whatever you want
+- Signed makes this a signed book, you can set this to false to leave it unsigned
+- Each line of text is a new page, not a new line on a page. You can insert new lines on a page using `<n>`
+- While text will automatically move to new lines if space is required, there is no guarantee that the text you write will fit on the page. This may take some trial and error to ensure the text you want to show does in fact fit its page.
+
+This is can be given in a similar fashion as other item scripts.
+You can test this out with `/ex give fancy_book`
+
+Despite this being similar to item scripts, book scripts are not necessarily valid ItemTags in all situations, and thereby cannot be used in all the same ways that other ItemTags can be used, in particular when verifying that the book a player has is indeed a result of the script.
+For instance if you are looking to use this in events, you would need to link it to an item script via the `book` key like so:
+```dscript_green
+fancy_book_item:
+    type: item
+    material: written_book
+    book: fancy_book
+```
+
+After than you can then use `fancy_book_item` in events such as:
+```dscript_green
+fancy_book_events:
+    type: world
+    events:
+        on player clicks block with:fancy_book_item:
+        - narrate "Opening the fancy book!!!"
+```
 
 ### Related Technical Docs