Merge branch 'master' of https://github.com/klashdevelopment/Caramel

Author: GavinGoGaming

.github/workflows/javadoc.yml

@@ -1,7 +1,7 @@
 name: Deploy Javadoc
 
 on:
-#  push:
+ push:
 #    branches:
 #      - master
 #      - main
@@ -12,12 +12,17 @@ jobs:
     permissions:
       contents: write  # if you have a protection rule on your repository, you'll need to give write permission to the workflow.
     steps:
+      - uses: actions/checkout@v4
+      - name: Setup Java JDK
+        uses: actions/[email protected]
+        with:
+          java-version: 21
+          distribution: temurin
       - name: Create branch for Javadoc
         uses: MathieuSoysal/[email protected]
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          javadoc-branch: javadoc
           java-version: 17
-          target-folder: docs/javadoc # url will be https://<username>.github.io/<repo>/javadoc, This can be left as nothing to generate javadocs in the root folder.
-          project: maven # or gradle
-          # subdirectories: moduleA moduleB #for subdirectories support, needs to be run with custom command
+          javadoc-branch: javadoc
+          target-folder: docs/javadoc
+          project: maven

docs/configs.md

@@ -0,0 +1,24 @@
+# Configs
+
+## READ ME FIRST
+If you'd like to make a config **without** having a template file in your resources folder (configs created at-runtime with changing filenames), use a `CaramelBlankConfig` instead of a `CaramelConfig` class!
+
+## Creating one
+First, make a variable for it:
+```java
+CaramelConfig coolConfig;
+```
+
+Then in your onEnable, initialize it:
+```java
+coolConfig = new CaramelConfig(this, "coolest-config.yml");
+// If using blank configs, use .saveBlankConfig() instead.
+coolConfig.saveDefaultConfig();
+```
+
+And use it:
+```java
+coolConfig.getData() // returns a FileConfiguration
+coolConfig.getData().getString("my.path");
+coolConfig.getData().setString("my.path", "Setting!");
+```

docs/index.md

@@ -40,9 +40,9 @@ depend: [Caramel]
 ## Features
 Caramel has a few main features.
 - [Commands](https://pages.klash.dev/Caramel/commands)
-- [Items](https://pages.klash.dev/Caramel/items) - Docs incomplete
+- [Items](https://pages.klash.dev/Caramel/items) (WIP Docs)
 - [Guis](https://pages.klash.dev/Caramel/guis)
 - [Currencies](https://pages.klash.dev/Caramel/currencies)
-- [Recipes](https://pages.klash.dev/Caramel/recipes) - Docs incomplete
-- [YAML Configs](https://pages.klash.dev/Caramel/configs) - Docs incomplete
+- [Recipes](https://pages.klash.dev/Caramel/recipes)
+- [YAML Configs](https://pages.klash.dev/Caramel/configs)
 - [SQL Configs](https://pages.klash.dev/Caramel/sql)

docs/items.md

@@ -0,0 +1,36 @@
+# Items
+
+The documentation for items are WIP, but here's a simple implementation while you wait:
+
+```java
+    public class MyItem implements CaramelItem {
+
+        @Override
+        public CaramelItemDetail getDetails() {
+            return CaramelItemDetail.builder()
+                    .id("item_identifier") // Required
+                    .defaultStack(1) // Required
+                    .modelData(0) // Optional - Custom Model Data
+                    .itemBase(Material.PAPER) // Required
+                    .itemName(CaramelUtility.colorcomp("<gold><bold>Supports miniMessage")) // Required
+                    .lore(Arrays.asList("Lore <red>is cool<yellow>!")) // Required
+                    .build();
+        }
+
+        @Override
+        public ItemStack modifyBeforeFinalizing(ItemStack item) {
+            // You can add custom modifications (attributes) here.
+            // Return the item back to keep it the same.
+            return item;
+        }
+
+        @Override
+        public void onItemUse(ClickType type, ItemStack item, PlayerInteractEvent event) {
+            // Handle interactions here.
+            // ClickType is a dev.klash.caramel.items, not bukkit.
+            event.getPlayer().sendMessage(CaramelUtility.colorcomp("Hello!"));
+        }
+    }
+```
+
+Please see Commands for registering, but use `Caramel.getInstance().items` and define it as a `CaramelItem`.

docs/recipes.md

@@ -0,0 +1,70 @@
+# Recipes
+
+## Making each recipe
+First, get started by making a new class for your recipe, and implementing all the methods:
+```java
+public class MyFirstRecipe extends CaramelRecipe {
+  public ItemStack getResult() {return ...;};
+  public CaramelRecipeDetail getDetails() {return ...;};
+  public NamespacedKey getKey() {return ...;};
+}
+```
+
+Result needs to be an ItemStack to return as the output.
+
+Key needs to be a NamespacedKey with your Plugin/Identifier and the recipe's identifier.
+
+The details are where we define the actual recipe:
+```java
+CaramelRecipeDetail.of(
+  new CaramelRecipeValue[] {},
+  new String[] {
+    "   ",
+    "   ",
+    "   "
+  }
+);
+```
+
+The array of values are your mappings for your pattern. See the values section below.
+
+The array of strings is your pattern, and should be 3x tripple-letter strings.
+
+
+<br/><br/>
+
+
+## Recipe Values
+A recipe value is a mapping of character <--> an itemstack or material to be used in the crafting grid.
+
+You can create these by the `CaramelRecipeValueItem` and `CaramelRecipeValueMaterial` constructors:
+
+```java
+// A material value is only the material.
+new CaramelRecipeValueMaterial('D', Material.DIAMOND)
+
+// A item value is for more specific recipe values.
+new CaramelRecipeValueItem('D', new ItemStack(Material.DIAMOND))
+```
+
+
+<br/><br/>
+
+
+## Registering your recipes
+Recipes are registered through RecipeLists. You can create these directly from the instance of Caramel:
+
+```java
+// Define your list in your class:
+CaramelRecipeList myRecipes;
+
+// Inside your onEnable:
+recipeList = Caramel.createRecipeList(
+  myFirstRecipe,
+  mySecondRecipe
+);
+recipeList.registerAll();
+
+// Inside your onDisable:
+recipeList.cleanup();
+```