Added API support for handling with internal aspects and handling of …

…player interactions (#1885)

* Implemented PortalsManager and ProtectionManager services

* Merged `dev` changes

* Added WorldRecordService

* Added entity records to the WorldRecordService

* Added player move handling to the RegionManagerService

* Combined all player statuses into one enum

* Moved signs logic out the listener class

* Moved all island-related notification methods to their own class

* Moved the stacked blocks interaction methods to a dedicated service

* Removed old event-based methods for dealing with hand items in favor of the new PlayerHand API

* Removed listeners instances cache

* Fixed stacked blocks not dropped when broken by players

* Fixed detection of the correct version of UltimateStacker (#1867)

* Added documentation to the portals manager

* Added check to ensure player can enter the destination island when going through portals

* Added documentation to the region manager

* Added documentation to the stacked blocks interaction service

* Added documentation to the world record service

* Added documentation to the player status

* Removed annotations of other libs in favor of BG-Software's framework

* Changed WorldRecordFlag to a custom IntType

* Optimized some aspects of the plugin

* Renamed ProtectionHelper#preventInteractionInternal to a more indicative ma,e

API/src/main/java/com/bgsoftware/superiorskyblock/api/player/DelegateSuperiorPlayer.java

@@ -421,25 +421,41 @@ public void setSchematicPos2(@Nullable Block block) {
     }
 
     @Override
+    @Deprecated
     public boolean isImmunedToPvP() {
         return this.handle.isImmunedToPvP();
     }
 
     @Override
+    @Deprecated
     public void setImmunedToPvP(boolean immunedToPvP) {
         this.handle.setImmunedToPvP(immunedToPvP);
     }
 
     @Override
+    @Deprecated
     public boolean isLeavingFlag() {
         return this.handle.isLeavingFlag();
     }
 
     @Override
+    @Deprecated
     public void setLeavingFlag(boolean leavingFlag) {
         this.handle.setLeavingFlag(leavingFlag);
     }
 
+    @Override
+    @Deprecated
+    public boolean isImmunedToPortals() {
+        return this.handle.isImmunedToPortals();
+    }
+
+    @Override
+    @Deprecated
+    public void setImmunedToPortals(boolean immuneToPortals) {
+        this.handle.setImmunedToPortals(immuneToPortals);
+    }
+
     @Nullable
     @Override
     public BukkitTask getTeleportTask() {
@@ -452,13 +468,13 @@ public void setTeleportTask(@Nullable BukkitTask teleportTask) {
     }
 
     @Override
-    public boolean isImmunedToPortals() {
-        return this.handle.isImmunedToPortals();
+    public PlayerStatus getPlayerStatus() {
+        return this.handle.getPlayerStatus();
     }
 
     @Override
-    public void setImmunedToPortals(boolean immuneToPortals) {
-        this.handle.setImmunedToPortals(immuneToPortals);
+    public void setPlayerStatus(PlayerStatus playerStatus) {
+        this.handle.setPlayerStatus(playerStatus);
     }
 
     @Override

API/src/main/java/com/bgsoftware/superiorskyblock/api/player/PlayerStatus.java

@@ -0,0 +1,30 @@
+package com.bgsoftware.superiorskyblock.api.player;
+
+public enum PlayerStatus {
+
+    /**
+     * The player is immuned to PvP and cannot be damaged by other players.
+     */
+    PVP_IMMUNED,
+
+    /**
+     * The player cannot be teleported by portals.
+     */
+    PORTALS_IMMUNED,
+
+    /**
+     * The player recently left an island.
+     */
+    LEAVING_ISLAND,
+
+    /**
+     * The player is being teleported by void-teleport.
+     */
+    VOID_TELEPORT,
+
+    /**
+     * The player has no special status.
+     */
+    NONE
+
+}

API/src/main/java/com/bgsoftware/superiorskyblock/api/service/portals/EntityPortalResult.java

@@ -0,0 +1,57 @@
+package com.bgsoftware.superiorskyblock.api.service.portals;
+
+import com.bgsoftware.superiorskyblock.api.events.IslandEnterPortalEvent;
+
+public enum EntityPortalResult {
+
+    /**
+     * The player is immuned to portal teleports.
+     */
+    PLAYER_IMMUNED_TO_PORTAL,
+
+    /**
+     * The portal is not inside an island.
+     */
+    PORTAL_NOT_IN_ISLAND,
+
+    /**
+     * The player cannot enter the island the portal leads to.
+     */
+    DESTINATION_ISLAND_NOT_PERMITTED,
+
+    /**
+     * The world the portal leads to is not an islands world.
+     */
+    DESTINATION_NOT_ISLAND_WORLD,
+
+    /**
+     * The world the portal leads to is disabled.
+     */
+    DESTINATION_WORLD_DISABLED,
+
+    /**
+     * The world the portal leads to is not unlocked for the island.
+     */
+    WORLD_NOT_UNLOCKED,
+
+    /**
+     * The schematic for the destination world is being generated.
+     */
+    SCHEMATIC_GENERATING_COOLDOWN,
+
+    /**
+     * The {@link IslandEnterPortalEvent} event that had been fired was cancelled.
+     */
+    PORTAL_EVENT_CANCELLED,
+
+    /**
+     * There is no valid schematic for the destination world.
+     */
+    INVALID_SCHEMATIC,
+
+    /**
+     * The entity went through the portal successfully.
+     */
+    SUCCEED
+
+}

API/src/main/java/com/bgsoftware/superiorskyblock/api/service/portals/PortalsManagerService.java

@@ -0,0 +1,49 @@
+package com.bgsoftware.superiorskyblock.api.service.portals;
+
+import com.bgsoftware.superiorskyblock.api.island.Island;
+import com.bgsoftware.superiorskyblock.api.wrappers.SuperiorPlayer;
+import org.bukkit.Location;
+import org.bukkit.PortalType;
+import org.bukkit.entity.Entity;
+
+public interface PortalsManagerService {
+
+    /**
+     * Handle a player going through a portal.
+     *
+     * @param superiorPlayer            The player that entered the portal.
+     * @param portalLocation            The location of the portal.
+     * @param portalType                The type of the portal.
+     * @param destinationLocation       The location that the player should be teleported to.
+     * @param checkImmunedPortalsStatus Whether to check if the player is immuned to portal teleports.
+     * @return The result of going through the portal.
+     */
+    EntityPortalResult handlePlayerPortal(SuperiorPlayer superiorPlayer, Location portalLocation, PortalType portalType,
+                                          Location destinationLocation, boolean checkImmunedPortalsStatus);
+
+    /**
+     * Handle a player going through a portal on an island.
+     *
+     * @param superiorPlayer            The player that entered the portal.
+     * @param island                    The island the portal is inside.
+     * @param portalLocation            The location of the portal.
+     * @param portalType                The type of the portal.
+     * @param checkImmunedPortalsStatus Whether to check if the player is immuned to portal teleports.
+     * @return The result of going through the portal.
+     */
+    EntityPortalResult handlePlayerPortalFromIsland(SuperiorPlayer superiorPlayer, Island island,
+                                                    Location portalLocation, PortalType portalType,
+                                                    boolean checkImmunedPortalsStatus);
+
+    /**
+     * Handle an entity going through a portal on an island.
+     *
+     * @param entity         The entity that entered the portal.
+     * @param island         The island the portal is inside.
+     * @param portalLocation The location of the portal.
+     * @param portalType     The type of the portal.
+     * @return The result of going through the portal.
+     */
+    EntityPortalResult handleEntityPortalFromIsland(Entity entity, Island island, Location portalLocation, PortalType portalType);
+
+}

API/src/main/java/com/bgsoftware/superiorskyblock/api/service/region/InteractionResult.java

@@ -0,0 +1,27 @@
+package com.bgsoftware.superiorskyblock.api.service.region;
+
+import com.bgsoftware.superiorskyblock.api.island.IslandPrivilege;
+
+public enum InteractionResult {
+
+    /**
+     * The interaction was made outside an island.
+     */
+    OUTSIDE_ISLAND,
+
+    /**
+     * The player is missing an {@link IslandPrivilege} for doing the interaction.
+     */
+    MISSING_PRIVILEGE,
+
+    /**
+     * The interaction that was made cannot be done while the island is being recalculated.
+     */
+    ISLAND_RECALCULATE,
+
+    /**
+     * The interaction can be done.
+     */
+    SUCCESS
+
+}

API/src/main/java/com/bgsoftware/superiorskyblock/api/service/region/MoveResult.java

@@ -0,0 +1,42 @@
+package com.bgsoftware.superiorskyblock.api.service.region;
+
+import com.bgsoftware.superiorskyblock.api.events.IslandEnterEvent;
+
+public enum MoveResult {
+
+    /**
+     * The player cannot do the movement as he is banned from the island.
+     */
+    BANNED_FROM_ISLAND,
+
+    /**
+     * The player cannot do the movement as the island is locked to the public.
+     */
+    ISLAND_LOCKED,
+
+    /**
+     * The {@link IslandEnterEvent} event was cancelled.
+     */
+    ENTER_EVENT_CANCELLED,
+
+    /**
+     * The player cannot move out of an island into the wilderness.
+     */
+    LEAVE_ISLAND_TO_OUTSIDE,
+
+    /**
+     * The player was moved too far away while being in island-preview mode.
+     */
+    ISLAND_PREVIEW_MOVED_TOO_FAR,
+
+    /**
+     * The player was teleported due to void-teleport.
+     */
+    VOID_TELEPORT,
+
+    /**
+     * The player can do the movement.
+     */
+    SUCCESS
+
+}