Release 3.1.1

.github/workflows/modrinth-publish.yml

@@ -0,0 +1,46 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # !!! Make sure to select the correct Java version for your project !!!
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: adopt
+          cache: maven
+
+      # This step will take the version tag from the release and replace it in `pom.xml` before building.
+      - name: Set version from release tag
+        run: mvn -B versions:set -DnewVersion=${{ github.event.release.tag_name }} -DgenerateBackupPoms=false
+
+      - name: Build and package with Maven
+        run: mvn -B clean package --file pom.xml
+
+      - name: Upload to Modrinth
+        uses: cloudnode-pro/modrinth-publish@2.0.0
+        with:
+          # Configure the action
+          # api-domain: staging-api.modrinth.com
+          token: ${{ secrets.MODRINTH_TOKEN }}
+          project: aBVLHiAW
+          name: ${{ github.event.release.name }}
+          version: ${{ github.event.release.tag_name }}
+          changelog: ${{ github.event.release.body }}
+          loaders: |-
+            paper
+            spigot
+          game-versions: |-
+            1.21.3
+            1.21.4
+          files: target/BentoBox-${{ github.event.release.tag_name }}.jar

pom.xml

@@ -84,7 +84,7 @@
         <!-- Do not change unless you want different name for local builds. -->
         <build.number>-LOCAL</build.number>
         <!-- This allows to change between versions. -->
-        <build.version>3.0.1</build.version>
+        <build.version>3.1.1</build.version>
         <sonar.organization>bentobox-world</sonar.organization>
         <sonar.host.url>https://sonarcloud.io</sonar.host.url>
         <server.jars>${project.basedir}/lib</server.jars>
@@ -192,6 +192,12 @@
             <id>clojars</id>
             <url>https://repo.clojars.org/</url>
         </repository>
+        <!-- FancyNPC -->
+        <repository>
+            <id>fancyplugins-releases</id>
+            <name>FancyPlugins Repository</name>
+            <url>https://repo.fancyplugins.de/releases</url>
+        </repository>
     </repositories>
 
     <dependencies>
@@ -234,6 +240,12 @@
             <version>${spigot.version}</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+             <groupId>org.spigotmc......</groupId>
+             <artifactId>spigot</artifactId>
+             <version>1.21.4-R0.1-SNAPSHOT</version>
+             <scope>provided</scope>
+        </dependency>
         <dependency>
              <groupId>org.spigotmc.....</groupId>
              <artifactId>spigot</artifactId>
@@ -387,6 +399,13 @@
             <version>1.1.13</version>
             <scope>compile</scope>
          </dependency>
+         <!-- FancyNPCs -->
+        <dependency>
+            <groupId>de.oliver</groupId>
+            <artifactId>FancyNpcs</artifactId>
+            <version>2.4.0</version>
+            <scope>provided</scope>
+        </dependency>
     </dependencies>
 
     <build>

src/main/java/world/bentobox/bentobox/BentoBox.java

@@ -19,11 +19,13 @@
 
 import world.bentobox.bentobox.api.configuration.Config;
 import world.bentobox.bentobox.api.events.BentoBoxReadyEvent;
+import world.bentobox.bentobox.api.hooks.Hook;
 import world.bentobox.bentobox.api.localization.TextVariables;
 import world.bentobox.bentobox.api.user.Notifier;
 import world.bentobox.bentobox.api.user.User;
 import world.bentobox.bentobox.commands.BentoBoxCommand;
 import world.bentobox.bentobox.database.DatabaseSetup;
+import world.bentobox.bentobox.hooks.FancyNpcsHook;
 import world.bentobox.bentobox.hooks.ItemsAdderHook;
 import world.bentobox.bentobox.hooks.MultipaperHook;
 import world.bentobox.bentobox.hooks.MultiverseCoreHook;
@@ -192,6 +194,9 @@ private void completeSetup(long loadTime) {
 
         hooksManager.registerHook(new VaultHook());
 
+        // FancyNpcs
+        hooksManager.registerHook(new FancyNpcsHook());
+
         // MythicMobs
         hooksManager.registerHook(new MythicMobsHook());
 

src/main/java/world/bentobox/bentobox/api/addons/package-info.java

@@ -1,12 +1,20 @@
 /**
- * This package covers all addon-specific API
- * <p>
- * The Addon class and the associated Pladdon are like Bukkit plugins
- * but contain extra API specific for BentoBox games.
- * </p>
+ * This package contains classes and interfaces related to BentoBox addons.
+ * 
+ * Addons are modular extensions that enhance BentoBox functionality. Game-specific
+ * addons (e.g., BSkyBlock, AcidIsland) as well as generic addons (e.g., Challenges, Warps)
+ * are supported by this system. Developers can create custom addons to introduce
+ * new features or gamemodes.
+ * 
+ * Since BentoBox was created, server tech has changed and code remapping is done and that
+ * is usually only applied when a Plugin is loaded, so developers should use Pladdons
+ * which are a wrapper for Addons in a Plugin.
+ * 
+ * Key components:
+ * - AddonLoader: Manages the lifecycle of addons.
+ * - AddonConfig: Handles addon-specific configurations.
  *
  * @since 1.0
  * @author tastybento
- *
  */
 package world.bentobox.bentobox.api.addons;

src/main/java/world/bentobox/bentobox/api/commands/package-info.java

@@ -1,7 +1,9 @@
 /**
- * API for BentoBox commands
- */
-/**
+ * This package contains classes and handlers for BentoBox commands.
+ * 
+ * Commands allow players and administrators to interact with BentoBox, including
+ * managing islands, settings, and other in-game features. This package ensures
+ * smooth integration and execution of commands within the plugin.
  * <p>
  * The workhorse class is the abstract class CompositeCommand. It provides all the functionality for
  * a command including automatic help, sub-commands, convenience methods, etc. See examples of how to use
@@ -13,6 +15,10 @@
  * their own custom help if required, but most of the time it is not.
  * </p>
  * @author tastybento
- *
+ * 
+ * Key features:
+ * - Command registration and parsing.
+ * - Support for custom addon-specific commands.
+ * - Error handling and permission validation.
  */
 package world.bentobox.bentobox.api.commands;

src/main/java/world/bentobox/bentobox/api/configuration/package-info.java

@@ -1,4 +1,6 @@
 /**
- * Contains API related to configurations.
+ * Provides classes and interfaces for managing configuration settings within the BentoBox API.
+ * This package enables the definition, access, and manipulation of configuration options,
+ * facilitating the customization and extension of BentoBox's functionality.
  */
 package world.bentobox.bentobox.api.configuration;

src/main/java/world/bentobox/bentobox/api/events/package-info.java

@@ -1,7 +1,14 @@
 /**
- * API for all the events that BentoBox generates
- */
-/**
+ * This package defines events used within the BentoBox framework.
+ * 
+ * Events are triggered during key gameplay actions, such as island creation,
+ * deletion, or player interactions. Developers can use these events to customize
+ * behaviors or respond to actions in their addons.
+ * 
+ * Key features:
+ * - Custom event classes (e.g., IslandCreateEvent, PlayerJoinEvent).
+ * - Integration with Bukkit's event system.
+ * 
  * @author tastybento
  *
  */

src/main/java/world/bentobox/bentobox/api/package-info.java

@@ -0,0 +1,10 @@
+/**
+ * This package provides the core API for interacting with the BentoBox framework.
+ * 
+ * It enables developers to integrate their custom plugins or addons with BentoBox,
+ * offering simplified access to common functionalities like:
+ * - Island management (creation, deletion, permissions).
+ * - Player interactions within island-based games.
+ * - Events and hooks for extending core behavior.
+ */
+package world.bentobox.bentobox.api;

src/main/java/world/bentobox/bentobox/blueprints/BlueprintClipboard.java

@@ -2,7 +2,6 @@
 
 import java.util.ArrayList;
 import java.util.Arrays;
-import java.util.Collection;
 import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -23,8 +22,8 @@
 import org.bukkit.entity.AbstractHorse;
 import org.bukkit.entity.Ageable;
 import org.bukkit.entity.ChestedHorse;
+import org.bukkit.entity.Entity;
 import org.bukkit.entity.Horse;
-import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Player;
 import org.bukkit.entity.Tameable;
 import org.bukkit.entity.Villager;
@@ -44,6 +43,7 @@
 import world.bentobox.bentobox.blueprints.dataobjects.BlueprintBlock;
 import world.bentobox.bentobox.blueprints.dataobjects.BlueprintCreatureSpawner;
 import world.bentobox.bentobox.blueprints.dataobjects.BlueprintEntity;
+import world.bentobox.bentobox.hooks.FancyNpcsHook;
 import world.bentobox.bentobox.hooks.MythicMobsHook;
 
 /**
@@ -70,20 +70,22 @@ public class BlueprintClipboard {
     private final Map<Vector, BlueprintBlock> bpBlocks = new LinkedHashMap<>();
     private final BentoBox plugin = BentoBox.getInstance();
     private Optional<MythicMobsHook> mmh;
+    private Optional<FancyNpcsHook> npc;
 
     /**
      * Create a clipboard for blueprint
      * @param blueprint - the blueprint to load into the clipboard
      */
     public BlueprintClipboard(@NonNull Blueprint blueprint) {
+        this();
         this.blueprint = blueprint;
-        // MythicMobs
-        mmh = plugin.getHooks().getHook("MythicMobs").filter(MythicMobsHook.class::isInstance)
-                .map(MythicMobsHook.class::cast);
     }
 
     public BlueprintClipboard() {
-        // MythicMobs
+        // Citizens Hook
+        npc = plugin.getHooks().getHook("FancyNpcs").filter(FancyNpcsHook.class::isInstance)
+                .map(FancyNpcsHook.class::cast);
+        // MythicMobs Hook
         mmh = plugin.getHooks().getHook("MythicMobs").filter(MythicMobsHook.class::isInstance)
                 .map(MythicMobsHook.class::cast);
     }
@@ -136,13 +138,20 @@ public boolean copy(User user, boolean copyAir, boolean copyBiome) {
 
     private void copyAsync(World world, User user, List<Vector> vectorsToCopy, int speed, boolean copyAir, boolean copyBiome) {
         copying = false;
+        // FancyNpcs
+        if (npc.isPresent()) {
+            // Add all the citizens for the area in one go. This is pretty fast.
+            bpEntities.putAll(npc.get().getNpcsInArea(world, vectorsToCopy, origin));
+        }
+
+        // Repeating copy task
         copyTask = Bukkit.getScheduler().runTaskTimer(plugin, () -> {
             if (copying) {
                 return;
             }
             copying = true;
             vectorsToCopy.stream().skip(index).limit(speed).forEach(v -> {
-                List<LivingEntity> ents = world.getLivingEntities().stream()
+                List<Entity> ents = world.getEntities().stream()
                         .filter(Objects::nonNull)
                         .filter(e -> !(e instanceof Player))
                         .filter(e -> new Vector(Math.rint(e.getLocation().getX()),
@@ -153,6 +162,7 @@ private void copyAsync(World world, User user, List<Vector> vectorsToCopy, int s
                     count++;
                 }
             });
+
             index += speed;
             int percent = (int)(index * 100 / (double)vectorsToCopy.size());
             if (percent != lastPercentage && percent % 10 == 0) {
@@ -189,9 +199,9 @@ protected List<Vector> getVectors(BoundingBox b) {
         return r;
     }
 
-    private boolean copyBlock(Location l, boolean copyAir, boolean copyBiome, Collection<LivingEntity> entities) {
+    private boolean copyBlock(Location l, boolean copyAir, boolean copyBiome, List<Entity> ents) {
         Block block = l.getBlock();
-        if (!copyAir && block.getType().equals(Material.AIR) && entities.isEmpty()) {
+        if (!copyAir && block.getType().equals(Material.AIR) && ents.isEmpty()) {
             return false;
         }
         // Create position
@@ -202,14 +212,14 @@ private boolean copyBlock(Location l, boolean copyAir, boolean copyBiome, Collec
         Vector pos = new Vector(x, y, z);
 
         // Set entities
-        List<BlueprintEntity> bpEnts = setEntities(entities);
+        List<BlueprintEntity> bpEnts = setEntities(ents);
         // Store
         if (!bpEnts.isEmpty()) {
             bpEntities.put(pos, bpEnts);
         }
 
         // Return if this is just air block
-        if (!copyAir && block.getType().equals(Material.AIR) && !entities.isEmpty()) {
+        if (!copyAir && block.getType().equals(Material.AIR) && !ents.isEmpty()) {
             return true;
         }
 
@@ -291,9 +301,14 @@ private BlueprintCreatureSpawner getSpawner(CreatureSpawner spawner) {
         return cs;
     }
 
-    private List<BlueprintEntity> setEntities(Collection<LivingEntity> entities) {
+    /**
+     * Deals with any entities that are in this block. Technically, this could be more than one, but is usually one.
+     * @param ents collection of entities
+     * @return Serialized list of entities
+     */
+    private List<BlueprintEntity> setEntities(List<Entity> ents) {
         List<BlueprintEntity> bpEnts = new ArrayList<>();
-        for (LivingEntity entity: entities) {
+        for (Entity entity : ents) {
             BlueprintEntity bpe = new BlueprintEntity();
 
             bpe.setType(entity.getType());
@@ -329,6 +344,7 @@ private List<BlueprintEntity> setEntities(Collection<LivingEntity> entities) {
                 bpe.setStyle(horse.getStyle());
             }
 
+            // Mythic mob check
             mmh.filter(mm -> mm.isMythicMob(entity)).map(mm -> mm.getMythicMob(entity))
                     .ifPresent(bpe::setMythicMobsRecord);
 

src/main/java/world/bentobox/bentobox/blueprints/BlueprintPaster.java

@@ -124,12 +124,38 @@ public BlueprintPaster(@NonNull BentoBox plugin, @NonNull Blueprint bp, World wo
         location.setY(y);
     }
 
-    private record Bits(Map<Vector, BlueprintBlock> blocks,
+    /**
+     * A record of all the "bits" of the blueprint that need to be pasted
+     * Consists of blocks, attached blocks, entities, iterators for the blocks and a speed
+     */
+    private record Bits(
+            /**
+             * Basic blocks to the pasted (not attached blocks)
+             */
+            Map<Vector, BlueprintBlock> blocks,
+            /**
+             * Attached blocks
+             */
             Map<Vector, BlueprintBlock> attached,
+            /**
+             * Entities to be pasted
+             */
             Map<Vector, List<BlueprintEntity>> entities,
+            /**
+             * Basic block pasting iterator
+             */
             Iterator<Entry<Vector, BlueprintBlock>> it,
+            /**
+             * Attached block pasting iterator
+             */
             Iterator<Entry<Vector, BlueprintBlock>> it2,
+            /**
+             * Entity pasting iterator
+             */
             Iterator<Entry<Vector, List<BlueprintEntity>>> it3,
+            /**
+             * Paste speed
+             */
             int pasteSpeed) {}
 
     /**