Documentation update.

CHANGELOG.md

@@ -27,14 +27,17 @@
 * Added theme support for Lottie animations (vector graphics)
 * Added theme support for GIF animations
 * Added a GameSelectorComponent for displaying game media and metadata in the system view
-* Added support for displaying videos, Lottie animations and date/time elements to the system view
+* Added support to the system view for displaying videos, Lottie animations, GIF animations, date/time components and game ratings
 * Replaced the forceUppercase theme property with a more versatile letterCase property (forceUppercase is retained for legacy theme compatibility)
 * Made it possible to set any text element as a scrollable container using either metadata values or literal strings
 * Added support for defining the scrollable container speed, start delay and reset delay from the theme configuration
 * Added theme support for defining the opacity for most element types
+* Added theme support for defining color saturation for images, videos and animations
 * Added theme support for defining the video fade-in time
 * Added theme support for enabling and disabling video pillarboxes and scanline rendering
 * Added theme support for enabling or disabling audio playback for videos
+* Added theme support for setting the horizontal alignment for the help prompts (left/center/right)
+* Added theme support for setting separate textColorDimmed and iconColorDimmed properties for the system and gamelist views
 * Disabled the pillarboxes and scanline rendering menu options when using a non-legacy theme set
 * Improved theme element placement by replacing the "alignment" and "logoAlignment" properties with specific horizontal and vertical properties
 * Made it possible to use almost all game metadata field when theming text elements
@@ -72,6 +75,7 @@
 * Migrated the carousel code from SystemView to a separate new CarouselComponent
 * Changed all occurances of "GameList" to "Gamelist" throughout the codebase
 * Removed a huge amount of unnecessary Window* function parameters throughout the codebase
+* Removed a lot of unnecessary applyTheme() calls when updating help prompts
 * Changed the opacity data type and functions from unsigned char to float throughout the codebase
 * Refactored the six gamelist classes into two new classes; GamelistBase and GamelistView
 * Rewrote the gamelist logic to handle an arbitrary amount of components per type and split the legacy code into a separate file
@@ -95,6 +99,7 @@
 * When multi-scraping in semi-automatic mode and a long game name was scrolling, the start position was not reset when scraping the next game
 * Slide and fade transitions would sometimes stop working after changing theme sets
 * Using fade transitions, when holding a direction button to scroll the system view carousel, the key repeat would cause an unwanted background rendering
+* The outermost logos would sometimes glitch out during carousel transitions
 * Horizontal and vertical gradients were mixed up (showing the opposite gradient type if set in a theme)
 * The VideoComponent static images were not fading out smoothly on gamelist fast-scrolling
 * Rating icon outlines would not fade out correctly when fast-scrolling in a gamelist

THEMES-DEV.md

@@ -79,6 +79,8 @@ The following are the most important changes compared to the legacy theme struct
 * The ambiguous `alignment` property has been replaced with the `horizontalAlignment` and `verticalAlignment` properties (the same is true for `logoAlignment` for the `carousel` component)
 * The `forceUppercase` property has been replaced with the more versatile `letterCase` property
 * The carousel text element hacks `systemInfo` and `logoText` have been removed and replaced with proper carousel properties
+* The carousel property maxLogoCount is now in float format for more granular control of logo placement compared to integer format for legacy themes. However some legacy theme authors thought this property supported floats (as the theme documentation incorrectly stated this) and have therefore set it to fractional values such as 3.5. This was actually rounded up when loading the theme configuration, and this logic is retained for legacy themes for backward compatibility. But for current themes the float value is correctly interpreted which means a manual rounding of the value is required in order to retain an identical layout when porting theme sets to the new theme engine
+* The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views
 * Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail
 * Many additional elements and properties have been added, refer to the [Reference](THEMES-DEV.md#reference) section for more information
 
@@ -787,7 +789,7 @@ Properties:
     - `3dbox` - This will look for a 3D box image.
     - `fanart` - This will look for a fan art image.
 * `gameselector` - type: STRING
-    - If more than one gameselector elements have been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized.
+    - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized.
 * `tile` - type: BOOLEAN
     - If true, the image will be tiled instead of stretched to fit its size.  Useful for backgrounds.
 * `interpolation` - type: STRING
@@ -809,6 +811,10 @@ Properties:
     - Controls the level of transparency. If set to `0` the element will be disabled.
     - Minimum value is `0` and maximum value is `1`
     - Default is `1`
+* `saturation` - type: FLOAT
+    - Controls the level of color saturation.
+    - Minimum value is `0` (grayscale) and maximum value is `1` (original file saturation).
+    - Default is `1`
 * `visible` - type: BOOLEAN
     - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
     - Default is `true`
@@ -856,7 +862,7 @@ Properties:
     - `3dbox` - This will look for a 3D box image.
     - `fanart` - This will look for a fan art image.
 * `gameselector` - type: STRING
-    - If more than one gameselector elements have been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element.
+    - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element.
 * `audio` - type: BOOLEAN
     - Whether to enable or disable audio playback for the video.
     - Default is `true`
@@ -885,6 +891,10 @@ Properties:
     - Controls the level of transparency. If set to `0` the element will be disabled.
     - Minimum value is `0` and maximum value is `1`
     - Default is `1`
+* `saturation` - type: FLOAT
+    - Controls the level of color saturation. This affects both the static image and the video stream.
+    - Minimum value is `0` (grayscale) and maximum value is `1` (original file saturation).
+    - Default is `1`
 * `visible` - type: BOOLEAN
     - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
     - Default is `true`
@@ -937,6 +947,10 @@ Properties:
     - Controls the level of transparency. If set to `0` the element will be disabled.
     - Minimum value is `0` and maximum value is `1`
     - Default is `1`
+* `saturation` - type: FLOAT
+    - Controls the level of color saturation.
+    - Minimum value is `0` (grayscale) and maximum value is `1` (original file saturation).
+    - Default is `1`
 * `visible` - type: BOOLEAN
     - If set to false, the element will be disabled. This is equivalent to setting `opacity` to `0`
     - Default is `true`
@@ -1106,7 +1120,7 @@ Properties:
     - `controller` - The controller for the game. Will be blank if none has been selected.
     - `altemulator` - The alternative emulator for the game. Will be blank if none has been selected.
 * `gameselector` - type: STRING
-    - If more than one gameselector elements have been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `metadata` property is utilized.
+    - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `metadata` property is utilized.
 * `container` - type: BOOLEAN
     - Whether the text should be placed inside a scrollable container. Only available for the `gamelist` view.
 * `containerScrollSpeed` - type: FLOAT
@@ -1187,7 +1201,7 @@ Properties:
     - `releasedate` - The release date of the game.
     - `lastplayed` - The time the game was last played. This will be displayed as a value relative to the current date and time by default, but can be overridden using the `displayRelative` property.
 * `gameselector` - type: STRING
-    - If more than one gameselector elements have been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `metadata` property is utilized.
+    - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `metadata` property is utilized.
 * `fontPath` - type: PATH
     - Path to a TrueType font (.ttf).
 * `fontSize` - type: FLOAT
@@ -1286,7 +1300,10 @@ Properties:
 
 Displays a graphical representation of the game rating, from 0 to 5.
 
+To display game ratings in the `system` view, you first need to create a `gameselector` element.
+
 Supported views:
+* `system`
 * `gamelist`
 
 Instances per view:
@@ -1306,6 +1323,8 @@ Properties:
 * `rotationOrigin` - type: NORMALIZED_PAIR
     - Point around which the rating will be rotated.
     - Default is `0.5 0.5`
+* `gameselector` - type: STRING
+    - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view.
 * `color` - type: COLOR
     - Multiply each pixel's color by this color. For example, an all-white image with `<color>FF0000</color>` would become completely red.  You can also control the transparency of an image with `<color>FFFFFFAA</color>` - keeping all the pixels their normal color and only affecting the alpha channel.
 * `filledPath` - type: PATH
@@ -1327,6 +1346,8 @@ Properties:
 
 Displays a carousel for selecting game systems.
 
+ When using fade transitions, any elements placed below or at the same zIndex value as the carousel will be faded to black during transitions, and any elements with a higher zIndex value than the carousel will be faded to transparent.
+
 Supported views:
 * `system`
 
@@ -1339,12 +1360,14 @@ Properties:
     - Valid values are `horizontal`, `vertical`, `horizontal_wheel` or `vertical_wheel`.
     - Default is `horizontal`
 * `size` - type: NORMALIZED_PAIR
+    - Minimum value per axis is `0.05` and maximum value per axis is `1.5`
     - Default is `1 0.2325`
 * `pos` - type: NORMALIZED_PAIR
     - Default is `0 0.38375`
 * `origin` - type: NORMALIZED_PAIR
     - Where on the carousel `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the carousel exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
     - Minimum value per axis is `0` and maximum value per axis is `1`
+    - Default is `0 0`
 * `color` - type: COLOR
     - Color of the carousel background panel. Setting a value of `00000000` makes the background panel transparent.
     - Default is `FFFFFFD8`
@@ -1382,9 +1405,9 @@ Properties:
     - Sets `logo` and `text` alignment relative to the carousel on the Y axis, which applies when `type` is "horizontal", "horizontal_wheel" or "vertical_wheel".
     - Valid values are `top`, `center` or `bottom`
     - Default is `center`
-* `maxLogoCount` - type: UNSIGNED_INTEGER
+* `maxLogoCount` - type: FLOAT
     - Sets the number of logos to display in the carousel.
-    - Minimum value is `2` and maximum value is `30`
+    - Minimum value is `0.5` and maximum value is `30`
     - Default is `3`
 * `text` - type: STRING
     - A string literal to display if there is no `logo` or `defaultLogo` properties defined and if no images were found.
@@ -1469,7 +1492,7 @@ Properties:
 
 #### gameselector
 
-Selects games from the gamelists when navigating the `system` view. This makes it possible to display game media and game metadata directly from this view. It's possible to make separate gameselector configurations per game system, so that for instance a random game could be displayed for one system and the most recently played game could be displayed for another system. It's also possible to define multiple gameselector elements with different selection criterias per game system which makes it possible to for example set a random fan art background image and at the same time display a box cover image of the most recently played game. The gameselector logic can be used for the `image`, `video`, `text` and `datetime` elements.
+Selects games from the gamelists when navigating the `system` view. This makes it possible to display game media and game metadata directly from this view. It's possible to make separate gameselector configurations per game system, so that for instance a random game could be displayed for one system and the most recently played game could be displayed for another system. It's also possible to define multiple gameselector elements with different selection criterias per game system which makes it possible to for example set a random fan art background image and at the same time display a box cover image of the most recently played game. The gameselector logic can be used for the `image`, `video`, `text`, `datetime` and `rating` elements.
 
 Supported views:
 * `system`
@@ -1489,7 +1512,7 @@ Properties:
 
 #### helpsystem
 
-The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Note that this element does not have a zIndex value, instead it's always rendered on top of all other elements.
+The help system is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Note that this element does not have a zIndex value, instead it's always rendered on top of all other elements. As well an origin value of `0 0` is always applied for this element.
 
 Supported views:
 * `system`
@@ -1500,20 +1523,20 @@ Instances per view:
 
 Properties:
 * `pos` - type: NORMALIZED_PAIR
-    - Default is `0.012 0.9515`
-* `origin` - type: NORMALIZED_PAIR
-    - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place
-      the element exactly in the middle of the screen.
-    - Minimum value per axis is `0` and maximum value per axis is `1`
+    - This works a bit different than for the other elements. If `horizontalAlignment` is set to `left` then the x axis value works as expected, but if it's set to `right` then it acts as an offset from the right side of the screen. If setting the alignment to `center` the x axis value should be set to `0` as it doesn't make much sense to add an offset in this case. The y axis value always works as expected and is not affected by the choice of horizontal alignment.
+    - Default is `0.012 0.9515` when `horizontalAlignment` is set to `left` or `right`
+    - Default is `0 0.9515` when `horizontalAlignment` is set to `center`
+* `horizontalAlignment` - type: STRING
+    - Controls alignment on the X axis.
+    - Valid values are `left`, `center` or `right`
+    - Default is `left`
 * `textColor` - type: COLOR
     - Default is `777777FF`
 * `textColorDimmed` - type: COLOR
-    - Must be placed under the 'system' view.
     - Default is the same value as textColor.
 * `iconColor` - type: COLOR
     - Default is `777777FF`
 * `iconColorDimmed` - type: COLOR
-    - Must be placed under the 'system' view.
     - Default is the same value as iconColor.
 * `fontPath` - type: PATH
 * `fontSize` - type: FLOAT

THEMES-LEGACY.md

@@ -985,7 +985,7 @@ It's strongly recommended to use the same image dimensions for all badges as var
     - Accepted values are "left", "right" or "center" when `type` is "vertical" or "vertical_wheel".
     - Default is "center"
 * `maxLogoCount` - type: FLOAT.
-    - Sets the number of logos to display in the carousel.
+    - Sets the number of logos to display in the carousel. Note that fractional values are rounded up.
     - Default is 3
 * `zIndex` - type: FLOAT.
     - z-index value for component. Components will be rendered in order of z-index value from low to high with the carousel above all other components.

THEMES.md

@@ -983,7 +983,7 @@ It's strongly recommended to use the same image dimensions for all badges as var
     - Accepted values are "left", "right" or "center" when `type` is "vertical" or "vertical_wheel".
     - Default is "center"
 * `maxLogoCount` - type: FLOAT.
-    - Sets the number of logos to display in the carousel.
+    - Sets the number of logos to display in the carousel. Note that fractional values are rounded up.
     - Default is 3
 * `zIndex` - type: FLOAT.
     - z-index value for component.  Components will be rendered in order of z-index value from low to high.

USERGUIDE-DEV.md

@@ -230,7 +230,9 @@ The log file is located in the ES-DE home directory and would be something like
 
 Another possibility is that OpenGL drivers are actually installed but the GPU doesn't support the extensions listed above. That would be quite surprising though as these extensions have existed for many years. But for ancient graphics cards there's the possibility that ES-DE won't run.
 
-An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game.
+An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem.
+
+In order for ES-DE to find these emulators there are two possible solutions, the first is to manually add the emulator directories to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game. The second option is to place the emulators inside the ES-DE installation directory (for example `C:\Program Files\EmulationStation-DE\`) in which case they will also be found when launching a game.
 
 ## Specific notes for macOS
 
@@ -2004,7 +2006,7 @@ Sometimes the name of the console is (more or less) the same for multiple region
 
 For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name.
 
-The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
+The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable or place it inside the ES-DE installation directory. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
 
 The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core.
 
@@ -2025,7 +2027,7 @@ In general .zip or .7z files are recommended for smaller-sized games like those
 Consider the table below a work in progress as it's obvioulsy not fully populated yet!
 
 Default emulator/Alternative emulators columns: \
-**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs manual Path environment variable entry
+**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs to have a Path environment variable entry or be placed inside the ES-DE installation directory
 
 All emulators are RetroArch cores unless marked as **(Standalone**)
 

USERGUIDE.md

@@ -228,7 +228,9 @@ The log file is located in the ES-DE home directory and would be something like
 
 Another possibility is that OpenGL drivers are actually installed but the GPU doesn't support the extensions listed above. That would be quite surprising though as these extensions have existed for many years. But for ancient graphics cards there's the possibility that ES-DE won't run.
 
-An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game.
+An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem.
+
+In order for ES-DE to find these emulators there are two possible solutions, the first is to manually add the emulator directories to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game. The second option is to place the emulators inside the ES-DE installation directory (for example `C:\Program Files\EmulationStation-DE\`) in which case they will also be found when launching a game.
 
 ## Specific notes for macOS
 
@@ -1997,7 +1999,7 @@ Sometimes the name of the console is (more or less) the same for multiple region
 
 For the **Full name** column, text inside square brackets [] are comments and not part of the actual system name.
 
-The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
+The **Default emulator** column lists the primary emulator as configured in es_systems.xml. If this differs between Unix, macOS and Windows then it's specified in square brackets, such as [UW] for Unix and Windows and [M] for macOS. If one or more of the platforms are not specified it means that the system is not available on those platforms. For example Lutris which only exists on Unix is marked with only a [U]. There is a special [W*] indication for Windows which means that you need to manually add the emulator directory to the operating system's Path environment variable or place it inside the ES-DE installation directory. This is required as some emulators don't ship with proper installers but instead only as a zip file that can be extracted anywhere on the filesystem. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core. A number of systems are marked as _Placeholder_ which means that although there is a configuration entry present, the actual emulator is not preconfigured. If you want to use such a system, you need to add a custom configuration yourself. The long term goal is to have these placeholders replaced with proper emulator configuration so all systems can be used without requiring manual setup.
 
 The **Alternative emulators** column lists additional emulators configured in es_systems.xml that can be selected per system and per game, as explained earlier in this guide. This does not necessarily include everything in existence, as for some platforms there are a lot of emulators to choose from. In those cases the included emulators is a curated selection. In the same manner as the _Default emulator_ column, differences between Unix, macOS and Windows are marked using square brackets. Unless explicitly marked as **(Standalone)**, each emulator is a RetroArch core.
 
@@ -2018,7 +2020,7 @@ In general .zip or .7z files are recommended for smaller-sized games like those
 Consider the table below a work in progress as it's obvioulsy not fully populated yet!
 
 Default emulator/Alternative emulators columns: \
-**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs manual Path environment variable entry
+**[U]**: Unix, **[M]**: macOS, **[W]**: Windows, **[W\*]**: Windows, needs to have a Path environment variable entry or be placed inside the ES-DE installation directory
 
 All emulators are RetroArch cores unless marked as **(Standalone**)