Merge pull request #54 from PXAV/development

Changes for v.0.3.3 - Inventory patches

CHANGELOG/kelp-v0.3.3.md

@@ -0,0 +1,56 @@
+# v0.3.3
+> Release date: 03.04.2021
+
+**Small inventory patches**:
+* Item click listeners now use a `Consumer<KelpClickEvent>` instead of the custom `ClickListener` interface.
+* You can now use data types other than String to tag a `KelpItem`
+* Item tags can now be retrieved from `KelpItem` class directly using `getIntTag(String key)` for example. This fixes issue #50.
+* Remove `@CreateInventory` annotation. Annotation-based inventories won't be supported.  
+* `ItemStack` can now be converted to `KelpItem` via `KelpItem.from(ItemStack)` as well.
+* `KelpInventory` now has a `onClose` method that can be overridden if needed to stop things like schedulers when the inventory is closed 
+* Now the `KelpInventory` abstract class is holding all widgets instead of letting this do by each individual implementation.
+* Add `PlayerInventory` class allowing for better integration of `KelpItem` in player inventories
+  * This allows you to do things like `KelpPlayer#getInventory()#setItem(slot, KelpItem)`
+  * You can add normal `Widgets` to a player inventory and create a pagination of lobby servers like that for example
+  * Fix duplication bug when item click was canceled inside a creative inventory 
+* Fix bug that converting a bukkit `ItemStack` to `KelpItem` did not convert item tags as well.
+* Change inventory state management:
+  * Remove `SimpleStatelessInventory` as Kelp does now not focus on completely stateless inventories anymore. It is considered more useful to only make specific widgets stateless and exclude them from the update process.
+  * Replace `ItemWidget` with `StatelessItemWidget` (static content) and `StatefulItemWidget` (updatable content)
+  * Every widget now has `isStateful()` method indicating if it contains updatable content. When an inventory is updated, not all slots are cleared and replaced anymore, but only those of stateful widgets.
+* You can now check if a player has a `KelpInventory` open using `KelpPlayer#hasKelpInventory()` 
+* Write an implementation for `SimpleInventory`, which can now finally be used just as `AnimatedInventory`
+* Add properties to `KelpMaterial`: You can now check whether a specific material is an item or a block and if so which blast resistance and which hardness it has, etc.
+  * Add item groups such as armor, tools, melee weapons, etc. 
+* Add `SlotArea` class calculating slot areas like lines or rectangles based on the inventory size. This makes it easier to define the areas of a pagination or a placeholder.
+* Add `PlaceholderWidget` which can be used to add placeholder items (such as glass panes, etc.) to any inventory.
+* Add `ItemMetadata` for `KelpItems`:
+  * You can now give any KelpItem a metadata depending on which material it has. This enables you to use colored armor, custom head textures, etc.
+  * `LeatherArmorMetadata`: Give color to leather armor parts 
+    * Add `Color` class representing RGB colors and offering some minecraft default colors 
+  * `SkullMetadata`: Give either custom or player textures to skull items (`PLAYER_HEAD`)
+    * Add `HeadTexture` class for conversion between custom skins and their base64-URL needed by minecraft to display the skins.
+* Documentation improvements for some NPC classes and other item classes
+* Add `getRomanNumber(int)` method to `MathUtils` allowing to get the roman notation for a decimal number
+* Add custom enchantments:
+  * You can now define default minecraft enchantments as `KelpEnchantment` for version independence (`KelpItem#enchant(KelpEnchantment class, level)`)
+  * You can create your own custom enchantments by extending from `KelpEnchantment`
+  * Implement glow effect of `KelpItem`: There is now a custom enchantment `ItemGlowEnchantment` which can be applied to simply make an item glow without actually giving special abilities.
+* A `Pagination` widget now takes a supplier of widgets instead of a normal list allowing the amount of items inside a pagination to be changed.
+* The `Pagination` widget now accepts `SimpleWidgets` instead of only normal Kelp items.
+* Add `ORB_PICKUP` to `KelpSound` enum
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

README.md

@@ -127,13 +127,13 @@ There are version implementations for the following version implementations avai
 <dependency>
   <groupId>com.github.pxav.kelp</groupId>
   <artifactId>core</artifactId>
-  <version>0.3.2</version>
+  <version>0.3.3</version>
 </dependency>
 ```
 
 ### Gradle
 ```shell script
-compile group: 'com.github.pxav.kelp', name: 'core', version: '0.3.2'
+compile group: 'com.github.pxav.kelp', name: 'core', version: '0.3.3'
 ```
 
 ### Other build tools

core/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>com.github.pxav.kelp</groupId>
     <artifactId>parent</artifactId>
-    <version>0.3.2</version>
+    <version>0.3.3</version>
   </parent>
 
   <modelVersion>4.0.0</modelVersion>

core/src/main/java/de/pxav/kelp/core/KelpPlugin.java

@@ -11,6 +11,7 @@
 import de.pxav.kelp.core.inventory.KelpInventoryRepository;
 import de.pxav.kelp.core.event.listener.EventHandlerRegistration;
 import de.pxav.kelp.core.event.listener.KelpEventRepository;
+import de.pxav.kelp.core.inventory.enchant.KelpEnchantmentRepository;
 import de.pxav.kelp.core.npc.KelpNpcRepository;
 import de.pxav.kelp.core.particle.effect.ParticleEffectRepository;
 import de.pxav.kelp.core.particle.type.ParticleTypeVersionTemplate;
@@ -35,7 +36,7 @@
  *
  * @author pxav
  */
-@Plugin(name = "Kelp", version = "0.3.2")
+@Plugin(name = "Kelp", version = "0.3.3")
 @Author("pxav")
 @Description("A cross version spigot framework.")
 @Singleton
@@ -99,6 +100,7 @@ public void onEnable() {
 
     injector.getInstance(EventHandlerRegistration.class).initialize(this.getClass().getPackage().getName());
     injector.getInstance(KelpEventRepository.class).detectSubscriptions(this.getClass().getPackage().getName());
+    injector.getInstance(KelpEnchantmentRepository.class).loadEnchantments(this.getClass().getPackage().getName());
 
     injector.getInstance(KelpCommandRepository.class).loadCommands(this.getClass().getPackage().getName());
 
@@ -130,6 +132,7 @@ public void onDisable() {
     logger().log("[SIDEBAR] Removed all animation clusters.");
     injector.getInstance(ParticleEffectRepository.class).stopAllTimers();
     injector.getInstance(KelpSchedulerRepository.class).interruptAll();
+    injector.getInstance(KelpEnchantmentRepository.class).unregisterAll();
 
     logger().log("[VERSION] Disabling version implementation module");
     injector.getInstance(VersionBinderModule.getMainClass()).onDisable();

core/src/main/java/de/pxav/kelp/core/KelpServer.java

@@ -18,15 +18,16 @@
 @Singleton
 public class KelpServer {
 
+  private static final KelpVersion currentVersion = KelpVersion.withBukkitVersion(Bukkit.getBukkitVersion());
   private KelpPlayerRepository kelpPlayerRepository;
 
   @Inject
   public KelpServer(KelpPlayerRepository kelpPlayerRepository) {
     this.kelpPlayerRepository = kelpPlayerRepository;
   }
 
-  public KelpVersion getVersion() {
-    return KelpVersion.withBukkitVersion(Bukkit.getBukkitVersion());
+  public static KelpVersion getVersion() {
+    return currentVersion;
   }
 
   public Collection<KelpPlayer> getOnlinePlayers() {

core/src/main/java/de/pxav/kelp/core/common/MathUtils.java

@@ -10,6 +10,9 @@
  */
 public class MathUtils {
 
+  private static final int[] values = {           1000, 900,  500, 400,  100, 90,   50,  40,   10,  9,    5,   4,    1 };
+  private static final String[] romanLiterals = { "M",  "CM", "D", "CD", "C", "XC", "L", "XL", "X", "IX", "V", "IV", "I" };
+
   /**
    * Checks if the given number x is even, which is
    * equal to {@code x % 2 == 0}
@@ -53,4 +56,16 @@ public static boolean perCentChance(int chance) {
     return ThreadLocalRandom.current().nextInt(0, 101) < chance;
   }
 
+  public static String getRomanNumber(int number) {
+    StringBuilder s = new StringBuilder();
+
+    for (int i = 0; i < values.length; i++) {
+      while (number >= values[i]) {
+        number -= values[i];
+        s.append(romanLiterals[i]);
+      }
+    }
+    return s.toString();
+  }
+
 }

core/src/main/java/de/pxav/kelp/core/event/kelpevent/KelpInventoryCloseEvent.java

@@ -15,10 +15,10 @@
 public class KelpInventoryCloseEvent extends KelpPlayerEvent {
 
   private static final HandlerList handlers = new HandlerList();
-  private KelpInventory inventory;
+  private KelpInventory<?> inventory;
   private boolean animated;
 
-  public KelpInventoryCloseEvent(KelpPlayer who, KelpInventory inventory, boolean isAnimated) {
+  public KelpInventoryCloseEvent(KelpPlayer who, KelpInventory<?> inventory, boolean isAnimated) {
     super(who);
     this.inventory = inventory;
     this.animated = isAnimated;
@@ -29,7 +29,7 @@ public KelpInventoryCloseEvent(KelpPlayer who, KelpInventory inventory, boolean
    *
    * @return The closed inventory
    */
-  public KelpInventory getInventory() {
+  public KelpInventory<?> getInventory() {
     return this.inventory;
   }
 

core/src/main/java/de/pxav/kelp/core/event/kelpevent/KelpInventoryOpenEvent.java

@@ -16,16 +16,16 @@
 public class KelpInventoryOpenEvent extends KelpPlayerEvent {
 
   private static final HandlerList handlers = new HandlerList();
-  private KelpInventory inventory;
+  private KelpInventory<?> inventory;
   private boolean animatedInventory;
 
-  public KelpInventoryOpenEvent(KelpPlayer who, KelpInventory inventory, boolean isAnimated) {
+  public KelpInventoryOpenEvent(KelpPlayer who, KelpInventory<?> inventory, boolean isAnimated) {
     super(who);
     this.inventory = inventory;
     this.animatedInventory = isAnimated;
   }
 
-  public KelpInventory getInventory() {
+  public KelpInventory<?> getInventory() {
     return inventory;
   }
 

core/src/main/java/de/pxav/kelp/core/event/kelpevent/KelpInventoryUpdateEvent.java

@@ -15,9 +15,9 @@
 public class KelpInventoryUpdateEvent extends KelpPlayerEvent {
 
   private static final HandlerList handlers = new HandlerList();
-  private KelpInventory inventory;
+  private KelpInventory<?> inventory;
 
-  public KelpInventoryUpdateEvent(KelpPlayer who, KelpInventory inventory) {
+  public KelpInventoryUpdateEvent(KelpPlayer who, KelpInventory<?> inventory) {
     super(who);
     this.inventory = inventory;
   }
@@ -27,7 +27,7 @@ public KelpInventoryUpdateEvent(KelpPlayer who, KelpInventory inventory) {
    *
    * @return the updated inventory
    */
-  public KelpInventory getInventory() {
+  public KelpInventory<?> getInventory() {
     return inventory;
   }
 

core/src/main/java/de/pxav/kelp/core/event/kelpevent/npc/NpcDespawnEvent.java

@@ -3,16 +3,37 @@
 import de.pxav.kelp.core.npc.KelpNpc;
 import org.bukkit.event.HandlerList;
 
+/**
+ * This event is triggered when a {@link KelpNpc} is despawned.
+ * A despawn can be triggered when the NPC is out of range for example
+ * (caused by {@link de.pxav.kelp.core.npc.activity.AutoSpawnActivity})
+ * or when it is completely removed from the server, which can be
+ * checked with {@link #isRemove()}.
+ *
+ * When an NPC is just despawned, it is still registered in the NPC
+ * cache and affected by NPC ticks, but it won't be visible for any player.
+ *
+ * @author pxav
+ */
 public class NpcDespawnEvent extends NpcEvent {
 
   private static final HandlerList handlers = new HandlerList();
+
+  // whether the npc is completely removed from the server
   private boolean isRemove;
 
   public NpcDespawnEvent(KelpNpc npc, boolean isRemove) {
     super(npc);
     this.isRemove = isRemove;
   }
 
+  /**
+   * Checks whether the npc is completely removed from the server.
+   * This would mean that it has been removed from the cache as well
+   * as the tick system (no activities are executed on it anymore).
+   *
+   * @return {@code true} if the npc is completely removed, {@code false} if it was just a normal despawn
+   */
   public boolean isRemove() {
     return isRemove;
   }

core/src/main/java/de/pxav/kelp/core/event/kelpevent/npc/NpcEvent.java

@@ -5,22 +5,34 @@
 import org.bukkit.event.Event;
 
 /**
- * A class description goes here.
+ * Represents an event that is related to a {@link KelpNpc}.
  *
  * @author pxav
  */
 public abstract class NpcEvent extends Event {
 
+  // the npc handled by this event
   protected KelpNpc npc;
 
   public NpcEvent(KelpNpc npc) {
     this.npc = npc;
   }
 
+  /**
+   * Gets the {@link KelpNpc NPC} that is handled by this event.
+   *
+   * @return The npc that is handled by this event.
+   */
   public final KelpNpc getNpc() {
     return this.npc;
   }
 
+  /**
+   * Gets the owner of the NPC, the player who can see the NPC
+   * or is associated with it in the server cache.
+   *
+   * @return the owning {@link KelpPlayer player} of the NPC.
+   */
   public final KelpPlayer getPlayer() {
     return npc.getPlayer();
   }

core/src/main/java/de/pxav/kelp/core/event/kelpevent/npc/NpcInteractAction.java

@@ -1,8 +1,25 @@
 package de.pxav.kelp.core.event.kelpevent.npc;
 
+/**
+ * Represents the action type of an interaction with an NPC.
+ * This can be used when handling the {@link NpcInteractEvent}
+ * for example, which is triggered when a {@link de.pxav.kelp.core.npc.KelpNpc}
+ * is either right clicked or attacked.
+ *
+ * @author pxav
+ */
 public enum NpcInteractAction {
 
+  /**
+   * A player has right clicked the NPC.
+   */
   RIGHT_CLICK,
+
+  /**
+   * A player has left clicked the NPC
+   * which might indicate that they have tried
+   * to attack the NPC.
+   */
   LEFT_CLICK
 
 }

core/src/main/java/de/pxav/kelp/core/event/kelpevent/npc/NpcInteractEvent.java

@@ -3,16 +3,31 @@
 import de.pxav.kelp.core.npc.KelpNpc;
 import org.bukkit.event.HandlerList;
 
+/**
+ * This event is called when a {@link de.pxav.kelp.core.player.KelpPlayer} interacts
+ * with a {@link KelpNpc} by either right or left clicking/attacking it.
+ *
+ * @author pxav
+ */
 public class NpcInteractEvent extends NpcEvent {
 
   private static final HandlerList handlers = new HandlerList();
+
+  // the action performed on the NPC.
   private NpcInteractAction action;
 
   public NpcInteractEvent(KelpNpc npc, NpcInteractAction action) {
     super(npc);
     this.action = action;
   }
 
+  /**
+   * Gets the action performed on the NPC. This way you can
+   * determine whether the player has attacked/left clicked
+   * or right clicked the NPC.
+   *
+   * @return The type/action of the interaction.
+   */
   public NpcInteractAction getAction() {
     return action;
   }

core/src/main/java/de/pxav/kelp/core/event/kelpevent/npc/NpcSpawnEvent.java

@@ -3,6 +3,14 @@
 import de.pxav.kelp.core.npc.KelpNpc;
 import org.bukkit.event.HandlerList;
 
+/**
+ * This event is triggered when an NPC is spawned to a {@link de.pxav.kelp.core.world.KelpWorld}.
+ * It can either be triggered when an NPC spawns for the first time or when
+ * it spawns again after a {@link NpcDespawnEvent}. This can be queried
+ * using {@link #isInitialSpawn()}.
+ *
+ * @author pxav
+ */
 public class NpcSpawnEvent extends NpcEvent {
 
   private static final HandlerList handlers = new HandlerList();
@@ -13,6 +21,12 @@ public NpcSpawnEvent(KelpNpc npc, boolean initialSpawn) {
     this.initialSpawn = initialSpawn;
   }
 
+  /**
+   * Checks whether the NPC has spawned for the first time
+   * or if it just spawned again after it has been despawned.
+   *
+   * @return {@code true} if the npc spawns for the first time, {@code false} if it spawned after a respawn.
+   */
   public boolean isInitialSpawn() {
     return initialSpawn;
   }