Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-21 21:55:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2023-02-11 13:35:03 +01:00
parent 1e907adb12
commit 047ab9111e
5 changed files with 94 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
CHANGELOG.md
View file

@ -12,7 +12,7 @@ The 2.0 release introduces multiple fundamental changes to the application, most
Theme variants, color schemes, aspect ratios and transitions can now be defined by the theme author and are user-selectable from within the menu system. In addition to all this new theme functionality the application is still backward compatible with legacy theme sets.
The renderer has been modernized and rewritten and while still using OpenGL it's now fully shader-based instead of using a fixed function pipeline as was the case in previous releases. Rendering performance has been greatly improved in some areas such as post processing (used for the video player scanline and blur shaders among other things). A new SVG rendering library named LunaSVG has been introduced which offers much better file compatibility than before, while doing it with better performance.
The renderer has been modernized and rewritten and while still using OpenGL it's now fully shader-based instead of using a fixed function pipeline as was the case in previous releases. Tate mode (vertical screen orientation) support has been added including the ability to rotate the screen contents within the application window. Rendering performance has been greatly improved in some areas such as post processing (used for the video player scanline and blur shaders among other things). A new SVG rendering library named LunaSVG has been introduced which offers much better file compatibility than before, while doing it with better performance.
Overall application speed and performance has been greatly improved with faster startup times, less latency and lower CPU utilization. Many bugs have been fixed and multiple quality of life improvements have been made. Support for a lot more standalone emulators is also included with this release, see below for more details.
@ -187,6 +187,7 @@ Overall application speed and performance has been greatly improved with faster
* Added a metadataElement theme property to the image, video, animation and text element types to control fading and hiding of arbitrary elements
* Added the rendering of a green rectangle around the CarouselComponent when pressing Ctrl+i in debug mode
* Changed the color of the rectangle from blue to green for TextListComponent when pressing Ctrl+t in debug mode
* Added scraper settings for defining a retry count and a retry timer in case of errors
* Added scraper support for displaying the returned platform if it does not match the game platform, or if multiple platforms are defined for the system
* Added scraping of fan art and updated the media viewer to display these images
* Added scraping of box back covers when using TheGamesDB
@ -203,7 +204,9 @@ Overall application speed and performance has been greatly improved with faster
* Reduced CPU usage significantly by only rendering the necessary systems in SystemView
* Added support for dimming components (fade to black)
* Added logging of the display refresh rate on startup
* Added a command line option to rotate the application screen 180 degrees
* Added support for rotating the application screen contents 0, 90, 180 or 270 degrees
* Made many improvements to GUI sizing and positioning when running in vertical screen resolutions
* The application startup can now be aborted via an OS signal or using the configured keyboard quit shortcut
* Improved the behavior and consistency for the virtual keyboard when using non-standard keyboard mappings
* Improved the theme loading error logging to make it consistent and easier to understand
* Added a log warning for unthemed systems during theme set loading

2
CONTRIBUTING.md
View file

@ -68,6 +68,7 @@ The roadmap is under constant review so expect it to change from time to time. S
* New theme engine with generalized views (only System and Gamelist) and theme variants support
* Multiple new components (carousel support for the Gamelist view, grid component etc.)
* Support for Tate mode, i.e. portrait orientation for arcade cabinets and similar
* Lottie animation (vector graphics) and GIF animation support
* OpenGL ES 3.0 renderer for use on the Raspberry Pi
* Replace the OpenGL fixed function pipeline renderer with a shader-based renderer
@ -94,7 +95,6 @@ The roadmap is under constant review so expect it to change from time to time. S
* Reduced amount of gamelist reloading to retain cached textures and improve overall performance
* Add "time played" counter per game, similar to how it works in Steam
* Checksum support for the scraper for exact searches and for determining when to overwrite files
* Support for portrait orientation, e.g. for Tate Mode arcade cabinets
* Replace the built-in Unicode functions and lookup tables with those of the ICU library
* Add text kerning support using the HarfBuzz library

43
INSTALL-DEV.md
View file

@ -1057,26 +1057,26 @@ The input configuration is described in the [User guide](USERGUIDE-DEV.md#input-
You can use **--help** or **-h** to view the list of command line options, as shown here.
```
--display [index 1-4] Display/monitor to use
--resolution [width] [height] Application resolution
--screenrotate [1/on or 0/off] Rotate application screen 180 degrees
--vsync [1/on or 0/off] Turn VSync on or off (default is on)
--max-vram [size] Max VRAM to use (in mebibytes) before swapping
--anti-aliasing [0, 2 or 4] Set MSAA anti-aliasing to disabled, 2x or 4x
--no-splash Don't show the splash screen during startup
--gamelist-only Skip automatic game ROM search, only read from gamelist.xml
--ignore-gamelist Ignore the gamelist.xml files (useful for troubleshooting)
--show-hidden-files Show hidden files and folders
--show-hidden-games Show hidden games
--force-full Force the UI mode to Full
--force-kiosk Force the UI mode to Kiosk
--force-kid Force the UI mode to Kid
--force-input-config Force configuration of input device
--create-system-dirs Create game system directories
--home [path] Directory to use as home path
--debug Print debug information
--version, -v Display version information
--help, -h Summon a sentient, angry tuba
--display [1 to 4] Display/monitor to use
--resolution [width] [height] Application resolution
--screenrotate [0, 90, 180 or 270] Rotate screen contents within application window
--vsync [1/on or 0/off] Turn VSync on or off (default is on)
--max-vram [size] Max VRAM to use (in mebibytes) before swapping
--anti-aliasing [0, 2 or 4] Set MSAA anti-aliasing to disabled, 2x or 4x
--no-splash Don't show the splash screen during startup
--gamelist-only Skip automatic game ROM search, only read from gamelist.xml
--ignore-gamelist Ignore the gamelist.xml files (useful for troubleshooting)
--show-hidden-files Show hidden files and folders
--show-hidden-games Show hidden games
--force-full Force the UI mode to Full
--force-kiosk Force the UI mode to Kiosk
--force-kid Force the UI mode to Kid
--force-input-config Force configuration of input devices
--create-system-dirs Create game system directories
--home [path] Directory to use as home path
--debug Print debug information
--version, -v Display version information
--help, -h Summon a sentient, angry tuba
```
_The --anti-aliasing option is not available if ES-DE is built using the OpenGL ES renderer._
@ -1090,6 +1090,7 @@ Running with the --create-system-dirs option will generate all the game system d
For the following options, the es_settings.xml file is immediately updated/saved when passing the parameter:
```
--display
--screenrotate
--max-vram
--anti-aliasing
--gamelist-only
@ -1135,7 +1136,7 @@ If using the regular desktop OpenGL renderer, the allowed values are 3.3 (defaul
**ScraperConnectionTimeout**
Sets the server connection timeout for the scraper. Minimum value is 0 seconds (infinity) and maximum value is 300 seconds. Default value is 60 seconds.
Sets the server connection timeout for the scraper. Minimum value is 0 seconds (infinity) and maximum value is 300 seconds. Default value is 30 seconds.
**ScraperTransferTimeout**

99
THEMES-DEV.md
View file

@ -1187,7 +1187,8 @@ Properties:
- Valid values are `horizontal`, `vertical`, `horizontalWheel` or `verticalWheel`
- Default is `horizontal`
* `staticImage` - type: PATH
- Path to a static image file. Most common extensions are supported (including .svg, .jpg, .png, and unanimated .gif). This property can only be used in the `system` view.
- Path to a static image file. Most common extensions are supported (including .svg, .jpg, .png, and unanimated .gif).
- This property can only be used in the `system` view.
* `imageType` - type: STRING
- This displays a game image of a certain media type, and can only be used in the `gamelist` view. Optionally two types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined, and any superfluous entries will be ignored. Note that defining two entries can lead to quite a performance penalty so in general it's recommended to define a single value and instead use `defaultImage` as a fallback in case no image is found.
- Valid values:
@ -1206,29 +1207,29 @@ Properties:
- Path to the default image file which will be displayed if the image defined via the `staticImage` or `imageType` property is not found. Most common extensions are supported (including .svg, .jpg, .png, and unanimated .gif).
* `maxItemCount` - type: FLOAT
- Sets the number of carousel items to display.
- This property can only be used when `type` is `horizontal` or `vertical`
- Minimum value is `0.5` and maximum value is `30`
- Default is `3`
- This property can only be used when `type` is `horizontal` or `vertical`
* `itemsBeforeCenter` - type: UNSIGNED_INTEGER
- Sets the number of items before the center position (the currently selected item). By setting this property and `itemsAfterCenter` to different values an asymmetric wheel can be configured. Combine with `itemRotation` to control how many entries to display in the carousel.
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
- Minimum value is `0` and maximum value is `20`
- Default is `8`
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
* `itemsAfterCenter` - type: UNSIGNED_INTEGER
- Sets the number of items after the center position (the currently selected item). By setting this property and `itemsBeforeCenter` to different values an asymmetric wheel can be configured. Combine with `itemRotation` to control how many entries to display in the carousel.
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
- Minimum value is `0` and maximum value is `20`
- Default is `8`
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
* `itemStacking` - type: STRING
- Controls how to stack overlapping items. When set to `centered` the selected item will be raised and items further from the selected item (to the left/right or above/below depending on the carousel orientation) will be progressively rendered lower than the items closer to the center. If set to `ascending` then items will be rendered progressively higher from left to right or from top to bottom depending on the carousel orientation. If set to `descending` the opposite takes place with items being progressively rendered lower from left to right or top to bottom depending on the carousel orientation. Finally `ascendingRaised` and `descendingRaised` work identically to `ascending` and `descending` with the only difference that the currently selected item will be raised above the other items.
- This property can only be used when `type` is `horizontal` or `vertical`
- Valid values are `centered`, `ascending`, `ascendingRaised`, `descending` or `descendingRaised`
- Default is `centered`
- This property can only be used when `type` is `horizontal` or `vertical`
* `selectedItemMargins` - type: NORMALIZED_PAIR
- By default items are evenly spaced across the carousel area, but this property makes it possible to define margins (extra space or less space) around the currently selected item. The first value in the pair defines the margin to the left of the item if it's a horizontal carousel or above the item if it's a vertical carousel, and the second value of the pair sets the right or bottom margin for the selected item depending on the carousel orientation.
- This property can only be used when `type` is `horizontal` or `vertical`
- Minimum value per margin is `-1` and maximum value per margin is `1`
- Default is `0 0`
- This property can only be used when `type` is `horizontal` or `vertical`
* `itemSize` - type: NORMALIZED_PAIR
- Size of the item prior to multiplication by the `itemScale` value, i.e. the size of all unselected items. Both axes need to be defined.
- Minimum value per axis is `0.05` and maximum value per axis is `1`
@ -1239,20 +1240,20 @@ Properties:
- Default is `1.2`
* `itemRotation` - type: FLOAT
- Angle in degrees that items should be rotated. This value should be positive if the `itemRotationOrigin` X axis has a negative value, and it should be negative if the `itemRotationOrigin` X axis has a positive value, otherwise the wheel will rotate in the wrong direction.
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
- Default is `7.5`
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
* `itemRotationOrigin` - type: NORMALIZED_PAIR
- Point around which the items will be rotated. The X axis of this property is the distance from the left side of the item to the center of the wheel in multiples of the size defined by the `itemSize` X axis. So if for instance the itemSize X axis is set to 0.2 and itemRotationOrigin is set to -2, then the center of the wheel will be at a -0.4 distance from the left side of the item. In other words, if specifying a negative number the item will be located on the right side of the carousel, i.e. the wheel will be to the left and if specifying a positive number the wheel will be to the right. Note again that this is calculated from the left side of the item, so to get an identically sized wheel as the -2 wheel just mentioned you need to define 3 as the value rather than 2 if you want the wheel to the right side of the item. This is not an error but due to the way that coordinates are calculated. The Y axis should normally be left at `0.5` or you may get some weird results. It is however possible to use this axis value creatively if you know what you are doing.
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
- Default is `-3 0.5`
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
* `itemAxisHorizontal` - type: BOOLEAN
- Wheel carousel items are normally rotated towards the center of the wheel as defined by `itemRotation` and `itemRotationOrigin`. But if enabling this property the items will not get rotated along their own axis, meaning they will retain their original horizontal orientation regardless of their position along the wheel. Make sure that `itemVerticalAlignment` is set to `center` when using this property or you'll get strange alignment issues.
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
- Default is `false`
- This property can only be used when `type` is `horizontalWheel` or `verticalWheel`
* `itemAxisRotation` - type: FLOAT
- Angle in degrees that items should be rotated around their own axis. Note that this does not work well with reflections as these are rotated too which does not look right.
- This property can only be used when `type` is `horizontal` or `vertical`
- Default is `0`
- This property can only be used when `type` is `horizontal` or `vertical`
* `imageInterpolation` - type: STRING
- Interpolation method to use when scaling images. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother. The effect of this property is primarily visible for raster graphic images, but it has a limited effect also when using scalable vector graphics (SVG) images as these are rasterized at a set resolution and then scaled using the GPU.
- Valid values are `nearest` or `linear`
@ -1281,24 +1282,24 @@ Properties:
- Default is `animate`
* `itemHorizontalAlignment` - type: STRING
- Sets `staticImage` / `imageType` and `text` alignment relative to the carousel on the X axis.
- This property can only be used when `type` is `vertical` or `verticalWheel`
- Valid values are `left`, `center` or `right`
- Default is `center`
- This property can only be used when `type` is `vertical` or `verticalWheel`
* `itemVerticalAlignment` - type: STRING
- Sets `staticImage` / `imageType` and `text` alignment relative to the carousel on the Y axis. Make sure to set this to `center` if you've enabled `itemAxisHorizontal`
- This property can only be used when `type` is `horizontal`, `horizontalWheel` or `verticalWheel`
- Valid values are `top`, `center` or `bottom`
- Default is `center`
- This property can only be used when `type` is `horizontal`, `horizontalWheel` or `verticalWheel`
* `wheelHorizontalAlignment` - type: STRING
- Sets the horizontal alignment of the actual carousel inside the overall element area. Note that the positioning is calculated before `itemAxisHorizontal` is applied.
- This property can only be used when `type` is `verticalWheel`
- Valid values are `left`, `center` or `right`
- Default is `center`
- This property can only be used when `type` is `verticalWheel`
* `wheelVerticalAlignment` - type: STRING
- Sets the vertical alignment of the actual carousel inside the overall element area. Note that the positioning is calculated before `itemAxisHorizontal` is applied.
- This property can only be used when `type` is `horizontalWheel`
- Valid values are `top`, `center` or `bottom`
- Default is `center`
- This property can only be used when `type` is `horizontalWheel`
* `horizontalOffset` - type: FLOAT
- Offsets the carousel horizontally inside its designated area, as defined by the `size` property. The value of this property is relative to the width of the carousel (with `1` being equivalent to its entire width). This property can for example be used to add a margin if using `itemHorizontalAlignment` or to offset the selected item of horizontal carousels to a non-centered position.
- Minimum value is `-1.0` and maximum value is `1`
@ -1309,18 +1310,18 @@ Properties:
- Default is `0`
* `reflections` - type: BOOLEAN
- Enables reflections beneath the carousel items. It's probably a good idea to combine this with the `verticalOffset` property to define how much of the reflections should be visible.
- This property can only be used when `type` is `horizontal`
- Default is `false`
- This property can only be used when `type` is `horizontal`
* `reflectionsOpacity` - type: FLOAT
- Defines the base opacity for the reflections.
- This property can only be used when `type` is `horizontal`
- Minimum value is `0.1` and maximum value is `1`
- Default is `0.5`
- This property can only be used when `type` is `horizontal`
* `reflectionsFalloff` - type: FLOAT
- Defines the reflections opacity falloff, starting from the item's base opacity and ending at complete transparency. The value is set relative to the item height, so `1` will fade the bottom of the item to full transparency, `2` will fade to full transparency at half the item height and `0.5` will place the full transparency point at twice the item height.
- This property can only be used when `type` is `horizontal`
- Minimum value is `0` and maximum value is `10`
- Default is `1`
- This property can only be used when `type` is `horizontal`
* `unfocusedItemOpacity` - type: FLOAT
- Sets the opacity for the items that are not currently focused.
- Minimum value is `0.1` and maximum value is `1`
@ -1336,8 +1337,9 @@ Properties:
- Valid values are `horizontal` or `vertical`
- Default is `horizontal`
* `text` - type: STRING
- A string literal to display if there is no `staticImage` or `defaultImage` property defined and if no image is found. This property can only be used in the `system` view as for the gamelist view the game name is always used as fallback.
- A string literal to display if there is no `staticImage` or `defaultImage` property defined and if no image is found.
- Default is the full system name.
- This property can only be used in the `system` view as for the gamelist view the game name is always used as fallback.
* `textColor` - type: COLOR
- Default is `000000FF`
* `textBackgroundColor` - type: COLOR
@ -1345,7 +1347,7 @@ Properties:
* `fontPath` - type: PATH
- Path to a TrueType font (.ttf) used as fallback if there is no `staticImage` / `imageType` image defined or found, and if `defaultImage` has not been defined.
* `fontSize` - type: FLOAT
- Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. This property value is effectively multiplied by the `itemScale` value for the currently selected item (but if this property is omitted then the default value will not get multiplied by `itemScale`).
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area. This property value is effectively multiplied by the `itemScale` value for the currently selected item (but if this property is omitted then the default value will not get multiplied by `itemScale`).
- Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size.
- Default is `0.085`
* `letterCase` - type: STRING
@ -1353,9 +1355,10 @@ Properties:
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is `none` (original letter case is retained).
* `letterCaseAutoCollections` - type: STRING
- Sets the letter case specifically for automatic collection entries (_all games_, _favorites_ and _last played_) which have their names spelled in lowercase by default. This property can only be used in the `system` view and it will take precedence over `letterCase` if that has also been defined.
- Sets the letter case specifically for automatic collection entries (_all games_, _favorites_ and _last played_) which have their names spelled in lowercase by default.
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is the same value as `letterCase`
- This property can only be used in the `system` view and it will take precedence over `letterCase` if that has also been defined.
* `letterCaseCustomCollections` - type: STRING
- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over `letterCase` if that has also been defined.
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
@ -1366,17 +1369,17 @@ Properties:
- Default is `1.5`
* `systemNameSuffix` - type: BOOLEAN
- Whether to add the system name in square brackets after the game name when inside a collection system (automatic as well as custom collections). This assumes a fallback to text is made.
- This property can only be used in the `gamelist` view.
- Default is `true`
- This property can only be used in the `gamelist` view.
* `letterCaseSystemNameSuffix` - type: STRING
- Sets the letter case for the system name suffix.
- This property can only be used in the `gamelist` view and only when `systemNameSuffix` is `true`
- Valid values are `uppercase`, `lowercase` or `capitalize`
- Default is `uppercase`
- This property can only be used in the `gamelist` view and only when `systemNameSuffix` is `true`
* `fadeAbovePrimary` - type: BOOLEAN
- When using fade transitions, all elements in the `system` view with a zIndex value higher than the carousel are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the carousel will be dimmed to black and elements above the carousel will be faded to transparent.
- This property can only be used in the `system` view.
- Default is `false`
- This property can only be used in the `system` view.
* `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50`
@ -1405,7 +1408,8 @@ Properties:
- Minimum value per axis is `0` and maximum value per axis is `1`
- Default is `0 0`
* `staticImage` - type: PATH
- Path to a static image file. Most common extensions are supported (including .svg, .jpg, .png, and unanimated .gif). This property can only be used in the `system` view.
- Path to a static image file. Most common extensions are supported (including .svg, .jpg, .png, and unanimated .gif).
- This property can only be used in the `system` view.
* `imageType` - type: STRING
- This displays a game image of a certain media type, and can only be used in the `gamelist` view. Optionally two types can be defined, in which case the entries should be delimited by commas or by whitespace characters (tabs, spaces or line breaks). The media will be searched for in the order that the entries have been defined, and any superfluous entries will be ignored. Note that defining two entries can lead to quite a performance penalty so in general it's recommended to define a single value and instead use `defaultImage` as a fallback in case no image is found.
- Valid values:
@ -1519,8 +1523,9 @@ Properties:
- Valid values are `horizontal` or `vertical`
- Default is `horizontal`
* `text` - type: STRING
- A string literal to display if there is no `staticImage` or `defaultImage` property defined or if no image is found. This property can only be used in the `system` view as for the gamelist view the game name is always used as fallback.
- A string literal to display if there is no `staticImage` or `defaultImage` property defined or if no image is found.
- Default is the full system name.
- This property can only be used in the `system` view as for the gamelist view the game name is always used as fallback.
* `textRelativeScale` - type: FLOAT.
- This property makes it possible to size the text relative to the overall item size.
- Minimum value is `0.2` and maximum value is `1`
@ -1538,7 +1543,7 @@ Properties:
* `fontPath` - type: PATH
- Path to a TrueType font (.ttf) used as fallback if there is no `staticImage` / `imageType` image defined or found, and if `defaultImage` has not been defined.
* `fontSize` - type: FLOAT
- Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size.
- Default is `0.045`
* `letterCase` - type: STRING
@ -1546,9 +1551,10 @@ Properties:
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is `none` (original letter case is retained).
* `letterCaseAutoCollections` - type: STRING
- Sets the letter case specifically for automatic collection entries (_all games_, _favorites_ and _last played_) which have their names spelled in lowercase by default. This property can only be used in the `system` view and it will take precedence over `letterCase` if that has also been defined.
- Sets the letter case specifically for automatic collection entries (_all games_, _favorites_ and _last played_) which have their names spelled in lowercase by default.
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is the same value as `letterCase`
- This property can only be used in the `system` view and it will take precedence over `letterCase` if that has also been defined.
* `letterCaseCustomCollections` - type: STRING
- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over `letterCase` if that has also been defined.
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
@ -1559,17 +1565,17 @@ Properties:
- Default is `1.5`
* `systemNameSuffix` - type: BOOLEAN
- Whether to add the system name in square brackets after the game name when inside a collection system (automatic as well as custom collections). This assumes a fallback to text is made.
- This property can only be used in the `gamelist` view.
- Default is `true`
- This property can only be used in the `gamelist` view.
* `letterCaseSystemNameSuffix` - type: STRING
- Sets the letter case for the system name suffix.
- This property can only be used in the `gamelist` view and only when `systemNameSuffix` is `true`
- Valid values are `uppercase`, `lowercase` or `capitalize`
- Default is `uppercase`
- This property can only be used in the `gamelist` view and only when `systemNameSuffix` is `true`
* `fadeAbovePrimary` - type: BOOLEAN
- When using fade transitions, all elements in the `system` view with a zIndex value higher than the grid are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the grid will be dimmed to black and elements above the grid will be faded to transparent.
- This property can only be used in the `system` view.
- Default is `false`
- This property can only be used in the `system` view.
* `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50`
@ -1642,7 +1648,7 @@ Properties:
- Default is the same value as `selectedBackgroundColor`
* `fontPath` - type: PATH
* `fontSize` - type: FLOAT
- Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Default is `0.045`
* `horizontalAlignment` - type: STRING
- Controls alignment on the X axis.
@ -1656,9 +1662,10 @@ Properties:
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is `none` (original letter case is retained).
* `letterCaseAutoCollections` - type: STRING
- Sets the letter case specifically for automatic collection entries (_all games_, _favorites_ and _last played_) which have their names spelled in lowercase by default. This property can only be used in the `system` view and it will take precedence over `letterCase` if that has also been defined.
- Sets the letter case specifically for automatic collection entries (_all games_, _favorites_ and _last played_) which have their names spelled in lowercase by default.
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
- Default is the same value as `letterCase`
- This property can only be used in the `system` view and it will take precedence over `letterCase` if that has also been defined.
* `letterCaseCustomCollections` - type: STRING
- Sets the letter case specifically for custom collections entries. Be cautious about using this property as it will override whatever lettercase the user has defined for their custom collection names. This property takes precedence over `letterCase` if that has also been defined.
- Valid values are `none`, `uppercase`, `lowercase` or `capitalize`
@ -1677,8 +1684,8 @@ Properties:
- Default is `symbols`
* `systemNameSuffix` - type: BOOLEAN
- Whether to add the system name in square brackets after the game name when inside a collection system (automatic as well as custom collections).
- This property can only be used in the `gamelist` view.
- Default is `true`
- This property can only be used in the `gamelist` view.
* `letterCaseSystemNameSuffix` - type: STRING
- Sets the letter case for the system name suffix.
- This property can only be used in the `gamelist` view and only when `systemNameSuffix` is `true`
@ -1686,8 +1693,8 @@ Properties:
- Default is `uppercase`
* `fadeAbovePrimary` - type: BOOLEAN
- When using fade transitions, all elements in the `system` view with a zIndex value higher than the textlist are by default still rendered during transitions. If this property is enabled then all such elements will instead be faded out. Note that elements below the textlist will be dimmed to black and elements above the textlist will be faded to transparent.
- This property can only be used in the `system` view.
- Default is `false`
- This property can only be used in the `system` view.
* `zIndex` - type: FLOAT
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50`
@ -1955,9 +1962,9 @@ Properties:
- Default is `normal`
* `interpolation` - type: STRING
- Interpolation method to use when scaling. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother.
- This property can only be used for GIF animations.
- Valid values are `nearest` or `linear`
- Default is `nearest`
- This property can only be used for GIF animations.
* `brightness` - type: FLOAT
- Controls the relative level of brightness. This is intended primarily for fine adjustments.
- Minimum value is `-2` and maximum value is `2`
@ -2166,7 +2173,8 @@ Properties:
* `text` - type: STRING
- A string literal to display.
* `systemdata` - type: STRING
- This translates to some system data including values defined in es_systems.xml as well as some statistics. This property can only be used in the `system` view and you can only define a single value per element.
- This translates to some system data including values defined in es_systems.xml as well as some statistics.
- This property can only be used in the `system` view and you can only define a single value per element.
- Valid values:
- `name` - Short system name as defined in es_systems.xml.
- `fullname` - Full system name as defined in es_systems.xml.
@ -2200,13 +2208,13 @@ Properties:
- This property makes it possible to override the default "unknown" text that is displayed if `metadata` has been set to `developer`, `publisher`, `genre` or `players` and there is no metadata available for the defined type. Any string can be used but you can't set it to a blank value. If you don't want to display anything when there is no metadata available, then set this property to `:space:` in which case a blankspace will be used. This property has no effect on the metadata editor where "unknown" will still be shown for blank values.
* `systemNameSuffix` - type: BOOLEAN
- Whether to add the system name in square brackets after the game name when inside a collection system (automatic as well as custom collections). If `metadata` has been set to `description` then this property will only apply when inside the root of the grouped custom collections system where a summary of available games for the currently selected collection is displayed.
- This property can only be used when `metadata` has been set to `name` or `description`
- Default is `true`
- This property can only be used when `metadata` has been set to `name` or `description`
* `letterCaseSystemNameSuffix` - type: STRING
- Sets the letter case for the system name suffix.
- This property can only be used when `systemNameSuffix` is `true`, and if `metadata` has been set to `description` then it only applies if `letterCase` is also set to `none`
- Valid values are `uppercase`, `lowercase` or `capitalize`
- Default is `uppercase`
- This property can only be used when `systemNameSuffix` is `true`, and if `metadata` has been set to `description` then it only applies if `letterCase` is also set to `none`
* `metadataElement` - type: BOOLEAN
- By default game metadata and media are faded out during gamelist fast-scrolling. They are also hidden when enabling the _Hide metadata fields_ setting in the metadata editor. This includes the text metadata fields (except `systemName`, `systemFullname`, `sourceSystemName` and `sourceSystemFullname`), ratings and badges. Using this property it's possible to explicitly define additional text elements that should be treated as if they were game metadata entries. This is for example useful for hiding and fading out text labels or icons for the various metadata types like genre, publisher, players etc. Note that it's not possible to disable the metadata hiding functionality for the default metadata fields as that would break basic application behavior. Also note that there is a slight exception to the hiding logic for text containers with the metadata value set to `description`. In this case the element is by default not hidden when enabling the _Hide metadata fields_ setting. To also hide such containers, set this property to true.
- Default is `false`
@ -2219,8 +2227,8 @@ Properties:
- Default is `0`
* `container` - type: BOOLEAN
- Whether the text should be placed inside a scrollable container.
- This property can only be used in the `gamelist` view.
- Default is `true` if `metadata` is set to `description`, otherwise `false`
- This property can only be used in the `gamelist` view.
* `containerVerticalSnap` - type: BOOLEAN
- Whether the text should be vertically snapped to the font height. With this property enabled the container will have its height reduced as needed so that only complete rows of text are displayed at the start and end positions. This will not affect the "real" size of the container as set by the `size` property which means that the overall element placement will still be predictable if a vertical origin other than zero is used.
- Default is `true`
@ -2239,7 +2247,7 @@ Properties:
* `fontPath` - type: PATH
- Path to a TrueType font (.ttf).
* `fontSize` - type: FLOAT
- Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
- Default is `0.045`
* `horizontalAlignment` - type: STRING
@ -2250,6 +2258,7 @@ Properties:
- Controls alignment on the Y axis.
- Valid values are `top`, `center` or `bottom`
- Default is `center`
- This property can only be used if `container` is `false`
* `color` - type: COLOR
- Default is `000000FF`
* `backgroundColor` - type: COLOR
@ -2317,7 +2326,7 @@ Properties:
* `fontPath` - type: PATH
- Path to a TrueType font (.ttf).
* `fontSize` - type: FLOAT
- Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
- Default is `0.045`
* `horizontalAlignment` - type: STRING
@ -2390,7 +2399,7 @@ Properties:
* `fontPath` - type: PATH
- Path to a TrueType font (.ttf).
* `fontSize` - type: FLOAT
- Size of the font as a percentage of screen height (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Size of the font as a percentage of screen height for horizontally oriented screens or screen width for vertically oriented screens (e.g. for a value of `0.1`, the text's height would be 10% of the screen height). This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size. The font is allowed to overflow the height of the element by 100%, i.e. `fontSize` can be set to twice that of the y axis of the `size` property. Any value above that will be clamped.
- Default is `0.045`
* `horizontalAlignment` - type: STRING
@ -2501,8 +2510,8 @@ Properties:
- Default is `1`
* `allowDuplicates` - type: BOOLEAN
- If set to true then the same game may appear multiple times, i.e. the amount of entries defined by `gameCount` are always fully populated. This only applies to entries higher than the amount of available games for a system, for example if a system contains 3 games and `gameCount` has been set to `5`, then the first three entries will not contain any duplicate entries, but the last two will.
- This property can only be used when `selection` is `random`
- Default is `false`
- This property can only be used when `selection` is `random`
#### helpsystem
@ -2521,7 +2530,7 @@ Instances per view:
Properties:
* `pos` - type: NORMALIZED_PAIR
- Default is `0.012 0.9515`
- Default is `0.012 0.9515` for horizontally oriented screens and `0.012 0.975` for vertically oriented screens
* `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`
@ -2540,7 +2549,7 @@ Properties:
* `fontSize` - type: FLOAT
- This property implicitly sets the icon size and is therefore the means to change the overall size of the helpsystem element. This calculation is based on the reference 'S' character so other glyphs may not fill this area, or they may exceed this area.
- Minimum value is `0.001` and maximum value is `1.5`. Note that when running at a really low resolution, the minimum value may get clamped to a larger relative size.
- Default is `0.035`
- Default is `0.035` for horizontally oriented screens and `0.025` for vertically oriented screens
* `entrySpacing` - type: FLOAT
- Spacing between the help element pairs.
- Minimum value is `0` and maximum value is `0.04`

16
USERGUIDE-DEV.md
View file

@ -2214,6 +2214,14 @@ The region to scrape for. This affects game names, game media and release dates.
Multiple languages are supported by ScreenScraper, and this affects translations of game genres and game descriptions. As the option name implies this is the preferred language only as not all games have had their metadata translated. Unfortunately some less used languages have quite few games translated, but hopefully this will improve over time as there's an ongoing community effort to make more translations. If the preferred language is not available for a game, ES-DE will fall back to using the English metadata.
**Automatic retries on error**
How many times to automatically retry scraping if an error is encountered, from 1 to 10 tries.
**Retry attempt timer**
How long to wait between each scraper retry, from 1 to 30 seconds.
**Overwrite files and data**
Affects both overwriting of metadata as well as actual game media files on the filesystem. Even with this option disabled, metadata entries which are set to their default values will be populated by the scraper. In other words, this option only affects overwriting of previously scraped data, or data manually entered via the metadata editor. Game names are considered as set to their default values if either corresponding to the physical game file on disk minus the extension (e.g. the entry _Commando_ if the file is named _Commando.zip_), or for arcade games if corresponding to the MAME names as defined in the bundled mamenames.xml. Note that this setting does not affect generated miximages, that is instead controlled by the setting _Overwrite miximages (scraper/offline generator)_ found in the miximage settings menu.
@ -2258,10 +2266,6 @@ ScreenScraper has issues with some game names containing dots, such as _Super Ma
When a certain game media file does not exist for the selected region, ES-DE automatically performs a fallback to the regions _world_, _USA_, _Japan_, _EU_, and _custom_ in this specific order. If this setting is enabled then an additional fallback is performed to all other country-specific regions. This makes it possible to scrape media for some games only released in specific countries like Brazil or South Korea. It may also make it possible to scrape some game media that have been uploaded to ScreenScraper using the wrong region. The special _ss/ScreenScraper_ region is also enabled via this option, and among other things it contains media for games that never had official releases. This is relevant for instance for OpenBOR and PICO-8 games where 3D boxes and other images may become available. The drawback of this setting is that you may get inaccurate data such as box art in the wrong language or unofficial box art for arcade games, so you may want to experiment with this option on a per-system basis.
**Auto-retry on peer verification errors** _(ScreenScraper only)_
ScreenScraper sometimes has issues with its TLS certificates which causes searches to randomly fail. It's normally resolved within a few days, but in the meanwhile activating this setting will have the scraper automatically make up to eight additional attempts when this error occurs. That is normally enough to complete the search, but if not, just press _Retry_ in the error dialog and ES-DE will try eight more times. This setting applies to both the single-game scraper and the multi-scraper. The following error notification dialog and corresponding es_log.txt entry is displayed when this error occurs: "Error downloading thumbnail: SSL peer certificate or SSH remote key was not OK".
### UI settings
Various settings that affect the user interface.
@ -2593,6 +2597,10 @@ Sets the level of anti-aliasing for the application. You can select between _dis
This option sets the display to use for ES-DE for multi-monitor setups. The possible values are the monitor index numbers 1, 2, 3 or 4. If a value is set here for a display that does not actually exist, then ES-DE will set it to 1 upon startup. Index 1 is the primary display for the computer. It's also possible to override the setting by passing the --display command line argument. Doing so will also overwrite the display index setting in es_settings.xml. The Display/monitor index option only changes the display used by ES-DE; the emulators need to be configured separately (which can easily be done globally if using RetroArch).
**Rotate screen (requires restart)**
Rotates the application screen within the application window, i.e. it will not affect the actual window size but rather the contents within the window. Applied clockwise in 90 degree steps. Intended for Tate mode (vertical orientation) setups where you do not want to rotate the display on the operating system level. If you want to also rotate the entire application window you'll need to supply a resolution manually using the --resolution command line option.
**Keyboard quit shortcut**
This gives the choice of which key combination to use to quit the application. The default value is Alt + F4 on Windows and Linux and Command + Q on macOS. Other possible values are Ctrl + Q, Alt + Q and F4 but selecting either of these alternatives will not disable the default quit shortcut as that's implemented globally by the operating system.