From 3d26e0a786aa139b36010c2173f785d708a7dc66 Mon Sep 17 00:00:00 2001 From: Ibrahim Alhas Date: Tue, 22 Oct 2024 20:05:58 +0100 Subject: [PATCH] updated docs to take effect on AAI v4.2.0 changes + Minor doc typo fixes/changes. --- docs/Arena-Environment-Guide.md | 11 ++-- docs/Arena-Object-Definitions.md | 100 ++++++++++++++----------------- 2 files changed, 50 insertions(+), 61 deletions(-) diff --git a/docs/Arena-Environment-Guide.md b/docs/Arena-Environment-Guide.md index 422a3b1bb..cac196c4c 100644 --- a/docs/Arena-Environment-Guide.md +++ b/docs/Arena-Environment-Guide.md @@ -95,7 +95,7 @@ arenas: ##### * `blackouts` - a `list` defining the frames at which the lights are on or off during an episode. If omitted, lights remain on for the entire episode. For more information on blackouts, [see here](#blackouts). -**N. B:** These parameters are optional (except `timeLimit` and `passMark` ) and can be omitted from the configuration file. If omitted, default values are used, detailed in the [YAML Config Syntax](/docs/configGuide/YAML-Config-Syntax.md) guide. +**N. B:** The above parameters are optional (except `timeLimit` and `passMark` where if not specified, the arena will go on forever, with the agent's health and time will be frozen) and can be omitted from the configuration file. If omitted, default values are used, detailed in the [YAML Config Syntax](/docs/configGuide/YAML-Config-Syntax.md) guide. ## The Agent @@ -109,7 +109,6 @@ The controls are as follows: * `D` - move right * `C` - change camera perspective (first-person, third-person, eagle-view, only if `canChangePerspective` is `true`) * `R` - reset the arena (cycles to the next episode if `canResetEpisode` is `true`) -* `Q` - quit (exits the application upon press) The agent has a set of skins that can be used to change its appearance in the arena. The skins are as follows: @@ -140,7 +139,7 @@ The agent has a HUD that displays the following information per episode by defau | ------------------------------------------------ | ------------------------------------------------- | | ![](../docs/figs/Agent-HUD/notification-bad.png)|![](../docs/figs/Agent-HUD/notification-good.png)| -### Arena/Agent Limitations +### Animal-AI/Arena/Agent Limitations Consider the following limitations of the arena and agent: @@ -181,7 +180,7 @@ All objects can be configured using a set of parameters for each `item` Unity Ga ##### * **`colors`**: A list of `RGB` values (integers in the range `[0,255]`). If the list is empty, the color is sampled randomly. Note that not all objects can have their color changed; for those (e.g., transparent objects), this value will be ignored. -**Note**: Any of these parameters can be omitted in the configuration files per object. Omitted fields are automatically randomized. However, specifying these parameters allows for a more controlled environment in your arena(s). Any `Vector3` that contains a -1 for any of its dimensions will spawn that dimension randomly (e.g., `x: -1, y: 10, z: 2` will spawn the object randomly along the x-axis). Some objects have specific parameters applicable only to them, which are described in the [Unique/Special Objects](#uniquespecial-object-parameters). +**Note**: Any of these parameters can be omitted in the configuration files per object. Omitted fields are automatically randomized. However, specifying these parameters allows for a more controlled environment. Any `Vector3` that contains a -1 for any of its dimensions will spawn that dimension randomly (e.g., `x: -1, y: 10, z: 2` will spawn the object randomly along the x-axis). Some objects have specific parameters applicable only to them, which are described in the [Unique/Special Objects](#uniquespecial-object-parameters). **All value ranges for the above fields can be found in the [Arena Object Definitions](/docs/Arena-Object-Definitions.md) guide**. If you go above or below the range for size, it will automatically be set to the max or min, respectively. If you try to spawn objects outside the arena (e.g., `x = 41, z = 41` ) or overlapping with another object with very close spawn positions, the overlapping object will not be spawned. Objects are placed in the order defined, so the second overlapping object will not spawn. @@ -306,5 +305,5 @@ When configuring an arena, follow these rules and be aware of certain behaviors: * **Randomization**: Use `-1` or leave blank in `positions`, `sizes`, and `rotations` for random values where supported. * **Ground Level Spawning**: Setting `positions.y = 0` spawns objects at ground level with a `0.1` height buffer. * **Goal Scaling**: Goals (except red zones) scale equally on all axes. For sphere goals, only the `x` component of `Vector3` scales all axes. -* **Arena Height Bounds**: Objects can spawn at any height within the arena. Recommended height range is `0` to `50` units. Heights above `50` units may cause objects to fall from the sky, which can take time depending on their mass and drag. -* **Arena Size Bounds**: The arena is a fixed `40x40` square with coordinates ranging from `[0,40]x[0,40]`. Coordinates outside this range will be discarded. Arena size configurability is planned for the future. \ No newline at end of file +* **Arena Height Bounds**: Objects can spawn at any height within the arena. Recommended height range is `0` to `50` units. Heights above `50` units may cause objects to fall from the sky, which can take time depending on their mass and drag applied. +* **Arena Size Bounds**: The arena is a fixed `40x40` square with coordinates `[x=40,z=40]`. Coordinates outside this range will be discarded. Arena size configurability is a planned feature for the future. \ No newline at end of file diff --git a/docs/Arena-Object-Definitions.md b/docs/Arena-Object-Definitions.md index 7cf42b4fd..47ddb7564 100644 --- a/docs/Arena-Object-Definitions.md +++ b/docs/Arena-Object-Definitions.md @@ -33,12 +33,12 @@ All except `name` and `positions` parameters can be omitted in the configuration ## The Arena
- New Default Arena + New Default Arena
Animal-AI Default Arena (Animal-AI v4.1.0)
-A single Arena, as shown above, comes with a single Agent (spherical animal, [see below](#the-agent)), a floor, and four walls. It is a square of size 40x40, with the origin (the bottom-left corner) at `(0,0)`. You can provide coordinates for objects in the range `[0,40]x[0,40]` as floats. +A single _Arena_, as shown above, comes with a single _Agent_ (spherical animal), a ground, and four walls/boundaries. It is a square of size 40x40, with the origin (the bottom-left corner) at `(0,0)`. You can provide coordinates for objects in xy,z axis in the range `[0,39.9],[0,~],[0,39.9]` as floats (note y axis is the vertical axis and can be unbounded). Note that in Unity, the **y** axis is the vertical axis. In the above picture, with the agent on the ground in the center of the environment, the Agent's coordinates are `(x = 20, y = 0, z = 20)`. @@ -48,7 +48,7 @@ The agent can be placed anywhere in the arena with any rotation. It has a fixed * **Name**: `Agent` * **Size**: `(1,1,1)` (not changeable) -* **Skins** (`skins`): `"hedgehog"`, `"panda"`, `"pig"` (can be randomized) +* **Skins**: `"hedgehog"`, `"panda"`, `"pig"` (can be randomized) Notes: The agent can be frozen for a specified number of frames at the start of an episode. There is no reward decrement during the frozen period. This can be set with an integer value passed to the `frozenAgentDelays` parameter (defaults to `0`). @@ -63,7 +63,7 @@ Notes: The agent can be frozen for a specified number of frames at the start of ## Immovable Objects -_Immovable_ objects are fixed in place and cannot be moved. The outer walls of the arena are also immovable and are permanently fixed in place to prevent the player/agent from escaping the arena. +_Immovable_ objects are fixed in place and cannot be moved. The outer walls of the arena are also immovable and are permanently fixed in place to prevent the player/agent from escaping the arena. Immovable objecs are available from Animal-AI v2.0.0. ### Wall @@ -107,7 +107,7 @@ _Immovable_ objects are fixed in place and cannot be moved. The outer walls of t ## Movable Objects -_Movable_ objects can be easily moved by the agent or other objects. These objects can be pushed by the player/agent as the physics engine is enabled for these objects directly. Note that these objects have aliases (alternative names) for backwards compatibility with previous versions of AAI. +_Movable_ objects can be easily moved by the agent or other objects. These objects can be pushed by the player/agent as the physics engine is enabled for these objects. Note that some movable objects have aliases (alternative names, now deprecated) for backwards compatibility with previous versions of AAI. ### Light Block @@ -117,7 +117,7 @@ _Movable_ objects can be easily moved by the agent or other objects. These objec * **Name**: `LightBlock` * **Size Range**: `(0.5,0.5,0.5)-(10,10,10)` -* **Color**: Not changeable / (stone textured) +* **Color**: Changeable / (stone textured) from AAI v4.2.0 onwards * **Alias**: `CardBox1` _Updated textures (right) available from Animal-AI v4.2.0 onwards._ @@ -130,7 +130,7 @@ _Updated textures (right) available from Animal-AI v4.2.0 onwards._ * **Name**: `HeavyBlock` * **Size Range**: `(0.5,0.5,0.5)-(10,10,10)` -* **Color**: Not changeable / (stone textured) +* **Color**: Changeable / (stone textured) from AAI v4.2.0 onwards * **Alias**: `CardBox2` _Updated textures (right) available from Animal-AI v4.2.0 onwards._ @@ -141,7 +141,7 @@ _Updated textures (right) available from Animal-AI v4.2.0 onwards._ * **Name**: `UBlock` * **Size Range**: `(1,0.3,3)-(5,2,20)` -* **Color**: Not changeable / (grey) +* **Color**: Changeable / (cardboard textured) from AAI v4.2.0 onwards * **Alias**: `UObject` ### L-shaped Block @@ -150,7 +150,7 @@ _Updated textures (right) available from Animal-AI v4.2.0 onwards._ * **Name**: `LBlock` * **Size Range**: `(1,0.3,3)-(5,2,20)` -* **Color**: Not changeable / (grey) +* **Color**: Changeable / (cardboard textured) from AAI v4.2.0 onwards * **Alias**: `LObject` ### J-shaped Block @@ -159,7 +159,7 @@ _Updated textures (right) available from Animal-AI v4.2.0 onwards._ * **Name**: `JBlock` * **Size Range**: `(1,0.3,3)-(5,2,20)` -* **Color**: Not changeable / (grey) +* **Color**: Changeable / (cardboard textured) from AAI v4.2.0 onwards * **Alias**: `JObject` ### Hollow Box @@ -168,7 +168,7 @@ _Updated textures (right) available from Animal-AI v4.2.0 onwards._ * **Name**: `HollowBox` * **Size Range**: (`1.10 x 1.10 x 1.10`) -* **Color**: Not changeable / (grey) +* **Color**: Changeable / (cardboard textured) from AAI v4.2.0 onwards _Available from Animal-AI v4.2.0 onwards._ @@ -181,70 +181,65 @@ Valenced objects increase or decrease the agent's reward when the agent touches * **Name**: `GoodGoal` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (green) -* **Valence**: Positive, proportional to size +* **Size Range**: `1` +* **Color**: Changeable / (green) from AAI v4.2.0 onwards +* **Valence**: Positive ### Moving Episode-Ending Positive Goal * **Name**: `GoodGoalBounce` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (green) -* **Valence**: Positive, proportional to size +* **Size Range**: `1` +* **Color**: Changeable / (green) from AAI v4.2.0 onwards +* **Valence**: Positive ### Non-Episode-Ending Positive Multi Goal * **Name**: `GoodGoalMulti` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (green) -* **Valence**: Positive, proportional to size - -Notes: The `rotations` parameter sets the direction of motion. +* **Size Range**: `1` +* **Color**: Not changeable / (green) from AAI v4.2.0 onwards +* **Valence**: Positive ### Stationary Episode-Ending Negative Goal * **Name**: `BadGoal` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (red) -* **Valence**: Negative, proportional to size +* **Size Range**: `-1` +* **Color**: Changeable / (red) from AAI v4.2.0 onwards +* **Valence**: Negative ### Moving Episode-Ending Negative Goal * **Name**: `BadGoalBounce` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (red) -* **Valence**: Negative, proportional to size +* **Size Range**: `-1` +* **Color**: Changeable / (red) from AAI v4.2.0 onwards +* **Valence**: Negative ### Non-Episode-Ending Negative Multi Goal -* **Name**: `BadGoalMulti` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (orange) -* **Valence**: Negative, proportional to size +* **Name**: `BadGoalMulti.experimental` +* **Size Range**: `-0.003` +* **Color**: Changeable / (orange) from AAI v4.2.0 onwards +* **Valence**: Negative _Available from Animal-AI v4.2.0 onwards._ -Notes: The `rotations` parameter sets the direction of motion. - - ### Stationary Non-Episode-Ending Positive Goal * **Name**: `GoodGoalMulti` -* **Size Range**: `0.5-5` -* **Color**: Not changeable / (yellow) -* **Valence**: Positive, proportional to size +* **Size Range**: `0.5-1` +* **Color**: Changeable / (yellow) from AAI v4.2.0 onwards +* **Valence**: Positive ### Moving Non-Episode-Ending Positive Goal @@ -252,10 +247,8 @@ Notes: The `rotations` parameter sets the direction of motion. * **Name**: `GoodGoalMultiBounce` * **Size Range**: `0.5-5` -* **Color**: Not changeable / (yellow) -* **Valence**: Positive, proportional to size - -Notes: The `rotations` parameter sets the direction of motion. +* **Color**: Changeable / (yellow) from AAI v4.2.0 onwards +* **Valence**: Positive ### Non-Episode-Ending Ripen Goal @@ -263,7 +256,7 @@ Notes: The `rotations` parameter sets the direction of motion. * **Name**: `RipenGoal` * **Valence Range**: `0-5` -* **Size**: automatically sets to final reward value (dynamic) +* **Size**: Automatically sets to final reward value (dynamic), proportionally to the `ripenRate` * **Color**: Not changeable / (yellow and blue) * **Ripen Onset Delay Range (frames)** (`delays`): `0-Inf` (default `150`) * **Ripen Rate (frames)** (`changeRates`): `0.001-Inf` (default `0.005`) @@ -277,7 +270,7 @@ Note: Colour changes (from grey to yellow) and a radial-timer fills over time du * **Name**: `DecayGoal` * **Valence Range**: `0-5` -* **Size**: automatically sets to final reward value (dynamic) +* **Size**: automatically sets to final reward value (dynamic), proportionally to the `decayRate` * **Color**: Not changeable / (yellow and orange) * **Decay Onset Delay Range (frames)** (`delays`): `0-Inf` (default `150`) * **Decay Rate (frames)** (`changeRates`): `-0.001-Inf` (default `-0.005`, automatically converts to negative values if positive provided) @@ -289,26 +282,24 @@ Note: Colour changes (from yellow to grey) and a radial-timer depletes over time * **Name**: `GrowGoal` -* **Size Range**: `0-5` +* **Size Range**: `0.5-5` * **Valence Change Rate** (`changeRates`): `0.001-Inf` (default `0.005`) * **Valence**: Positive, proportional to size -* **Color**: Not changeable / (green) +* **Color**: Changeable / (green) from AAI v4.2.0 onwards * **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`) -Note: Growth halts if the the goal is trapped between/underneath other objects. Maximum size is `5` . Initial valence can be set with a float passed to the `initialValues` parameter, and valence can be set with a float passed to the `finalValues` parameter. - ### Episode-Ending Shrink Goal * **Name**: `ShrinkGoal` -* **Size Range**: `0-5` +* **Size Range**: `5-0.5` * **Valence Change Rate** (`changeRates`): `0.001-Inf` (default `0.005`) -* **Valence**: Positive, proportional to size -* **Color**: Not changeable / (green) +* **Valence**: Negative, proportional to size +* **Color**: Changeable / (green) from AAI v4.2.0 onwards * **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`) -Note: Maximum size is `5` . Initial valence can be set with a float passed to the `initialValues` parameter, and valence can be set with a float passed to the `finalValues` parameter. +Notes: Maximum size is `5` . Initial valence can be set with a float passed to the `initialValues` parameter, and valence can be set with a float passed to the `finalValues` parameter. ### Decoy Goal @@ -323,7 +314,6 @@ Note: The agent's reward is not affected when it touches the decoy goal. It is s _Available from Animal-AI v4.1.0 onwards._ - ### Episode-Ending DeathZone @@ -376,7 +366,7 @@ Notes: The tree spawns `GoodGoalMulti` . They grow on the trees before dropping * **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`) * **Alias**: `SpawnerDispenser` -Notes: The dispenser spawns `GoodGoalMulti` . The valence of the goals is proportional to their size. The number of seconds between spawnings (relative to the timescale of the environment) can be set with the `timesBetweenSpawns` parameter (default: 1.5). The object has a door that can be animated to open and close. The number of seconds before the door opens can be set with the `doorDelays` parameter (default: `10.0` ), and the number of seconds the door remains open for can be ste with the `timesBetweenDoorOpens` parameter (default: `-1` , if `< 0` then, once opened, the door stays open permanently). +Notes: The dispenser spawns `GoodGoalMulti`. The valence of the goals is proportional to their size. The number of seconds between spawnings (relative to the timescale of the environment) can be set with the `timesBetweenSpawns` parameter (default: 1.5). The object has a door that can be animated to open and close. The number of seconds before the door opens can be set with the `doorDelays` parameter (default: `10.0` ), and the number of seconds the door remains open for can be ste with the `timesBetweenDoorOpens` parameter (default: `-1` , if `< 0` then, once opened, the door stays open permanently). ### SpawnerContainerShort @@ -402,7 +392,7 @@ Notes: The dispenser spawns `GoodGoalMulti` . The valence of the goals is propor * **Color**: Not changeable / (yellow and light blue) * **Alias**: `Pillar-Button` -Notes: Spawns a goal when the player/agent *interacts* with it by colliding with the physical object. The position of the spawned goal can be set with the a `!Vector3` passed to the `rewardSpawnPos` parameter. The probability that a goal will spawn upon a press can be set with a float between 0 and 1 passed to the `spawnProbability` parameter. Different valenced objects can be spawned on different presses. A list, such as `["GoodGoal", "BadGoal", "GoodGoalMulti"]` , can be passed to `rewardNames` to define the valenced objects (only these three are supported at the moment). A corresponding list of floats between 0 and 1 can be passed to the `rewardWeights` to determine the probability of spawning each of the types of valenced object. The probabilities are normalized to sum to one. The number of frames taken for the button to depress upon touching it can be defined with `moveDurations` , and the number of frames for the button to be reset before it can be pressed again can be set with `resetDurations`. +Notes: Spawns a goal when the player/agent *interacts* with it by colliding with the physical button object (blue). The position of the spawned goal can be set with the a `!Vector3` passed to the `rewardSpawnPos` parameter. The probability that a goal will spawn upon a press can be set with a float between 0 and 1 passed to the `spawnProbability` parameter. Different valenced objects can be spawned on different presses. A list, such as `["GoodGoal", "BadGoal", "GoodGoalMulti"]` , can be passed to `rewardNames` to define the valenced objects (only these three are supported at the moment). A corresponding list of floats between 0 and 1 can be passed to the `rewardWeights` to determine the probability of spawning each of the types of valenced object. The probabilities are normalized to sum to one. The number of frames taken for the button to depress upon touching it can be defined with `moveDurations` , and the number of frames for the button to be reset before it can be pressed again can be set with `resetDurations`. ## Sign Boards