diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 000000000..5008ddfcf Binary files /dev/null and b/.DS_Store differ diff --git a/docs/BT_basics.md b/docs/BT_basics.md index 12b396059..14044e6af 100644 --- a/docs/BT_basics.md +++ b/docs/BT_basics.md @@ -8,7 +8,7 @@ The __leaves__ of the tree are the actual commands, i.e. the place where our coordinating component interacts with the rest of the system. For instance, in a service-oriented architecture, the leaves would contain -the "client" code that communicate with the "server" that performs the +the "client" code that communicates with the "server" that performs the operation. In the following example, we can see two Actions executed in a sequence, @@ -19,7 +19,7 @@ In the following example, we can see two Actions executed in a sequence, The other nodes of the tree, those which are __not leaves__, control the "flow of execution". -To better understand how this control flow takes place , imagine a signal +To better understand how this control flow takes place, imagine a signal called "__tick__"; it is executed at the __root__ of the tree and it propagates through the branches until it reaches one or multiple leaves. @@ -51,10 +51,10 @@ which child should be ticked next or may return a result to its own parent. __ControlNodes__ are nodes which can have 1 to N children. Once a tick is received, this tick may be propagated to one or more of the children. -__DecoratorNodes__ is similar to the ControlNode, but it can have only a single child. +__DecoratorNodes__ are similar to the ControlNode, but can only have a single child. __ActionNodes__ are leaves and do not have any children. The user should -implement their own ActionNodes to perform the actual task. +implement their own ActionNodes to perform the actual tasks. __ConditionNodes__ are equivalent to ActionNodes, but they are always atomic and synchronous, i.e. they must not return RUNNING. @@ -65,7 +65,7 @@ They should not alter the state of the system. ## Examples -To better understand how a BehaviorTrees work, let's focus on some practical +To better understand how BehaviorTrees work, let's focus on some practical examples. For the sake of simplicity we will not take into account what happens when an action returns RUNNING. @@ -108,7 +108,7 @@ You can extend your grammar creating your own Decorators. ![Simple Decorator: Enter Room](images/DecoratorEnterRoom.png) The node __Inverter__ is a Decorator that inverts -the result returned by its child; Inverter followed by the node called +the result returned by its child; An Inverter followed by the node called __DoorOpen__ is therefore equivalent to "Is the door closed?". @@ -133,9 +133,9 @@ But... ### Second ControlNode: Fallback -[FallbackNodes](FallbackNode.md), known also as __"Selector"__, +[FallbackNodes](FallbackNode.md), known also as __"Selectors"__, are nodes that can express, as the name suggests, fallback strategies, -ie. what to do next if a child returns FAILURE. +i.e. what to do next if a child returns FAILURE. It ticks the children in order and: @@ -144,7 +144,7 @@ It ticks the children in order and: Fallback returns SUCCESS. - If all the children return FAILURE, then the Fallback returns FAILURE too. -In the next example, you can see how Sequence and Fallbacks can be combined: +In the next example, you can see how Sequences and Fallbacks can be combined: ![FallbackNodes](images/FallbackBasic.png) diff --git a/docs/FallbackNode.md b/docs/FallbackNode.md index ffba22972..5732dc06b 100644 --- a/docs/FallbackNode.md +++ b/docs/FallbackNode.md @@ -17,14 +17,14 @@ They share the following rules: - If a child returns __SUCCESS__, it stops and returns __SUCCESS__. All the children are halted. -The two version of fallback differ in the way they react when a child returns +The two versions of Fallback differ in the way they react when a child returns RUNNING: -- Plain old Fallback will return RUNNING and, the next time it is ticked, - it will tick the same child. +- FallbackStar will return RUNNING and the next time it is ticked, + it will tick the same child where it left off before. - Plain old Fallback will return RUNNING and the index of the next child to - execute is reset. + execute is reset after each execution. ## Fallback diff --git a/docs/SequenceNode.md b/docs/SequenceNode.md index 7b03836a9..094141f05 100644 --- a/docs/SequenceNode.md +++ b/docs/SequenceNode.md @@ -18,7 +18,7 @@ They share the following rules: - If the __last__ child returns __SUCCESS__ too, all the children are halted and the sequence returns __SUCCESS__. -To understand how the tree ControlNodes differ, refer to the following table: +To understand how the three ControlNodes differ, refer to the following table: | Type of ControlNode | Child returns FAILURE | Child returns RUNNING | @@ -74,11 +74,11 @@ This node is particularly useful to continuously check Conditions; but the user should also be careful when using asynchronous children, to be sure that thy are not ticked more often that expected. -Let's take a look to another example: +Let's take a look at another example: ![ReactiveSequence](images/ReactiveSequence.png) -`ApproachEnemy` is an __asynchronous__ action that m return RUNNING until +`ApproachEnemy` is an __asynchronous__ action that returns RUNNING until it is, eventually, completed. The condition `isEnemyVisible` will be called many times and, @@ -107,8 +107,8 @@ if it becomes false (i,e, "FAILURE"), `ApproachEnemy` is halted. ## SequenceStar -Use this ControlNode when you don't want to tick again children that -return SUCCESS already +Use this ControlNode when you don't want to tick children again that +already returned SUCCESS. __Example__: diff --git a/docs/tutorial_02_basic_ports.md b/docs/tutorial_02_basic_ports.md index 7b5ca935e..069687b1e 100644 --- a/docs/tutorial_02_basic_ports.md +++ b/docs/tutorial_02_basic_ports.md @@ -27,13 +27,13 @@ of the Tree. An "entry" of the Blackboard is a __key/value pair__. -Inputs ports can read an entry in the Blackboard, whilst an Output port +Input ports can read an entry in the Blackboard, whilst an Output port can write into an entry. Let's suppose that we want to create an ActionNode called `SaySomething`, that should print a given string on `std::cout`. -Such string will be passed using an input port called `message`. +Such a string will be passed using an input port called `message`. Consider these alternative XML syntaxes: @@ -48,7 +48,7 @@ The attribute `message` in the __first node__ means: The message is read from the XML file, therefore it can not change at run-time. -The syntax of the __second node__, instead, means: +The syntax of the __second node__ instead means: "Read the current value in the entry of the blackboard called 'greetings' ". @@ -124,7 +124,7 @@ check the validity of the returned value and to decide what to do: An input port pointing to the entry of the blackboard will be valid only if another node have already wrritten "something" inside that same entry. -`ThinkWhatToSay` is an example of Node that uses a __output port__ to writes a +`ThinkWhatToSay` is an example of Node that uses an __output port__ to write a string into an entry. ```C++ @@ -151,7 +151,7 @@ class ThinkWhatToSay : public SyncActionNode }; ``` -Alternatively, most of the times for debugging purposes, it is possible to write a +Alternatively, most of the time for debugging purposes, it is possible to write a static value into an entry using the built-in Actions called `SetBlackboard`. ```XML diff --git a/docs/tutorial_03_generic_ports.md b/docs/tutorial_03_generic_ports.md index afb9679f2..c981dafaa 100644 --- a/docs/tutorial_03_generic_ports.md +++ b/docs/tutorial_03_generic_ports.md @@ -4,7 +4,7 @@ In the previous tutorials we introduced input and output ports, where the type of the port itself was a `std::string`. This is the easiest port type to deal with, because any parameter passed -from the XML definition will be (obviosly) a string. +from the XML definition will be (obviously) a string. Next, we will describe how to use any generic C++ type in your code. @@ -13,7 +13,7 @@ Next, we will describe how to use any generic C++ type in your code. __BehaviorTree.CPP__ supports automatic conversion of strings into common types, such as `int`, `long`, `double`, `bool`, `NodeStatus`, etc. -But user defined types can be supported easily. For instance: +But user defined types can be supported easily as well. For instance: ```C++ // We want to be able to use this custom type @@ -69,7 +69,7 @@ About the previous code: ## Example Similarly to the previous tutorial, we can create two custom Actions, -one will writes into a port and the other will reads from a port. +one will write into a port and the other will read from a port. ```C++ @@ -123,7 +123,7 @@ public: }; ``` -We can now connect input/output ports as usual, pointing at the same +We can now connect input/output ports as usual, pointing to the same entry of the Blackboard. The tree in the next example is a Sequence of 4 actions diff --git a/docs/tutorial_04_sequence_star.md b/docs/tutorial_04_sequence_star.md index 500c34f2f..ec51e4414 100644 --- a/docs/tutorial_04_sequence_star.md +++ b/docs/tutorial_04_sequence_star.md @@ -140,15 +140,15 @@ Expected output: Robot says: "mission completed!" ``` -You may noticed that when `executeTick()` was called, `MoveBase` returned +You may have noticed that when `executeTick()` was called, `MoveBase` returned __RUNNING__ the 1st and 2nd time, and eventually __SUCCESS__ the 3rd time. `BatteryOK` is executed only once. -If we use `ReactiveSequence` instead, when the child `MoveBase` returns RUNNING, +If we use a `ReactiveSequence` instead, when the child `MoveBase` returns RUNNING, the sequence is restarted and the condition `BatteryOK` is executed __again__. -If, at any point, `BatteryOK` returned __FAILURE__, the `MoveBase` actions +If, at any point, `BatteryOK` returned __FAILURE__, the `MoveBase` action would be _interrupted_ (_halted_, to be specific). ```XML hl_lines="3" diff --git a/docs/tutorial_05_subtrees.md b/docs/tutorial_05_subtrees.md index ad166b733..39c071624 100644 --- a/docs/tutorial_05_subtrees.md +++ b/docs/tutorial_05_subtrees.md @@ -1,6 +1,6 @@ # Composition of Behaviors with Subtree -We can build large scale behavior composing togheter smaller and reusable +We can build large scale behavior composing together smaller and reusable behaviors into larger ones. In other words, we want to create __hierarchical__ behavior trees. @@ -57,7 +57,7 @@ The desired behavior is: ## Loggers -On the C++ side we don't need to do anything to build reusable subtree. +On the C++ side we don't need to do anything to build reusable subtrees. Therefore we take this opportunity to introduce another neat feature of _BehaviorTree.CPP_ : __Loggers__. diff --git a/docs/tutorial_06_subtree_ports.md b/docs/tutorial_06_subtree_ports.md index e7ee6e085..90d12bd8c 100644 --- a/docs/tutorial_06_subtree_ports.md +++ b/docs/tutorial_06_subtree_ports.md @@ -14,7 +14,7 @@ remapping is done entirely in the XML definition. ## Example -Le't consider this Beahavior Tree. +Let's consider this Beahavior Tree. ```XML hl_lines="8 9" @@ -49,7 +49,7 @@ Le't consider this Beahavior Tree. You may notice that: -- We have a `MainTree` that include a suntree called `MoveRobot`. +- We have a `MainTree` that includes a subtree called `MoveRobot`. - We want to "connect" (i.e. "remap") ports inside the `MoveRobot` subtree with other ports in the `MainTree`. - This is done using the XMl tag ____, where the words __internal/external__ @@ -64,7 +64,7 @@ respective blackboard, not the relationship in terms of Behavior Trees. ![ports remapping](images/t06_remapping.png) In terms of C++, we don't need to do much. For debugging purpose, we may show some -information about the current state of a blackaboard with the method `debugMessage()`. +information about the current state of a blackboard with the method `debugMessage()`. ```C++ int main() diff --git a/docs/tutorial_08_additional_args.md b/docs/tutorial_08_additional_args.md index b504255e9..83ae4a388 100644 --- a/docs/tutorial_08_additional_args.md +++ b/docs/tutorial_08_additional_args.md @@ -11,9 +11,9 @@ constructor with the following signature In same cases, it is desirable to pass to the constructor of our class additional arguments, parameters, pointers, references, etc. -We will just use with the word _"parameter"_ for the rest of the tutorial. +We will just use the word _"parameter"_ for the rest of the tutorial. -Even if, theoretically, this parameters can be passed using Input Ports, +Even if, theoretically, these parameters can be passed using Input Ports, that would be the wrong way to do it if: - The parameters are know at _deployment-time_. @@ -24,7 +24,7 @@ If all these conditions are met, using ports is just cumbersome and highly disco ## The C++ example -Next, we can see two alternatice ways to pass parameters to a class: +Next, we can see two alternative ways to pass parameters to a class: either as arguments of the constructor of the class or in an `init()` method. ```C++ diff --git a/docs/tutorial_09_coroutines.md b/docs/tutorial_09_coroutines.md index 959995516..83e22321e 100644 --- a/docs/tutorial_09_coroutines.md +++ b/docs/tutorial_09_coroutines.md @@ -1,21 +1,21 @@ # Async Actions using Coroutines BehaviorTree.CPP provides two easy-to-use abstractions to create an -asynchronous Action, i.e those actions which: +asynchronous Action, i.e. those actions which: - Take a long time to be concluded. - May return "RUNNING". - Can be __halted__. -The first class is __AsyncActionNode__, that execute the tick() method in a +The first class is a __AsyncActionNode__ that executes the tick() method in a _separate thread_. -In this tutorial, we introduce __CoroActionNode__, a different action that uses +In this tutorial, we introduce the __CoroActionNode__, a different action that uses [coroutines](https://www.geeksforgeeks.org/coroutines-in-c-cpp/) to achieve similar results. The main reason is that Coroutines do not spawn a new thread and are much more efficient. -Furthermore, you don't need to worry about thread-safety in your code.. +Furthermore, you don't need to worry about thread-safety in your code... In Coroutines, the user should explicitly call a __yield__ method when he/she wants the execution of the Action to be suspended. @@ -25,7 +25,7 @@ he/she wants the execution of the Action to be suspended. ## The C++ source example -The next example can be used as a "template" of your own implementation. +The next example can be used as a "template" for your own implementation. ``` c++ @@ -113,7 +113,7 @@ class MyAsyncAction: public CoroActionNode ``` -As you may notice, the action "pretends" to wait for a request message; +As you may have noticed, the action "pretends" to wait for a request message; the latter will arrive after _100 milliseconds_. To spice things up, we create a Sequence with two actions, but the entire