There are some main concepts that you need to understand first.

This approach reduces the amount of boilerplate in your code; as a reference

please look at the [first tutorial](tutorial_A_create_trees.md) amd the one

describing [non intrusive integration with legacy code](tutorial_g_legacy.md).

Despite the fact that the library is written in C++, trees themselves

can be composed at run-time, reading the tree structure from file.

An XML format is descibed in details [here](xml_format.md).

Note that the following syntax is also valid:

!!! Note

You can find more details about the XML schema [here](xml_format.md).

In the [first tutorial](tutorial_A_create_trees.md) this simple tree

was presented.

``` XML

<root main_tree_to_execute = "MainTree" >

<BehaviorTree ID="MainTree">

<Sequence name="root_sequence">

<SaySomething name="action_hello" message="Hello"/>

<OpenGripper name="open_gripper"/>

<ApproachObject name="approach_object"/>

<CloseGripper name="close_gripper"/>

</Sequence>

</BehaviorTree>

</root>

You may notice that:

- The first tag of the tree is `<root>`. It should contain 1 or more tags `<BehaviorTree>`.

- The tag `<BehaviorTree>` should have the attribute `[ID]`.

- The tag `<root>` should contain the attribute `[main_tree_to_execute]`,refering the ID of the main tree.

- The attribute `[main_tree_to_execute]` is mandatory if the file contains multiple `<BehaviorTree>`,

optional otherwise.

- Each TreeNode is represented by a single tag. In particular:

- The name of the tag is the __ID__ used to register the TreeNode in the factory.

- The attribute `[name]` refers to the name of the instance and is __optional__.

- Nodeparameters are passed as attribute as well. In the previous example, the action

`SaySomething` requires the NodeParameter `message`.

- In terms of number of children:

- `ControlNodes` contain __1 to N children__.

- `DecoratorNodes` and Subtrees contain __only 1 child__.

- `ActionNodes` and `ConditionNodes` have __no child__.

The following two syntaxes are both valid:

``` XML

<SaySomething name="action_hello" message="Hello World"/>

<Action ID="SaySomething" name="action_hello" message="Hello World"/>

We will call the former syntax "__compact__" and the latter "__explicit__".

The first example represented with the explicit syntax would become:

``` XML

<root main_tree_to_execute = "MainTree" >

<BehaviorTree ID="MainTree">

<Sequence name="root_sequence">

<Action ID="SaySomething" name="action_hello" message="Hello"/>

<Action ID="OpenGripper" name="open_gripper"/>

<Action ID="ApproachObject" name="approach_object"/>

<Action ID="CloseGripper" name="close_gripper"/>

</Sequence>

</BehaviorTree>

</root>

Even if the compact syntax is more convenient and easier to write, it provides

too little information about the model of the TreeNode. Tools like __Groot__ require either

the _explicit_ syntax or additional information.

This information can be added using the tag `<TreeNodeModel>`.

To make the compact version of our tree compatible with Groot, the XML must be modified as follows:

``` XML

<root main_tree_to_execute = "MainTree" >

<BehaviorTree ID="MainTree">

<Sequence name="root_sequence">

<SaySomething name="action_hello" message="Hello"/>

<OpenGripper name="open_gripper"/>

<ApproachObject name="approach_object"/>

<CloseGripper name="close_gripper"/>

</Sequence>

</BehaviorTree>

<!-- the BT executor don't require this, but Groot does -->

<TreeNodeModel>

<Action ID="SaySomething" message="default message"/>

<Action ID="OpenGripper"/>

<Action ID="ApproachObject"/>

<Action ID="CloseGripper"/>

</TreeNodeModel>

</root>

As we saw in [this tutorial](tutorial_D_subtrees.md), it is possible to include

a Subtree inside another tree to avoid "copy and pasting" the same tree in

multiple location and to reduce complexity.

Let's say that we want to incapsulate few action into the behaviorTree "__GraspObject__"

(being optional, attributes [name] are omitted for simplicity).

``` XML hl_lines="6"

<root main_tree_to_execute = "MainTree" >

<BehaviorTree ID="MainTree">

<Sequence>

<Action ID="SaySomething" message="Hello World"/>

<Subtree ID="GraspObject"/>

</Sequence>

</BehaviorTree>

<BehaviorTree ID="GraspObject">

<Sequence>

<Action ID="OpenGripper"/>

<Action ID="ApproachObject"/>

<Action ID="CloseGripper"/>

</Sequence>

</BehaviorTree>

</root>

We may notice as the entire tree "GraspObject" is executed after "SaySomething".

__Since version 2.4__.

You can include external files in a way that is similar to __#include <file>__ in C++.

We can do this easily using the tag:

``` XML

<include path="relative_or_absolute_path_to_file">

```

using the previous example, we may split the two behavior trees into two files:

``` XML hl_lines="5"

<!-- file maintree.xml -->

<root main_tree_to_execute = "MainTree" >

<include path="grasp.xml"/>

<BehaviorTree ID="MainTree">

<Sequence>

<Action ID="SaySomething" message="Hello World"/>

<Subtree ID="GraspObject"/>

</Sequence>

</BehaviorTree>

</root>

```

``` XML

<!-- file grasp.xml -->

<root main_tree_to_execute = "GraspObject" >

<BehaviorTree ID="GraspObject">

<Sequence>

<Action ID="OpenGripper"/>

<Action ID="ApproachObject"/>

<Action ID="CloseGripper"/>

</Sequence>

</BehaviorTree>

</root>

!!! Note "Note for ROS users"

If you want to find a file inside a [ROS package](http://wiki.ros.org/Packages),

you can use this syntax:

`<include ros_pkg="name_package" path="path_relative_to_pkg/grasp.xml"/>`

- "the XML format": xml_format.md