Add static encode/decode for block long keys (#1712)

Should make this API easier to use.

4 files changed, 92 insertions, 43 deletions

diff --git a/Spigot-API-Patches/0138-Allow-Blocks-to-be-accessed-via-a-long-key.patch b/Spigot-API-Patches/0138-Allow-Blocks-to-be-accessed-via-a-long-key.patch
index aa4b9746d8..c4a1f16e07 100644
--- a/Spigot-API-Patches/0138-Allow-Blocks-to-be-accessed-via-a-long-key.patch
+++ b/Spigot-API-Patches/0138-Allow-Blocks-to-be-accessed-via-a-long-key.patch
@@ -1,4 +1,4 @@
-From d9d41debeb4d52f921e1751ed7f401aeba037dbd Mon Sep 17 00:00:00 2001
+From 777336e47986d99c007847d7ae72f3db8279da5b Mon Sep 17 00:00:00 2001
 From: Spottedleaf <[email protected]>
 Date: Tue, 14 Aug 2018 21:42:10 -0700
 Subject: [PATCH] Allow Blocks to be accessed via a long key
@@ -18,22 +18,29 @@ Y range: [0, 1023]
 X, Z range: [-67 108 864, 67 108 863]
 
 diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java
-index 84b7d93cf..334e31350 100644
+index 4c2a269d..2719eecb 100644
 --- a/src/main/java/org/bukkit/Location.java
 +++ b/src/main/java/org/bukkit/Location.java
-@@ -578,6 +578,18 @@ public class Location implements Cloneable, ConfigurationSerializable {
+@@ -13,7 +13,6 @@ import org.jetbrains.annotations.Nullable;
+ 
+ // Paper start
+ import java.util.Collection;
+-import java.util.Collections;
+ import java.util.function.Predicate;
+ import org.bukkit.entity.Entity;
+ import org.bukkit.entity.LivingEntity;
+@@ -578,6 +577,17 @@ public class Location implements Cloneable, ConfigurationSerializable {
          blockLoc.setZ(getBlockZ());
          return blockLoc;
      }
 +
 +    // Paper Start
-+
 +    /**
 +     * @return The block key for this location's block location.
-+     * @see Block#getBlockKey()
++     * @see Block#getBlockKey(int, int, int)
 +     */
 +    public long toBlockKey() {
-+        return ((long)getBlockX() & 0x7FFFFFF) | (((long)getBlockZ() & 0x7FFFFFF) << 27) | ((long)getBlockY() << 54);
++        return Block.getBlockKey(getBlockX(), getBlockY(), getBlockZ());
 +    }
 +    // Paper End
 +
@@ -41,10 +48,10 @@ index 84b7d93cf..334e31350 100644
       * @return A new location where X/Y/Z are the center of the block
       */
 diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
-index 1b0744ed9..158917492 100644
+index 1b0744ed..fa736b07 100644
 --- a/src/main/java/org/bukkit/World.java
 +++ b/src/main/java/org/bukkit/World.java
-@@ -80,6 +80,39 @@ public interface World extends PluginMessageRecipient, Metadatable {
+@@ -80,6 +80,38 @@ public interface World extends PluginMessageRecipient, Metadatable {
      @NotNull
      public Block getBlockAt(@NotNull Location location);
  
@@ -54,29 +61,28 @@ index 1b0744ed9..158917492 100644
 +     *
 +     * @param key The block key. See {@link Block#getBlockKey()}
 +     * @return Block at the key
-+     * @see Location#toBlockKey()
-+     * @see Block#getBlockKey()
++     * @see Block#getBlockKey(int, int, int)
 +     */
 +    @NotNull
 +    public default Block getBlockAtKey(long key) {
-+        int x = (int) ((key << 37) >> 37);
-+        int y = (int) (key >>> 54);
-+        int z = (int) ((key << 10) >> 37);
++        int x = Block.getBlockKeyX(key);
++        int y = Block.getBlockKeyY(key);
++        int z = Block.getBlockKeyZ(key);
 +        return getBlockAt(x, y, z);
 +    }
++
 +    /**
 +     * Gets the {@link Location} at the given block key
 +     *
 +     * @param key The block key. See {@link Location#toBlockKey()}
 +     * @return Location at the key
-+     * @see Location#toBlockKey()
-+     * @see Block#getBlockKey()
++     * @see Block#getBlockKey(int, int, int)
 +     */
 +    @NotNull
 +    public default Location getLocationAtKey(long key) {
-+        int x = (int) ((key << 37) >> 37);
-+        int y = (int) (key >>> 54);
-+        int z = (int) ((key << 10) >> 37);
++        int x = Block.getBlockKeyX(key);
++        int y = Block.getBlockKeyY(key);
++        int z = Block.getBlockKeyZ(key);
 +        return new Location(this, x, y, z);
 +    }
 +    // Paper end
@@ -85,37 +91,80 @@ index 1b0744ed9..158917492 100644
       * Gets the y coordinate of the lowest block at this position such that the
       * block and all blocks above it are transparent for lighting purposes.
 diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
-index 708288e99..42f31db29 100644
+index 708288e9..c20f903a 100644
 --- a/src/main/java/org/bukkit/block/Block.java
 +++ b/src/main/java/org/bukkit/block/Block.java
-@@ -153,6 +153,33 @@ public interface Block extends Metadatable {
+@@ -153,6 +153,76 @@ public interface Block extends Metadatable {
       */
      int getZ();
  
 +    // Paper Start
++    /**
++     * Returns this block's coordinates packed into a long value.
++     * Computed via: {@code Block.getBlockKey(this.getX(), this.getY(), this.getZ())}
++     * @see Block#getBlockKey(int, int, int)
++     * @return This block's x, y, and z coordinates packed into a long value
++     */
++    public default long getBlockKey() {
++        return Block.getBlockKey(this.getX(), this.getY(), this.getZ());
++    }
 +
 +    /**
-+     * Returns this block's coordinates packed into a long value
++     * Returns the specified block coordinates packed into a long value
 +     * <p>
 +     * The return value can be computed as follows:
 +     * <br>
-+     * {@code long value = ((long)getX() & 0x7FFFFFF) | (((long)getZ() & 0x7FFFFFF) << 27) | ((long)getY() << 54);}
++     * {@code long value = ((long)x & 0x7FFFFFF) | (((long)z & 0x7FFFFFF) << 27) | ((long)y << 54);}
++     * </br>
 +     * </p>
 +     *
 +     * <p>
 +     * And may be unpacked as follows:
-+     *<br>
++     * <br>
 +     * {@code int x = (int) ((packed << 37) >> 37);}
++     * </br>
 +     * <br>
 +     * {@code int y = (int) (packed >>> 54);}
++     * </br>
 +     * <br>
 +     * {@code int z = (int) ((packed << 10) >> 37);}
++     * </br>
 +     * </p>
 +     *
 +     * @return This block's x, y, and z coordinates packed into a long value
 +     */
-+    public default long getBlockKey() {
-+        return ((long)getX() & 0x7FFFFFF) | (((long)getZ() & 0x7FFFFFF) << 27) | ((long)getY() << 54);
++    public static long getBlockKey(int x, int y, int z) {
++        return ((long)x & 0x7FFFFFF) | (((long)z & 0x7FFFFFF) << 27) | ((long)y << 54);
++    }
++
++    /**
++     * Returns the x component from the packed value.
++     * @param packed The packed value, as computed by {@link Block#getBlockKey(int, int, int)}
++     * @see Block#getBlockKey(int, int, int)
++     * @return The x component from the packed value.
++     */
++    public static int getBlockKeyX(long packed) {
++        return (int) ((packed << 37) >> 37);
++    }
++
++    /**
++     * Returns the y component from the packed value.
++     * @param packed The packed value, as computed by {@link Block#getBlockKey(int, int, int)}
++     * @see Block#getBlockKey(int, int, int)
++     * @return The y component from the packed value.
++     */
++    public static int getBlockKeyY(long packed) {
++        return (int) (packed >>> 54);
++    }
++
++    /**
++     * Returns the z component from the packed value.
++     * @param packed The packed value, as computed by {@link Block#getBlockKey(int, int, int)}
++     * @see Block#getBlockKey(int, int, int)
++     * @return The z component from the packed value.
++     */
++    public static int getBlockKeyZ(long packed) {
++        return (int) ((packed << 10) >> 37);
 +    }
 +    // Paper End
 +
diff --git a/Spigot-API-Patches/0140-isChunkGenerated-API.patch b/Spigot-API-Patches/0140-isChunkGenerated-API.patch
index e28add102e..5ecdc91d9f 100644
--- a/Spigot-API-Patches/0140-isChunkGenerated-API.patch
+++ b/Spigot-API-Patches/0140-isChunkGenerated-API.patch
@@ -1,11 +1,11 @@
-From e69f6fd86a2a77175c639ee9438deccd46f0f2c5 Mon Sep 17 00:00:00 2001
+From 39f88f102e19e146cd9a008dfc0af879190f3f3a Mon Sep 17 00:00:00 2001
 From: cswhite2000 <[email protected]>
 Date: Tue, 21 Aug 2018 19:39:46 -0700
 Subject: [PATCH] isChunkGenerated API
 
 
 diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java
-index 334e31350..57ce443a5 100644
+index 2719eecb..a90f78d5 100644
 --- a/src/main/java/org/bukkit/Location.java
 +++ b/src/main/java/org/bukkit/Location.java
 @@ -1,5 +1,6 @@
@@ -15,7 +15,7 @@ index 334e31350..57ce443a5 100644
  import java.util.HashMap;
  import java.util.Map;
  
-@@ -519,6 +520,15 @@ public class Location implements Cloneable, ConfigurationSerializable {
+@@ -518,6 +519,15 @@ public class Location implements Cloneable, ConfigurationSerializable {
      public boolean isChunkLoaded() { return world.isChunkLoaded(locToBlock(x) >> 4, locToBlock(z) >> 4); } // Paper
  
      // Paper start
@@ -32,10 +32,10 @@ index 334e31350..57ce443a5 100644
      /**
       * Sets the position of this Location and returns itself
 diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
-index 158917492..6b91635fe 100644
+index fa736b07..38dae649 100644
 --- a/src/main/java/org/bukkit/World.java
 +++ b/src/main/java/org/bukkit/World.java
-@@ -197,6 +197,17 @@ public interface World extends PluginMessageRecipient, Metadatable {
+@@ -196,6 +196,17 @@ public interface World extends PluginMessageRecipient, Metadatable {
          return getChunkAt((int) chunkKey, (int) (chunkKey >> 32));
      }
  
diff --git a/Spigot-API-Patches/0159-Add-sun-related-API.patch b/Spigot-API-Patches/0159-Add-sun-related-API.patch
index 990987d79e..172194fe0f 100644
--- a/Spigot-API-Patches/0159-Add-sun-related-API.patch
+++ b/Spigot-API-Patches/0159-Add-sun-related-API.patch
@@ -1,14 +1,14 @@
-From 379c946835805584f3916a588cc3f4ab0fd39eb1 Mon Sep 17 00:00:00 2001
+From 7401b4dc7ba58b3d5d00428a19bc05f18a3e74c5 Mon Sep 17 00:00:00 2001
 From: BillyGalbreath <[email protected]>
 Date: Sun, 7 Oct 2018 00:54:15 -0500
 Subject: [PATCH] Add sun related API
 
 
 diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
-index 6b91635f..3d8ff98a 100644
+index 38dae649..107f4173 100644
 --- a/src/main/java/org/bukkit/World.java
 +++ b/src/main/java/org/bukkit/World.java
-@@ -1518,6 +1518,16 @@ public interface World extends PluginMessageRecipient, Metadatable {
+@@ -1517,6 +1517,16 @@ public interface World extends PluginMessageRecipient, Metadatable {
       */
      public void setFullTime(long time);
  
@@ -44,5 +44,5 @@ index afdc103f..784db447 100644
  
      /**
 -- 
-2.17.1
+2.21.0
 
diff --git a/Spigot-API-Patches/0179-Flip-some-Spigot-API-null-annotations.patch b/Spigot-API-Patches/0179-Flip-some-Spigot-API-null-annotations.patch
index ff1f88bd89..e0cef6db18 100644
--- a/Spigot-API-Patches/0179-Flip-some-Spigot-API-null-annotations.patch
+++ b/Spigot-API-Patches/0179-Flip-some-Spigot-API-null-annotations.patch
@@ -1,4 +1,4 @@
-From 15f50823f87c276744bb804694914c8164e4a708 Mon Sep 17 00:00:00 2001
+From 33fb1bc679558ecf173b799fc670e6660e6dc32a Mon Sep 17 00:00:00 2001
 From: Aikar <[email protected]>
 Date: Sun, 24 Mar 2019 18:39:01 -0400
 Subject: [PATCH] Flip some Spigot API null annotations
@@ -9,7 +9,7 @@ a ton of noise to plugin developers.
 These do not help plugin developers if they bring moise noise than value.
 
 diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
-index 6b0a09067..5ed9726c8 100644
+index 6b0a0906..5ed9726c 100644
 --- a/src/main/java/org/bukkit/Bukkit.java
 +++ b/src/main/java/org/bukkit/Bukkit.java
 @@ -1183,7 +1183,7 @@ public final class Bukkit {
@@ -31,10 +31,10 @@ index 6b0a09067..5ed9726c8 100644
          return server.getTag(registry, tag, clazz);
      }
 diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java
-index 57ce443a5..fcb9059d5 100644
+index a90f78d5..8352b77c 100644
 --- a/src/main/java/org/bukkit/Location.java
 +++ b/src/main/java/org/bukkit/Location.java
-@@ -45,7 +45,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
+@@ -44,7 +44,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
       * @param y The y-coordinate of this new location
       * @param z The z-coordinate of this new location
       */
@@ -43,7 +43,7 @@ index 57ce443a5..fcb9059d5 100644
          this(world, x, y, z, 0, 0);
      }
  
-@@ -59,7 +59,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
+@@ -58,7 +58,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
       * @param yaw The absolute rotation on the x-plane, in degrees
       * @param pitch The absolute rotation on the y-plane, in degrees
       */
@@ -52,7 +52,7 @@ index 57ce443a5..fcb9059d5 100644
          this.world = world;
          this.x = x;
          this.y = y;
-@@ -82,7 +82,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
+@@ -81,7 +81,7 @@ public class Location implements Cloneable, ConfigurationSerializable {
       *
       * @return World that contains this location
       */
@@ -62,7 +62,7 @@ index 57ce443a5..fcb9059d5 100644
          return world;
      }
 diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
-index 66d22ba79..eb23417b7 100644
+index 66d22ba7..eb23417b 100644
 --- a/src/main/java/org/bukkit/Server.java
 +++ b/src/main/java/org/bukkit/Server.java
 @@ -988,7 +988,7 @@ public interface Server extends PluginMessageRecipient {
@@ -84,7 +84,7 @@ index 66d22ba79..eb23417b7 100644
  
      /**
 diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java
-index dca77bbaf..56734f8ee 100644
+index dca77bba..56734f8e 100644
 --- a/src/main/java/org/bukkit/inventory/ItemFactory.java
 +++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
 @@ -3,6 +3,7 @@ package org.bukkit.inventory;
@@ -105,7 +105,7 @@ index dca77bbaf..56734f8ee 100644
  
      /**
 diff --git a/src/main/java/org/bukkit/inventory/ItemStack.java b/src/main/java/org/bukkit/inventory/ItemStack.java
-index 1b19f8215..1d3b0a312 100644
+index 1b19f821..1d3b0a31 100644
 --- a/src/main/java/org/bukkit/inventory/ItemStack.java
 +++ b/src/main/java/org/bukkit/inventory/ItemStack.java
 @@ -9,6 +9,7 @@ import java.util.Set;