Behavior tree documentation

Bytekeeper · Bytekeeper · commit 1eb3de71c83f · 2020-03-10T22:59:49.000+01:00
diff --git a/src/main/java/org/bk/ass/bt/AcquireLock.java b/src/main/java/org/bk/ass/bt/AcquireLock.java
@@ -2,6 +2,11 @@
 
 import org.bk.ass.manage.Lock;
 
+/**
+ * Leaf node that will succeed if the supplied lock can be acquired. Fails otherwise.
+ *
+ * @param <T> the lock kind
+ */
 public class AcquireLock<T> extends TreeNode {
 
   private final Lock<T> lock;
diff --git a/src/main/java/org/bk/ass/bt/BehaviorTree.java b/src/main/java/org/bk/ass/bt/BehaviorTree.java
@@ -2,10 +2,30 @@
 
 import static java.util.Objects.requireNonNull;
 
+/**
+ * A behavior tree. Main difference to other compound nodes is that the actual root tree node is
+ * constructed on initialization.
+ * <p/>
+ * This allows data oriented programming, with simplified access to some data:
+ * <pre>
+ *   {@code
+ *   public class MyTree extends BehaviorTree {
+ *     // Data shared by nodes of this tree
+ *     private Data myData = new Data(...);
+ *     protected TreeNode getRoot() {
+ *       return new Sequence(new SomeCondition(myData), new Action(myData));
+ *     }
+ *   }
+ *   }
+ * </pre>
+ */
 public abstract class BehaviorTree extends TreeNode {
 
   private TreeNode root;
 
+  /**
+   * Will be called <em>once</em> to create the actual root to be ticked.
+   */
   protected abstract TreeNode getRoot();
 
   @Override
diff --git a/src/main/java/org/bk/ass/bt/CompoundNode.java b/src/main/java/org/bk/ass/bt/CompoundNode.java
@@ -5,7 +5,11 @@
 import java.util.Comparator;
 import java.util.List;
 
+/**
+ * Base class for non-leaf nodes. Usually not subclassed directly.
+ */
 public abstract class CompoundNode extends TreeNode {
+
   protected static final Comparator<TreeNode> UTILITY_COMPARATOR =
       Comparator.comparing(TreeNode::getUtility).reversed();
   protected final List<TreeNode> children;
diff --git a/src/main/java/org/bk/ass/bt/Condition.java b/src/main/java/org/bk/ass/bt/Condition.java
@@ -3,7 +3,11 @@
 import java.util.Objects;
 import java.util.function.BooleanSupplier;
 
+/**
+ * Node that will succeed if the given check passed, fails otherwise.
+ */
 public class Condition extends TreeNode {
+
   private final BooleanSupplier check;
 
   public Condition(BooleanSupplier check) {
diff --git a/src/main/java/org/bk/ass/bt/Decorator.java b/src/main/java/org/bk/ass/bt/Decorator.java
@@ -2,7 +2,11 @@
 
 import java.util.Objects;
 
+/**
+ * Base class for nodes that delegate execution and modify the delegate or the status.
+ */
 public abstract class Decorator extends TreeNode {
+
   private final TreeNode delegate;
 
   public Decorator(TreeNode delegate) {
diff --git a/src/main/java/org/bk/ass/bt/Distributor.java b/src/main/java/org/bk/ass/bt/Distributor.java
@@ -14,6 +14,15 @@
 import org.bk.ass.StopWatch;
 import org.bk.ass.bt.Parallel.Policy;
 
+/**
+ * This is like <code>map</code> for streams. Maps each item of a given list to a node. New nodes
+ * will only be created for new items. Nodes for items that are no longer present will be aborted
+ * and discarded.
+ * <p/>
+ * The created child nodes will be executed in parallel in the order of the item list.
+ *
+ * @param <T> the type of the item used to create new nodes
+ */
 public class Distributor<T> extends TreeNode {
 
   private Policy policy;
diff --git a/src/main/java/org/bk/ass/bt/ExecutionContext.java b/src/main/java/org/bk/ass/bt/ExecutionContext.java
@@ -7,6 +7,9 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Can be used to create tree stack traces and log performance numbers of nodes.
+ */
 public class ExecutionContext {
 
   public static final ExecutionContext NOOP =
diff --git a/src/main/java/org/bk/ass/bt/Inverter.java b/src/main/java/org/bk/ass/bt/Inverter.java
@@ -1,5 +1,9 @@
 package org.bk.ass.bt;
 
+/**
+ * Delegates execution but returns the inverted status (ie. failed -> success; success -> failed;
+ * running -> running).
+ */
 public class Inverter extends Decorator {
 
   public Inverter(TreeNode delegate) {
diff --git a/src/main/java/org/bk/ass/bt/LambdaNode.java b/src/main/java/org/bk/ass/bt/LambdaNode.java
@@ -2,7 +2,11 @@
 
 import java.util.function.Supplier;
 
+/**
+ * Allows inline nodes using lambdas.
+ */
 public class LambdaNode extends TreeNode {
+
   private final Supplier<NodeStatus> delegate;
 
   public LambdaNode(Supplier<NodeStatus> delegate) {
diff --git a/src/main/java/org/bk/ass/bt/Memo.java b/src/main/java/org/bk/ass/bt/Memo.java
@@ -1,5 +1,11 @@
 package org.bk.ass.bt;
 
+/**
+ * Most nodes of <pre>ASS</pre> are reactive (they will execute no matter what the last execution
+ * result was). Using this class, once the delegate reaches a non-running status the result will be
+ * remembered. Further invocations will not change the status and the delegate will not be ticked
+ * again.
+ */
 public class Memo extends Decorator {
 
   public Memo(TreeNode delegate) {
diff --git a/src/main/java/org/bk/ass/bt/NodeStatus.java b/src/main/java/org/bk/ass/bt/NodeStatus.java
@@ -1,18 +1,38 @@
 package org.bk.ass.bt;
 
+/**
+ * Status of a node.
+ */
 public enum NodeStatus {
+  /**
+   * Initial status of a node or a resetted node.
+   */
   INITIAL,
+  /**
+   * Node did not fail, but also has not completed its task yet.
+   */
   RUNNING,
+  /**
+   * Node is done, but can still be ticked and change its status.
+   */
   SUCCESS,
+  /**
+   * Node has failed, but can still be ticked and change its status.
+   */
   FAILURE,
-  /** Child was in state RUNNING but will not be called again due to a parent having completed. */
+  /**
+   * Child was in state RUNNING but will not be ticked again due to a parent having completed.
+   */
   ABORTED {
     @Override
     public TreeNode after(Runnable block) {
       throw new UnsupportedOperationException("Abort should not be used this way.");
     }
   };
 
+  /**
+   * Executes the given code block but will return this NodeStatus' value.
+   */
   public TreeNode after(Runnable block) {
     return new LambdaNode(
         () -> {
diff --git a/src/main/java/org/bk/ass/bt/Parallel.java b/src/main/java/org/bk/ass/bt/Parallel.java
@@ -12,7 +12,13 @@ public class Parallel extends CompoundNode {
   private final Policy policy;
 
   public enum Policy {
+    /**
+     * Run all children in order, stop if one has {@link NodeStatus#FAILURE}
+     */
     SEQUENCE,
+    /**
+     * Run all children in order, stop if one has {@link NodeStatus#SUCCESS}
+     */
     SELECTOR
   }
 
diff --git a/src/main/java/org/bk/ass/bt/Repeat.java b/src/main/java/org/bk/ass/bt/Repeat.java
@@ -2,14 +2,38 @@
 
 import java.util.Objects;
 
+/**
+ * Repeatedly ticks a delegate node. If the delegate completes its operation, it will automatically
+ * be resetted and re-ticked.
+ * <p/>
+ * An internal {@link Policy} is used to determine the status of the Repeat node based on the result
+ * of the delegate.
+ * <p/>
+ * Use {@link Policy#SEQUENCE} to tick a delegate as long as it is succeeding. Use {@link
+ * Policy#SELECTOR} to tick a delegate until it succeeds. Use {@link Policy#SELECTOR_INVERTED} to
+ * tick a delegate until it fails.
+ */
 public class Repeat extends Decorator {
+
   private final int initialLimit;
   private int remaining;
   private final Policy policy;
 
   public enum Policy {
+    /**
+     * Repeat will have status {@link NodeStatus#RUNNING} while the delegate has status {@link
+     * NodeStatus#SUCCESS} or {@link NodeStatus#RUNNING}. It will fail otherwise.
+     */
     SEQUENCE,
+    /**
+     * Repeat will have status {@link NodeStatus#RUNNING} while the delegate has status {@link
+     * NodeStatus#FAILURE} or {@link NodeStatus#RUNNING}. It will succeed otherwise.
+     */
     SELECTOR,
+    /**
+     * Repeat will have status {@link NodeStatus#RUNNING} while the delegate has status {@link
+     * NodeStatus#SUCCESS} or {@link NodeStatus#RUNNING}. It will succeed otherwise.
+     */
     SELECTOR_INVERTED
   }
 
diff --git a/src/main/java/org/bk/ass/bt/Succeeder.java b/src/main/java/org/bk/ass/bt/Succeeder.java
@@ -1,7 +1,7 @@
 package org.bk.ass.bt;
 
 /**
- * Never fails, but
+ * Never fails, even if the delegate fails.
  */
 public class Succeeder extends Decorator {
 
diff --git a/src/main/java/org/bk/ass/bt/TreeNode.java b/src/main/java/org/bk/ass/bt/TreeNode.java
@@ -1,60 +1,106 @@
 package org.bk.ass.bt;
 
+/**
+ * Base class of all of ASS' behavior trees.
+ */
 public abstract class TreeNode {
 
   String name = getClass().getSimpleName();
   NodeStatus status;
 
+  /**
+   * Should be called before using this node.
+   */
   public void init() {
     status = NodeStatus.INITIAL;
   }
 
-  public void close() {}
+  /**
+   * Should be called if this node will not be used again and might perform some operations at the
+   * end. If used for clean-ups, be aware that some nodes might get {@link #abort()}ed instead and
+   * will not receive a close call.
+   */
+  public void close() {
+  }
 
+  /**
+   * Executes this node, with an {@link ExecutionContext} for meta data.
+   */
   public void exec(ExecutionContext executionContext) {
     exec();
   }
 
+  /**
+   * Executes this node without any meta data context.
+   */
   public abstract void exec();
 
   /**
    * Used by {@link CompoundNode}s to determine order of execution. Generally, nodes with {@link
    * Selector} like behavior will run children in decreasing order of utility. Nodes with {@link
    * Sequence} like behavior will not change the order of children unless explicitly stated.
+   *
+   * @return 0 by default.
    */
   public double getUtility() {
     return 0;
   }
 
+  /**
+   * Returns the status of the last execution.
+   */
   public final NodeStatus getStatus() {
     return status;
   }
 
+  /**
+   * Mark node as successful.
+   */
   public final void success() {
     status = NodeStatus.SUCCESS;
   }
 
+  /**
+   * Mark node as running.
+   */
   public final void running() {
     status = NodeStatus.RUNNING;
   }
 
+  /**
+   * Mark node as failed.
+   */
   public final void failed() {
     status = NodeStatus.FAILURE;
   }
 
-  public void reset() {
-    status = NodeStatus.INITIAL;
-  }
-
+  /**
+   * Aborts any operation of this node and marks the status as aborted. Subclasses should call
+   * <pre>super.abort()</pre> on override.
+   */
   public void abort() {
     status = NodeStatus.ABORTED;
   }
 
+  /**
+   * Resets the node and its status. If overridden, should always call <pre>super.reset()</pre> to
+   * ensure status is correct.
+   */
+  public void reset() {
+    status = NodeStatus.INITIAL;
+  }
+
+  /**
+   * Sets a name for this node which can be used to identify it in the complete tree.
+   */
   public final TreeNode withName(String name) {
     this.name = name;
     return this;
   }
 
+  /**
+   * The previously set name.
+   */
   public String getName() {
     return name;
   }
diff --git a/src/main/java/org/bk/ass/bt/Wait.java b/src/main/java/org/bk/ass/bt/Wait.java
@@ -1,5 +1,9 @@
 package org.bk.ass.bt;
 
+/**
+ * Node which always is in status {@link NodeStatus#RUNNING}. Usually used in conjunction with a
+ * {@link Sequence} and a {@link Condition} to make sure it's not waiting endlessly.
+ */
 public class Wait extends TreeNode {
 
   public static final Wait INSTANCE = new Wait();
diff --git a/src/main/java/org/bk/ass/grid/BooleanGrid.java b/src/main/java/org/bk/ass/grid/BooleanGrid.java
@@ -0,0 +1,28 @@
+package org.bk.ass.grid;
+
+public class BooleanGrid extends VersionedGrid<Boolean> {
+
+  public BooleanGrid(int width, int height) {
+    super(width, height);
+  }
+
+  @Override
+  public Boolean get(int x, int y) {
+    return dataVersion[y][x] == version;
+  }
+
+  @Override
+  public void set(int x, int y, Boolean value) {
+    dataVersion[y][x] = value ? version : 0;
+  }
+
+  @Override
+  protected Boolean internalGet(int x, int y) {
+    throw new IllegalStateException("Should not be called");
+  }
+
+  @Override
+  protected void internalSet(int x, int y, Boolean value) {
+    throw new IllegalStateException("Should not be called");
+  }
+}
diff --git a/src/main/java/org/bk/ass/grid/Grids.java b/src/main/java/org/bk/ass/grid/Grids.java
diff --git a/src/main/java/org/bk/ass/grid/Rectangle.java b/src/main/java/org/bk/ass/grid/Rectangle.java
diff --git a/src/main/java/org/bk/ass/grid/VersionedGrid.java b/src/main/java/org/bk/ass/grid/VersionedGrid.java
diff --git a/src/main/java/org/bk/ass/path/Position.java b/src/main/java/org/bk/ass/path/Position.java
diff --git a/src/test/java/org/bk/ass/grid/VersionedGridTest.java b/src/test/java/org/bk/ass/grid/VersionedGridTest.java
