Polish up behaviour tree, add docs

engine/breeze/ai/behaviour_tree.h

@@ -18,8 +18,8 @@ typedef enum BzBTNodeType {
     // Composite
     BZ_BT_COMP_SELECTOR,
     BZ_BT_COMP_SEQUENCE,
-    BZ_BT_COMP_P_SELECTOR,
-    BZ_BT_COMP_P_SEQUENCE,
+    BZ_BT_COMP_PSELECTOR,
+    BZ_BT_COMP_PSEQUENCE,
     // Decorator
     BZ_BT_DECOR_DUMMY,
     BZ_BT_DECOR_SUCCESS,
@@ -56,26 +56,166 @@ typedef struct BzBTStateDesc {
     void *userData;
 } BzBTStateDesc;
 
+/**
+ * @brief Useful for allocating BzBTNode pools.
+ * @return size of BzBTNode
+ */
 size_t  bzBTGetNodeSize();
+/**
+ * @brief Useful for allocating BzBTNodeState pools.
+ * @return size of BzBTNodeState
+ */
 size_t  bzBTGetNodeStateSize();
 
+/**
+ * @brief Utility function for converting enum type to human readable string.
+ * @return human-readable node type
+ */
 const char *bzBTNodeTypeToStr(BzBTNodeType type);
 
+/**
+ * @brief Starting point of BT.
+ * @param nodePool pool
+ * @return allocated node
+ */
 BzBTNode *bzBTMakeRoot(BzObjectPool *nodePool);
-void      bzBTDestroyRoot(BzObjectPool *nodePool, BzBTNode *node);
+/**
+ * @brief Recursively cleans up BT.
+ * @param nodePool pool
+ * @param node BT root
+ */
+void bzBTDestroyRoot(BzObjectPool *nodePool, BzBTNode *node);
 
-BzBTNode *bzBTCompSelector(BzObjectPool *nodePool, BzBTNode *parent, bool parallel);
-BzBTNode *bzBTCompSequence(BzObjectPool *nodePool, BzBTNode *parent, bool parallel);
+/**
+ * @brief Execute all children in turn until one fails.
+ *
+ * Execution is BZ_BT_SUCCESS, if all children are ran successfully.
+ * Child execution, does not progress unless child finishes (no BZ_BT_RUNNING status).
+ *
+ * @param nodePool pool
+ * @param parent parent of the composite
+ * @return allocated composite
+ */
+BzBTNode *bzBTCompSelector(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Execute all children in turn until first one succeeds.
+ *
+ * Execution is BZ_BT_FAIL, if no children are ran successfully.
+ * Child execution is blocking -> it does not progress unless child
+ * finishes (is not BZ_BT_RUNNING).
+ *
+ * @param nodePool pool
+ * @param parent parent of the composite
+ * @return allocated composite
+ */
+BzBTNode *bzBTCompSequence(BzObjectPool *nodePool, BzBTNode *parent);
 
+/**
+ * @brief Execute all children in turn until one fails.
+ *
+ * Execution is BZ_BT_SUCCESS, if all children are ran successfully.
+ * Children are executed in non-blocking way in the order of BT.
+ *
+ * @param nodePool pool
+ * @param parent parent of the composite
+ * @return allocated composite
+ */
+BzBTNode *bzBTCompPSelector(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Execute all children in turn until first one succeeds.
+ *
+ * Execution is BZ_BT_FAIL, if no children are ran successfully.
+ * Children are executed in non-blocking way in the order of BT.
+ *
+ * @param nodePool pool
+ * @param parent parent of the composite
+ * @return allocated composite
+ */
+BzBTNode *bzBTCompPSequence(BzObjectPool *nodePool, BzBTNode *parent);
+
+/**
+ * @brief Returns child status.
+ *
+ * Note: Useful when nesting BTs.
+ *
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorDummy(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Returns BZ_BT_SUCCESS, if no BZ_BT_ERROR occurred.
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorSuccess(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Returns BZ_BT_FAIL, if no BZ_BT_ERROR occurred.
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorFail(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Inverts child result.
+ *
+ * Note: Only for BZ_BT_SUCCESS and BZ_BT_FAIL. Other statuses
+ * are propagated up.
+ *
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorInvert(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Repeats child execution until it returns BZ_BT_SUCCESS.
+ *
+ * Note: BZ_BT_ERROR also causes it to return.
+ *
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorUntilSuccess(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Repeats child execution until it returns BZ_BT_FAIL.
+ *
+ * Note: BZ_BT_ERROR also causes it to return.
+ *
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorUntilFail(BzObjectPool *nodePool, BzBTNode *parent);
+/**
+ * @brief Repeats child execution n-times.
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @param n number of repeats
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorRepeat(BzObjectPool *nodePool, BzBTNode *parent, i32 n);
+/**
+ * @brief Delays child/sibling execution for specified ms.
+ *
+ * Note: for this to properly work, correct dt must be passed
+ * in when executing BT.
+ *
+ * @param nodePool pool
+ * @param parent parent of the decorator
+ * @param ms milliseconds to wait
+ * @return allocated decorator
+ */
 BzBTNode *bzBTDecorDelay(BzObjectPool *nodePool, BzBTNode *parent, f32 ms);
 
+/**
+ * @brief Creates BT task.
+ * @param nodePool pool
+ * @param parent parent of the task
+ * @param fn function pointer for the task
+ * @return allocated action
+ */
 BzBTNode *bzBTAction(BzObjectPool *nodePool, BzBTNode *parent, BzBTActionFn fn);
 
 // Reflection data
@@ -102,9 +242,24 @@ BzBTNode *bzBTCompStateGetRunningChild(const BzBTNodeState *state);
 i32 bzBTRepeatStateGetIter(const BzBTNodeState *state);
 f32 bzBTDelayStateGetElapsed(const BzBTNodeState *state);
 
-BzBTState   bzBTCreateState(const BzBTStateDesc *desc);
-void        bzBTDestroyState(BzBTState *state);
+/**
+ * @brief Creates state for a given BT.
+ * @param desc input parameters
+ * @return BT state
+ */
+BzBTState bzBTCreateState(const BzBTStateDesc *desc);
+/**
+ * @brief Cleans up state (does not modify BT).
+ * @param state state to clean up
+ */
+void bzBTDestroyState(BzBTState *state);
 
+/**
+ * @brief Tick behaviour tree.
+ * @param state state of the behaviour tree
+ * @param dt delta time
+ * @return status of BT tick
+ */
 BzBTStatus bzBTExecute(BzBTState *state, f32 dt);
 
 #endif //BREEZE_BEHAVIOUR_TREE_H