From 96479bc93f81f6a66bdf335b99aa8ae9dc0470ca Mon Sep 17 00:00:00 2001
From: Lena Linke <130255332+lenalinke@users.noreply.github.com>
Date: Sat, 27 Apr 2024 02:47:09 +0200
Subject: [PATCH] Add documentation regarding TaskBundles to
 quickstart-guide.md and task-bundle.md

---
 .../ScheduleBasedExecution/TaskActions.cs     |  5 +-
 .../TaskBundle Sample/TaskBundleController.cs |  3 +-
 Documentation/manual/quickstart-guide.md      |  9 ++--
 Documentation/manual/task-bundle.md           | 47 +++++++++++++++++++
 Documentation/manual/toc.yml                  |  2 +
 5 files changed, 60 insertions(+), 6 deletions(-)
 create mode 100644 Documentation/manual/task-bundle.md

diff --git a/Assets/Virtual Agents Framework/Runtime/Scripts/ScheduleBasedExecution/TaskActions.cs b/Assets/Virtual Agents Framework/Runtime/Scripts/ScheduleBasedExecution/TaskActions.cs
index 152ddd8..78909e0 100644
--- a/Assets/Virtual Agents Framework/Runtime/Scripts/ScheduleBasedExecution/TaskActions.cs	
+++ b/Assets/Virtual Agents Framework/Runtime/Scripts/ScheduleBasedExecution/TaskActions.cs	
@@ -124,7 +124,8 @@ public AgentBaseTask PickUp(GameObject pickupObject, int priority = 0, SocketId
         /// <returns></returns>
         public AgentBaseTask GoToAndPickUp(GameObject destinationObject, int priority = 0, SocketId bodyAttachPoint = SocketId.RightHand, float minDistance = 0.3f)
         {
-            AgentMovementTask goToTask = (AgentMovementTask)GoTo(destinationObject, default, priority, true);
+            // TODO: return this as TaskBundle
+            AgentMovementTask goToTask = (AgentMovementTask) GoTo(destinationObject, default, priority, true);
             goToTask.MinDistance = minDistance;
 
             AgentBaseTask pickUpTask = PickUp(destinationObject, priority, bodyAttachPoint);
@@ -154,6 +155,7 @@ public AgentBaseTask DropItem(GameObject dropObject = null, int priority = 0)
         /// <returns></returns>
         public AgentBaseTask GoToAndDropItem(Vector3 destinationCoordinates, GameObject dropObject = null, int priority = 0)
         {
+            // TODO: return this as TaskBundle
             AgentBaseTask goToTask = GoTo(destinationCoordinates, priority);
             AgentBaseTask dropTask = DropItem(dropObject, priority);
             return dropTask;
@@ -168,6 +170,7 @@ public AgentBaseTask GoToAndDropItem(Vector3 destinationCoordinates, GameObject
         /// <returns></returns>
         public AgentBaseTask GoToAndDropItem(Transform destinationTransform, GameObject dropObject = null, int priority = 0)
         {
+            // TODO: return this as TaskBundle
             AgentBaseTask goToTask = GoTo(destinationTransform, default, priority);
             AgentBaseTask dropTask = DropItem(dropObject, priority);
             return dropTask;
diff --git a/Assets/Virtual Agents Framework/Samples/TaskBundle Sample/TaskBundleController.cs b/Assets/Virtual Agents Framework/Samples/TaskBundle Sample/TaskBundleController.cs
index b915489..2212af4 100644
--- a/Assets/Virtual Agents Framework/Samples/TaskBundle Sample/TaskBundleController.cs	
+++ b/Assets/Virtual Agents Framework/Samples/TaskBundle Sample/TaskBundleController.cs	
@@ -26,7 +26,7 @@ protected override void Start()
             // Parameters can be added in brackets on the left side of the arrow
             preconditions.Add(() =>
             {
-                // This lambda function checks if the agent is close to the first waypoint
+                // This lambda function checks if the agent is close to the last waypoint
                 // If a precondition is not met, the TaskBundle will not be executed
                 // Compare vectors equality with accuracy of 0.5
                 float distance = Vector3.Distance(waypoints[waypoints.Count -1].position, agent.transform.position);
@@ -44,6 +44,7 @@ protected override void Start()
             // This TaskBundle will be executed because the agent is not close to the last waypoint
             TaskBundle taskBundleSuccess = new TaskBundle(this, tasks, preconditions);
 
+
             // Create a new TaskBundle with the tasks and preconditions
             // This TaskBundle will not be executed
             // because after executing the taskBundleSuccess the agent is close to the last waypoint
diff --git a/Documentation/manual/quickstart-guide.md b/Documentation/manual/quickstart-guide.md
index 28bb2ab..c7ddc06 100644
--- a/Documentation/manual/quickstart-guide.md
+++ b/Documentation/manual/quickstart-guide.md
@@ -53,10 +53,11 @@ Going from least to most complex, it is recommended to look at the samples in th
 1. Navigation Sample
 2. Wait Sample
 3. Dynamic Navigation Sample
-4. Parallel Task Sample ([manual page](parallel-tasks.md))
-5. Aiming Sample ([manual page](aiming.md))
-6. Adaptive Gaze Sample ([manual page](adaptive-gaze.md))
-7. Item Pickup Sample ([manual page](items.md))
+4. TaskBundle Sample ([manual page](task-bundle.md))
+5. Parallel Task Sample ([manual page](parallel-tasks.md))
+6. Aiming Sample ([manual page](aiming.md))
+7. Adaptive Gaze Sample ([manual page](adaptive-gaze.md))
+8. Item Pickup Sample ([manual page](items.md))
 
 ## Customization of agents
 To make the application look more appealing from the beginning custom agent models can be used, see [Adding Own Agent Models and Animations](own-agents.md) for that.
diff --git a/Documentation/manual/task-bundle.md b/Documentation/manual/task-bundle.md
new file mode 100644
index 0000000..6cbd036
--- /dev/null
+++ b/Documentation/manual/task-bundle.md
@@ -0,0 +1,47 @@
+# TaskBundles
+TaskBundles are a way to group multiple sub-tasks together.
+The resulting task bundle can be added to a task system like any other task.
+A TaskBundle can also include a list of boolean preconditions.
+They are checked beforehand and determine if the TaskBundle prematurely finishes, in the event that one of the preconditions is not met.
+Tasks in a TaskBundle are executed back to back in sequence and cannot be interrupted by other tasks.
+
+# Construct a TaskBundle
+The are three TaskBundle constructors, that can be used to create a TaskBundle:
+1. `TaskBundle(MonoBehaviour coroutineHost)`
+2. `TaskBundle(MonoBehaviour coroutineHost, List<AgentBaseTask> tasks)`
+3. `TaskBundle(MonoBehaviour coroutineHost, List<AgentBaseTask> tasks, List<Func <bool>> preconditions)`
+
+The `coroutineHost` is the MonoBehaviour that will host the coroutine that executes the TaskBundle.
+`tasks` is a list of subtasks. Of note is, that TaskActions cannot be used here, as they would also add the sub-tasks to the regular scheduler.
+`preconditions` is a list of boolean functions, so in particular lambda expressions can be used.
+Other functions may be evaluated beforehand, so are not suitable for this purpose.
+The lambda functions must return a boolean value. `() => {...}` syntax is a lambda expression that defines an anonymous function inline.
+Parameters can be added in brackets on the left side of the arrow.
+
+Example:
+```csharp
+public List<Transform> waypoints;
+List<AgentBaseTask> tasks = new List<AgentBaseTask>();
+List<System.Func<bool>> preconditions = new List<System.Func<bool>>();
+preconditions.Add(() =>
+            {
+                // This lambda function checks if the agent is close to the last waypoint
+                // Compare vectors equality with accuracy of 0.5
+                float distance = Vector3.Distance(waypoints[waypoints.Count -1].position, agent.transform.position);
+                return distance > 1.0f;
+            });
+for (int i = 0; i < waypoints.Count; i++)
+            {
+                tasks.Add(new AgentMovementTask(waypoints[i].position));
+            }
+TaskBundle myTaskBundle = new TaskBundle(this, tasks, preconditions);
+```
+
+
+# Example Scene
+
+The framework contains one example scene that more comprehensively demonstrates the use of TaskBundles.
+In the `TaskBundleSample` the agent attempts to execute two TaskBundles, of which only one's preconditions are met.
+
+The `TaskBundleController` has the option to add multiple waypoints where the agent should walk.
+At the end of the execution of the first TaskBundle, the agent is close to the last waypoint, which leads to the precondition of the second bundle to fail.
\ No newline at end of file
diff --git a/Documentation/manual/toc.yml b/Documentation/manual/toc.yml
index fa6d66a..663e289 100644
--- a/Documentation/manual/toc.yml
+++ b/Documentation/manual/toc.yml
@@ -12,6 +12,8 @@
       href: adaptive-gaze.md
     - name: Aiming and Pointing
       href: aiming.md
+    - name: TaskBundles
+      href: task-bundle.md
 - name: Customization
   items:
     - name: Adding Own Agent Models and Animations