Merge branch 'doc-work'

doc_classes/BTDynamicSelector.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="BTDynamicSelector" inherits="BTComposite" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
-		BT composite that executes tasks from the beginning each tick until first [code]SUCCESS[/code].
+		BT composite that executes tasks from scratch every tick until first [code]SUCCESS[/code].
 	</brief_description>
 	<description>
-		BT composite that executes child tasks from first to last until any child returns [code]SUCCESS[/code]. BTDynamicSelector will execute tasks from the beginning each tick, reevaluating their statuses.
-		Returns [code]RUNNING[/code] if a task returns [code]RUNNING[/code], and remembers last [code]RUNNING[/code] child. In contrast to normal selector, on the next execution tick it will reexecute preceeding tasks and reevaluate their return statuses. If any of the preceeding tasks does not return [code]FAILURE[/code], it will cancel execution of the remembered [code]RUNNING[/code] task.
-		Returns [code]FAILURE[/code] if all tasks return [code]FAILURE[/code].
-		Returns [code]SUCCESS[/code] if any task returns [code]SUCCESS[/code].
+		BTDynamicSelector executes its child tasks sequentially, from first to last, until any child returns [code]SUCCESS[/code]. Unlike [BTSelector], it will execute tasks from the beginning every tick, reevaluating their statuses. It is quite useful when you want to retry higher-priority behaviors in every tick.
+		Returns [code]RUNNING[/code] if a child task results in [code]RUNNING[/code]. BTDynamicSelector will remember the last [code]RUNNING[/code] child, but, unlike [BTSequence], on the next execution tick, it will reexecute preceding tasks and reevaluate their return statuses. If any of the preceding tasks doesn't result in [code]FAILURE[/code], it will abort the remembered [code]RUNNING[/code] task.
+		Returns [code]FAILURE[/code] if all child tasks result in [code]FAILURE[/code].
+		Returns [code]SUCCESS[/code] if a child task results in [code]SUCCESS[/code].
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/BTDynamicSequence.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="BTDynamicSequence" inherits="BTComposite" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
-		BT composite that executes tasks from the beginning each tick for as long as they return [code]SUCCESS[/code].
+		BT composite that executes tasks from scratch every tick as long as they return [code]SUCCESS[/code].
 	</brief_description>
 	<description>
-		BT composite that executes child tasks from first to last for as long as they return [code]SUCCESS[/code]. BTDynamicSequence will execute tasks from the beginning each tick, reevaluating their statuses.
-		Returns [code]RUNNING[/code] if a task returns [code]RUNNING[/code], and remembers last [code]RUNNING[/code] child. In contrast to [BTSequence], on the next execution tick it will reexecute preceeding tasks and reevaluate their return statuses. If any of the preceeding tasks does not return [code]SUCCESS[/code], it will cancel execution of the remembered [code]RUNNING[/code] task.
-		Returns [code]FAILURE[/code] if any task returns [code]FAILURE[/code]. 
-		Returns [code]SUCCESS[/code] if all tasks return [code]SUCCESS[/code].
+		BTDynamicSequence executes its child tasks sequentially, from first to last, for as long as they return [code]SUCCESS[/code]. Unlike [BTSequence], it will execute tasks from the beginning every tick, reevaluating their statuses. It is quite useful when you want to recheck conditions preceding a long-running action during each tick and abort the [code]RUNNING[/code] action when any condition results in [code]FAILURE[/code].
+		Returns [code]RUNNING[/code] if a child task results in [code]RUNNING[/code]. BTDynamicSequence will remember the last [code]RUNNING[/code] child, but, unlike [BTSequence], on the next execution tick, it will reexecute preceding tasks and reevaluate their return statuses. If any of the preceding tasks doesn't result in [code]SUCCESS[/code], it will abort the remembered [code]RUNNING[/code] task.
+		Returns [code]FAILURE[/code] if a child task results in [code]FAILURE[/code].
+		Returns [code]SUCCESS[/code] if all child tasks result in [code]SUCCESS[/code].
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/BTParallel.xml

@@ -1,23 +1,23 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="BTParallel" inherits="BTComposite" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
-		BT composite that executes child tasks until one of the criteria is met.
+		BT composite that executes all of its child tasks simultaneously.
 	</brief_description>
 	<description>
-		BTParallel executes its child tasks until one of the criterea is met. It will execute each task at least once, from the first to the last, before returning a result.
-		If set to [member repeat], the child tasks will be re-executed, regardless of whether they previously resulted in a [code]SUCCESS[/code] or [code]FAILURE[/code].
-		Returns [code]FAILURE[/code] when the required number of tasks return [code]FAILURE[/code]. When [member repeat] is set to [code]false[/code], if none of the criteria were met, and all child tasks resulted in a [code]SUCCESS[/code] or [code]FAILURE[/code], BTParallel will return [code]FAILURE[/code].
-		Returns [code]SUCCESS[/code] when the required number of tasks return [code]SUCCESS[/code].
+		BTParallel executes all of its child tasks simultaneously. Note that BTParallel doesn't involve multithreading. It processes each task sequentially, from first to last, in the same tick before returning a result. If one of the abort criterea is met, any tasks currently [code]RUNNING[/code] will be terminated, and the result will be either [code]FAILURE[/code] or [code]SUCCESS[/code]. The [member num_failures_required] determines when BTParallel fails and [member num_successes_required] when it succeeds. When both are fullfilled, it gives priority to [member num_failures_required].
+		If set to [member repeat], all child tasks will be re-executed each tick, regardless of whether they previously resulted in [code]SUCCESS[/code] or [code]FAILURE[/code].
+		Returns [code]FAILURE[/code] when the required number of child tasks result in [code]FAILURE[/code]. When [member repeat] is set to [code]false[/code], if none of the criteria were met and all child tasks resulted in either [code]SUCCESS[/code] or [code]FAILURE[/code], BTParallel will return [code]FAILURE[/code].
+		Returns [code]SUCCESS[/code] when the required number of child tasks result in [code]SUCCESS[/code].
 		Returns [code]RUNNING[/code] if none of the criterea were fulfilled, and either [member repeat] is set to [code]true[/code] or a child task resulted in [code]RUNNING[/code].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="num_failures_required" type="int" setter="set_num_failures_required" getter="get_num_failures_required" default="1">
-			When the specified number of child tasks return [code]SUCCESS[/code], BTParallel will also return [code]SUCCESS[/code].
+			If the specified number of child tasks return [code]SUCCESS[/code], BTParallel will also return [code]SUCCESS[/code].
 		</member>
 		<member name="num_successes_required" type="int" setter="set_num_successes_required" getter="get_num_successes_required" default="1">
-			When the specified number of child tasks return [code]FAILURE[/code], BTParallel will also return [code]FAILURE[/code].
+			If the specified number of child tasks return [code]FAILURE[/code], BTParallel will also return [code]FAILURE[/code].
 		</member>
 		<member name="repeat" type="bool" setter="set_repeat" getter="get_repeat" default="false">
 			When [code]true[/code], the child tasks will be executed again, regardless of whether they previously resulted in a [code]SUCCESS[/code] or [code]FAILURE[/code].

doc_classes/BTProbabilitySelector.xml

@@ -5,10 +5,10 @@
 	</brief_description>
 	<description>
 		BTProbabilitySelector chooses a child task to execute based on attached probabilities. It is typically used for decision-making purposes. Probability distribution is calculated based on weights assigned to each child task.
-		Returns [code]SUCCESS[/code] when a child task returns [code]SUCCESS[/code].
-		Returns [code]RUNNING[/code] when a child task returns [code]RUNNING[/code].
-		The behavior of BTProbabilitySelector when a child task results in [code]FAILURE[/code] depends on the value of the [member abort_on_failure] property:
-		- If [member abort_on_failure] is [code]false[/code], when a child task results in [code]FAILURE[/code], BTProbabilitySelector will normalize the probability distribution over the remaiming children and choose a new child task to be executed. If all child tasks fail, the composite will return [code]FAILURE[/code].
+		Returns [code]SUCCESS[/code] when a child task results in [code]SUCCESS[/code].
+		Returns [code]RUNNING[/code] when a child task results in [code]RUNNING[/code].
+		The behavior of BTProbabilitySelector when a child task results in [code]FAILURE[/code] depends on the [member abort_on_failure] value:
+		- If [member abort_on_failure] is [code]false[/code], when a child task results in [code]FAILURE[/code], BTProbabilitySelector will normalize the probability distribution over the remaining children and choose a new child task to be executed. If all child tasks fail, the composite will return [code]FAILURE[/code].
 		- If [member abort_on_failure] is [code]true[/code], when a child task results in [code]FAILURE[/code], BTProbabilitySelector will not choose another child task to be executed and will immediately return [code]FAILURE[/code].
 	</description>
 	<tutorials>

doc_classes/BTRandomSelector.xml

@@ -4,10 +4,10 @@
 		BT composite that executes tasks in random order until first [code]SUCCESS[/code].
 	</brief_description>
 	<description>
-		BT composite that executes child tasks in random order until any child returns [code]SUCCESS[/code].
-		Returns [code]RUNNING[/code] if a task returns [code]RUNNING[/code], and remembers last [code]RUNNING[/code] child and the order of execution. BTRandomSelector will continue where it left off on the next execution tick. 
-		Returns [code]FAILURE[/code] if all tasks return [code]FAILURE[/code]. 
-		Returns [code]SUCCESS[/code] if any task returns [code]SUCCESS[/code].
+		BTRandomSelector executes its child tasks in a random order until any child returns [code]SUCCESS[/code]. If a child task results in [code]FAILURE[/code], BTRandomSelector will immediately execute another child task until one of them returns [code]SUCCESS[/code] or all of them result in [code]FAILURE[/code].
+		Returns [code]RUNNING[/code] if a child task results in [code]RUNNING[/code]. BTRandomSelector will remember the execution order and the last child task that returned [code]RUNNING[/code], ensuring it resumes from that point in the next tick.
+		Returns [code]FAILURE[/code] if all child tasks result in [code]FAILURE[/code].
+		Returns [code]SUCCESS[/code] if a child task results in [code]SUCCESS[/code].
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/BTRandomSequence.xml

@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="BTRandomSequence" inherits="BTComposite" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
-		BT composite that executes tasks in random order for as long as they return [code]SUCCESS[/code].
+		BT composite that executes tasks in random order as long as they return [code]SUCCESS[/code].
 	</brief_description>
 	<description>
-		BTRandomSequence executes child tasks in random order for as long as they return [code]SUCCESS[/code].
-		Returns [code]RUNNING[/code] if a task returns [code]RUNNING[/code], and remembers last [code]RUNNING[/code] child and the order of execution. BTRandomSequence will continue where it left off on the next execution tick. 
-		Returns [code]FAILURE[/code] if any task returns [code]FAILURE[/code]. 
-		Returns [code]SUCCESS[/code] if all tasks return [code]SUCCESS[/code].
+		BTRandomSequence executes its child tasks in a random order as long as they return [code]SUCCESS[/code]. If a child task results in [code]SUCCESS[/code], BTRandomSequence will immediately execute the next child task until one of them returns [code]FAILURE[/code] or all of them result in [code]SUCCESS[/code].
+		Returns [code]RUNNING[/code] if a child task results in [code]RUNNING[/code]. BTRandomSequence will remember the execution order and the last child task that returned [code]RUNNING[/code], ensuring it resumes from that point in the next tick.
+		Returns [code]FAILURE[/code] if a child task results in [code]FAILURE[/code].
+		Returns [code]SUCCESS[/code] if all child tasks result in [code]SUCCESS[/code].
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/BTSelector.xml

@@ -4,10 +4,10 @@
 		BT composite that sequentially executes tasks until first [code]SUCCESS[/code].
 	</brief_description>
 	<description>
-		BTSelector executes its child tasks sequentially, from first to last, until any child returns [code]SUCCESS[/code].
-		Returns [code]RUNNING[/code] if any child task returns [code]RUNNING[/code]. The composite will also remember the last child task that returned [code]RUNNING[/code], ensuring it resumes from that point in the next execution tick.
-		Returns [code]FAILURE[/code] if all child tasks return [code]FAILURE[/code].
-		Returns [code]SUCCESS[/code] if a child task returns [code]SUCCESS[/code].
+		BTSelector executes its child tasks sequentially, from first to last, until any child returns [code]SUCCESS[/code]. If a child task results in [code]FAILURE[/code], BTSelector will immediately execute the next child task until one of them returns [code]SUCCESS[/code] or all of them result in [code]FAILURE[/code]. BTSelector and [BTSequence] are two of the most common building blocks of behavior trees. Essentially, while [BTSequence] is similar to a boolean AND operation, BTSelector is similar to a boolean OR operation. Selectors enable the behavior tree to respond to changes in the environment and trigger transitions between various fallback behaviors.
+		Returns [code]RUNNING[/code] if a child task results in [code]RUNNING[/code]. BTSelector will remember the last child task that returned [code]RUNNING[/code], ensuring it resumes from that point in the next execution tick.
+		Returns [code]SUCCESS[/code] if a child task results in [code]SUCCESS[/code].
+		Returns [code]FAILURE[/code] if all child tasks result in [code]FAILURE[/code].
 	</description>
 	<tutorials>
 	</tutorials>

doc_classes/BTSequence.xml

@@ -4,10 +4,10 @@
 		BT composite that sequentially executes tasks as long as they return [code]SUCCESS[/code].
 	</brief_description>
 	<description>
-		BTSequence executes its child tasks sequentially, from first to last, as long as they return [code]SUCCESS[/code].
-		Returns [code]RUNNING[/code] if any child task returns [code]RUNNING[/code]. The composite will also remember the last child task that returned [code]RUNNING[/code], ensuring it resumes from that point in the next execution tick.
-		Returns [code]FAILURE[/code] if a child task returns [code]FAILURE[/code].
-		Returns [code]SUCCESS[/code] if all child tasks return [code]SUCCESS[/code].
+		BTSequence executes its child tasks sequentially, from first to last, as long as they return [code]SUCCESS[/code]. If a child task results in [code]SUCCESS[/code], BTSequence will immediately execute the next child task until one of them returns [code]FAILURE[/code] or all of them result in [code]SUCCESS[/code]. BTSequence and [BTSelector] are two of the most common building blocks of behavior trees. Essentially, while [BTSelector] is similar to a boolean OR operation, BTSequence is similar to a boolean AND operation. Sequences enable the behavior tree to compose complex behaviors from a chain of simpler tasks.
+		Returns [code]RUNNING[/code] if any child task results in [code]RUNNING[/code]. BTSequence will remember the last child task that returned [code]RUNNING[/code], ensuring it resumes from that point in the next execution tick.
+		Returns [code]SUCCESS[/code] if all child tasks result in [code]SUCCESS[/code].
+		Returns [code]FAILURE[/code] if a child task results in [code]FAILURE[/code].
 	</description>
 	<tutorials>
 	</tutorials>

editor/task_palette.cpp

@@ -402,7 +402,7 @@ void TaskPalette::refresh() {
 
 			String descr;
 			if (E) {
-				if (E->value.description.is_empty() || E->value.description.length() > 1000) {
+				if (E->value.description.is_empty() || E->value.description.length() > 1400) {
 					descr = DTR(E->value.brief_description);
 				} else {
 					descr = DTR(E->value.description);