Merge pull request #13 from Sollimann/release-0.3.9

Release 0.3.9

DEVELOPMENT.md

@@ -11,6 +11,12 @@ Enable pre-commit in repo
 $ pre-commit install
 ```
 
+### Install dev dependencies
+
+```sh
+$ make install-dev-deps
+```
+
 ### Useful resources
 
 * [Game AI BT](https://faculty.cc.gatech.edu/~surban6/2018sp-gameAI/homeworks/homework6.html)

Makefile

@@ -0,0 +1,10 @@
+.PHONY: install-dev-deps dry-run publish
+
+install-dev-deps:
+	sudo apt-get update && sudo apt-get install libudev-dev pkg-config librust-alsa-sys-dev
+
+dry-run:
+	cargo publish --package bonsai-bt --dry-run
+
+publish:
+	cargo publish --package bonsai-bt

README.md

@@ -10,7 +10,7 @@
 <!-- [![version](https://img.shields.io/badge/version-1.0.0-blue)](https://GitHub.com/Sollimann/CleanIt/releases/) -->
 [![Build Status](https://github.com/Sollimann/bonsai/workflows/rust-ci/badge.svg)](https://github.com/Sollimann/bonsai/actions)
 [![Bonsai crate](https://img.shields.io/crates/v/bonsai-bt.svg)](https://crates.io/crates/bonsai-bt)
-[![minimum rustc 1.56](https://img.shields.io/badge/rustc-1.56+-blue.svg)](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
+[![minimum rustc 1.60](https://img.shields.io/badge/rustc-1.60+-blue.svg)](https://rust-lang.github.io/rfcs/2495-min-rust-version.html)
 [![Docs](https://docs.rs/bonsai-bt/badge.svg)](https://docs.rs/bonsai-bt)
 [![codecov](https://codecov.io/gh/Sollimann/bonsai/branch/main/graph/badge.svg?token=JX8JBPWORV)](https://codecov.io/gh/Sollimann/bonsai)
 [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/Sollimann/bonsai/graphs/commit-activity)
@@ -42,9 +42,7 @@ A _Behavior Tree_ (BT) is a data structure in which we can set the rules of how
 
 ### How to use a Behavior tree?
 
-An AI behavior tree is a very generic way of organizing interactive logic.
-It has built-in semantics for processes that signals `Running`, `Success` or
-`Failure`.
+A Behavior Tree forms a tree structure where each node represents a process. When the process terminates, it signals `Success` or `Failure`. This can then be used by the parent node to select the next process. A signal `Running` is used to tell the process is not done yet.
 
 For example, if you have a state `A` and a state `B`:
 

bonsai/Cargo.toml

@@ -12,7 +12,7 @@ name = "bonsai-bt"
 readme = "../README.md"
 repository = "https://github.com/sollimann/bonsai.git"
 rust-version = "1.60.0"
-version = "0.3.8"
+version = "0.3.9"
 
 [lib]
 name = "bonsai_bt"

bonsai/src/bt.rs

@@ -54,7 +54,17 @@ impl<A: Clone, K: Debug, V: Debug> BT<A, K, V> {
         &mut bt.state
     }
 
-    /// todo
+    /// The behavior tree is a stateful data structure in which the immediate
+    /// state of the BT is allocated and updated in heap memory through the lifetime
+    /// of the BT. The state of the BT is said to be `transient` meaning upon entering
+    /// a this state, the process may never return this state again. If a behavior concludes,
+    /// only the latest results will be stored in heap memory.
+    ///
+    /// If your BT has surpassed a desired state or that your BT has reached a steady state - meaning
+    /// that the behavior has concluded and ticking the BT won't progress any further - then it could
+    /// be desirable to return the BT to it's initial state at t=0.0 before it was ever ticked.
+    ///
+    /// PS! invoking reset_bt does not reset the Blackboard.
     pub fn reset_bt(&mut self) {
         self.state = self.initial_state.clone();
     }

bonsai/src/lib.rs

@@ -9,9 +9,10 @@
 //!
 //! ### How to use a Behavior tree?
 
-//! An AI behavior tree is a very generic way of organizing interactive logic.
-//! It has built-in semantics for processes that signals `Running`, `Success` or
-//! `Failure`.
+//! A Behavior Tree forms a tree structure where each node represents a process.
+//! When the process terminates, it signals `Success` or `Failure`. This can then
+//! be used by the parent node to select the next process.
+//! A signal `Running` is used to tell the process is not done yet.
 
 //! For example, if you have a state `A` and a state `B`:
 
@@ -110,6 +111,10 @@
 //!     let bb = bt.get_blackboard();
 //!     let count = bb.get_db().get("count").unwrap();
 //!     assert_eq!(*count, 1);
+//!
+//!     // if the behavior tree concludes (reaches a steady state)
+//!     // you can reset the tree back to it's initial state at t=0.0
+//!     bt.reset_bt();
 //! }
 //! ```
 

bonsai/tests/bt_tests.rs

@@ -47,7 +47,6 @@ fn tick(mut acc: i32, dt: f64, bt: &mut BT<TestActions, String, i32>) -> (i32, b
 fn test_select_succeed_on_second_last() {
     let a: i32 = 3;
     let sel = Select(vec![Action(LessThan(1)), Action(Dec), Action(Inc)]);
-    // let mut state = State::new(sel);
 
     let h: HashMap<String, i32> = HashMap::new();
     let mut bt = BT::new(sel, h);

docs/concepts/README.md

@@ -5,10 +5,10 @@
   - [When to use a Behavior Tree?](#when-to-use-a-behavior-tree)
     - [BT vs FSM:](#bt-vs-fsm)
   - [How to use a Behavior tree?](#how-to-use-a-behavior-tree)
-- [Types of Nodes](#types-of-nodes)
-- [Understand Asynchrous Nodes, Concurrency and Parallelism](#understand-asynchrous-nodes-concurrency-and-parallelism)
-  - [Concurrency vs Parallelism](#concurrency-vs-parallelism)
-  - [Asynchronous vs Synchronous](#asynchronous-vs-synchronous)
+- [Parallel semantics](#parallel-semantics)
+- [Behavior vs State](#behavior-vs-state)
+- [Events](#events)
+- [Instant Actions](#instant-actions)
 
 ## Fundamentals
 
@@ -60,35 +60,30 @@ For example, if you have a state `A` and a state `B`:
 
 See the `Behavior` enum for more information.
 
+## Parallel semantics
+Parallel semantics has two important properties:
 
-## Types of Nodes
+* Makes it easier to create more complex behavior from simpler ones
+* Infinite loops of behavior can be terminated based on external conditions
 
-TODO
+This semantics solves the problem of scaling up building blocks of behavior to any arbitrary size. Such trees can be put together in many complex ways, resulting in many complex states.
 
+The building blocks used in this library has been crafted to cover as many parallel scenarios as possible using common sense as guide.
 
-## Understand Asynchrous Nodes, Concurrency and Parallelism
+One effect of parallel semantics is that it can't be simulated perfectly on a single thread. The behavior is deterministic, but the logic breaks down for shorter time intervals than given by updates per second. The consequences are determined by the interaction of side effects.
 
-When designing reactive Behavior Trees, it is important to understand 2 main concepts:
+For example, in a racing game, `WhenAny` can be used to detect when there is a winner, keeping track of a process for each car. The first car in the list might trigger `Success` even if the second car logically should come first, but only if the first car completes within a delta time interval. However, this will have no logical consequences if the physical simulation runs separately and the winner is picked based on who actually crossed the finish line first.
 
-- what we mean by **"Asynchronous"** Actions VS **"Synchronous"** ones.
-- The difference between **Concurrency** and **Parallelism** in general and in the context of behavior trees.
+## Behavior vs State
 
-### Concurrency vs Parallelism
+For each behavior there is a state that keeps track of current running process. When you declare a behavior, this state is not included, resulting in a compact representation that can be copied or shared between objects having same behavior. Behavior means the declarative representation of the behavior, and State represents the executing instance of that behavior.
 
-If you Google those words, you will read many good articles about this topic.
+## Events
 
-* **Concurrency** is when two or more tasks can start, run, and complete in overlapping time periods. It doesn't necessarily mean they'll ever both be running at the same instant.
+The Bonsai behavior tree models the world in terms of an discretized event loop where updates comes with a *delta time interval* `dt`. When an process terminates, it tells how much time is left of the delta time interval, such that the next process can be executed for the remaining time.
 
-* **Parallelism** is when tasks literally run at the same time in different  threads, e.g., on a multicore processor.
+Events are partially consumable. When one action terminates, it can pass on the remaining delta time to the next action.
 
-### Asynchronous vs Synchronous
+## Instant Actions
 
-In general, an Asynchronous Action (or TreeNode) is simply one that:
-
-- May return RUNNING instead of SUCCESS or FAILURE, when ticked.
-- Can be stopped as fast as possible when the method `halt()` (to be implemented by the developer) is invoked.
-
-When your Tree ends up executing an Asynchronous action that returns running, that RUNNING state is usually propagated backbard and the entire Tree is itself in the RUNNING state.
-
-In the example below, "ActionE" is asynchronous and RUNNING; when
-a node is RUNNING, usually its parent returns RUNNING too.
+Update actions that does not consume delta time, returning the same delta time as they receive, can lead to infinite loops. A `Wait` behavior can be used to prevent this. The meaning of update is defined as "consume time to stop" so it will continue running actions until it hits one that does not have enough time to terminate.