SPIGOT-4833: Allow access to LivingEntity memories

By: Yannick Lamprecht <yannicklamprecht@live.de>

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -9,6 +9,7 @@ import org.bukkit.Material;
 import org.bukkit.World;
 import org.bukkit.attribute.Attributable;
 import org.bukkit.block.Block;
+import org.bukkit.entity.memory.MemoryKey;
 import org.bukkit.inventory.EntityEquipment;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
@@ -474,4 +475,29 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @return collision status
      */
     boolean isCollidable();
+
+    /**
+     * Returns the value of the memory specified.
+     * <p>
+     * Note that the value is null when the specific entity does not have that
+     * value by default.
+     *
+     * @param memoryKey memory to access
+     * @param <T> the type of the return value
+     * @return a instance of the memory section value or null if not present
+     */
+    @Nullable
+    <T> T getMemory(@NotNull MemoryKey<T> memoryKey);
+
+    /**
+     * Sets the value of the memory specified.
+     * <p>
+     * Note that the value will not be persisted when the specific entity does
+     * not have that value by default.
+     *
+     * @param memoryKey the memory to access
+     * @param memoryValue a typed memory value
+     * @param <T> the type of the passed value
+     */
+    <T> void setMemory(@NotNull MemoryKey<T> memoryKey, @Nullable T memoryValue);
 }

paper-api/src/main/java/org/bukkit/entity/memory/MemoryKey.java

@@ -0,0 +1,74 @@
+package org.bukkit.entity.memory;
+
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import org.bukkit.Keyed;
+import org.bukkit.Location;
+import org.bukkit.NamespacedKey;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a key used for accessing memory values of a
+ * {@link org.bukkit.entity.LivingEntity}.
+ *
+ * @param <T> the class type of the memory value
+ */
+public final class MemoryKey<T> implements Keyed {
+
+    private final NamespacedKey namespacedKey;
+    private final Class<T> tClass;
+
+    private MemoryKey(NamespacedKey namespacedKey, Class<T> tClass) {
+        this.namespacedKey = namespacedKey;
+        this.tClass = tClass;
+        MEMORY_KEYS.put(namespacedKey, this);
+    }
+
+    @NotNull
+    @Override
+    public NamespacedKey getKey() {
+        return namespacedKey;
+    }
+
+    /**
+     * Gets the class of values associated with this memory.
+     *
+     * @return the class of value objects
+     */
+    @NotNull
+    public Class<T> getMemoryClass() {
+        return tClass;
+    }
+
+    private static final Map<NamespacedKey, MemoryKey> MEMORY_KEYS = new HashMap<>();
+    //
+    public static final MemoryKey<Location> HOME = new MemoryKey<>(NamespacedKey.minecraft("home"), Location.class);
+    public static final MemoryKey<Location> MEETING_POINT = new MemoryKey<>(NamespacedKey.minecraft("meeting_point"), Location.class);
+    public static final MemoryKey<Location> JOB_SITE = new MemoryKey<>(NamespacedKey.minecraft("job_site"), Location.class);
+
+    /**
+     * Returns a {@link MemoryKey} by a {@link NamespacedKey}.
+     *
+     * @param namespacedKey the {@link NamespacedKey} referencing a
+     * {@link MemoryKey}
+     * @return the {@link MemoryKey} or null when no {@link MemoryKey} is
+     * available under that key
+     */
+    @Nullable
+    public static MemoryKey getByKey(@NotNull NamespacedKey namespacedKey) {
+        return MEMORY_KEYS.get(namespacedKey);
+    }
+
+    /**
+     * Returns the set of all MemoryKeys.
+     *
+     * @return the memoryKeys
+     */
+    @NotNull
+    public static Set<MemoryKey> values() {
+        return new HashSet<>(MEMORY_KEYS.values());
+    }
+}