Add documentation for multi-arena episodes

CHANGELOG.md

@@ -7,8 +7,19 @@ This document records all notable changes to the Animal-AI project. It follows t
 _A small breaking change is introduced in this version for YAML configuration files. The YAML syntax for defining arenas has been updated to be more user-friendly and intuitive. The new syntax is backward incompatible with the previous version `v4.0.0`. Please refer to the updated documentation for more information._
 
 ### Added
+- _New Object: [Spawner] `Hollow-Object`._
+  - This new object is a hollow box that can be configured to have a reward spawn right above it (by setting the y axis to anything above 1). The reward will be spawned at the same x and z position as the hollow object, so it is easy to configure the reward to spawn directly above the hollow object. The hollow object can be used to create more complex environments and challenges for the agent.
+  - The new object has a few parameters specific to it, such as `rewardToSpawn` (string), `rewardSpawnPosition` (Vector3), `delayRewardSpawn` (bool), delayTime (float), and `rewardSpawnHeight` (float).
+- _New UI Element: `AAI Build Version`._
+  - Now, users will directly see the Animal-AI Build Version in the UI they are using for quick reference. It is displayed in the bottom-right corner of the UI.
+- _New Functionality: `mergeArenas`._ 
+  - This new functionality allows users to merge multiple arenas into one. This is useful for creating more complex environments with multiple arenas. The merged arenas will be placed in the same position in the scene, and the agent will be able to move between them seamlessly. An example YAML configuration file is provided in the documentation (see [here](docs/configGuide/Example-Merged-Arenas-YAML-File.yml)).
 
 ### Changed
+- YAML syntax has major (breaking) changes: 
+  - `"t"` parameter has been renamed to `"timeLimit"` to better reflect its purpose and improve readability.
+  - `"pass_mark"` parameter has been renamed to `"passMark"` for coherency with other parameters.
+  - UI text elements have been set to use the same font style for coherency.
 - _New Object: [Spawner] `Hollow-Object`._
   - This new object is a hollow box that can be configured to have a reward spawn right above it (by setting the y axis to anything above 1). The reward will be spawned at the same x and z position as the hollow object, so it is easy to configure the reward to spawn directly above the hollow object. The hollow object can be used to create more complex environments and challenges for the agent.
   - The new object has a few parameters specific to it, such as `rewardToSpawn` (string), `rewardSpawnPosition` (Vector3), `delayRewardSpawn` (bool), delayTime (float), and `rewardSpawnHeight` (float).
@@ -17,6 +28,7 @@ _A small breaking change is introduced in this version for YAML configuration fi
 - _New Functionality: `mergeArenas`._ 
   - This new functionality allows users to merge multiple arenas into one. This is useful for creating more complex environments with multiple arenas. The merged arenas will be placed in the same position in the scene, and the agent will be able to move between them seamlessly. An example YAML configuration file is provided in the documentation (see [here](docs/configGuide/Example-Merged-Arenas-YAML-File.yml)).
 
+
 ### Fixed
 
 ---

docs/configGuide/Example-Merged-Arenas-YAML-File.yml

@@ -0,0 +1,46 @@
+### IMPORTANT NOTES ###
+# 1. The YAML file must be indented correctly. The indentation must be consistent throughout the file.
+# 2. The YAML file must be saved with a .yaml extension.
+
+### IMPORTANT NEWS ###
+# As of AAI v4.1.0, the parameters "t" and "pass_mark" have been deprecated. Replace them with "timeLimit" and "passMark" respectively.
+# ... You may still use the old parameter names in AAI v4.0.0 and below.
+
+!ArenaConfig
+arenas:
+  0: !Arena
+    timeLimit: 50
+    passMark: 50
+    mergeNextArena: true # This line indicates that the next arena will be merged with this one, meaning the agent will not be reset between arenas.
+    items:
+    - !Item
+      name: GoodGoal
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 25}
+      rotations: [0]
+      sizes:
+      - !Vector3 {x: 1, y: 1, z: 1}
+    - !Item
+      name: Agent
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 20}
+      rotations: [0]
+
+  1: !Arena
+    timeLimit: 50
+    passMark: 50
+    items:
+    - !Item
+      name: GoodGoal
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 15}
+      rotations: [0]
+      sizes:
+      - !Vector3 {x: 1, y: 1, z: 1}
+    - !Item
+      name: Agent
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 20}
+      rotations: [0]
+      sizes:
+      - !Vector3 {x: 1, y: 1, z: 1}

docs/configGuide/Example-YAML-File.yaml

@@ -3,8 +3,8 @@
 # 2. The YAML file must be saved with a .yaml extension.
 
 ### IMPORTANT NEWS ###
-# As of AAI v4.1.0, the parameters "t" and "pass_mark" have been deprecated (name change). Replace them with "timeLimit" and "passMark" respectively.
-# ... You may still use the older parameter names in AAI builds v4.0.0 and below.
+# As of AAI v4.1.0, the parameters "t" and "pass_mark" have been deprecated. Replace them with "timeLimit" and "passMark" respectively.
+# ... You may still use the old parameter names in AAI v4.0.0 and below.
 
 !ArenaConfig
 arenas:

docs/configGuide/YAML-Config-Syntax.md

@@ -15,10 +15,10 @@
    3.5 [Example 5 - SpawnerButton (Interactive Objects)](#example-5---spawnerbutton-interactive-objects)
    3.6 [Example 6 - Multiple Arenas (Randomisation)](#example-6---multiple-arenas-randomisation)
    3.7 [Example 7 - Arena 'Blackouts'](#example-7---arena-blackouts)
+   3.8 [Example 8 - Multi-Arena Episodes](#example-8---multi-arena-episodes)
 4. [Conclusion](#conclusion)
 5. [Further Reading and Documentation](#further-reading-and-documentation)
 
-
 ### Introduction
 
 Let's take a look at some examples to understand how to use the YAML syntax in Animal-AI to create custom arenas. We will start with some simple examples and then move on to more complex examples. 
@@ -27,9 +27,10 @@ _Please note that becuase AAI is being developed actively, the screenshots and e
 
 **Important Notes/News:**
 
-- **As of AAI v4.1.0**, the `t` parameter has been renamed to `timeLimit` and the `pass_mark` parameter has been renamed to `passMark`. Please adjust your YAML configurations accordingly, either manually or use the Helper Script provided [here](/docs/integration/Helper-Scripts.md). However, you may still use these parameters with their older, deprecated names in AAI v4.0.0 and below.
+* **As of AAI v4.1.0**, the `t` parameter has been renamed to `timeLimit` and the `pass_mark` parameter has been renamed to `passMark`. Please adjust your YAML configurations accordingly, either manually or use the Helper Script provided [here](/docs/integration/Helper-Scripts.md). However, you may still use these parameters with their older, deprecated names in AAI v4.0.0 and below.
 
 ### Understanding YAML Syntax
+
 #### YAML Hierarchical Syntax
 
 ```YAML
@@ -73,7 +74,7 @@ arenas:
 
 We can observe:
 
-* The default values for the global parameters are as follows: `canChangePerspective: true`,  `canResetEpisode: true`,  `showNotification: false`, and `randomizeArenas: false`.
+* The default values for the global parameters are as follows: `canChangePerspective: true`,   `canResetEpisode: true`,   `showNotification: false`, and `randomizeArenas: false`.
 Bear in mind that the global parameters are optional to define. If we do not define them, the default values are used. 
 * If we do not provide global parameters, the default values are used. For example, if we do not provide a value for `canChangePerspective`, the default value of `true` is used.
 * If we provide a value for a global parameter, the value is applied to all arenas in the file. For example, if we set `canChangePerspective` to `false`, the agent will not be able to change its perspective in any of the arenas in the file. However, if we set `canChangePerspective` to `true`, the agent will be able to change its perspective in any of the arenas in the file.
@@ -204,14 +205,14 @@ arenas:
 </p>
 
 **Observations:** 
-* The number of parameters for `positions`,  `rotations`, and `sizes` do not need to match.
+* The number of parameters for `positions`,   `rotations`, and `sizes` do not need to match.
 * The environment will spawn `max(len(positions), len(rotations), len(sizes))` objects.
 * Missing parameters are assigned randomly. For example, if `positions` is specified, but `sizes` are not, the environment will randomly assign sizes values to the objects.
 
 In this scenario, the objects will spawn in the following order:
 
 * A pink Cube will appear at coordinates `[10, 10]` on the ground. It will have a rotation of `45` degrees and its size will be random along the `x` and `z` axes, with a fixed size of `y=5`.
-Another Cube will be placed on the ground at a random x coordinate and `z=30`. This cube's rotation, size, and color will all be randomly determined.
+Another Cube will be placed on the ground at a random x coordinate and `z=30` . This cube's rotation, size, and color will all be randomly determined.
 * Three CylinderTunnel objects will spawn next, and each of these will be entirely random in terms of position, size, color, and rotation.
 * A GoodGoal object will then appear, with all its attributes randomized.
 * Finally, the agent will spawn first. This is an important point to note, as it currently priority over all other objects and would be spawned first, before any other object(s).
@@ -557,6 +558,50 @@ We can observe that:
 * Additionally, if we set `blackouts` to `[-20]`, the arena will blackout every 20 frames (because we placed the '-' indicating repeat).
 * The blackout has no effect on any other aspect of the agent or the arena. For example, the agent will still be able to move around the arena, and the objects in the arena will still be visible to the agent. _RayCasting_ will still work. 
 
+#### EXAMPLE 8 - Multi-Arena Episodes
+
+```YAML
+!ArenaConfig
+arenas:
+  0: !Arena
+    t: 50
+    mergeNextArena: true # Here, we set mergeNextArena to true, which means that the next arena will be merged with this arena, creating a single episode.
+    items:
+    - !Item
+      name: GoodGoal
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 25}
+      rotations: [0]
+      sizes:
+      - !Vector3 {x: 1, y: 1, z: 1}
+    - !Item
+      name: Agent
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 20}
+      rotations: [0]
+  1: !Arena
+    t: 50
+    items:
+    - !Item
+      name: GoodGoal
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 15}
+      rotations: [0]
+      sizes:
+      - !Vector3 {x: 1, y: 1, z: 1}
+    - !Item
+      name: Agent
+      positions:
+      - !Vector3 {x: 20, y: 0, z: 20}
+      rotations: [0]
+      sizes:
+      - !Vector3 {x: 1, y: 1, z: 1}
+```
+
+**Observations:**
+
+Sometimes we would like to include multiple arenas in a single episode (for example to test in-context learning of the shape of a maze). This can be achieved by setting the `mergeNextArena` parameter to `true` . In the example above, this causes Animal-AI to treat arena 0 (where the reward is ahead of the agent) and arena 1 (where it is behind) as a single unit, only ending the episode when it is failed or both arenas are completed. More than two arenas can be merged in this way, using the `mergeNextArena` parameter in each arena to add the following arena to the episode.
+
 ### Conclusion
 
 We hope that this guide has helped you understand how to use the YAML syntax in Animal-AI to create custom arenas.