The Agent as a hedgehog
The Agent as a panda
The Agent as a pig
-A single arena is as shown above, it comes with a single agent (spherical animal, [see below](#the-agent)), a floor and four walls. It is a square of size 40x40, the origin (the bottom-left corner) of the arena is `(0,0)`. You can provide coordinates for objects in the range `[0,40]x[0,40]` as floats.
+A single arena is as shown above, it comes with a single agent (spherical animal, [see below](#the-agent)), a floor and four walls. It is a square of size 40x40, the origin (the bottom-left corner) of the arena is `(0,0)` . You can provide coordinates for objects in the range `[0,40]x[0,40]` as floats.
-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 its coordinates are `(20, 0, 20)`.
+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 its coordinates are `(20, 0, 20)` .
For each arena you can provide the following parameters and a list of objects to spawn:
-- `t` an `int`, the length of an episode which can change from one episode to the other. A value of `0` means that the episode will not terminate until a reward has been collected (setting `t=0` and having no reward will lead to an infinite episode). This value is converted into a decay rate for the health of the agent. A `t` of 100 means that the agent's health will decay to 0, and the episode will end, after 100 time steps.
-- `pass_mark` an `int`, the reward threshold that should constitute a ‘pass’ in the environment. Leaving this parameter undefined leads to the default value of 0, whereby any reward value obtained by the Agent results in a pass. This parameter also determines the notifications that players receive at the end of an episode. If used, this parameter should be defined with consideration to the reward size that can feasibly be obtained by the agent in each configuration file.
-- `blackouts`
+* `t` an `int`, the length of an episode which can change from one episode to the other. A value of `0` means that the episode will not terminate until a reward has been collected (setting `t=0` and having no reward will lead to an infinite episode). This value is converted into a decay rate for the health of the agent. A `t` of 100 means that the agent's health will decay to 0, and the episode will end, after 100 time steps.
+* `pass_mark` an `int`, the reward threshold that should constitute a ‘pass’ in the environment. Leaving this parameter undefined leads to the default value of 0, whereby any reward value obtained by the Agent results in a pass. This parameter also determines the notifications that players receive at the end of an episode. If used, this parameter should be defined with consideration to the reward size that can feasibly be obtained by the agent in each configuration file.
+* `blackouts`
### Blackouts
@@ -51,27 +50,29 @@ Blackouts are parameters you can pass to each arena, which define between which
on or off. If omitted, this parameter automatically sets to have lights on for the entire episode. You can otherwise
pass two types of arguments for this parameter:
-- passing a list of frames `[5,10,15,20,25]` will start with the lights on, switch them off from frames 5 to 9 included,
+* passing a list of frames `[5,10,15,20,25]` will start with the lights on, switch them off from frames 5 to 9 included,
then back on from 15 to 19 included etc...
-- passing a single negative argument `[-20]` will automatically switch lights on and off every 20 frames.
+* passing a single negative argument `[-20]` will automatically switch lights on and off every 20 frames.
-**Note**: for infinite episodes (where `t=0`), the first point above would leave the light off after frame `25` while the second point would keep switching the lights every `20` frames indefinitely.
+**Note**: for infinite episodes (where `t=0` ), the first point above would leave the light off after frame `25` while the second point would keep switching the lights every `20` frames indefinitely.
## The Agent
The agent can be placed anywhere in the arena with any rotation. It has a fixed size and a fixed set of skins.
-- **Name**: `Agent`
-- **Size**: `(1,1,1)` (not changeable)
-- **Skins** (`skins`): `"hedgehog"`, `"panda"`, `"pig"`, `"random"`
+* **Name**: `Agent`
+* **Size**: `(1,1,1)` (not changeable)
+* **Skins** (`skins`): `"hedgehog"`, `"panda"`, `"pig"`, `"random"`
-Notes: The agent can be frozefor 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`).
+Notes: The agent can be frozefor 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` ).
The Agent as a hedgehog |
The Agent as a panda |
The Agent as a pig |
+
-- **Name**: `Wall`
-- **Size Range**: `(0.1,0.1,0.1)-(40,10,40)`
-- **Color**: RGB range `(0,0,0)-(255,255,255)`
+* **Name**: `Wall`
+* **Size Range**: `(0.1,0.1,0.1)-(40,10,40)`
+* **Color**: RGB range `(0,0,0)-(255,255,255)`
### Transparent Wall
+
-- **Name**: `WallTransparent`
-- **Size Range**: `(0.1,0.1,0.1)-(40,10,40)`
-- **Color**: Not changeable
+* **Name**: `WallTransparent`
+* **Size Range**: `(0.1,0.1,0.1)-(40,10,40)`
+* **Color**: Not changeable
### Ramp
+
-- **Name**: `Ramp`
-- **Size Range**: `(0.5,0.1,0.5)-(40,10,40)`
-- **Color**: RGB range `(0,0,0)-(255,255,255)`
+* **Name**: `Ramp`
+* **Size Range**: `(0.5,0.1,0.5)-(40,10,40)`
+* **Color**: RGB range `(0,0,0)-(255,255,255)`
### Tunnel
+
-- **Name**: `CylinderTunnel`
-- **Size Range**: `(2.5,2.5,2.5)-(10,10,10)`
-- **Color**: RGB range `(0,0,0)-(255,255,255)`
+* **Name**: `CylinderTunnel`
+* **Size Range**: `(2.5,2.5,2.5)-(10,10,10)`
+* **Color**: RGB range `(0,0,0)-(255,255,255)`
### Transparent Tunnel
+
-- **Name**: `CylinderTunnelTransparent`
-- **Size Range**: `(2.5,2.5,2.5)-(10,10,10)`
-- **Color**: Not changeable
+* **Name**: `CylinderTunnelTransparent`
+* **Size Range**: `(2.5,2.5,2.5)-(10,10,10)`
+* **Color**: Not changeable
## 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.
### Light Cardboard Block
+
-- **Name**: `LightBlock`
-- **Size Range**: `(0.5,0.5,0.5)-(10,10,10)`
-- **Color**: Not changeable
-- **Alias**: `CardBox1`
+* **Name**: `LightBlock`
+* **Size Range**: `(0.5,0.5,0.5)-(10,10,10)`
+* **Color**: Not changeable
+* **Alias**: `CardBox1`
### Heavy Cardboard Block
+
-- **Name**: `HeavyBlock`
-- **Size Range**: `(0.5,0.5,0.5)-(10,10,10)`
-- **Color**: Not changeable
-- **Alias**: `CardBox2`
+* **Name**: `HeavyBlock`
+* **Size Range**: `(0.5,0.5,0.5)-(10,10,10)`
+* **Color**: Not changeable
+* **Alias**: `CardBox2`
### U-shaped Block
+
-- **Name**: `UBlock`
-- **Size Range**: `(1,0.3,3)-(5,2,20)`
-- **Color**: Not changeable
-- **Alias**: `UObject`
+* **Name**: `UBlock`
+* **Size Range**: `(1,0.3,3)-(5,2,20)`
+* **Color**: Not changeable
+* **Alias**: `UObject`
### L-shaped Block
+
-- **Name**: `LBlock`
-- **Size Range**: `(1,0.3,3)-(5,2,20)`
-- **Color**: Not changeable
-- **Alias**: `LObject`
+* **Name**: `LBlock`
+* **Size Range**: `(1,0.3,3)-(5,2,20)`
+* **Color**: Not changeable
+* **Alias**: `LObject`
### J-shaped Block
+
-- **Name**: `JBlock`
-- **Size Range**: `(1,0.3,3)-(5,2,20)`
-- **Color**: Not changeable
-- **Alias**: `LObject2`
+* **Name**: `JBlock`
+* **Size Range**: `(1,0.3,3)-(5,2,20)`
+* **Color**: Not changeable
+* **Alias**: `LObject2`
## Valenced Objects
Valenced objects increase or decrease the agent's reward when the agent touches them. Some are stationary and some have an initial velocity at the start of an episode. Note that some of these objects have aliases (alternative names) for backwards compatibility with previous versions of AAI.
### Stationary Episode-Ending Positive Goal
+
-- **Name**: `GoodGoal`
-- **Size Range**: `0.5-5`
-- **Color**: Not changeable
-- **Valence**: Positive, proportional to size
+* **Name**: `GoodGoal`
+* **Size Range**: `0.5-5`
+* **Color**: Not changeable
+* **Valence**: Positive, proportional to size
### Moving Episode-Ending Positive Goal
+
-- **Name**: `GoodGoalBounce`
-- **Size Range**: `0.5-5`
-- **Color**: Not changeable
-- **Valence**: Positive, proportional to size
+* **Name**: `GoodGoalBounce`
+* **Size Range**: `0.5-5`
+* **Color**: Not changeable
+* **Valence**: Positive, proportional to size
Notes: The `rotations` parameter sets the direction of motion.
### Stationary Episode-Ending Negative Goal
+
-- **Name**: `BadGoal`
-- **Size Range**: `0.5-5`
-- **Color**: Not changeable
-- **Valence**: Negative, proportional to size
+* **Name**: `BadGoal`
+* **Size Range**: `0.5-5`
+* **Color**: Not changeable
+* **Valence**: Negative, proportional to size
### Moving Episode-Ending Negative Goal
+
-- **Name**: `BadGoalBounce`
-- **Size Range**: `0.5-5`
-- **Color**: Not changeable
-- **Valence**: Negative, proportional to size
+* **Name**: `BadGoalBounce`
+* **Size Range**: `0.5-5`
+* **Color**: Not changeable
+* **Valence**: Negative, proportional to size
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
-- **Valence**: Positive, proportional to size
+* **Name**: `GoodGoalMulti`
+* **Size Range**: `0.5-5`
+* **Color**: Not changeable
+* **Valence**: Positive, proportional to size
### Moving Non-Episode-Ending Positive Goal
+
-- **Name**: `GoodGoalMultiBounce`
-- **Size Range**: `0.5-5`
-- **Color**: Not changeable
-- **Valence**: Positive, proportional to size
+* **Name**: `GoodGoalMultiBounce`
+* **Size Range**: `0.5-5`
+* **Color**: Not changeable
+* **Valence**: Positive, proportional to size
Notes: The `rotations` parameter sets the direction of motion.
### Non-Episode-Ending Ripen Goal
+
-- **Name**: `RipenGoal`
-- **Valence Range**: `0-5`
-- **Size**: automatically sets to final reward value
-- **Color**: Not changeable
-- **Ripen Onset Delay Range (frames)** (`delays`): `0-Inf` (default `150`)
-- **Ripen Rate (frames)** (`changeRates`): `0.001-Inf` (default `0.005`)
-- **Alias**: `AntiDecayGoal`
+* **Name**: `RipenGoal`
+* **Valence Range**: `0-5`
+* **Size**: automatically sets to final reward value
+* **Color**: Not changeable
+* **Ripen Onset Delay Range (frames)** (`delays`): `0-Inf` (default `150`)
+* **Ripen Rate (frames)** (`changeRates`): `0.001-Inf` (default `0.005`)
+* **Alias**: `AntiDecayGoal`
Notes: Colour changes (from purple to grey) and a radial-timer fills over time during ripening process. 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.
### Non-Episode-Ending Decay Goal
+
-- **Name**: `DecayGoal`
-- **Valence Range**: `0-5`
-- **Size**: automatically sets to final reward value
-- **Color**: Not changeable
-- **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)
+* **Name**: `DecayGoal`
+* **Valence Range**: `0-5`
+* **Size**: automatically sets to final reward value
+* **Color**: Not changeable
+* **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)
Notes: Colour changes (from purple to grey) and a radial-timer depletes over time during decay process. 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 Grow Goal
+
-- **Name**: `GrowGoal`
-- **Size Range**: `0-5`
-- **Valence Change Rate** (`changeRates`): `0.001-Inf` (default `0.005`)
-- **Valence**: Positive, proportional to size
-- **Color**: Not changeable
-- **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
+* **Name**: `GrowGoal`
+* **Size Range**: `0-5`
+* **Valence Change Rate** (`changeRates`): `0.001-Inf` (default `0.005`)
+* **Valence**: Positive, proportional to size
+* **Color**: Not changeable
+* **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
-Notes: 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.
+Notes: 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`
-- **Valence Change Rate** (`changeRates`): `0.001-Inf` (default `0.005`)
-- **Valence**: Positive, proportional to size
-- **Color**: Not changeable
-- **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
+* **Name**: `ShrinkGoal`
+* **Size Range**: `0-5`
+* **Valence Change Rate** (`changeRates`): `0.001-Inf` (default `0.005`)
+* **Valence**: Positive, proportional to size
+* **Color**: Not changeable
+* **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
-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.
+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.
### Episode-Ending DeathZone
+
-- **Name**: `DeathZone`
-- **Size Range**: `(1,0.5,1)-(40,10,40)`
-- **Valence**: `-1`
-- **Color**: Not changeable
+* **Name**: `DeathZone`
+* **Size Range**: `(1,0.5,1)-(40,10,40)`
+* **Valence**: `-1`
+* **Color**: Not changeable
### Non-Episode-Ending HotZone
+
-- **Name**: `HotZone`
-- **Valence**: `min(-10/t, -0.00001)` for `t > 0`, `-0.00001` otherwise, where `t` is the number of steps in the episode
-- **Color**: Not changeable
+* **Name**: `HotZone`
+* **Valence**: `min(-10/t, -0.00001)` for `t > 0`, `-0.00001` otherwise, where `t` is the number of steps in the episode
+* **Color**: Not changeable
Notes: When the agent enters the hot zone, reward decrement is accelerated by a factor of 10 compared to time alone. If a `DeathZone` and a `HotZone` overlap, `DeathZone` prevails.
-
## Dispensers
These objects dispense valenced objects. They are immovable.
### SpawnerTree
+
-- **Name**: `SpawnerTree`
-- **Size**: Fixed (`5.19 x 5.95 x 5.02`)
-- **Spawned Goal Size Range**: `0.2-3`
-- **Number of goals to spawn** (`spawnCounts`): `0-Inf` (leave blank or set to `-1` to spawn infinitely)
-- **Color**: Not changeable
-- **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
+* **Name**: `SpawnerTree`
+* **Size**: Fixed (`5.19 x 5.95 x 5.02`)
+* **Spawned Goal Size Range**: `0.2-3`
+* **Number of goals to spawn** (`spawnCounts`): `0-Inf` (leave blank or set to `-1` to spawn infinitely)
+* **Color**: Not changeable
+* **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
-Notes: The tree spawns `GoodGoalMulti`. They grow on the trees before dropping to the floor once they have reached their final size. The starting size of the goals can be set with the `initialValues` parameter (default: `0.2`) and the final size with the `finalValues` parameter (default: `1.0`). The valence of the goals is proportional to their size. The number of seconds it takes to 'grow' the goals on the tree (relative to the timescale of the environment) can be set with the `ripenTimes` parameter. The number of seconds between spawnings (relative to the timescale of the environment) can be set with the `timesBetweenSpawns` parameter (default: 4.0).
+Notes: The tree spawns `GoodGoalMulti` . They grow on the trees before dropping to the floor once they have reached their final size. The starting size of the goals can be set with the `initialValues` parameter (default: `0.2` ) and the final size with the `finalValues` parameter (default: `1.0` ). The valence of the goals is proportional to their size. The number of seconds it takes to 'grow' the goals on the tree (relative to the timescale of the environment) can be set with the `ripenTimes` parameter. The number of seconds between spawnings (relative to the timescale of the environment) can be set with the `timesBetweenSpawns` parameter (default: 4.0).
### SpawnerDispenserTall
+
-- **Name**: `SpawnerDispenserTall`
-- **Size**: Fixed (`1.67 x 4.46 x 1.67`)
-- **Spawned Goal Size Range**: `0.2-1`
-- **Number of goals to spawn** (`spawnCounts`): `0-Inf` (leave blank or set to `-1` to spawn infinitely)
-- **Color**: RGB range `(0,0,0)-(255,255,255)`
-- **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
-- **Alias**: `SpawnerDispenser`
+* **Name**: `SpawnerDispenserTall`
+* **Size**: Fixed (`1.67 x 4.46 x 1.67`)
+* **Spawned Goal Size Range**: `0.2-1`
+* **Number of goals to spawn** (`spawnCounts`): `0-Inf` (leave blank or set to `-1` to spawn infinitely)
+* **Color**: RGB range `(0,0,0)-(255,255,255)`
+* **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
+
-- **Name**: `SpawnerDispenserShort`
-- **Size**: Fixed (`1.67 x 1.67 x 1.67`)
-- **Spawned Goal Size Range**: `0.2-1`
-- **Number of goals to spawn** (`spawnCounts`): `0-Inf` (leave blank or set to `-1` to spawn infinitely)
-- **Color**: RGB range `(0,0,0)-(255,255,255)`
-- **Growth Onset Delay Range (frames)** (`delays`): `0-Inf` (default `0`)
-- **Alias**: `SpawnerDispenser`
+* **Name**: `SpawnerDispenserShort`
+* **Size**: Fixed (`1.67 x 1.67 x 1.67`)
+* **Spawned Goal Size Range**: `0.2-1`
+* **Number of goals to spawn** (`spawnCounts`): `0-Inf` (leave blank or set to `-1` to spawn infinitely)
+* **Color**: RGB range `(0,0,0)-(255,255,255)`
+* **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).
### SpawnerButton
+
-- **Name**: `SpawnerButton`
-- **Size**: Fixed
-- **Spawned Goal Size**: `1`
-- **Color**: Not changeable
-- **Alias**: `Pillar-Button`
+* **Name**: `SpawnerButton`
+* **Size**: Fixed
+* **Spawned Goal Size**: `1`
+* **Color**: Not changeable
+* **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 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` .
## Sign Boards
+
-
-
## Unity Editor
The Unity Editor is the core interface where game development takes place. It provides a user-friendly environment for building game scenes, adding assets, and scripting behavior.
-- **Overview**: [Unity Editor Overview](https://docs.unity3d.com/Manual/UsingTheEditor.html)
-- **Interface Guide**: [Unity Editor Interface](https://learn.unity.com/tutorial/unity-editor-interface-overview)
+* **Overview**: [Unity Editor Overview](https://docs.unity3d.com/Manual/UsingTheEditor.html)
+* **Interface Guide**: [Unity Editor Interface](https://learn.unity.com/tutorial/unity-editor-interface-overview)
## Prefabs
Prefabs in Unity are pre-configured templates of game objects that can be reused across your projects. They are essential for efficient game development.
-- **Introduction to Prefabs**: [Working with Prefabs](https://docs.unity3d.com/Manual/Prefabs.html)
-- **Prefab Workflow**: [Prefab Workflow Guide](https://learn.unity.com/tutorial/introduction-to-prefabs)
+* **Introduction to Prefabs**: [Working with Prefabs](https://docs.unity3d.com/Manual/Prefabs.html)
+* **Prefab Workflow**: [Prefab Workflow Guide](https://learn.unity.com/tutorial/introduction-to-prefabs)
## Scripting
Scripting in Unity is primarily done using C#. It allows you to define the behavior of your game objects, control game logic, and interact with user inputs.
-- **Scripting Overview**: [Unity Scripting API](https://docs.unity3d.com/ScriptReference/)
-- **C# Scripting Tutorial**: [C# Scripting in Unity](https://learn.unity.com/tutorial/introduction-to-scripting)
+* **Scripting Overview**: [Unity Scripting API](https://docs.unity3d.com/ScriptReference/)
+* **C# Scripting Tutorial**: [C# Scripting in Unity](https://learn.unity.com/tutorial/introduction-to-scripting)
## Physics
Unity's physics engine allows for realistic simulation of physical interactions between objects in the game world.
-- **Physics System**: [Unity Physics System](https://docs.unity3d.com/Manual/PhysicsSection.html)
-- **Rigidbody and Colliders**: [Using Rigidbody and Colliders](https://learn.unity.com/tutorial/physics-rigidbodies-and-colliders)
+* **Physics System**: [Unity Physics System](https://docs.unity3d.com/Manual/PhysicsSection.html)
+* **Rigidbody and Colliders**: [Using Rigidbody and Colliders](https://learn.unity.com/tutorial/physics-rigidbodies-and-colliders)
## Animation
Unity provides a comprehensive system for animating characters and objects, offering tools for creating detailed animations and controlling them via scripts.
-- **Animation Overview**: [Unity Animation System](https://docs.unity3d.com/Manual/AnimationOverview.html)
-- **Animator Component**: [Using the Animator](https://learn.unity.com/tutorial/animator-component)
+* **Animation Overview**: [Unity Animation System](https://docs.unity3d.com/Manual/AnimationOverview.html)
+* **Animator Component**: [Using the Animator](https://learn.unity.com/tutorial/animator-component)
## Asset Management
Managing assets is a crucial part of game development in Unity. Unity supports a wide range of asset types including 3D models, textures, audio, and more.
-- **Asset Management**: [Unity Asset Workflow](https://docs.unity3d.com/Manual/AssetWorkflow.html)
-- **Asset Store**: [Unity Asset Store](https://assetstore.unity.com/)
+* **Asset Management**: [Unity Asset Workflow](https://docs.unity3d.com/Manual/AssetWorkflow.html)
+* **Asset Store**: [Unity Asset Store](https://assetstore.unity.com/)
## User Interface (UI)
Unity's UI system allows you to create interactive and intuitive user interfaces for your games.
-- **UI Overview**: [Unity UI System](https://docs.unity3d.com/Manual/UISystem.html)
-- **UI Toolkit**: [Using Unity's UI Toolkit](https://learn.unity.com/tutorial/introduction-to-the-new-ui-system)
+* **UI Overview**: [Unity UI System](https://docs.unity3d.com/Manual/UISystem.html)
+* **UI Toolkit**: [Using Unity's UI Toolkit](https://learn.unity.com/tutorial/introduction-to-the-new-ui-system)
## Conclusion
diff --git a/docs/Background-YAML.md b/docs/Background-YAML.md
index 670056f2f..593d093b5 100644
--- a/docs/Background-YAML.md
+++ b/docs/Background-YAML.md
@@ -1,19 +1,19 @@
# Background: YAML
#### Table of Contents
-- [Background: YAML](#background-yaml)
+
+* [Background: YAML](#background-yaml)
- [Table of Contents](#table-of-contents)
- - [YAML? What is it?](#yaml-what-is-it)
- - [Configuration of Training Environments and Agents](#configuration-of-training-environments-and-agents)
+ + [YAML? What is it?](#yaml-what-is-it)
+ + [Configuration of Training Environments and Agents](#configuration-of-training-environments-and-agents)
- [Defining Agent Behaviors](#defining-agent-behaviors)
- [Setting Hyperparameters for Training](#setting-hyperparameters-for-training)
- - [Example of a YAML Configuration in ML-Agents](#example-of-a-yaml-configuration-in-ml-agents)
- - [Example of a YAML Configuration in Animal-AI](#example-of-a-yaml-configuration-in-animal-ai)
- - [Advantages in Animal-AI Context](#advantages-in-animal-ai-context)
+ + [Example of a YAML Configuration in ML-Agents](#example-of-a-yaml-configuration-in-ml-agents)
+ + [Example of a YAML Configuration in Animal-AI](#example-of-a-yaml-configuration-in-animal-ai)
+ + [Advantages in Animal-AI Context](#advantages-in-animal-ai-context)
- [Easy to Read and Modify](#easy-to-read-and-modify)
- [Facilitating Complex Configurations](#facilitating-complex-configurations)
-
## YAML? What is it?
*YAML* (YAML Ain't Markup Language) is a data serialization format widely used in Unity and other setups (as well as in ML-Agents) for its readability and ease of use. It allows developers and researchers to define and adjust the behavior and training parameters of AI agents within Unity simulations. Due to it's human-readable format, YAML is also useful for researchers who have little experience with programming.
@@ -51,6 +51,7 @@ behaviors:
time_horizon: 64
summary_freq: 10000
```
+
The above example shows a YAML configuration file for a soccer player agent in ML-Agents, for agent training. The agent's behavior is defined by the `SoccerPlayer` behavior name. The `trainer_type` parameter specifies the type of training algorithm used to train the agent. The `hyperparameters` section defines the hyperparameters for the training process. The `network_settings` section defines the neural network architecture for the agent. The `reward_signals` section defines the reward signals used to train the agent. The `max_steps` parameter defines the maximum number of steps the agent can take in the environment. The `time_horizon` parameter defines the number of steps the agent can take before the environment is reset. The `summary_freq` parameter defines the frequency at which the agent's training progress is logged.
## Example of a YAML Configuration in Animal-AI
@@ -78,6 +79,7 @@ arenas:
spawnProbability: 1.0
rewardSpawnPos: !Vector3 {x: 20, y: 0, z: 35}
```
+
The above example shows a YAML configuration file for an arena in Animal-AI. The `!ArenaConfig` tag indicates that the file is a configuration file for an arena. The `arenas` section defines the arenas in the environment. The `0` tag indicates that the arena is the first arena in the environment. The `pass_mark` parameter defines the minimum score required to pass the arena. The `t` parameter defines the maximum number of steps the agent can take in the arena. The `items` section defines the objects in the arena. The `name` parameter defines the name of the object. The `positions` parameter defines the positions of the object. The `rotations` parameter defines the rotations of the object. The `moveDurations` parameter defines the durations of the object's movements. The `resetDurations` parameter defines the durations of the object's resets. The `rewardNames` parameter defines the names of the object's rewards. The `rewardWeights` parameter defines the weights of the object's rewards. The `spawnProbability` parameter defines the probability of the object spawning. The `rewardSpawnPos` parameter defines the position of the object's reward.
## Advantages in Animal-AI Context
@@ -90,4 +92,4 @@ YAML's human-readable format makes it easier for developers and researchers to u
The structure of YAML supports complex configurations with nested parameters, allowing for clear hierarchies and groupings of settings in Animal-AI. This makes it easier for developers to organize and modify their configurations.
----
\ No newline at end of file
+---
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index db150cff5..6ea4f4525 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,108 +8,129 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
### Added
-
### Changed
-
### Fixed
-
---
+
## [3.1.3] - 30.09.2023
+
### Fixed
-- Resolved Spawner Tree Clock desync issue.
-- Resolved Multiple Arenas improper cycling issue.
-- Addressed Unity native warning in Training Arena script.
-- Rectified the invisibility issue of the SignBoard prefab.
+* Resolved Spawner Tree Clock desync issue.
+* Resolved Multiple Arenas improper cycling issue.
+* Addressed Unity native warning in Training Arena script.
+* Rectified the invisibility issue of the SignBoard prefab.
### Added
-- Enhanced arenas randomization via the `randomizeArenas` parameter in YAML.
-- Added more robust error-checking for arena ID's and arena cycling.
-- Conducted unit tests on `TrainingArena.cs` and `ArenaParameters.cs`.
-- Added visual elements of paired reinforcing cues such as colours and short GIFs for better visual understanding for the user.
+
+* Enhanced arenas randomization via the `randomizeArenas` parameter in YAML.
+* Added more robust error-checking for arena ID's and arena cycling.
+* Conducted unit tests on `TrainingArena.cs` and `ArenaParameters.cs`.
+* Added visual elements of paired reinforcing cues such as colours and short GIFs for better visual understanding for the user.
### Changed
-- Shortened end-of-episode notification to *2.5 seconds*.
-- Undertook minor Unity script optimizations.
-- Updated the `README.md` file with more detailed instructions.
+
+* Shortened end-of-episode notification to *2.5 seconds*.
+* Undertook minor Unity script optimizations.
+* Updated the `README.md` file with more detailed instructions.
## [3.1.2.exp1] - 11.09.2023
+
### Fixed
-- Implemented hot fix for a newly discovered bug affecting the Spawner Tree.
+* Implemented hot fix for a newly discovered bug affecting the Spawner Tree.
## [3.1.1] - 10.08.2023
+
### Added
-- Introduced "End of Episode Notification" feature.
-- Supported "Headless" mode unofficially for training agents (works with Raycasting).
+* Introduced "End of Episode Notification" feature.
+* Supported "Headless" mode unofficially for training agents (works with Raycasting).
### Fixed
-- Fixed bug affecting the Spawner Tree.
-- Fixed bug affecting the Interactive Button.
+
+* Fixed bug affecting the Spawner Tree.
+* Fixed bug affecting the Interactive Button.
## [3.1.0]
+
### Added
-- Introduced "Interactive Button" feature.
+* Introduced "Interactive Button" feature.
## [3.0.2]
+
### Changed
-- Upgraded Mlagents to 2.3.0-exp3 (mlagents python version 0.30.0).
+* Upgraded Mlagents to 2.3.0-exp3 (mlagents python version 0.30.0).
## [3.0.1]
+
### Added
-- Added Agent Freezing Parameter.
+* Added Agent Freezing Parameter.
## [3.0]
+
### Changed
-- Updated agent handling for improved stop and acceleration.
-- Added new objects, spawners, signs, goal types.
-- Updated graphics for many objects.
-- Made the Unity Environment available.
-- Upgraded to Mlagents 2.1.0-exp.1 (ml-agents python version 0.27.0).
+* Updated agent handling for improved stop and acceleration.
+* Added new objects, spawners, signs, goal types.
+* Updated graphics for many objects.
+* Made the Unity Environment available.
+* Upgraded to Mlagents 2.1.0-exp.1 (ml-agents python version 0.27.0).
### Fixed
-- Various bug fixes.
+
+* Various bug fixes.
### Note
-- Due to changes to controls and graphics, agents trained on previous versions might not perform the same.
+
+* Due to changes to controls and graphics, agents trained on previous versions might not perform the same.
## [2.2.3]
+
### Added
-- Ability to specify multiple different arenas in a single YAML config file.
+* Ability to specify multiple different arenas in a single YAML config file.
## [2.2.2]
+
### Changed
-- Introduced a low-quality version with improved fps.
+* Introduced a low-quality version with improved fps.
## [2.2.1]
+
### Fixed
-- Improved UI scaling with respect to screen size.
-- Fixed an issue with cardbox objects spawning at the wrong sizes.
-- Fixed an issue where the environment would time out incorrectly.
+* Improved UI scaling with respect to screen size.
+* Fixed an issue with cardbox objects spawning at the wrong sizes.
+* Fixed an issue where the environment would time out incorrectly.
### Changed
-- Improved Death Zone shader for unusual Zone sizes.
+
+* Improved Death Zone shader for unusual Zone sizes.
## [2.2.0]
+
### Added
-- Switched to health-based system.
-- Added basic Gym Wrapper.
-- Added basic heuristic agent for benchmarking and testing.
+* Switched to health-based system.
+* Added basic Gym Wrapper.
+* Added basic heuristic agent for benchmarking and testing.
### Fixed
-- Fixed a reset environment bug during training.
-- Added the ability to set the DecisionPeriod (frameskip) when instantiating an environment.
+
+* Fixed a reset environment bug during training.
+* Added the ability to set the DecisionPeriod (frameskip) when instantiating an environment.
## [2.1.1] - 01.07.2021
+
### Added
-- RayCast Observations
+* RayCast Observations
+
### Fixed
-- Fixed raycast length being less than diagonal length of standard arena.
+
+* Fixed raycast length being less than diagonal length of standard arena.
## [2.1] - Beta Release 2019
+
### Added
-- Raycast observations.
-- Agent global position to observations.
+* Raycast observations.
+* Agent global position to observations.
### Changed
-- Upgraded to ML-Agents release 2 (0.26.0).
+
+* Upgraded to ML-Agents release 2 (0.26.0).
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 1fd1a01b6..9eee9972f 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -1,78 +1,95 @@
# Frequently Asked Questions
+
This document provides a comprehensive list of frequently asked questions and troubleshooting tips for the Animal-AI environment.
#### Table of Contents
- - [1. Troubleshooting Installation Issues](#1-troubleshooting-installation-issues)
+
+ + [1. Troubleshooting Installation Issues](#1-troubleshooting-installation-issues)
- [1.1 Resolving Environment Permission Errors](#11-resolving-environment-permission-errors)
- [1.1.1 For macOS and Linux Users](#111-for-macos-and-linux-users)
- [1.1.2 For Windows Users](#112-for-windows-users)
- [1.2 Addressing Environment Connection Timeouts](#12-addressing-environment-connection-timeouts)
- [1.3 Communication Port Conflict](#13-communication-port-conflict)
- [1.4 Mean Reward Displaying NaN](#14-mean-reward-displaying-nan)
- - [2. Python API / Package Dependency Issues](#2-python-api--package-dependency-issues)
+ + [2. Python API / Package Dependency Issues](#2-python-api--package-dependency-issues)
- [2.1 No Module Named `animalai`](#21-no-module-named-animalai)
- [2.3 Incompatible Python Version](#23-incompatible-python-version)
- - [3. File Not Found Error](#3-file-not-found-error)
+ + [3. File Not Found Error](#3-file-not-found-error)
## 1. Troubleshooting Installation Issues
+
Encountering issues while installing the Animal-AI environment? Here are some solutions to common problems:
### 1.1 Resolving Environment Permission Errors
+
#### 1.1.1 For macOS and Linux Users
Permission errors after importing a Unity environment? Adjust file permissions with these commands:
**macOS:**
+
```sh
chmod -R 755 *.app
```
**Linux:**
+
```sh
chmod -R 755 *.x86_64
```
#### 1.1.2 For Windows Users
+
Windows users generally don't need additional permissions. If needed, refer to [Microsoft Documentation](https://docs.microsoft.com/).
### 1.2 Addressing Environment Connection Timeouts
-Timeout errors when launching through `UnityEnvironment`? Consider these fixes:
-- **No Agent in Scene:** Ensure an agent is in the scene.
-- **Firewall Issues on macOS:** Follow [Apple's instructions](https://support.apple.com/) to add exceptions.
-- **Errors in Unity Environment:** Refer to [Unity log files](https://docs.unity3d.com/Manual/LogFiles.html).
-- **Running in a Headless Environment:** Use `--no-graphics` or `no_graphics=True` if you intend on using this feature (not fully supported).
+Timeout errors when launching through `UnityEnvironment` ? Consider these fixes:
+
+* **No Agent in Scene:** Ensure an agent is in the scene.
+* **Firewall Issues on macOS:** Follow [Apple's instructions](https://support.apple.com/) to add exceptions.
+* **Errors in Unity Environment:** Refer to [Unity log files](https://docs.unity3d.com/Manual/LogFiles.html).
+* **Running in a Headless Environment:** Use `--no-graphics` or `no_graphics=True` if you intend on using this feature (not fully supported).
### 1.3 Communication Port Conflict
+
Encountering port conflicts? Try changing the worker number or port:
```python
UnityEnvironment(file_name=filename, worker_id=X)
```
+
Or find an available port:
+
```python
port = 5005 + random.randint(0, 1000)
```
### 1.4 Mean Reward Displaying NaN
-Seeing `Mean reward : nan`? Set the `Max Steps` to a non-zero value or script custom termination conditions.
+Seeing `Mean reward : nan` ? Set the `Max Steps` to a non-zero value or script custom termination conditions.
## 2. Python API / Package Dependency Issues
+
Encountering issues with the Python API or package dependencies? Here are some solutions to common problems:
### 2.1 No Module Named `animalai`
-Seeing `ModuleNotFoundError: No module named 'animalai'`? Ensure the `animalai` package is installed:
+
+Seeing `ModuleNotFoundError: No module named 'animalai'` ? Ensure the `animalai` package is installed:
```sh
pip install animalai
```
+
or if you are using a virtual environment:
+
```sh
pip install animalai --user
```
+
or conda:
```sh
conda install -c conda-forge animalai
+
```
Please do not forget to activate your environment before installing the package.
@@ -80,10 +97,13 @@ You can verify the installation by running:
```sh
python -c "import animalai"
```
+
### 2.3 Incompatible Python Version
+
Currently, the Animal-AI environment only supports **Python 3.6 to 3.9.** We have tested using 3.6, 3.7 and 3.8, but we cannot guarantee that it will work with these versions for everyone. If you are using a different version of Python, please install Python 3.9 for the optimal experience.
Please verify that you are using the correct version of Python by running:
+
```sh
python --version
```
@@ -92,8 +112,8 @@ If you are using a different version of Python, please install Python 3.9 for th
## 3. File Not Found Error
-Seeing `FileNotFoundError: [Errno 2] No such file or directory: 'AnimalAI/AnimalAI.app'`? Ensure the `AnimalAI` folder is in the same directory as your Python script.
+Seeing `FileNotFoundError: [Errno 2] No such file or directory: 'AnimalAI/AnimalAI.app'` ? Ensure the `AnimalAI` folder is in the same directory as your Python script.
-If you are using macOS, you may get this error: `FileNotFoundError: [Errno 2] No such file or directory: 'env/AnimalAI'`. This error occurs when running the ``python play.py`` command from the ``animal-ai/examples`` folder.
+If you are using macOS, you may get this error: `FileNotFoundError: [Errno 2] No such file or directory: 'env/AnimalAI'` . This error occurs when running the ` `python play.py` ` command from the ` `animal-ai/examples` ` folder.
-To fix this, simply rename the 'MACOS.app' folder you downloaded to AnimalAI. This will allow the ``play.py`` script to find the environment. Note that this error is likely to occur in older versions of Animal-AI.
\ No newline at end of file
+To fix this, simply rename the 'MACOS.app' folder you downloaded to AnimalAI. This will allow the ` `play.py` ` script to find the environment. Note that this error is likely to occur in older versions of Animal-AI.
diff --git a/docs/Glossary.md b/docs/Glossary.md
index 763613bfd..a624e9516 100644
--- a/docs/Glossary.md
+++ b/docs/Glossary.md
@@ -1,6 +1,7 @@
# Animal-AI Glossary
#### Table of Contents
+
1. [Animal-AI Terms](#animal-ai-terms)
2. [RL/ML-Agents Terms](#rlml-agents-terms)
3. [Unity Terms](#unity-terms)
@@ -8,48 +9,46 @@
## Animal-AI Terms
-- **Animal-AI**: The Animal-AI environment, encompassing the Unity environment, Python API, and associated documentation.
-- **Episode**: A single run of the environment, starting with a reset and ending with a failure or success.
-- **Arena**: The area in which the agent is placed at the start of an episode, which is synonymous with the environment/episode.
-
+* **Animal-AI**: The Animal-AI environment, encompassing the Unity environment, Python API, and associated documentation.
+* **Episode**: A single run of the environment, starting with a reset and ending with a failure or success.
+* **Arena**: The area in which the agent is placed at the start of an episode, which is synonymous with the environment/episode.
## RL/ML-Agents Terms
-- **Academy**: A singleton object controlling the timing, reset, and training/inference settings of the environment.
-- **Action**: The execution of a decision by an agent within the environment.
-- **Agent**: A Unity Component that generates observations and takes actions in the environment, based on decisions from a Policy.
-- **Decision**: The output of a Policy, specifying an action in response to an observation.
-- **Editor**: The Unity Editor, encompassing various panes like Hierarchy, Scene, Inspector.
-- **Environment**: The Unity scene containing Agents.
-- **Experience**: A tuple [Agent observations, actions, rewards] representing a single Agent's data after a Step.
-- **FixedUpdate**: A Unity method called at each step of the game engine, where ML-Agents logic is typically executed.
-- **Frame**: An instance of rendering by the main camera, corresponding to each `Update` call in the game engine.
-- **Observation**: Information available to an agent about the environment's state (e.g., Vector, Visual).
-- **Policy**: The decision-making mechanism (often a neural network) that produces decisions from observations.
-- **Reward**: A signal indicating the desirability of an agent’s action within the current environment state.
-- **State**: The underlying properties of the environment and all agents within it at a given time.
-- **Step**: An atomic change in the engine occurring between Agent decisions.
-- **Trainer**: A Python class responsible for training a group of Agents.
-- **Update**: A Unity function called at each frame rendering. ML-Agents logic is typically not executed here.
+* **Academy**: A singleton object controlling the timing, reset, and training/inference settings of the environment.
+* **Action**: The execution of a decision by an agent within the environment.
+* **Agent**: A Unity Component that generates observations and takes actions in the environment, based on decisions from a Policy.
+* **Decision**: The output of a Policy, specifying an action in response to an observation.
+* **Editor**: The Unity Editor, encompassing various panes like Hierarchy, Scene, Inspector.
+* **Environment**: The Unity scene containing Agents.
+* **Experience**: A tuple [Agent observations, actions, rewards] representing a single Agent's data after a Step.
+* **FixedUpdate**: A Unity method called at each step of the game engine, where ML-Agents logic is typically executed.
+* **Frame**: An instance of rendering by the main camera, corresponding to each `Update` call in the game engine.
+* **Observation**: Information available to an agent about the environment's state (e.g., Vector, Visual).
+* **Policy**: The decision-making mechanism (often a neural network) that produces decisions from observations.
+* **Reward**: A signal indicating the desirability of an agent’s action within the current environment state.
+* **State**: The underlying properties of the environment and all agents within it at a given time.
+* **Step**: An atomic change in the engine occurring between Agent decisions.
+* **Trainer**: A Python class responsible for training a group of Agents.
+* **Update**: A Unity function called at each frame rendering. ML-Agents logic is typically not executed here.
## Unity Terms
-- **Unity Objects**: Fundamental components in the Unity Engine, serving as containers for all other components or functionalities within a Unity scene.
-- **GameObjects**: Core elements in Unity, representing characters, props, scenery, cameras, lights, etc.
-- **Prefabs**: Templates created from GameObjects in Unity, allowing for reuse and consistency across scenes or projects.
-- **Immovable Objects**: Objects in the Animal-AI environment that are fixed in place and cannot be moved, like walls and ramps.
-- **Movable Objects**: Objects that can be easily moved by the agent or other objects in the environment.
-- **Rewards**: Objects providing positive or negative feedback to the agent, including stationary and moving goals.
-- **Reward Spawners**: Objects with the primary function of spawning rewards in the environment.
-- **Environment Permission Errors**: Issues related to file permissions when importing a Unity environment, particularly on macOS and Linux.
-- **Environment Connection Timeouts**: Problems encountered when launching the Animal-AI environment through `UnityEnvironment`.
-- **Communication Port Conflict**: Issues arising from port conflicts when initializing the Unity environment.
-- **Mean Reward Displaying NaN**: A scenario where the mean reward metric shows 'nan', indicating an issue with the environment setup or configuration.
+* **Unity Objects**: Fundamental components in the Unity Engine, serving as containers for all other components or functionalities within a Unity scene.
+* **GameObjects**: Core elements in Unity, representing characters, props, scenery, cameras, lights, etc.
+* **Prefabs**: Templates created from GameObjects in Unity, allowing for reuse and consistency across scenes or projects.
+* **Immovable Objects**: Objects in the Animal-AI environment that are fixed in place and cannot be moved, like walls and ramps.
+* **Movable Objects**: Objects that can be easily moved by the agent or other objects in the environment.
+* **Rewards**: Objects providing positive or negative feedback to the agent, including stationary and moving goals.
+* **Reward Spawners**: Objects with the primary function of spawning rewards in the environment.
+* **Environment Permission Errors**: Issues related to file permissions when importing a Unity environment, particularly on macOS and Linux.
+* **Environment Connection Timeouts**: Problems encountered when launching the Animal-AI environment through `UnityEnvironment`.
+* **Communication Port Conflict**: Issues arising from port conflicts when initializing the Unity environment.
+* **Mean Reward Displaying NaN**: A scenario where the mean reward metric shows 'nan', indicating an issue with the environment setup or configuration.
## YAML Terms
-- **YAML File**: A file containing data in YAML format.
-- **YAML Configuration File**: A YAML file containing configuration data for the Animal-AI environment.
-- **YAML Configuration Name**: The name of a YAML configuration file, which is used to identify the configuration. Your custom configurations are used to create a new environment.
-- **YAML Configuration Path**: The path to a YAML configuration file.
-
+* **YAML File**: A file containing data in YAML format.
+* **YAML Configuration File**: A YAML file containing configuration data for the Animal-AI environment.
+* **YAML Configuration Name**: The name of a YAML configuration file, which is used to identify the configuration. Your custom configurations are used to create a new environment.
+* **YAML Configuration Path**: The path to a YAML configuration file.
diff --git a/docs/Technical-Overview.md b/docs/Technical-Overview.md
index 87bce5a50..2029a7880 100644
--- a/docs/Technical-Overview.md
+++ b/docs/Technical-Overview.md
@@ -5,11 +5,12 @@ This guide will walk you through the engineering aspects of the Animal-AI Enviro
If you have any questions or issues, please check the [FAQ](docs/FAQ.md) and documentation before posting an issue on GitHub.
#### Table of Contents
-- [Running the Environment](#running-the-environment)
- - [Play Mode](#play-mode)
+
+* [Running the Environment](#running-the-environment)
+ + [Play Mode](#play-mode)
- [Controls in Play Mode](#controls-in-play-mode)
- - [Train Mode](#train-mode)
-- [Environment Overview](#environment-overview)
+ + [Train Mode](#train-mode)
+* [Environment Overview](#environment-overview)
- [Observations](#observations)
- [Actions](#actions)
- [Rewards](#rewards)
@@ -17,7 +18,7 @@ If you have any questions or issues, please check the [FAQ](docs/FAQ.md) and doc
- [Configuration Files](#configuration-files)
- [Arena Files](#arena-files)
- [Unity Editor](#unity-editor)
-- [Training Agents](#training-agents)
+* [Training Agents](#training-agents)
- [Baselines](#baselines)
- [Training Scripts](#training-scripts)
- [Training Observations](#training-observations)
@@ -25,16 +26,14 @@ If you have any questions or issues, please check the [FAQ](docs/FAQ.md) and doc
- [Training Curriculum](#training-curriculum)
- [Training Arena Files](#training-arena-files)
- [Training Configuration Files](#training-configuration-files)
-- [Testing Agents](#testing-agents)
-- [Contributing](#contributing)
-- [Citation](#citation)
-- [License](#license)
-
+* [Testing Agents](#testing-agents)
+* [Contributing](#contributing)
+* [Citation](#citation)
+* [License](#license)
## Running the Environment
-The Animal-AI Environment can be run in one of two modes: `Play` and `Train`. In `Play` mode, the environment is run with a human player controlling the agent. In `Train` mode, the environment is run with an AI agent (see [Training Agents](#training-agents)).
-
+The Animal-AI Environment can be run in one of two modes: `Play` and `Train` . In `Play` mode, the environment is run with a human player controlling the agent. In `Train` mode, the environment is run with an AI agent (see [Training Agents](#training-agents)).
### Play Mode
@@ -43,6 +42,7 @@ To run the environment in `Play` mode, simply run the Animal-AI application for
```bash
animalai play configs/curriculum/0.yaml
```
+
#### Controls in Play Mode
In play mode, you can switch the camera view and control the agent using the following keyboard commands:
@@ -57,7 +57,7 @@ In play mode, you can switch the camera view and control the agent using the fol
| R | Reset environment |
| Q | Quit application |
-Toggle the camera between first-person, third-person, and bird's eye view using the `C` key. The agent can be controlled using `W`, `A`, `S`, `D` (or the arrow keys). Hitting `R` or collecting certain rewards (green or red) will reset the arena. Note that the camera and agent controls are not available in `Train` mode, with only third-person perspective implemented currently (we plan to add multiple camera observations during training at some point). Furthermore, you can toggle on/off the ability to restrict the player's camera angles via the `canChangePerspective` parameter in the configuration file. If this is set to false, then the player will not be able to change the camera angle. In addition, you can toggle on/off the ability to reset the arena via the `canResetArena` parameter in the configuration file. If this is set to false, then the player will not be able to reset the arena manually. A new feature added is that users can now toggle on/off Lastly, if you have multiple arenas specified in youur configuration file, you can randomize via the `randomizeArenas` parameter. This is false by default.
+Toggle the camera between first-person, third-person, and bird's eye view using the `C` key. The agent can be controlled using `W` , `A` , `S` , `D` (or the arrow keys). Hitting `R` or collecting certain rewards (green or red) will reset the arena. Note that the camera and agent controls are not available in `Train` mode, with only third-person perspective implemented currently (we plan to add multiple camera observations during training at some point). Furthermore, you can toggle on/off the ability to restrict the player's camera angles via the `canChangePerspective` parameter in the configuration file. If this is set to false, then the player will not be able to change the camera angle. In addition, you can toggle on/off the ability to reset the arena via the `canResetArena` parameter in the configuration file. If this is set to false, then the player will not be able to reset the arena manually. A new feature added is that users can now toggle on/off Lastly, if you have multiple arenas specified in youur configuration file, you can randomize via the `randomizeArenas` parameter. This is false by default.
### Train Mode
@@ -70,5 +70,3 @@ animalai train configs/curriculum/0.yaml
## Environment Overview
Regardless on what mode you are using, the arena you specify in the configuration file will be loaded. The agent will be placed in the arena and the environment will run until the agent reaches the goal or the episode time limit is reached. The environment will then reset and the process will repeat. The order of the arenas in the configuration file will be used to determine the order in which the arenas are loaded. Take a look at the [Configuration Files](#configuration-files) section for more details on how to create your own configuration files.
-
-
diff --git a/docs/Using-Jupyter-Notebooks.md b/docs/Using-Jupyter-Notebooks.md
index 54d3cafe0..74bbfd271 100644
--- a/docs/Using-Jupyter-Notebooks.md
+++ b/docs/Using-Jupyter-Notebooks.md
@@ -3,87 +3,129 @@
This guide combines instructions on creating a custom kernel for Jupyter Notebooks and specific steps for using Jupyter Notebooks with the Animal-AI environment. It is advised that you either create a python virtual environment or Anaconda for easier project management. See [Using-Virtual-Environments](/docs/Using-Virtual-Environment.md) for more information on creating and using a virtual environment. For more information on Jupyter Notebooks, refer to the [official documentation](https://jupyter-notebook.readthedocs.io/en/stable/)
#### Table of Contents
-- [Creating a Kernel for Jupyter Notebooks](#creating-a-kernel-for-jupyter-notebooks)
-- [Using Jupyter Notebooks with Animal-AI](#using-jupyter-notebooks-with-animal-ai)
-- [Advantages of Using Jupyter Notebooks](#advantages-of-using-jupyter-notebooks)
-- [Tips for Effective Jupyter Notebook Use](#tips-for-effective-jupyter-notebook-use)
+
+* [Creating a Kernel for Jupyter Notebooks](#creating-a-kernel-for-jupyter-notebooks)
+* [Using Jupyter Notebooks with Animal-AI](#using-jupyter-notebooks-with-animal-ai)
+* [Advantages of Using Jupyter Notebooks](#advantages-of-using-jupyter-notebooks)
+* [Tips for Effective Jupyter Notebook Use](#tips-for-effective-jupyter-notebook-use)
## Creating a Kernel for Jupyter Notebooks
### Step-by-Step Guide
+
1. **Install the IPython Kernel**:
- ```bash
+
+
+```bash
pip install ipykernel
```
+
2. **Create a New Python Environment**:
- Using venv:
- ```bash
+
+
+
+```bash
python -m venv /path/to/new/virtual/environment
```
+
- Using Conda:
- ```bash
+
+
+
+```bash
conda create -n myenv python=3.x
```
+
3. **Activate the Environment**:
- Using venv:
- ```bash
+
+
+
+```bash
source /path/to/new/virtual/environment/bin/activate
```
+
- Using Conda:
- ```bash
+
+
+
+```bash
conda activate myenv
```
+
4. **Install Necessary Packages**:
- ```bash
+
+
+```bash
pip install numpy pandas matplotlib
```
+
5. **Add Your Kernel to Jupyter**:
- ```bash
+
+
+```bash
ipython kernel install --name "myenv" --user
```
+
6. **Launch Jupyter Notebook**:
- ```bash
+
+
+```bash
jupyter notebook
```
+
7. **Select Your Kernel**:
Choose "myenv" from the kernel list in Jupyter.
### Notes
-- Replace placeholders with your desired directory and environment name.
-- Adjust Python version as needed.
+
+* Replace placeholders with your desired directory and environment name.
+* Adjust Python version as needed.
## Using Jupyter Notebooks with Animal-AI
### Introduction
+
_Jupyter Notebooks_ are interactive documents that combine live code, output, text, and visualizations.
### Setup
+
1. **Install Jupyter**:
- ```bash
+
+
+```bash
pip install notebook
```
+
2. **Start Jupyter Notebook**:
- - Use `jupyter notebook` or JupyterLab (`jupyter lab`).
+ - Use `jupyter notebook` or JupyterLab ( `jupyter lab` ).
### Using with Animal-AI
-- **Create a New Notebook**: In your project directory.
-- **Import Animal-AI Package**:
- ```python
+
+* **Create a New Notebook**: In your project directory.
+* **Import Animal-AI Package**:
+
+
+```python
from animalai.envs.environment import AnimalAIEnvironment
# Other necessary imports for your script
```
### Writing Interactive Scripts
-- **Initialize Environment**: Set up the Animal-AI environment.
-- **Run Experiments**: Write code for experiments, training, or visualization.
-- **Visualize Outputs**: Display results using Jupyter's capabilities.
+
+* **Initialize Environment**: Set up the Animal-AI environment.
+* **Run Experiments**: Write code for experiments, training, or visualization.
+* **Visualize Outputs**: Display results using Jupyter's capabilities.
## Advantages of Using Jupyter Notebooks
-- **Interactivity**: Test code in small, independent blocks.
-- **Documentation**: Combine code with rich text and visualizations.
-- **Experimentation**: Ideal for testing new ideas and visualizing data.
+
+* **Interactivity**: Test code in small, independent blocks.
+* **Documentation**: Combine code with rich text and visualizations.
+* **Experimentation**: Ideal for testing new ideas and visualizing data.
## Tips for Effective Jupyter Notebook Use
-- **Manage Resources**: Be aware of resource usage, especially when running complex simulations.
-- **Kernel Management**: Restart the Jupyter kernel to clear memory and state if needed.
-- **Version Control**: Export code to Python scripts for version control in larger projects.
+
+* **Manage Resources**: Be aware of resource usage, especially when running complex simulations.
+* **Kernel Management**: Restart the Jupyter kernel to clear memory and state if needed.
+* **Version Control**: Export code to Python scripts for version control in larger projects.
diff --git a/docs/Using-Virtual-Environment.md b/docs/Using-Virtual-Environment.md
index 5c3ff2699..c702af929 100644
--- a/docs/Using-Virtual-Environment.md
+++ b/docs/Using-Virtual-Environment.md
@@ -1,26 +1,29 @@
# Using Virtual Environments for Animal-AI
#### Table of Contents
-- [Introduction to Virtual Environments](#introduction-to-virtual-environments)
-- [Benefits of Using a Virtual Environment](#benefits-of-using-a-virtual-environment)
-- [Python Version Compatibility](#python-version-compatibility)
-- [Setting Up Virtual Environments](#setting-up-virtual-environments)
- - [Common Steps](#common-steps)
- - [Mac OS X](#mac-os-x)
- - [Ubuntu](#ubuntu)
- - [Windows](#windows)
-- [Introduction to Conda Environments](#introduction-to-conda-environments)
-- [Setting Up Conda Environments](#setting-up-conda-environments)
- - [Installing Conda](#installing-conda)
- - [Creating a Conda Environment](#creating-a-conda-environment)
- - [Managing Packages](#managing-packages)
- - [Deactivating an Environment](#deactivating-an-environment)
-- [Conclusion](#conclusion)
+
+* [Introduction to Virtual Environments](#introduction-to-virtual-environments)
+* [Benefits of Using a Virtual Environment](#benefits-of-using-a-virtual-environment)
+* [Python Version Compatibility](#python-version-compatibility)
+* [Setting Up Virtual Environments](#setting-up-virtual-environments)
+ + [Common Steps](#common-steps)
+ + [Mac OS X](#mac-os-x)
+ + [Ubuntu](#ubuntu)
+ + [Windows](#windows)
+* [Introduction to Conda Environments](#introduction-to-conda-environments)
+* [Setting Up Conda Environments](#setting-up-conda-environments)
+ + [Installing Conda](#installing-conda)
+ + [Creating a Conda Environment](#creating-a-conda-environment)
+ + [Managing Packages](#managing-packages)
+ + [Deactivating an Environment](#deactivating-an-environment)
+* [Conclusion](#conclusion)
## Introduction to Virtual Environments
+
A _Virtual Environment_ in Python is a self-contained directory that includes a specific version of Python and various packages. This isolated environment helps in managing project dependencies effectively. For more details, visit the [Python venv documentation](https://docs.python.org/3/library/venv.html) and [Anaconda documentation](https://docs.anaconda.com/).
## Benefits of Using a Virtual Environment
+
Using a Virtual Environment offers several advantages:
1. Simplifies dependency management for individual projects.
2. Facilitates testing with different versions of libraries, ensuring code compatibility.
@@ -28,64 +31,79 @@ Using a Virtual Environment offers several advantages:
4. Allows for easy sharing of project requirements with collaborators.
## Python Version Compatibility
-- This guide is compatible with Python version `3.9.9`.
-- Using newer Python versions might lead to compatibility issues with some libraries.
+
+* This guide is compatible with Python version `3.9.9`.
+* Using newer Python versions might lead to compatibility issues with some libraries.
## Setting Up Virtual Environments
### Common Steps
+
1. **Install Python 3.9.9**: Ensure this version is installed on your system. If not, download it from [Python's official website](https://www.python.org/downloads/).
2. **Install Pip**:
- Download Pip: `curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py`
+
- Install Pip: `python3 get-pip.py`
+
- Verify installation: `pip3 -V`
- - **Ubuntu Note**: If you encounter a `ModuleNotFoundError`, install `python3-distutils` using `sudo apt-get install python3-distutils`.
+
+ - **Ubuntu Note**: If you encounter a `ModuleNotFoundError` , install `python3-distutils` using `sudo apt-get install python3-distutils` .
### Mac OS X
+
1. Create a directory for environments: `mkdir ~/python-envs`.
2. Create a new environment: `python3 -m venv ~/python-envs/sample-env`.
3. Activate the environment: `source ~/python-envs/sample-env/bin/activate`.
4. Update Pip and setuptools:
- `pip3 install --upgrade pip`
- - `pip3 install --upgrade setuptools`.
+
+ - `pip3 install --upgrade setuptools` .
5. Deactivate with `deactivate` (reactivate using the same command).
### Ubuntu
+
1. Install the `python3-venv` package: `sudo apt-get install python3-venv`.
2. Follow the Mac OS X steps for environment creation and management.
### Windows
-1. Create a directory for environments: `md python-envs`.
-2. Create a new environment: `python -m venv python-envs\sample-env`.
-3. Activate the environment: `python-envs\sample-env\Scriptsctivate`.
-4. Update Pip: `pip install --upgrade pip`.
+
+1. Create a directory for environments: `md python-envs` .
+2. Create a new environment: `python -m venv python-envs\sample-env` .
+3. Activate the environment: `python-envs\sample-env\Scriptsctivate` .
+4. Update Pip: `pip install --upgrade pip` .
5. Deactivate with `deactivate` (reactivate using the same command).
**Additional Notes for Windows Users**:
-- Confirm Python version: `python --version`.
-- Admin privileges may be required for Python installation.
-- This guide is specific to Windows 10 with a 64-bit architecture.
+* Confirm Python version: `python --version`.
+* Admin privileges may be required for Python installation.
+* This guide is specific to Windows 10 with a 64-bit architecture.
## Introduction to Conda Environments
+
_Anaconda_ (or simply Conda) is an open-source package management and environment management system that runs on Windows, macOS, and Linux. Conda environments are similar to Python virtual environments but they are managed with the Conda package manager.
## Setting Up Conda Environments
### Installing Conda
+
1. Download and install Anaconda or Miniconda from [Conda's official website](https://www.anaconda.com/distribution/).
2. Open a terminal (or Anaconda Prompt on Windows) and check the Conda version: `conda --version`.
### Creating a Conda Environment
+
1. Create a new environment: `conda create --name myenv` (replace `myenv` with your desired environment name).
2. Activate the environment: `conda activate myenv`.
### Managing Packages
-- Install a package: `conda install numpy` (replace `numpy` with your desired package).
-- Update a package: `conda update numpy`.
-- List installed packages: `conda list`.
+
+* Install a package: `conda install numpy` (replace `numpy` with your desired package).
+* Update a package: `conda update numpy`.
+* List installed packages: `conda list`.
### Deactivating an Environment
-- Deactivate with `conda deactivate`.
+
+* Deactivate with `conda deactivate`.
## Conclusion
+
Virtual Environments offer a robust solution for managing complex dependencies and are particularly useful for projects requiring a combination of Python and non-Python packages. This guide should help you get started with Conda or Python's Virtual Environments for using with Animal-AI.
diff --git a/docs/configGuide/YAML-Config-Syntax.md b/docs/configGuide/YAML-Config-Syntax.md
index 44b99972c..14449ccf8 100644
--- a/docs/configGuide/YAML-Config-Syntax.md
+++ b/docs/configGuide/YAML-Config-Syntax.md
@@ -1,6 +1,7 @@
# Detailed Arena Config Guide
#### Table of Contents
+
1. [Introduction](#introduction)
2. [Understanding YAML Syntax](#understanding-yaml-syntax)
2.1 [YAML Hierarchical Syntax](#yaml-hierarchical-syntax)
@@ -22,10 +23,10 @@
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.
-
### Understanding YAML Syntax
#### YAML Hierarchical Syntax
+
```YAML
# note that the arena has a fixed size of 40x40, meaning the size of the arena does not change.
# in later versions of Animal-AI, the arena size will be configurable. and be set dynamically.
@@ -35,19 +36,21 @@ arenas:
Items:
... # rest of configuration file...
```
+
**Observations:**
We can observe the following structure:
-- `!ArenaConfig` is the root tag.
-- `arenas` is the tag for the arenas.
-- `0` is the tag for the first arena in the file.
-- `!Arena` is the tag for the arena itself.
-- `Items` is the tag for the objects to spawn in the arena.
+* `!ArenaConfig` is the root tag.
+* `arenas` is the tag for the arenas.
+* `0` is the tag for the first arena in the file.
+* `!Arena` is the tag for the arena itself.
+* `Items` is the tag for the objects to spawn in the arena.
-The `!ArenaConfig` tag is used to indicate that the following YAML file is an ArenaConfig file. The `arenas` tag is used to indicate that the following YAML file contains one or more arenas. The `0` tag indicates that the following arena is the first arena in the file, upto `n arenas`. The `!Arena` tag indicates that the following YAML file contains an arena. The `!` tag is used to indicate that the following YAML file is a custom class. In this case, the `!Arena` tag indicates that the following YAML file is an Arena file. The `!Arena` tag is followed by a list of parameters that are used to define the arena, with the objects to spawn for that particular arena only. Some arena parameters are applied locally, such as `t` (time limit) and `pass_mark` (more on this later), while others are applied globally (see below for an example).
+The `!ArenaConfig` tag is used to indicate that the following YAML file is an ArenaConfig file. The `arenas` tag is used to indicate that the following YAML file contains one or more arenas. The `0` tag indicates that the following arena is the first arena in the file, upto `n arenas` . The `!Arena` tag indicates that the following YAML file contains an arena. The `!` tag is used to indicate that the following YAML file is a custom class. In this case, the `!Arena` tag indicates that the following YAML file is an Arena file. The `!Arena` tag is followed by a list of parameters that are used to define the arena, with the objects to spawn for that particular arena only. Some arena parameters are applied locally, such as `t` (time limit) and `pass_mark` (more on this later), while others are applied globally (see below for an example).
#### YAML Hierarchical Syntax (Config/YAML Global Parameters)
+
```YAML
!ArenaConfig
# Global Parameters that are optional to put here.
@@ -60,18 +63,20 @@ arenas:
... # rest of configuration file...
```
+
**Observations:**
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.
+* 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.
In the example above, the global parameters are defined before the arenas. These parameters are applied to all arenas in the file. Please note that these parameters are only applicable during `Play` mode, not agent `Training` mode.
#### YAML Hierarchical Syntax (Arena/Item Local Parameters)
+
```YAML
!ArenaConfig
arenas:
@@ -98,11 +103,12 @@ arenas:
skins:
- "hedgehog"
```
+
**Observations:**
Regarding Arena and Item local parameters, we can observe respectively that:
-- The _arena-specific_ parameters are only applicable to the arena in which they are defined. For example, if `t` is set to `250`, the time limit for the arena will be 250 seconds. However, if there are multiple arenas defined in the same YAML configuration file `t` is set to `500`, the time limit for the arena will be 500 seconds for that arena only. Please note that these parameters are applicable during `Play` and `Training` modes. Lastly, the properties of each "Item" is a local parameter specified for that particular object only. For example, if the `Agent` object is specified to have a `hedgehog` skin, only the `Agent` object will have a `hedgehog` skin for that particular arena.
+* The _arena-specific_ parameters are only applicable to the arena in which they are defined. For example, if `t` is set to `250`, the time limit for the arena will be 250 seconds. However, if there are multiple arenas defined in the same YAML configuration file `t` is set to `500`, the time limit for the arena will be 500 seconds for that arena only. Please note that these parameters are applicable during `Play` and `Training` modes. Lastly, the properties of each "Item" is a local parameter specified for that particular object only. For example, if the `Agent` object is specified to have a `hedgehog` skin, only the `Agent` object will have a `hedgehog` skin for that particular arena.
```YAML
!ArenaConfig
@@ -134,7 +140,7 @@ arenas:
- !Vector3 {x: 1000, y: 1000, z: 1000}
```
-- Moreover, we can observe that the `!Item` tag also contains local parameters of its own, which we define as _item-only_ local parameters. Such item-only local parameters are only applicable to the object in which they are defined. For example, if we define a `Wall` object twice in the same arena (as demonstrated in the above YAML snippet), the local parameters such as positions, sizes, colors, rotations etc. defined for the first `Wall` object will not apply to the second `Wall` object in the same arena.
+* Moreover, we can observe that the `!Item` tag also contains local parameters of its own, which we define as _item-only_ local parameters. Such item-only local parameters are only applicable to the object in which they are defined. For example, if we define a `Wall` object twice in the same arena (as demonstrated in the above YAML snippet), the local parameters such as positions, sizes, colors, rotations etc. defined for the first `Wall` object will not apply to the second `Wall` object in the same arena.
The syntax implemented allows for a high degree of flexibility in the creation of custom arenas where multiple objects of the same type can be defined with different properties for the same arena, without conflict.
@@ -145,6 +151,7 @@ Let's now take a look at more complex examples to understand how to use the YAML
Let's take a look at some examples to understand how to use the YAML syntax in Animal-AI to create custom arenas.
#### EXAMPLE 1 - Standard Parameters & Randomisation
+
```YAML
!ArenaConfig
arenas:
@@ -177,21 +184,22 @@ arenas:
**Observations:**
-- 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.
+* 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`.
+* 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.
-- 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 in a random position and orientation if it is unspecified in the arena instance. This is an important point to note, as if the agent was specified, it would have priority over all other objects and would be spawned first, before any other object(s).
+* 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 in a random position and orientation if it is unspecified in the arena instance. This is an important point to note, as if the agent was specified, it would have priority over all other objects and would be spawned first, before any other object(s).
-
+
#### EXAMPLE 2 - Decay Goals / Size-Changing Goals
+
```YAML
!ArenaConfig
arenas:
@@ -252,19 +260,20 @@ arenas:
**Observations:**
-This example showcases various goals that undergo changes such as `decay`, `growth`, `shrinkage`, and `ripening` (anti-decay). Each Item in this setup includes certain parameters that are either irrelevant or used incorrectly. These 'red herring' parameters, while not utilized properly, do not impact the overall outcome or cause issues with the AAI environment.
+This example showcases various goals that undergo changes such as `decay` , `growth` , `shrinkage` , and `ripening` (anti-decay). Each Item in this setup includes certain parameters that are either irrelevant or used incorrectly. These 'red herring' parameters, while not utilized properly, do not impact the overall outcome or cause issues with the AAI environment.
In the above scenario:
-- The `ShrinkGoal` and `GrowGoal` ignore the declared `sizes` parameter. Instead, their sizes change based on the initialValues and finalValues.
-- For both `DecayGoal` and `AntiDecayGoal`, the size is determined by the larger of the `initialValue` or `finalValue`.
-- Additionally, the reward for these goals transitions from the initial value to the final value over time.
+* The `ShrinkGoal` and `GrowGoal` ignore the declared `sizes` parameter. Instead, their sizes change based on the initialValues and finalValues.
+* For both `DecayGoal` and `AntiDecayGoal`, the size is determined by the larger of the `initialValue` or `finalValue`.
+* Additionally, the reward for these goals transitions from the initial value to the final value over time.
Interestingly, the ShrinkGoal includes a `symbolNames` parameter, which is typically reserved for `SignBoard` objects. This parameter is not applicable here and is therefore disregarded.
-- Furthermore, an 'animal skin' feature is utilized in this example. Specifically, the Agent is configured to always appear with a 'hedgehog' skin.
+* Furthermore, an 'animal skin' feature is utilized in this example. Specifically, the Agent is configured to always appear with a 'hedgehog' skin.
-
+
#### EXAMPLE 3 - SignBoard (Preset Symbols)
+
```YAML
!ArenaConfig
arenas:
@@ -310,9 +319,10 @@ arenas:
This example illustrates how to employ predefined symbols using the `symbolNames` parameter, which is exclusive to `SignBoard` objects. Each symbol in this list comes with a default color. However, these colors do not affect the texture of the symbol. Instead, the color of the SignBoard gameobject is determined by the `colors` parameter and only that.
-
+
#### EXAMPLE 4 - SignBoard (Special Symbols)
+
```YAML
!ArenaConfig
arenas:
@@ -354,13 +364,14 @@ arenas:
**Observations:**
-This example demonstrates the use of *special codes* to generate black-and-white pixel grids to use as symbols. `0` -> black, `1` -> white, and `*` is a 'joker' character that chooses to output black or white at random. The dimensions of the grid are given by the `/` character - each row between `/`s must be of the same size for the code to be valid.
+This example demonstrates the use of *special codes* to generate black-and-white pixel grids to use as symbols. `0` -> black, `1` -> white, and `*` is a 'joker' character that chooses to output black or white at random. The dimensions of the grid are given by the `/` character - each row between `/` s must be of the same size for the code to be valid.
-Fully-random grids can be generated using the code `"MxN"`, where `M` and `N` are the grid width and height dimensions respectively. For example, `"5x3"` will generate a 5x3 grid.
+Fully-random grids can be generated using the code `"MxN"` , where `M` and `N` are the grid width and height dimensions respectively. For example, `"5x3"` will generate a 5x3 grid.
-
+
#### EXAMPLE 5 - SpawnerButton (Interactive Objects)
+
```YAML
!ArenaConfig
arenas:
@@ -399,23 +410,24 @@ arenas:
**Observations:**
-- The `SpawnerButton` object is an interactive object, meaning that it can be interacted with by the player/agent.
-- The `SpawnerButton` object is a modular object, meaning that it is made up of multiple modules. In this case, the `SpawnerButton` object is made up of 2 modules.
+* The `SpawnerButton` object is an interactive object, meaning that it can be interacted with by the player/agent.
+* The `SpawnerButton` object is a modular object, meaning that it is made up of multiple modules. In this case, the `SpawnerButton` object is made up of 2 modules.
In the above example, the `SpawnerButton` object is used to spawn rewards upon interaction with the button (by 'colliding' with the gameobject) by the player/agent. We can observe that the `SpawnerButton` object has a number of parameters that are used to define the object's behaviour. These parameters are as follows:
-- `moveDurations`: The duration of the movement of the button when it is pressed.
-- `resetDurations`: The duration of the movement of the button when it is reset.
-- `rewardNames`: The list of rewards that can be spawned.
-- `rewardWeights`: The weights of each reward in the rewards list.
-As an added feature, the weights can be used to control the probability of spawning each reward. For example, if the weights are `[100, 0, 0]`, the probability of spawning the first reward is 100%, while the probability of spawning the second and third rewards are 0%. If the weights are `[50, 50, 0]`, the probability of spawning the first and second rewards are 50%, while the probability of spawning the third reward is 0%. If the weights are `[33, 33, 33]`, the probability of spawning each reward is 33%.
-- `spawnProbability`: The probability of spawning the reward upon interaction with the SpawnerButton. This parameter is used in conjunction with the `rewardWeights` parameter. Essentially, it controls the overall probability of spawning _a_ reward upon interaction with the SpawnerButton. For example, if you have the `rewardWeights` set to `[100, 100, 100]` but the `spawnProbability` set to `0.5`, the probability of spawning a reward is 50% at each interaction. Conversely, if you have the `rewardWeights` set to `[100, 100, 100]` but the `spawnProbability` set to `0.0`, the probability of spawning a reward is 0% at each interaction, meaning no reward will ever be spawned.
-- `maxRewardCounts`: The maximum number of times each reward can be spawned. A value of -1 means no limit to the number of times the reward can be spawned per episode.
-- `rewardSpawnPos`: The position where the reward will be spawned. If left unspecified, the reward will be spawned randomly within the arena.
+* `moveDurations`: The duration of the movement of the button when it is pressed.
+* `resetDurations`: The duration of the movement of the button when it is reset.
+* `rewardNames`: The list of rewards that can be spawned.
+* `rewardWeights`: The weights of each reward in the rewards list.
+As an added feature, the weights can be used to control the probability of spawning each reward. For example, if the weights are `[100, 0, 0]` , the probability of spawning the first reward is 100%, while the probability of spawning the second and third rewards are 0%. If the weights are `[50, 50, 0]` , the probability of spawning the first and second rewards are 50%, while the probability of spawning the third reward is 0%. If the weights are `[33, 33, 33]` , the probability of spawning each reward is 33%.
+* `spawnProbability`: The probability of spawning the reward upon interaction with the SpawnerButton. This parameter is used in conjunction with the `rewardWeights` parameter. Essentially, it controls the overall probability of spawning _a_ reward upon interaction with the SpawnerButton. For example, if you have the `rewardWeights` set to `[100, 100, 100]` but the `spawnProbability` set to `0.5`, the probability of spawning a reward is 50% at each interaction. Conversely, if you have the `rewardWeights` set to `[100, 100, 100]` but the `spawnProbability` set to `0.0`, the probability of spawning a reward is 0% at each interaction, meaning no reward will ever be spawned.
+* `maxRewardCounts`: The maximum number of times each reward can be spawned. A value of -1 means no limit to the number of times the reward can be spawned per episode.
+* `rewardSpawnPos`: The position where the reward will be spawned. If left unspecified, the reward will be spawned randomly within the arena.
-
+
#### EXAMPLE 6 - Multiple Arenas (Randomisation)
+
```YAML
!ArenaConfig
randomizeArenas: true # Here, we set randomizeArenas to true, which means that the arenas will be randomized upon play. Note that this is not applicable to training mode.
@@ -453,9 +465,11 @@ arenas:
Arena 0 |
 Arena 1 |
+
2D view of the Arena |
 First-person view of agent |
 Full view of arena |
+
 Close-up of arena ground |
 Third Persion view of one of the agent skins |
 Side view of walls |
+
Hedgehog |
 Panda |
 Pig |
+