diff --git a/src/main/java/net/citizensnpcs/api/ai/tree/Behavior.java b/src/main/java/net/citizensnpcs/api/ai/tree/Behavior.java
index cc53e05d..a4854993 100644
--- a/src/main/java/net/citizensnpcs/api/ai/tree/Behavior.java
+++ b/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 behavior tree, 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
+ * executing nodes which are transitioned between using the {@link BehaviorStatus} they return.
+ *
+ * New child nodes are selected to become executing nodes 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 https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control)
@@ -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 once 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();
}
diff --git a/src/main/java/net/citizensnpcs/api/ai/tree/StatusCoercer.java b/src/main/java/net/citizensnpcs/api/ai/tree/StatusMapper.java
similarity index 64%
rename from src/main/java/net/citizensnpcs/api/ai/tree/StatusCoercer.java
rename to src/main/java/net/citizensnpcs/api/ai/tree/StatusMapper.java
index a9a7c835..72ccac35 100644
--- a/src/main/java/net/citizensnpcs/api/ai/tree/StatusCoercer.java
+++ b/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 to;
private final Behavior wrapping;
- private StatusCoercer(Behavior wrapping, Supplier to) {
+ private StatusMapper(Behavior wrapping, Supplier to) {
this.wrapping = wrapping;
this.to = to;
}
@@ -29,7 +29,7 @@ public boolean shouldExecute() {
return wrapping.shouldExecute();
}
- public static StatusCoercer coercing(Behavior wrapping, Supplier to) {
- return new StatusCoercer(wrapping, to);
+ public static StatusMapper mapping(Behavior wrapping, Supplier to) {
+ return new StatusMapper(wrapping, to);
}
}
diff --git a/src/main/java/net/citizensnpcs/api/npc/NPC.java b/src/main/java/net/citizensnpcs/api/npc/NPC.java
index 6a697bcf..f4cc765c 100644
--- a/src/main/java/net/citizensnpcs/api/npc/NPC.java
+++ b/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.
*/