Skip to content

Commit 1eb3de7

Browse files
author
Bytekeeper
committed
Behavior tree documentation
1 parent fdfe190 commit 1eb3de7

22 files changed

+342
-8
lines changed

src/main/java/org/bk/ass/bt/AcquireLock.java

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
import org.bk.ass.manage.Lock;
44

5+
/**
6+
* Leaf node that will succeed if the supplied lock can be acquired. Fails otherwise.
7+
*
8+
* @param <T> the lock kind
9+
*/
510
public class AcquireLock<T> extends TreeNode {
611

712
private final Lock<T> lock;

src/main/java/org/bk/ass/bt/BehaviorTree.java

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,30 @@
22

33
import static java.util.Objects.requireNonNull;
44

5+
/**
6+
* A behavior tree. Main difference to other compound nodes is that the actual root tree node is
7+
* constructed on initialization.
8+
* <p/>
9+
* This allows data oriented programming, with simplified access to some data:
10+
* <pre>
11+
* {@code
12+
* public class MyTree extends BehaviorTree {
13+
* // Data shared by nodes of this tree
14+
* private Data myData = new Data(...);
15+
* protected TreeNode getRoot() {
16+
* return new Sequence(new SomeCondition(myData), new Action(myData));
17+
* }
18+
* }
19+
* }
20+
* </pre>
21+
*/
522
public abstract class BehaviorTree extends TreeNode {
623

724
private TreeNode root;
825

26+
/**
27+
* Will be called <em>once</em> to create the actual root to be ticked.
28+
*/
929
protected abstract TreeNode getRoot();
1030

1131
@Override

src/main/java/org/bk/ass/bt/CompoundNode.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,11 @@
55
import java.util.Comparator;
66
import java.util.List;
77

8+
/**
9+
* Base class for non-leaf nodes. Usually not subclassed directly.
10+
*/
811
public abstract class CompoundNode extends TreeNode {
12+
913
protected static final Comparator<TreeNode> UTILITY_COMPARATOR =
1014
Comparator.comparing(TreeNode::getUtility).reversed();
1115
protected final List<TreeNode> children;

src/main/java/org/bk/ass/bt/Condition.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,11 @@
33
import java.util.Objects;
44
import java.util.function.BooleanSupplier;
55

6+
/**
7+
* Node that will succeed if the given check passed, fails otherwise.
8+
*/
69
public class Condition extends TreeNode {
10+
711
private final BooleanSupplier check;
812

913
public Condition(BooleanSupplier check) {

src/main/java/org/bk/ass/bt/Decorator.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
import java.util.Objects;
44

5+
/**
6+
* Base class for nodes that delegate execution and modify the delegate or the status.
7+
*/
58
public abstract class Decorator extends TreeNode {
9+
610
private final TreeNode delegate;
711

812
public Decorator(TreeNode delegate) {

src/main/java/org/bk/ass/bt/Distributor.java

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,15 @@
1414
import org.bk.ass.StopWatch;
1515
import org.bk.ass.bt.Parallel.Policy;
1616

17+
/**
18+
* This is like <code>map</code> for streams. Maps each item of a given list to a node. New nodes
19+
* will only be created for new items. Nodes for items that are no longer present will be aborted
20+
* and discarded.
21+
* <p/>
22+
* The created child nodes will be executed in parallel in the order of the item list.
23+
*
24+
* @param <T> the type of the item used to create new nodes
25+
*/
1726
public class Distributor<T> extends TreeNode {
1827

1928
private Policy policy;

src/main/java/org/bk/ass/bt/ExecutionContext.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
import java.util.List;
88
import java.util.Map;
99

10+
/**
11+
* Can be used to create tree stack traces and log performance numbers of nodes.
12+
*/
1013
public class ExecutionContext {
1114

1215
public static final ExecutionContext NOOP =

src/main/java/org/bk/ass/bt/Inverter.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
package org.bk.ass.bt;
22

3+
/**
4+
* Delegates execution but returns the inverted status (ie. failed -> success; success -> failed;
5+
* running -> running).
6+
*/
37
public class Inverter extends Decorator {
48

59
public Inverter(TreeNode delegate) {

src/main/java/org/bk/ass/bt/LambdaNode.java

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@
22

33
import java.util.function.Supplier;
44

5+
/**
6+
* Allows inline nodes using lambdas.
7+
*/
58
public class LambdaNode extends TreeNode {
9+
610
private final Supplier<NodeStatus> delegate;
711

812
public LambdaNode(Supplier<NodeStatus> delegate) {

src/main/java/org/bk/ass/bt/Memo.java

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
package org.bk.ass.bt;
22

3+
/**
4+
* Most nodes of <pre>ASS</pre> are reactive (they will execute no matter what the last execution
5+
* result was). Using this class, once the delegate reaches a non-running status the result will be
6+
* remembered. Further invocations will not change the status and the delegate will not be ticked
7+
* again.
8+
*/
39
public class Memo extends Decorator {
410

511
public Memo(TreeNode delegate) {

0 commit comments

Comments
 (0)