API v4

api/build.gradle.kts

@@ -21,12 +21,15 @@ repositories {
     maven("https://maven.enginehub.org/repo/")
     maven("https://repo.papermc.io/repository/maven-public/")
     maven("https://repo.thenextlvl.net/releases")
+    maven("https://repo.thenextlvl.net/snapshots")
 }
 
 dependencies {
     compileOnly("com.fastasyncworldedit:FastAsyncWorldEdit-Core")
     compileOnly("com.fastasyncworldedit:FastAsyncWorldEdit-Bukkit") { isTransitive = false }
     compileOnly("io.papermc.paper:paper-api:1.21.8-R0.1-SNAPSHOT")
+
+    compileOnly("net.thenextlvl.core:paper:2.3.0-pre1")
 
     implementation("net.thenextlvl.core:nbt:2.3.2")
     implementation("net.thenextlvl.core:files:3.0.0")

api/src/main/java/net/thenextlvl/protect/flag/Flag.java

@@ -1,34 +1,73 @@
 package net.thenextlvl.protect.flag;
 
+import com.google.common.base.Preconditions;
+import com.mojang.brigadier.arguments.ArgumentType;
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.Keyed;
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 
-/**
- * Represents a flag with a specific value type.
- *
- * @param <T> The type of the flag value.
- */
-public interface Flag<T> extends Comparable<@NonNull Flag<?>> {
-    /**
-     * Retrieves the {@link Key} associated with this flag.
-     *
-     * @return the Key of the flag
-     */
-    @NonNull
-    Key key();
-
-    /**
-     * Retrieves the type of the flag value.
-     *
-     * @return the type of the flag value
-     */
-    @NonNull
-    Class<? extends T> type();
-
-    /**
-     * Retrieves the default value for a flag.
-     *
-     * @return The default value for the flag.
-     */
-    T defaultValue();
+public abstract class Flag<T> implements Keyed, Comparable<@NonNull Flag<?>> {
+    private final @NonNull Key key;
+    private final T defaultValue;
+    private final T protectedValue;
+    private final boolean nullable;
+
+    protected Flag(@NonNull Key key, @Nullable T defaultValue, @Nullable T protectedValue, boolean nullable) {
+        Preconditions.checkArgument(nullable || defaultValue != null, "Default value must be non-null if flag is not nullable");
+        this.key = key;
+        this.defaultValue = defaultValue;
+        this.protectedValue = protectedValue;
+        this.nullable = nullable;
+    }
+
+    protected Flag(@NonNull Key key, @NonNull T defaultValue, @Nullable T protectedValue) {
+        this(key, defaultValue, protectedValue, false);
+    }
+
+    protected Flag(@NonNull Key key, @Nullable T defaultValue, boolean nullable) {
+        this(key, defaultValue, null, nullable);
+    }
+
+    protected Flag(@NonNull Key key, @NonNull T defaultValue) {
+        this(key, defaultValue, null, false);
+    }
+
+    protected Flag(@NonNull Key key) {
+        this(key, null, true);
+    }
+
+    @Contract(pure = true)
+    public abstract @NonNull Class<T> getValueType();
+
+    @Contract(value = " -> new", pure = true)
+    public abstract @NonNull ArgumentType<T> getArgumentType();
+
+    @Override
+    @Contract(pure = true)
+    public @NonNull Key key() {
+        return key;
+    }
+
+    @Contract(pure = true)
+    public T getDefaultValue() {
+        return defaultValue;
+    }
+
+    @Contract(pure = true)
+    public T getProtectedValue() {
+        return protectedValue;
+    }
+
+    @Contract(pure = true)
+    public boolean isNullable() {
+        return nullable;
+    }
+
+    @Override
+    @Contract(pure = true)
+    public int compareTo(@NonNull Flag<?> flag) {
+        return key.compareTo(flag.key());
+    }
 }

api/src/main/java/net/thenextlvl/protect/flag/FlagRegistry.java

@@ -1,10 +1,11 @@
 package net.thenextlvl.protect.flag;
 
 import net.kyori.adventure.key.Key;
-import net.kyori.adventure.key.KeyPattern;
 import org.bukkit.plugin.Plugin;
+import org.bukkit.plugin.java.JavaPlugin;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Unmodifiable;
 import org.jspecify.annotations.NonNull;
-import org.jspecify.annotations.NullMarked;
 
 import java.util.Optional;
 import java.util.Set;
@@ -13,118 +14,61 @@
  * FlagRegistry is an interface that provides methods for managing registered flags.
  */
 public interface FlagRegistry {
+    @NonNull
+    @Unmodifiable
+    @Contract(pure = true)
+    Set<@NonNull Flag<?>> getFlags();
 
-    /**
-     * Retrieves the set of flags associated with this FlagRegistry.
-     *
-     * @return a Set of flags associated with the FlagRegistry
-     */
-    @NullMarked
-    Set<Flag<?>> getFlags();
+    @NonNull
+    @Unmodifiable
+    @Contract(pure = true)
+    Set<@NonNull Flag<?>> getFlags(Plugin plugin);
 
     /**
-     * Retrieves the set of flags associated with the given plugin.
+     * Retrieves the flag associated with the given key.
      *
-     * @param plugin the plugin for which to retrieve the flags
-     * @return a set of flags associated with the plugin
+     * @param key the key of the flag to retrieve
+     * @param <T> the type of the flag
+     * @return an {@code Optional} containing the flag, or empty if no flag was found
      */
-    @NullMarked
-    Set<Flag<?>> getFlags(Plugin plugin);
+    @Contract(pure = true)
+    <T extends Flag<?>> @NonNull Optional<@NonNull T> getFlag(Key key);
 
     /**
-     * Retrieves the flag associated with the given Key.
+     * Registers a new flag with the specified plugin.
      *
-     * @param key the Key of the flag to retrieve
-     * @param <T> the type of the flag value
-     * @return an Optional containing the flag, or an empty Optional if no flag was found
+     * @param plugin the plugin registering the flag
+     * @return {@code true} if the flag was registered, {@code false} otherwise
      */
-    @NullMarked
-    <T> Optional<Flag<T>> getFlag(Key key);
+    boolean register(@NonNull Plugin plugin, @NonNull Flag<?> flag);
 
-    /**
-     * Registers a new flag with the specified plugin, name, and default value.
-     *
-     * @param <T>          the type of the flag value
-     * @param plugin       the plugin registering the flag
-     * @param name         the name of the flag
-     * @param defaultValue the default value of the flag
-     * @return the registered flag
-     * @throws IllegalStateException if a flag by the same plugin with the same name is already registered
-     * @see #register(Plugin, Class, String, Object)
-     */
-    @NullMarked
-    @SuppressWarnings("unchecked")
-    default <T> Flag<T> register(Plugin plugin, @KeyPattern.Value String name, T defaultValue) throws IllegalStateException {
-        return register(plugin, (Class<T>) defaultValue.getClass(), name, defaultValue);
+    default boolean register(@NonNull Flag<?> flag) {
+        return register(JavaPlugin.getProvidingPlugin(flag.getClass()), flag);
     }
 
     /**
-     * Registers a new flag with the specified plugin, type, name, and default value.
-     *
-     * @param <T>          the type of the flag value
-     * @param plugin       the plugin registering the flag
-     * @param type         the class type of the flag value
-     * @param name         the name of the flag
-     * @param defaultValue the default value of the flag
-     * @return the registered flag
-     * @throws IllegalStateException if a flag by the same plugin with the same name is already registered
-     */
-    <T> @NonNull Flag<T> register(@NonNull Plugin plugin, @NonNull Class<? extends T> type,
-                                  @KeyPattern.Value String name, T defaultValue
-    ) throws IllegalStateException;
-
-    /**
-     * Registers a new protection flag with the specified plugin, name, default value, and protected value.
+     * Unregisters the given flag.
      *
-     * @param <T>            the type of the flag value
-     * @param plugin         the plugin registering the flag
-     * @param name           the name of the flag
-     * @param defaultValue   the default value of the flag
-     * @param protectedValue the protected value of the flag, which is typically opposite to the default value
-     * @return the registered protection flag
-     * @throws IllegalStateException if a flag by the same plugin with the same name is already registered
-     * @see #register(Plugin, Class, String, Object, Object)
+     * @param flag the flag to unregister
+     * @return {@code true} if the flag was unregistered, {@code false} otherwise
      */
-    @NullMarked
-    @SuppressWarnings("unchecked")
-    default <T> ProtectionFlag<T> register(Plugin plugin, @KeyPattern.Value String name, T defaultValue, T protectedValue) throws IllegalStateException {
-        return register(plugin, (Class<T>) defaultValue.getClass(), name, defaultValue, protectedValue);
+    default boolean unregister(@NonNull Flag<?> flag) {
+        return unregister(flag.key());
     }
 
     /**
-     * Registers a new protection flag with the specified plugin, name, default value, and protected value.
-     * <p>
-     * protectedValue defines (generally the opposite of defaultValue) what the flag value is to protect against it,
-     * for example, taking the flag 'explosions', protectedValue would be false and defaultValue true
-     * <p>
-     * {@code var explosions = register(plugin, Boolean.class, "explosions", true, false);}
-     *
-     * @param <T>            the type of the flag value
-     * @param plugin         the plugin registering the flag
-     * @param type           the class type of the flag value
-     * @param name           the name of the flag
-     * @param defaultValue   the default value of the flag
-     * @param protectedValue the protected value of the flag, which is typically opposite to the default value
-     * @return the registered protection flag
-     * @throws IllegalStateException if a flag by the same plugin with the same name is already registered
-     */
-    <T> @NonNull ProtectionFlag<T> register(@NonNull Plugin plugin, @NonNull Class<? extends T> type,
-                                            @KeyPattern.Value @NonNull String name, T defaultValue, T protectedValue
-    ) throws IllegalStateException;
-
-    /**
-     * Unregisters a flag identified by the given Key.
+     * Unregisters the flag by the given key.
      *
-     * @param flag the Key of the flag to unregister
-     * @return true if the flag was unregistered, false otherwise
+     * @param key the key of the flag to unregister
+     * @return {@code true} if the flag was unregistered, {@code false} otherwise
      */
-    boolean unregister(@NonNull Key flag);
+    boolean unregister(@NonNull Key key);
 
     /**
      * Unregisters all flags associated with the specified plugin.
      *
      * @param plugin the plugin for which to unregister flags
-     * @return true if any flag was unregistered, false otherwise
+     * @return {@code true} if any flag was unregistered, {@code false} otherwise
      */
     boolean unregisterAll(@NonNull Plugin plugin);
 }

api/src/main/java/net/thenextlvl/protect/flag/collection/CollectionFlag.java

@@ -0,0 +1,18 @@
+package net.thenextlvl.protect.flag.collection;
+
+import net.kyori.adventure.key.Key;
+import net.thenextlvl.protect.flag.Flag;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Collection;
+
+public abstract class CollectionFlag<E, T extends Collection<E>> extends Flag<T> {
+    protected CollectionFlag(@NonNull Key key, @NonNull T defaultValue, @Nullable T protectedValue) {
+        super(key, defaultValue, protectedValue, false);
+    }
+
+    protected CollectionFlag(@NonNull Key key, @NonNull T defaultValue) {
+        this(key, defaultValue, null);
+    }
+}

api/src/main/java/net/thenextlvl/protect/flag/collection/ListFlag.java

@@ -0,0 +1,17 @@
+package net.thenextlvl.protect.flag.collection;
+
+import net.kyori.adventure.key.Key;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+import java.util.List;
+
+public abstract class ListFlag<T> extends CollectionFlag<T, List<T>> {
+    public ListFlag(@NonNull Key key, @NonNull List<T> defaultValue, @Nullable List<T> protectedValue) {
+        super(key, defaultValue, protectedValue);
+    }
+
+    public ListFlag(@NonNull Key key, @NonNull List<T> defaultValue) {
+        super(key, defaultValue);
+    }
+}

api/src/main/java/net/thenextlvl/protect/flag/collection/SetFlag.java

@@ -0,0 +1,17 @@
+package net.thenextlvl.protect.flag.collection;
+
+import net.kyori.adventure.key.Key;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Set;
+
+public abstract class SetFlag<T> extends CollectionFlag<T, Set<T>> {
+    public SetFlag(@NonNull Key key, @NonNull Set<T> defaultValue, @Nullable Set<T> protectedValue) {
+        super(key, defaultValue, protectedValue);
+    }
+
+    public SetFlag(@NonNull Key key, @NonNull Set<T> defaultValue) {
+        super(key, defaultValue);
+    }
+}

api/src/main/java/net/thenextlvl/protect/flag/location/LocationFlag.java

@@ -0,0 +1,46 @@
+package net.thenextlvl.protect.flag.location;
+
+import com.mojang.brigadier.arguments.ArgumentType;
+import core.paper.command.WrappedArgumentType;
+import io.papermc.paper.command.brigadier.argument.ArgumentTypes;
+import net.kyori.adventure.key.Key;
+import net.thenextlvl.protect.flag.Flag;
+import org.bukkit.Location;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
+
+public final class LocationFlag extends Flag<Location> {
+    public LocationFlag(@NonNull Key key, @Nullable Location defaultValue, @Nullable Location protectedValue, boolean nullable) {
+        super(key, defaultValue, protectedValue, nullable);
+    }
+
+    public LocationFlag(@NonNull Key key, @NonNull Location defaultValue, @Nullable Location protectedValue) {
+        super(key, defaultValue, protectedValue);
+    }
+
+    public LocationFlag(@NonNull Key key, @Nullable Location defaultValue, boolean nullable) {
+        super(key, defaultValue, nullable);
+    }
+
+    public LocationFlag(@NonNull Key key) {
+        super(key);
+    }
+
+    @Override
+    public @NonNull Class<Location> getValueType() {
+        return Location.class;
+    }
+
+    @Override
+    public @NonNull ArgumentType<Location> getArgumentType() {
+        return new WrappedArgumentType<>(
+                ArgumentTypes.finePosition(),
+                (reader, type) -> {
+                    // var resolver = context.getArgument("value", FinePositionResolver.class);
+                    // var area = context.getArgument("area", Area.class);
+                    // return resolver.resolve(context.getSource()).toLocation(area.getWorld());
+                    return null; // fixme
+                },
+                (context, builder) -> builder.buildFuture());
+    }
+}