Add documentation to Behavior, use standard name for StatusCoercer

src/main/java/net/citizensnpcs/api/ai/tree/Behavior.java

@@ -7,11 +7,15 @@
  * {@link BehaviorGoalAdapter}.
  *
  * A behavior is a common term for the parts of a <em>behavior tree</em>, which is a simple directed acyclic graph (DAG)
- * for AI that is easy for designers to use. It is a simple state machine using {@link BehaviorStatus} as the separate
- * states.
+ * for AI. It is a simple state machine using {@link BehaviorStatus}.
  *
- * This can be represented as shouldExecute() returning true -> RUNNING -> FAILURE | SUCCESS. The graph is made up of
- * many {@link Selector}s and {@link Sequence}s, with the leaf nodes being concrete actions.
+ * Nodes are executed in a top-down fashion through the tree. For legacy reasons, the tree is executed as a number of
+ * <em>executing nodes</em> which are transitioned between using the {@link BehaviorStatus} they return.
+ *
+ * New child nodes are selected to become <em>executing nodes</em> based on {@link Behavior#shouldExecute()}. The
+ * selection behavior can vary, e.g. running a list of nodes using {@link Sequence} or choosing from children nodes
+ * using {@link Selector}. The executing nodes are repeatedly {@link Behavior#run()} until the return result changes
+ * from {@link BehaviorStatus#RUNNING}.
  *
  * @see <a href=
  *      "https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control)">https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control)</a>
@@ -23,14 +27,16 @@ public interface Behavior {
     void reset();
 
     /**
-     * Ticks the behavior, optionally changing the state that it is in.
+     * Runs the behavior for one 'tick', optionally changing the state that it is in.
      *
-     * @return The new status
+     * @return The new state
      */
     BehaviorStatus run();
 
     /**
-     * @return Whether the behavior is ready to run
+     * Returns whether the behavior is ready to run. Note this is called <em>once</em> when deciding whether to start
+     * execution of a leaf node. The actual execution status is determined by the return value of {@link Behavior#run()}
+     * which is repeatedly called by the executing node.
      */
     boolean shouldExecute();
 }

src/main/java/net/citizensnpcs/api/ai/tree/StatusCoercer.java → src/main/java/net/citizensnpcs/api/ai/tree/StatusMapper.java

@@ -3,13 +3,13 @@
 import com.google.common.base.Supplier;
 
 /**
- * Wraps an {@link Behavior} and returns a supplied {@link BehaviorStatus} instead of the actual status.
+ * Wraps an {@link Behavior} and returns a supplied {@link BehaviorStatus} instead of the underlying status.
  */
-public class StatusCoercer extends BehaviorGoalAdapter {
+public class StatusMapper extends BehaviorGoalAdapter {
     private final Supplier<BehaviorStatus> to;
     private final Behavior wrapping;
 
-    private StatusCoercer(Behavior wrapping, Supplier<BehaviorStatus> to) {
+    private StatusMapper(Behavior wrapping, Supplier<BehaviorStatus> to) {
         this.wrapping = wrapping;
         this.to = to;
     }
@@ -29,7 +29,7 @@ public boolean shouldExecute() {
         return wrapping.shouldExecute();
     }
 
-    public static StatusCoercer coercing(Behavior wrapping, Supplier<BehaviorStatus> to) {
-        return new StatusCoercer(wrapping, to);
+    public static StatusMapper mapping(Behavior wrapping, Supplier<BehaviorStatus> to) {
+        return new StatusMapper(wrapping, to);
     }
 }

src/main/java/net/citizensnpcs/api/npc/NPC.java

@@ -502,6 +502,14 @@ public enum Metadata {
          * Whether to use Minecraft AI. Boolean.
          */
         USE_MINECRAFT_AI("minecraft-ai"),
+        /**
+         * Whether player is actively using held item. Boolean defaults to false.
+         */
+        USING_HELD_ITEM("using-held-item"),
+        /**
+         * Whether player is actively using offhand item. Boolean defaults to false.
+         */
+        USING_OFFHAND_ITEM("using-offhand-item"),
         /**
          * Whether to block Minecraft villager trades. Boolean defaults to true.
          */