Fully use ability namespaces and api changes

Author: PrimordialMoros

api/src/main/java/me/moros/bending/api/ability/AbilityDescription.java

@@ -26,50 +26,50 @@
 import java.util.Locale;
 import java.util.Objects;
 import java.util.function.Function;
+import java.util.function.UnaryOperator;
 
 import me.moros.bending.api.ability.element.Element;
+import me.moros.bending.api.util.KeyUtil;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.Keyed;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.TextComponent;
 import net.kyori.adventure.text.event.ClickEvent;
 import net.kyori.adventure.translation.Translatable;
-import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * AbilityDescription is immutable and thread-safe.
  * Assume that all collections returning AbilityDescription are also immutable
  */
 public sealed class AbilityDescription implements Keyed, Translatable permits AbilityDescription.Sequence {
-  public static final String NAMESPACE = "bending.ability";
-
   private final Key key;
   private final String name;
-  private final Function<AbilityDescription, ? extends Ability> constructor;
   private final Element element;
+  private final Component displayName;
+  private final Function<AbilityDescription, ? extends Ability> constructor;
   private final EnumSet<Activation> activations;
   private final Collection<String> requiredPermissions;
-  private final Component displayName;
   private final boolean canBind;
   private final boolean hidden;
   private final boolean bypassCooldown;
   private final int hashcode;
 
   private AbilityDescription(Builder builder) {
+    key = builder.key;
     name = builder.name;
-    constructor = builder.constructor;
     element = builder.element;
+    displayName = Component.text(name, element.color());
+    constructor = builder.constructor;
     activations = builder.activations;
     requiredPermissions = List.copyOf(builder.requiredPermissions);
     canBind = builder.canBind && !isActivatedBy(Activation.SEQUENCE);
     hidden = builder.hidden;
     bypassCooldown = builder.bypassCooldown;
-    displayName = Component.text(name, element.color());
-    hashcode = Objects.hash(name, element, activations);
-    key = Key.key(NAMESPACE, name.toLowerCase(Locale.ROOT));
+    hashcode = Objects.hash(key, element, activations);
   }
 
+  @Deprecated(forRemoval = true)
   public String name() {
     return name;
   }
@@ -106,28 +106,32 @@ public Collection<String> permissions() {
     return requiredPermissions;
   }
 
+  @Deprecated(forRemoval = true)
   public Component meta() {
-    return displayName().clickEvent(ClickEvent.runCommand("/bending help " + name()));
+    return displayName().clickEvent(ClickEvent.runCommand("/bending help " + key().asString()));
   }
 
   @Override
-  public @NonNull Key key() {
+  public Key key() {
     return key;
   }
 
   @Override
-  public @NonNull String translationKey() {
-    return NAMESPACE + "." + key().value();
+  public String translationKey() {
+    return key().namespace() + ".ability." + key().value();
   }
 
+  @Deprecated(forRemoval = true)
   public String descriptionKey() {
     return translationKey() + ".description";
   }
 
+  @Deprecated(forRemoval = true)
   public String instructionsKey() {
     return translationKey() + ".instructions";
   }
 
+  @Deprecated(forRemoval = true)
   public String deathKey() {
     return translationKey() + ".death";
   }
@@ -141,7 +145,7 @@ public boolean equals(Object obj) {
       return false;
     }
     AbilityDescription other = (AbilityDescription) obj;
-    return name.equals(other.name) && element == other.element && activations.equals(other.activations);
+    return key.equals(other.key) && element == other.element && activations.equals(other.activations);
   }
 
   @Override
@@ -150,18 +154,29 @@ public int hashCode() {
   }
 
   public static <T extends Ability> Builder builder(String name, Function<AbilityDescription, T> constructor) {
+    return builder(KeyUtil.BENDING_NAMESPACE, name, constructor);
+  }
+
+  public static <T extends Ability> Builder builder(String namespace, String name, Function<AbilityDescription, T> constructor) {
+    Objects.requireNonNull(namespace);
     Objects.requireNonNull(name);
     Objects.requireNonNull(constructor);
-    if (name.isEmpty()) {
-      throw new IllegalArgumentException("Ability name cannot be empty!");
+    if (namespace.isEmpty()) {
+      namespace = KeyUtil.BENDING_NAMESPACE;
+    }
+    boolean validName = name.chars().allMatch(c -> (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'));
+    if (name.isEmpty() || !validName) {
+      throw new IllegalArgumentException("Name must be an alphabetical non-empty string!");
     }
-    return new Builder(name, constructor);
+    return new Builder(namespace, name, constructor);
   }
 
   /**
    * Immutable and thread-safe representation of a sequence
    */
   public static final class Sequence extends AbilityDescription {
+    public static final int MAX_STEPS = 16;
+
     private final List<SequenceStep> steps;
     private Component instructions;
 
@@ -204,11 +219,11 @@ private Component generateInstructions() {
           // Check if the next instruction is to release sneak.
           SequenceStep next = steps.get(i + 1);
           if (desc.equals(next.ability()) && next.activation() == Activation.SNEAK_RELEASE) {
-            key = Activation.NAMESPACE + ".sneak-tap";
+            key = "bending.activation.sneak-tap";
             i++;
           }
         }
-        builder.append(Component.text(desc.name())).append(Component.text(" ("))
+        builder.append(desc.displayName()).append(Component.text(" ("))
           .append(Component.translatable(key)).append(Component.text(")"));
       }
       return builder.build();
@@ -241,19 +256,21 @@ public boolean matches(List<SequenceStep> otherSteps) {
    * Builder to create {@link AbilityDescription}.
    */
   public static final class Builder {
+    private final Key key;
     private final String name;
-    private final Function<AbilityDescription, ? extends Ability> constructor;
     private Element element;
+    private final Function<AbilityDescription, ? extends Ability> constructor;
     private EnumSet<Activation> activations;
     private Collection<String> requiredPermissions;
     private boolean canBind = true;
     private boolean hidden = false;
     private boolean bypassCooldown = false;
 
-    private <T extends Ability> Builder(String name, Function<AbilityDescription, T> constructor) {
+    private <T extends Ability> Builder(String namespace, String name, Function<AbilityDescription, T> constructor) {
+      this.key = Key.key(namespace, name.toLowerCase(Locale.ROOT));
       this.name = name;
       this.constructor = constructor;
-      this.requiredPermissions = List.of(AbilityDescription.NAMESPACE + "." + name);
+      this.requiredPermissions = List.of(defaultPermission());
     }
 
     public Builder element(Element element) {
@@ -273,7 +290,7 @@ public Builder activation(Activation method, Activation @Nullable ... methods) {
 
     public Builder require(String @Nullable ... permissions) {
       Collection<String> c = new ArrayList<>();
-      c.add(AbilityDescription.NAMESPACE + "." + name);
+      c.add(defaultPermission());
       if (permissions != null) {
         c.addAll(List.of(permissions));
       }
@@ -304,6 +321,19 @@ public AbilityDescription build() {
       return new AbilityDescription(this);
     }
 
+    public Sequence buildSequence(UnaryOperator<SequenceBuilder> function) {
+      validate();
+      if (!activations.contains(Activation.SEQUENCE)) {
+        throw new IllegalStateException("Ability must be activated by sequence");
+      }
+      List<SequenceStep> sequenceSteps = function.apply(new SequenceBuilder()).validateAndBuild();
+      return new Sequence(this, sequenceSteps);
+    }
+
+    /**
+     * @deprecated use {@link #buildSequence(UnaryOperator)} instead
+     */
+    @Deprecated(forRemoval = true)
     public Sequence buildSequence(SequenceStep step1, SequenceStep step2, SequenceStep @Nullable ... steps) {
       validate();
       if (!activations.contains(Activation.SEQUENCE)) {
@@ -325,5 +355,9 @@ private void validate() {
         throw new IllegalStateException("Activation methods cannot be empty");
       }
     }
+
+    private String defaultPermission() {
+      return "bending.ability." + key.value();
+    }
   }
 }

api/src/main/java/me/moros/bending/api/ability/Activation.java

@@ -19,15 +19,14 @@
 
 package me.moros.bending.api.ability;
 
+import me.moros.bending.api.util.KeyUtil;
 import net.kyori.adventure.key.Key;
-import net.kyori.adventure.key.Keyed;
 import net.kyori.adventure.translation.Translatable;
-import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
  * Represents a type of ability activation.
  */
-public enum Activation implements Keyed, Translatable {
+public enum Activation implements Translatable {
   /**
    * Passive abilities are always active.
    */
@@ -68,18 +67,11 @@ public enum Activation implements Keyed, Translatable {
   private final Key key;
 
   Activation(String value) {
-    this.key = Key.key(NAMESPACE, value);
+    this.key = KeyUtil.simple("activation." + value);
   }
 
   @Override
-  public @NonNull Key key() {
-    return key;
+  public String translationKey() {
+    return KeyUtil.concat(key);
   }
-
-  @Override
-  public @NonNull String translationKey() {
-    return NAMESPACE + "." + key().value();
-  }
-
-  public static final String NAMESPACE = "bending.activation";
 }

api/src/main/java/me/moros/bending/api/ability/SequenceBuilder.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2020-2024 Moros
+ *
+ * This file is part of Bending.
+ *
+ * Bending is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Bending is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Bending. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package me.moros.bending.api.ability;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+import me.moros.bending.api.ability.AbilityDescription.Sequence;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * Utility to link multiple {@link SequenceStep}.
+ */
+public final class SequenceBuilder {
+  private final List<SequenceStep> steps;
+
+  SequenceBuilder() {
+    this.steps = new ArrayList<>();
+  }
+
+  public SequenceBuilder add(AbilityDescription ability, Activation activation) {
+    Objects.requireNonNull(ability);
+    Objects.requireNonNull(activation);
+    if (steps.size() > Sequence.MAX_STEPS) {
+      throw new IllegalStateException("Cannot add more than %d steps!".formatted(Sequence.MAX_STEPS));
+    }
+    if (!ability.canBind()) {
+      throw new IllegalArgumentException("%s cannot be used as a sequence activation step!".formatted(ability.key().asString()));
+    }
+    if (activation == Activation.PASSIVE || activation == Activation.SEQUENCE) {
+      throw new IllegalArgumentException("%s cannot be used for sequence activation!".formatted(activation.name()));
+    }
+    this.steps.add(SequenceStep.of(ability, activation));
+    return this;
+  }
+
+  public SequenceBuilder add(AbilityDescription ability, Activation activation, Activation @Nullable ... activations) {
+    add(ability, activation);
+    if (activations != null) {
+      for (Activation temp : activations) {
+        add(ability, temp);
+      }
+    }
+    return this;
+  }
+
+  List<SequenceStep> validateAndBuild() {
+    if (steps.size() < 2) {
+      throw new IllegalStateException("Sequences require at least 2 activation steps!");
+    }
+    return List.copyOf(steps);
+  }
+}

api/src/main/java/me/moros/bending/api/ability/SequenceStep.java

@@ -23,4 +23,16 @@
  * Pair representation of {@link AbilityDescription} and {@link Activation}.
  */
 public record SequenceStep(AbilityDescription ability, Activation activation) {
+  /**
+   * @deprecated use {@link #of(AbilityDescription, Activation)} instead
+   */
+  @Deprecated(forRemoval = true)
+  public SequenceStep(AbilityDescription ability, Activation activation) {
+    this.ability = ability;
+    this.activation = activation;
+  }
+
+  public static SequenceStep of(AbilityDescription ability, Activation activation) {
+    return new SequenceStep(ability, activation);
+  }
 }

api/src/main/java/me/moros/bending/api/ability/element/Element.java

@@ -23,12 +23,12 @@
 import java.util.Locale;
 
 import me.moros.bending.api.util.ColorPalette;
+import me.moros.bending.api.util.KeyUtil;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.Keyed;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.format.TextColor;
 import net.kyori.adventure.translation.Translatable;
-import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
@@ -47,7 +47,7 @@ public enum Element implements Keyed, Translatable {
   Element(String elementName, TextColor color) {
     this.elementName = elementName;
     this.color = color;
-    this.key = Key.key(NAMESPACE, elementName.toLowerCase(Locale.ROOT));
+    this.key = KeyUtil.simple("element." + elementName.toLowerCase(Locale.ROOT));
   }
 
   @Override
@@ -56,13 +56,13 @@ public String toString() {
   }
 
   @Override
-  public @NonNull Key key() {
+  public Key key() {
     return key;
   }
 
   @Override
-  public @NonNull String translationKey() {
-    return NAMESPACE + "." + key().value();
+  public String translationKey() {
+    return KeyUtil.concat(key);
   }
 
   /**
@@ -106,7 +106,6 @@ public TextColor color() {
     return null;
   }
 
-  public static final String NAMESPACE = "bending.element";
   public static final List<Element> VALUES = List.of(values());
   public static final List<String> NAMES = List.of("Air", "Water", "Earth", "Fire");
 }