Crate behaviortree

Expand description

§behaviortree

‘behaviortree’ implements a behavior tree library similar to BehaviorTree.CPP but in Rust.

Examples implementing the BehaviorTree.CPP tutorials can be found here. For embedded devices similar examples are available here

⚠️ INFO ⚠️ This crate is still in development.

§Usage

Below is a very simple example using functions as Actions. For more examples see:

use behaviortree::prelude::*;

const XML: &str = r#"
<root BTCPP_format="4">
    <BehaviorTree ID="MyBehavior">
        <Sequence>
			<MyAction1/>
			<MyAction2/>
        </Sequence>
    </BehaviorTree>
</root>
"#;

fn action_1() -> BehaviorResult {
    // your activity
    // ...

    // In case of Failure    
    //return Ok(BehaviorState::Failure);

    // In case of Success    
    Ok(BehaviorState::Success)
}

fn action_2() -> BehaviorResult {
    // your activity
    // ...
    Ok(BehaviorState::Success)
}

#[tokio::main]
async fn main() {
    // create a behavior factory
    let mut factory = BehaviorTreeFactory::new().unwrap();

    // register your behaviors
    register_simple_behavior!(factory, action_1, "MyAction1", BehaviorKind::Action).unwrap();
    register_simple_behavior!(factory, action_2, "MyAction2", BehaviorKind::Action).unwrap();

    // create the tree
    let mut tree = factory.create_from_text(XML).unwrap();
    
    // run the tree until Success or Failure
    tree.tick_while_running().await.unwrap();
}

For implementation of your own behaviors, there is a set of derive macros: Action, Condition, Control and Decorator.

use behaviortree::prelude::*;

const XML: &str = r#"
<root BTCPP_format="4">
    <BehaviorTree ID="MyBehavior">
        <MyAction message = "hello world!"/>
    </BehaviorTree>
</root>
"#;

/// Derive an `Action`
#[derive(Action, Debug, Default)]
pub struct SaySomething;

/// Implement the `Action`s functionality
#[async_trait::async_trait]
impl Behavior for SaySomething {
    /// Minimum implement the tick function
	async fn tick(
		&mut self,
		behavior: &mut BehaviorData,
		_children: &mut BehaviorTreeElementList,
		_runtime: &SharedRuntime,
	) -> BehaviorResult {
        // getting the port
		let msg = behavior.get::<String>("message")?;
        // doing something
		println!("Robot says: {msg}");
        // signaling success
		Ok(BehaviorState::Success)
	}

    /// Define the available ports.
    /// This is optional, the default implementation is for no ports.
	fn provided_ports() -> PortList {
		port_list! {input_port!(String, "message")}
	}
}

#[tokio::main]
async fn main() {
    // create a behavior factory
    let mut factory = BehaviorTreeFactory::new().unwrap();

    // register the behavior
    SaySomething::register(&mut factory, "MyAction").unwrap();

    // create the tree
    let mut tree = factory.create_from_text(XML).unwrap();
    
    // run the tree until Success or Failure
    tree.tick_while_running().await.unwrap();
}

§Capabilities

✅: Supported
☑️: Supported with some caveats
🚦: Needs testing but basically works
🔴: Not yet supported
??: Unclear if it can be supported
❌: Will not be supported

§General capabilities

Capability	std OS	Embedded	Caveats
XML
- parsing	✅	✅	embedded tree depth <= 12
- generation	✅	✅

Ports
- remapping	✅	✅
- access by ref	✅	✅

Subtrees
- structure	✅	✅
- remapping	✅	✅
- ‘include’ from file	✅	❌

Blackboard
- hierarchy	✅	✅
- remapping	✅	✅
- access by ref	✅	✅
- backup	🔴	??

Pre-/post-conditions	✅	✅
Scripting	✅	✅

Loggers/Observers	✅	🚦	basically works, no time info, no groot2 observer
Substitution rules	🚦	🚦	no delay in embedded, currently no functions possible

Using Groot2 for:
- XML Create/Edit	☑️	☑️	different type systems
- Live Monitoring	☑️	??	different type systems
- Pro Features	🔴	??

§Built-in behaviors

Names as in BehaviorTree.CPP	std OS	Embedded
Actions
`AlwaysFailure`, `AlwaysSuccess`	✅	✅
`Script`	✅	✅
`SetBlackboard`, `UnsetBlackboard`	✅	✅
`PopFromQueue<T>`	✅	✅
`Sleep`	🚦	🔴

Conditions
`ScriptCondition`	✅	✅
`WasEntryUpdated`	✅	✅

Controls
`Fallback`	✅	✅
`AsyncFallback`, `ReactiveFallback`	✅	✅
`Sequence`, `SequenceWithMemory`	✅	✅
`AsyncSequence`, `ReactiveSequence`	✅	✅
`Parallel`, `ParallelAll`	✅	✅
`IfThenElse`, `WhileDoElse`	✅	✅
`Switch<u8>`	✅	✅
`ManualSelector`	🔴	??

Decorators
`ForceFailure`, `ForceSuccess`	✅	✅
`Inverter`	✅	✅
`KeepRunningUntilFailure`	✅	✅
`Repeat`	✅	✅
`RetryUntilSuccessful`	✅	✅
`EntryUpdated`	✅	✅
`LoopQueue<T>`	✅	✅
`RunOnce`	✅	✅
`Precondition`	✅	✅
`Delay`	🚦	🔴
`Timeout`	🚦	🔴

§License

Licensed with the fair use “NGMC” license, see license file

§Contribution

Any contribution intentionally submitted for inclusion in the work by you, shall be licensed with the same “NGMC” license, without any additional terms or conditions.

Re-exports§

pub use behavior::Behavior;
pub use behavior::BehaviorError;
pub use behavior::BehaviorExecution;
pub use behavior::BehaviorKind;
pub use behavior::BehaviorResult;
pub use behavior::BehaviorState;
pub use behavior::behavior_data::BehaviorData;
pub use behavior::behavior_description::BehaviorDescription;
pub use factory::BehaviorTreeFactory;
pub use port::PortList;

Modules§

behavior: behaviortree behavior module.
factory: behaviortree factory module.
port: behaviortree port module.
prelude: Most commonly used interfaces of behaviortree.

Macros§

inout_port: macro for creation of an in/out port definition
input_port: macro for creation of an input port definition
output_port: macro for creation of an output port definition
port_list: macro for creation of a PortList
register_behaviorDeprecated: Macro to register different kinds of behaviors.
register_groot2_behaviorDeprecated: Macro to register groot2 behaviors. It as the same usage as the macro register_behavior!(...), the difference is, that it marks a behavior as known by Groot2.
register_scripting_enum: Macro to register enums for scripting. Enum must derive ScriptEnum. It is also possible to register discrete value(s).
register_simple_behavior: Macro to register different kinds of functions as behaviors.

Structs§

BehaviorTree: A Tree of BehaviorTreeElements. A certain BehaviorTree can contain up to 65536 BehaviorTreeElements.
BehaviorTreeElement: A tree elements.
BehaviorTreeObserver: An observer collecting BehaviorTree statistics
Error: factory error type
Groot2Connector: The Groot2Connector is used to create an interface between Groot2 and the tree executor.
XmlCreator: Write different kinds of XML from various sources.

Constants§

ACTION: BehaviorKind literal “Action”
BEHAVIORTREE: Literal "BehaviorTree"
CONDITION: BehaviorKind literal “Condition”
CONTROL: BehaviorKind literal “Control”
DECORATOR: BehaviorKind literal “Decorator”
EMPTY_STR: Often needed empty str
FAILURE: BehaviorState literal “Failure”
IDLE: BehaviorState literal “Idle”
RUNNING: BehaviorState literal “Running”
SKIPPED: BehaviorState literal “Skipped”
SUBTREE: BehaviorKind literal "SubTree"
SUCCESS: BehaviorState literal “Success”
TREENODESMODEL: Literal "TreeNodesModel"

Type Aliases§

BehaviorTreeResult: Result type definition for behavior trees.
Mutex: A primitive that synchronizes the execution of multiple threads. See mutex::Mutex for documentation.

Derive Macros§

Action: Derive macro for an Action type Behavior, usage.
Condition: Derive macro for an Condition type Behavior, usage.
Control: Derive macro for an Control type Behavior, usage.
Decorator: Derive macro for an Decorator type Behavior, usage.