docs for loot compat

docs/groovyscript/content/content.md

@@ -1,6 +1,6 @@
 # Content
 
-This part of GroovyScript allows the creation of game content like items and blocks. It's equivalent to ContentTweaker
+This part of GroovyScript allows for the creation of game content like items and blocks. It's equivalent to ContentTweaker
 for CraftTweaker, but for GroovyScript it doesn't require another mod.
 
 !!! Note

docs/groovyscript/minecraft/loot/loot.md

@@ -1,6 +1,44 @@
 # Loot
 
-This is not a mod compat. It is a powerful standalone implementation to edit any loot tables.
+This part of GroovyScript allows for the modification of LootTables. It's equivalent to LootTweaker for CraftTweaker, but for GroovyScript it doesn't require another mod.
 
-Documentation is not yet available for tweaking loot tables.
-In the meantime have a look at some examples [here](https://github.com/CleanroomMC/GroovyScript/blob/master/examples/loot.groovy).
+!!! Note
+    Requires at least version 0.7.0. <br>
+    Works for all loot tables (including those added by mods).
+
+## Visualizing LootTables
+
+The following methods are availble for viewing in game loot tables.
+
+```groovy
+loot.printTables() // (1)!
+loot.printPools() // (2)!
+loot.printPools(String tableResourceLocation) // (3)!
+loot.printEntries() // (4)!
+loot.printEntries(String tableResourceLocation) // (5)!
+loot.printEntries(String tableResourceLocation, String poolResourceLocation) // (6)!
+```
+
+1. Prints the resource locations of all currently loaded LootTables.
+2. Prints the resource locations of all currently loaded LootPools.
+3. Prints the resource locations of all LootPools in the specified LootTable.
+4. Prints the items of all currently loaded LootEntries.
+5. Prints the items of all LootEntries in the specified LootTable.
+6. Prints the items of all LootEntries in the specified LootPool.
+
+!!! example
+
+    Below is an example what the output of `loot.printEntries()` looks like in [groovy.log](../../../getting_started.md/#groovy-log)
+    ```
+    minecraft:entities/shulker
+        - main
+            - minecraft:shulker_shell
+    minecraft:entities/wither_skeleton
+        - main
+            - minecraft:coal
+        - pool1
+            - minecraft:bone
+        - pool2
+            - minecraft:skull
+    ...
+    ```

docs/groovyscript/minecraft/loot/lootcondition.md

@@ -0,0 +1,48 @@
+# LootConditions
+
+Loot conditions are conditions which must be met for the given loot to be rolled, they can be added to pools and entries. Groovy provides some common loot conditions such as:
+
+```groovy
+.killedByPlayer() // (1)!
+.killedByNonPlayer() // (2)!
+.randomChance(float) // (3)!
+.randomChanceWithLooting(float /* (4)! */, float /* (5)! */)
+```
+
+1. An entity must be killed by a player for this entry to be rolled.
+2. An entity must be killed by a non-player for this entry to be rolled.
+3. The will only be rolled if the specified random chance (as a float [0, 1]) is successful.
+4. random chance (as a float [0, 1]).
+5. looting multiplier which is multiplied with the looting level and added to the random chance.
+
+For use in pool builders and entry builders.
+
+## Custom LootConditions
+
+You can pass a [groovy closure](../../../groovy/closure.md) to `loot.condition()` for use in a builder or to store as a groovy variable.
+
+!!! example
+
+    ```groovy
+    loot.poolBuilder()
+        .table('minecraft:entities/chicken')
+        .name('main2')
+        .entry(item('minecraft:diamond'))
+        .condition{ random, context -> random.nextFloat() < 0.05f } // (1)!
+        .register()
+    ```
+
+    1. The parameters of the closure should be java.util.Random and net.minecraft.world.storage.loot.LootContext (in that order).
+
+    ```groovy
+    def nat20Condition = loot.condition{ Random random, LootContext context -> random.nextFloat() < 0.05f } // (1)!
+
+    loot.poolBuilder()
+        .table('minecraft:entities/chicken')
+        .name('main2')
+        .entry(item('minecraft:diamond'))
+        .condition(nat20Condition)
+        .register()
+    ```
+
+    1. Don't forget to import the classes if specifying types.

docs/groovyscript/minecraft/loot/lootentry.md

@@ -0,0 +1,189 @@
+# LootEntries
+
+## Adding a LootEntry
+
+GroovyScript's Loot module provides a builder that can be used to create and register LootEntry. <br>
+Don't know what a builder is? Check [this](https://groovyscript-docs.readthedocs.io/en/latest/groovy/builder/) out.
+
+```groovy
+loot.entryBuilder()
+```
+
+Naming the entry: (optional (defaults to Item's resource location))
+
+```groovy
+.name(String)
+.name(ResourceLocation)
+```
+
+Specifying parent loot table: (required (optional if only building))
+
+```groovy
+.table(String)
+.table(ResourceLocation)
+```
+
+Specifying parent loot pool: (required (optional if only building))
+
+```groovy
+.pool(String)
+.pool(ResourceLocation)
+```
+
+Adding a weight: (optional (default is 1))
+
+```groovy
+.weight(int) // (1)!
+```
+
+1. Weight is this entry's relative likelihood of being selected amongst other entries in the same pool.
+
+Specifying quality: (optional (default is 0))
+
+```groovy
+.quality(int) // (1)!
+```
+
+1. Quality is a luck multiplier added to the weight of an item. The higher an item's quality, the more likely that player is to roll said entry as their luck value increases.
+
+Specifying random chance: (optional)
+
+```groovy
+.randomChance(float) // (1)!
+.randomChanceWithLooting(float /* (2)! */, float /* (3)! */)
+```
+
+1. The will only be rolled if the specified random chance (as a float [0, 1]) is successful.
+2. random chance (as a float [0, 1]).
+3. looting multiplier which is multiplied with the looting level and added to the random chance.
+
+Specifying loot conditions: (optional)
+
+```groovy
+.killedByPlayer() // (1)!
+.killedByNonPlayer() // (2)!
+.condition(LootCondition) // (3)!
+.condition{ java.util.Random /* (4)! */, net.minecraft.world.storage.loot.LootContext /* (5)! */ -> boolean /* (6)! */ }
+```
+
+1. An entity must be killed by a player for this entry to be rolled.
+2. An entity must be killed by a non-player for this entry to be rolled.
+3. This method exists so you can define and add a custom loot condition which implements net.minecraft.world.storage.loot.conditions.LootCondition.
+4. An instance of java.util.Random seeded by minecraft.
+5. The current LootContext which contains info about the player, world, etc.
+6. LootCondition closures must return a boolean. If true the LootPool will be rolled, if false it will not.
+
+Specifying loot functions: (optional)
+
+```groovy
+.enchantWithLevels(boolean /* (1)! */, int /* (2)! */, int /* (3)! */)
+.enchantWithLevels(boolean, int, int, LootCondition...) // (4)!
+.enchantRandomly() // (5)!
+.enchantRandomly(Enchantment...) // (6)!
+.enchantRandomly(LootCondition...) // (7)!
+.enchantRandomly(Enchantment, LootCondition...)
+.enchantRandomly(Enchantment[], LootCondition)
+.enchantRandomly(Enchantment[], LootCondition...)
+.lootingBonus(float, float) // (8)!
+.lootingBonus(float, float, int) // (9)!
+.lootingBonus(float, float, LootCondition...)
+.lootingBonus(float, float, int, LootCondition...)
+.setDamage(int) // (10)!
+.setDamage(int, int) // (11)!
+.setDamage(int, LootCondition...)
+.setDamage(int, int, LootCondition...)
+.setCount(int) // (12)!
+.setCount(int, int) // (13)!
+.setCount(int, LootCondition...)
+.setCount(int, int, LootCondition...)
+.setMetaData(int) // (14)!
+.setMetaData(int, int) // (15)!
+.setMetaData(int, LootCondition...)
+.setMetaData(int, int, LootCondition...)
+.setNBT(String) // (16)!
+.setNBT(Map<String, Object>) // (17)!
+.setNBT(NBTTagCompound)
+.setNBT(String, LootCondition...)
+.setNBT(Map<String, Object>, LootCondition...)
+.setNBT(NBTTagCompound, LootCondition...)
+.smelt() // (18)!
+.smelt(LootConditions...)
+.function(LootFunction) // (19)!
+.function{ ItemStack /* (20)! */, Random /* (21)! */, LootContext /* (22)! */ -> ItemStack /* (23)! */ }
+.function({LootFunction}, LootCondition...)
+```
+
+1. Whether or not tresure enchantments - mending or frost walker for instance - can be applied to the item.
+2. Miniumum player level the enchantments can be rolled with (uniformly distributed).
+3. Maximum player level the enchantments can be rolled with (uniformly distributed).
+4. Same as the method above but allows for the specification of loot conditions which must be met for the enchantment(s) to be applied.
+5. Apply's an random enchantment to the item at a random level.
+6. Same as .enchantRandomly() but lets you specify the pool of enchantments selected from.
+7. Same as .enchantRandomly() but lets you specify loot conditions which must be met for the enchantment to be met.
+8. Minimum and maximum number of bonus items when the player is using looting (uniformly distributed).
+9. Same as the above functions but with an integer limit on the max number of the item that the player can get after the bonus is applied.
+10. Set durability of the item.
+11. Set minimum and maximum durability of the item (uniformly distributed).
+12. Set quantity of item recieved.
+13. Set minimum and maximum quantity of the item (uniformly distributed).
+14. Set metadata of item recieved.
+15. Set minimum and maximum metadata of the item (uniformly distributed).
+16. Sets NBT data of the item (consumes an nbt json string).
+17. You can pass an nbt map to  this method.
+18. Smelt's the item using the cooresponding furnace recipe.
+19. General function for adding LootFunction to the entry.
+20. The item that is going to be given to the player.
+21. An instance of java.util.Random seeded by minecraft.
+22. The current LootContext which contains info about the player, world, etc.
+23. The item that actually gets given to the player (post-modifications).
+
+Build the LootEntry: (returns LootEntry)
+
+```groovy
+.build() // (1)!
+```
+
+1. Useful for saving an entry so it can be added to many tables/pools manually. Using LootPool.addEntry(LootEntry)
+
+Register LootEntry: (returns nothing)
+
+```groovy
+.register() // (1)!
+```
+
+1. Builds the loot entry and adds it to the specified pool.
+
+!!! example
+
+    Let's add a new loot entry that makes chickens able to drop a baked potato and a 1/20 chance of dropping 10 baked potatos instead...
+
+    ```groovy
+    loot.entryBuilder()
+        .table('minecraft:entities/chicken')
+        .pool('main')
+        .item(item('minecraft:potato'))
+        .function({ ItemStack stack, Random random, LootContext context -> // (1)!
+                stack.setCount(10)
+                return stack
+            },
+            loot.condition{ Random random, LootContext context -> random.nextFloat() < 0.05f } // (2)!
+        )
+        .smelt()
+        .register()
+    ```
+
+    1. Don't forget to import the classes that functions/conditions take as parameters.
+    2. When writing a closure condition for any function, you must wrap the closure in a loot.condition() call.
+
+## Removing a LootEntry
+
+```groovy
+LootPool.removeEntry(String)
+```
+
+!!! example
+
+    ```groovy
+    def chickenMainLootPool = loot.getTable('minecraft:entities/chicken').getPool('main')
+    chickenMainLootPool.removeEntry('minecraft:feather')
+    ```

docs/groovyscript/minecraft/loot/lootfunction.md

@@ -0,0 +1,101 @@
+# LootFunctions
+
+Loot functions are modifications to the item that a player rolls from a LootTable, they can be added to loot entries. Loot functions are always applied to the LootEntries item unless a condition(s) is specified, in which case the condition must be met for the function to be applied. Groovy provides some common loot functions such as:
+
+```groovy
+.enchantWithLevels(boolean /* (1)! */, int /* (2)! */, int /* (3)! */)
+.enchantWithLevels(boolean, int, int, LootCondition...) // (4)!
+.enchantRandomly() // (5)!
+.enchantRandomly(Enchantment...) // (6)!
+.enchantRandomly(LootCondition...) // (7)!
+.enchantRandomly(Enchantment, LootCondition...)
+.enchantRandomly(Enchantment[], LootCondition)
+.enchantRandomly(Enchantment[], LootCondition...)
+.lootingBonus(float, float) // (8)!
+.lootingBonus(float, float, int) // (9)!
+.lootingBonus(float, float, LootCondition...)
+.lootingBonus(float, float, int, LootCondition...)
+.setDamage(int) // (10)!
+.setDamage(int, int) // (11)!
+.setDamage(int, LootCondition...)
+.setDamage(int, int, LootCondition...)
+.setCount(int) // (12)!
+.setCount(int, int) // (13)!
+.setCount(int, LootCondition...)
+.setCount(int, int, LootCondition...)
+.setMetaData(int) // (14)!
+.setMetaData(int, int) // (15)!
+.setMetaData(int, LootCondition...)
+.setMetaData(int, int, LootCondition...)
+.setNBT(String) // (16)!
+.setNBT(Map<String, Object>) // (17)!
+.setNBT(NBTTagCompound)
+.setNBT(String, LootCondition...)
+.setNBT(Map<String, Object>, LootCondition...)
+.setNBT(NBTTagCompound, LootCondition...)
+.smelt() // (18)!
+.smelt(LootConditions...)
+```
+
+1. Whether or not tresure enchantments - mending or frost walker for instance - can be applied to the item.
+2. Miniumum player level the enchantments can be rolled with (uniformly distributed).
+3. Maximum player level the enchantments can be rolled with (uniformly distributed).
+4. Same as the method above but allows for the specification of loot conditions which must be met for the enchantment(s) to be applied.
+5. Apply's an random enchantment to the item at a random level.
+6. Same as .enchantRandomly() but lets you specify the pool of enchantments selected from.
+7. Same as .enchantRandomly() but lets you specify loot conditions which must be met for the enchantment to be met.
+8. Minimum and maximum number of bonus items when the player is using looting (uniformly distributed).
+9. Same as the above functions but with an integer limit on the max number of the item that the player can get after the bonus is applied.
+10. Set durability of the item.
+11. Set minimum and maximum durability of the item (uniformly distributed).
+12. Set quantity of item recieved.
+13. Set minimum and maximum quantity of the item (uniformly distributed).
+14. Set metadata of item recieved.
+15. Set minimum and maximum metadata of the item (uniformly distributed).
+16. Sets NBT data of the item (consumes an nbt json string).
+17. You can pass an nbt map to this method.
+18. Smelt's the item using the cooresponding furnace recipe.
+
+For use in LootEntry builders.
+
+## Custom LootFunctions
+
+You can pass a [groovy closure](../../../groovy/closure.md) to `loot.function()` for use in a builder or to store as a groovy variable.
+
+!!! example
+
+    ```groovy
+    loot.entryBuilder()
+        .table('minecraft:entities/chicken')
+        .pool('main')
+        .item(item('minecraft:potato'))
+        .function({ stack, random, context -> // (1)!
+                stack.setCount(10)
+                return stack
+            },
+            loot.condition{ random, context -> random.nextFloat() < 0.05f } // (2)!
+        )
+        .smelt()
+        .register()
+    ```
+
+    1. The parameters of the closure should be net.minecraft.item.ItemStack, java.util.Random, net.minecraft.world.storage.loot.LootContext (in that order).
+    2. When writing a closure condition for any function, you must wrap the closure in a loot.condition() call.
+
+    ```groovy
+    def nat20Condition = loot.condition{ Random random, LootContext context -> random.nextFloat() < 0.05f }
+    def lootPinataFunction = loot.function({ ItemStack stack, Random random, LootContext context -> // (1)!
+        stack.setCount(10)
+        return stack
+    }, nat20Condition)
+
+    loot.entryBuilder()
+        .table('minecraft:entities/chicken')
+        .pool('main')
+        .item(item('minecraft:potato'))
+        .function(lootPinataFunction)
+        .smelt()
+        .register()
+    ```
+
+    1. Don't forget to import the classes if specifying types.