feat: Add recipe documentation (#401)

Author: olijeffers0n

config/sidebar.paper.ts

@@ -148,6 +148,7 @@ const paper: SidebarsConfig = {
             "dev/api/plugin-messaging",
             "dev/api/plugin-configs",
             "dev/api/lifecycle",
+            "dev/api/recipes",
             "dev/api/folia-support",
             "dev/api/roadmap",
           ],

docs/paper/dev/api/recipes.mdx

@@ -0,0 +1,89 @@
+---
+slug: /dev/recipes
+description: How to create and manage recipes.
+---
+
+# Recipe API
+
+Recipes are a way to define a way to craft a particular item. They are defined by a plugin or
+datapack, however we are only going to cover the plugin side of things here.
+
+## <Javadoc name={"org.bukkit.inventory.ShapedRecipe"}>`ShapedRecipe`</Javadoc>
+
+A shaped recipe is a recipe that requires a specific pattern of items in the crafting grid to craft an item.
+These are created using a pattern string and a map of characters to items. The pattern strings are 3,
+3-character strings that represent the rows of the crafting grid. They can be created as follows:
+
+```java
+public class TestPlugin extends JavaPlugin {
+    @Override
+    public void onEnable() {
+        NamespacedKey key = new NamespacedKey(this, "WarriorSword");
+        ItemStack item = new ItemStack(Material.DIAMOND_SWORD);
+
+        ShapedRecipe recipe = new ShapedRecipe(key, item);
+        recipe.shape(" A ", "AAA", " B ");
+        recipe.setIngredient('A', Material.DIAMOND);
+        recipe.setIngredient('B', Material.STICK);
+
+        getServer().addRecipe(recipe);
+    }
+}
+```
+
+This recipe would require a diamond sword to be crafted with a diamond in the top row, a stick in
+the middle row, and a diamond in the bottom row. The diamond sword would be in the middle column of
+the bottom row. The result would look like this in the crafting grid:
+
+```
+ A
+AAA
+ B
+```
+
+:::info
+
+You do not need to register the recipe within your plugin's `onEnable` method, You can register it
+at any time. However, if you do not register it after the plugin has been enabled and there are
+players online, you will need to either resend all the recipes to the players or use the boolean
+parameter in the <Javadoc name={"org.bukkit.Server#addRecipe(org.bukkit.inventory.Recipe,boolean)"}>`addRecipe`</Javadoc>
+method to update all players with the new recipe.
+
+:::
+
+:::warning
+
+You cannot use Air as a material in a shaped recipe, this will cause an error.
+
+:::
+
+
+## <Javadoc name={"org.bukkit.inventory.ShapelessRecipe"}>`ShapelessRecipe`</Javadoc>
+
+A shapeless recipe is a recipe that requires a specific number of items in the crafting grid to craft an item.
+These are created using a list of items. They can be created as follows:
+
+```java
+public class TestPlugin extends JavaPlugin {
+    @Override
+    public void onEnable() {
+        NamespacedKey key = new NamespacedKey(this, "WarriorSword");
+        ItemStack item = new ItemStack(Material.DIAMOND_SWORD);
+
+        ShapelessRecipe recipe = new ShapelessRecipe(key, item);
+        recipe.addIngredient(3, Material.DIAMOND);
+        recipe.addIngredient(2, Material.STICK);
+
+        getServer().addRecipe(recipe);
+    }
+}
+```
+
+This recipe declares that you simply need 3 diamonds and 2 sticks to craft the item, without any specific
+orientation of the cross pattern in the crafting grid. This could be crafted in any of the following ways:
+```
+  DSS   |   SDS   |   S D
+  D     |   D     |   D
+  D     |   D     |   D S
+```
+And, any other composition of the 5 items.