From dedb8cf5c88884e279d0c869e87dc46ac83ae760 Mon Sep 17 00:00:00 2001 From: Ibrahim Alhas Date: Thu, 12 Sep 2024 20:15:57 +0100 Subject: [PATCH] updated docs on blackouts following code changes + minor file format fix --- docs/Arena-Environment-Guide.md | 59 ++++++++++---------------- docs/configGuide/YAML-Config-Syntax.md | 8 ++-- 2 files changed, 25 insertions(+), 42 deletions(-) diff --git a/docs/Arena-Environment-Guide.md b/docs/Arena-Environment-Guide.md index df182104d..422a3b1bb 100644 --- a/docs/Arena-Environment-Guide.md +++ b/docs/Arena-Environment-Guide.md @@ -1,24 +1,23 @@ # Arena Environment Guide #### Table of Contents - -* [Introduction](#introduction) -* [The Arena](#the-arena) -* [The Agent](#the-agent) - + [Agent HUD (Heads-Up Display)](#agent-hud-heads-up-display) - + [Arena/Agent Limitations](#arenaagent-limitations) - + [Agent Properties](#agent-properties) -* [GameObjects](#gameobjects) - + [Unique/Special Object Parameters](#uniquespecial-object-parameters) - + [Agent-Specific Parameters](#agent-specific-parameters) - + [Goal-Related Parameters](#goal-related-parameters) - + [Spawner Parameters](#spawner-parameters) - + [SignBoard Parameters](#signboard-parameters) -* [Blackouts](#blackouts) -* [CSV Logger](#csv-logger) -* [Rules and Notes for Arena Configurations](#rules-and-notes-for-arena-configurations) - + [Spawning GameObjects](#spawning-gameobjects) - + [Configuration File Values](#configuration-file-values) + - [Introduction](#introduction) + - [The Arena](#the-arena) + - [The Agent](#the-agent) + - [Agent HUD (Heads-Up Display)](#agent-hud-heads-up-display) + - [Arena/Agent Limitations](#arenaagent-limitations) + - [Agent Properties](#agent-properties) + - [Game Objects](#game-objects) + - [Unique/Special Object Parameters](#uniquespecial-object-parameters) + - [Agent-Specific Parameters](#agent-specific-parameters) + - [Goal-Related Parameters](#goal-related-parameters) + - [Spawner Parameters](#spawner-parameters) + - [SignBoard Parameters](#signboard-parameters) + - [Blackouts](#blackouts) + - [CSV Logger](#csv-logger) + - [Rules and Notes for Arena Configurations](#rules-and-notes-for-arena-configurations) + - [Spawning GameObjects](#spawning-gameobjects) + - [Configuration File Values](#configuration-file-values) ## Introduction @@ -30,19 +29,15 @@ For a detailed explanation of the syntax used in the configuration files, refer - - - -

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

@@ -124,12 +119,10 @@ The agent has a set of skins that can be used to change its appearance in the ar - -

Panda Skin

Pig Skin

Hedgehog Skin

@@ -143,17 +136,9 @@ The agent has a HUD that displays the following information per episode by defau * **Episode Notification**: A notification displayed at the end of an episode, consisting of color gradients and a short animated GIF. This HUD element is optional and only appears if the `showNotification` parameter is set to `true` in the configuration file. _Note: This feature is only for play mode and does not affect training._ -| - -![](../docs/figs/Agent-HUD/agent-health.png) | ![](../docs/figs/Agent-HUD/agent-REWARD.png) - - | +| ![](../docs/figs/Agent-HUD/agent-health.png)|![](../docs/figs/Agent-HUD/agent-REWARD.png)| | ------------------------------------------------ | ------------------------------------------------- | -| - -![](../docs/figs/Agent-HUD/notification-bad.png) | ![](../docs/figs/Agent-HUD/notification-good.png) - - | +| ![](../docs/figs/Agent-HUD/notification-bad.png)|![](../docs/figs/Agent-HUD/notification-good.png)| ### Arena/Agent Limitations @@ -285,11 +270,11 @@ Some objects have unique or special parameters that only apply to them or a sele _Blackouts_ define when the lights are on or off during an episode in each arena, resulting in a black screen/view in any camera angle. This is an optional parameter in the configuration file, and can be omitted if you don't want to use it. If omitted, the lights will be on for the entire episode. * **Default Behavior**: Lights are on for the entire episode if no blackout parameter is provided. -* **List of Frames**: Provide a list like `[5,10,15,20,25]` to toggle lights. Lights will be off between frames 5-9, 15-19, etc., and on at other times. +* **List of Frames**: Provide a list like `[10,20],[25,50]` to toggle lights. Lights will be off between frames 10,20, and 25-50, etc. * **Regular Intervals**: Use a negative number like `[-20]` to toggle lights every 20 frames. -* **Infinite Episodes**: For episodes with `t=0`, lights will follow the pattern indefinitely. +* **Infinite Episodes**: For episodes with `timeLimit=0`, the episode will be considered infinite. -**Note**: With a list of frames, the lights will stay off after the last frame in the list for infinite episodes. +**Note**: With a list of frames, the lights will stay off after the last frame in the list for infinite episodes. See the [YAML Config Syntax](/docs/configGuide/YAML-Config-Syntax.md) guide for a detailed tutorial on how to use blackouts. diff --git a/docs/configGuide/YAML-Config-Syntax.md b/docs/configGuide/YAML-Config-Syntax.md index 3fcde89b5..997e39cb2 100644 --- a/docs/configGuide/YAML-Config-Syntax.md +++ b/docs/configGuide/YAML-Config-Syntax.md @@ -554,15 +554,13 @@ arenas: 0: !Arena timeLimit: 100 passMark: 0 + blackouts: [10, 43, 50, 20] # We are defining the blackout times (in frames) for the arena at interval frames [10, 43], and [50 and 60]. The blackout zones are defined in frames, not in seconds. Note that the intervals are increasing in value from left to right, meaning. for example, a blackout can't start at frame 43 and end at frame 10. items: - !Item name: Agent positions: - !Vector3 {x: 10, y: 0, z: 20} rotations: [90] - skins: - - "pig" - blackouts: [10, 43, 50, 20] # here, we are defining the blackout times (in frames) for the arena at frames 10, 43, 50 and 20. ```

@@ -573,8 +571,8 @@ arenas: We can observe the following: -* The `blackouts` parameter defines the blackout zones for the arena. This parameter is a list of frames at which the arena will experience a blackout. For example, setting `blackouts` to `[10, 43, 50, 20]` means the arena will be blacked out at frames 10, 20, 43, and 50. During these frames, the player/agent will not receive any visual information, as no light will be emitted to the arena. -* If `blackouts` is set to `[-20]`, the arena will experience a blackout every 20 frames. The '-' sign indicates that the blackout should repeat at regular intervals. +* The `blackouts` parameter defines the blackout zones for the arena. This parameter is a list of frames at which the arena will experience a blackout. During these frames, the player will not receive any visual information, as no light will be emitted to the arena. +* If `blackouts` is set to a negative value, such as `[-20]`, the arena will experience a blackout every 20 frames. The '-' sign indicates that the blackout should repeat at regular intervals. * The blackout only affects visual visibility and does not impact other aspects of the agent or the arena. For example, the agent can still move around, and the objects within the arena remain visible to the agent. _RayCasting_ will continue to function as usual.