Added EmptyTestableEntity (dummy entities) for failed TestableEntity lookups

eco-api/src/main/java/com/willfp/eco/core/Handler.java

@@ -18,6 +18,8 @@ import com.willfp.eco.core.proxy.ProxyFactory;
 import com.willfp.eco.core.requirement.RequirementFactory;
 import com.willfp.eco.core.scheduling.Scheduler;
 import net.kyori.adventure.platform.bukkit.BukkitAudiences;
+import org.bukkit.Location;
+import org.bukkit.entity.Entity;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
@@ -232,4 +234,13 @@ public interface Handler {
      */
     @NotNull
     PlayerProfileHandler getPlayerProfileHandler();
+
+    /**
+     * Create dummy entity - never spawned, exists purely in code.
+     *
+     * @param location The location.
+     * @return The entity.
+     */
+    @NotNull
+    Entity createDummyEntity(@NotNull Location location);
 }

eco-api/src/main/java/com/willfp/eco/core/entities/Entities.java

@@ -2,6 +2,7 @@ package com.willfp.eco.core.entities;
 
 import com.willfp.eco.core.entities.args.EntityArgParseResult;
 import com.willfp.eco.core.entities.args.EntityArgParser;
+import com.willfp.eco.core.entities.impl.EmptyTestableEntity;
 import com.willfp.eco.core.entities.impl.ModifiedTestableEntity;
 import com.willfp.eco.core.entities.impl.SimpleTestableEntity;
 import com.willfp.eco.util.NamespacedKeyUtils;
@@ -80,31 +81,28 @@ public final class Entities {
      * much more power and flexibility. For example, you can have an entity with an
      * extra metadata tag, extra lore lines, different display name - and it
      * will still work as long as the test passes.
-     * <p>
-     * Unlike {@link com.willfp.eco.core.items.Items#lookup(String)}, this can return
-     * null as there is no empty entity equivalent.
      *
      * @param key The lookup string.
-     * @return The testable entity, or null if not found.
+     * @return The testable entity, or an empty testable entity if not found.
      */
-    @Nullable
+    @NotNull
     public static TestableEntity lookup(@NotNull final String key) {
         if (key.contains("?")) {
             String[] options = key.split("\\?");
             for (String option : options) {
                 TestableEntity lookup = lookup(option);
-                if (lookup != null) {
+                if (!(lookup instanceof EmptyTestableEntity)) {
                     return lookup;
                 }
             }
 
-            return null;
+            return new EmptyTestableEntity();
         }
 
         String[] args = StringUtils.parseTokens(key);
 
         if (args.length == 0) {
-            return null;
+            return new EmptyTestableEntity();
         }
 
         TestableEntity entity;
@@ -116,7 +114,7 @@ public final class Entities {
             try {
                 type = EntityType.valueOf(args[0].toUpperCase());
             } catch (IllegalArgumentException e) {
-                return null;
+                return new EmptyTestableEntity();
             }
             entity = new SimpleTestableEntity(type);
         } else {
@@ -127,7 +125,7 @@ public final class Entities {
             TestableEntity part = REGISTRY.get(namespacedKey);
 
             if (part == null) {
-                return null;
+                return new EmptyTestableEntity();
             }
 
             entity = part;

eco-api/src/main/java/com/willfp/eco/core/entities/impl/EmptyTestableEntity.java

@@ -0,0 +1,33 @@
+package com.willfp.eco.core.entities.impl;
+
+import com.willfp.eco.core.Eco;
+import com.willfp.eco.core.entities.TestableEntity;
+import org.apache.commons.lang3.Validate;
+import org.bukkit.Location;
+import org.bukkit.entity.Entity;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Empty entity.
+ */
+public class EmptyTestableEntity implements TestableEntity {
+    /**
+     * Create a new empty testable entity.
+     */
+    public EmptyTestableEntity() {
+
+    }
+
+    @Override
+    public boolean matches(@Nullable final Entity entity) {
+        return false;
+    }
+
+    @Override
+    public Entity spawn(@NotNull final Location location) {
+        Validate.notNull(location.getWorld());
+
+        return Eco.getHandler().createDummyEntity(location);
+    }
+}

eco-api/src/main/java/com/willfp/eco/core/entities/impl/ModifiedTestableEntity.java

@@ -46,12 +46,6 @@ public class ModifiedTestableEntity implements TestableEntity {
         this.provider = provider;
     }
 
-    /**
-     * If the entity matches the test.
-     *
-     * @param entity The entity to test.
-     * @return If the entity matches the test.
-     */
     @Override
     public boolean matches(@Nullable final Entity entity) {
         return entity != null && handle.matches(entity) && test.test(entity);

eco-api/src/main/java/com/willfp/eco/core/entities/impl/SimpleTestableEntity.java

@@ -28,12 +28,6 @@ public class SimpleTestableEntity implements TestableEntity {
         Validate.notNull(type.getEntityClass(), "Entity cannot be of unknown type!");
     }
 
-    /**
-     * If the entity matches the type.
-     *
-     * @param entity The entity to test.
-     * @return If the entity is of the specified type.
-     */
     @Override
     public boolean matches(@Nullable final Entity entity) {
         return entity != null && entity.getType() == type;