From c4d2cc5598a8e3dce792e1706db28eb6375f17d0 Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Mon, 14 Aug 2023 23:49:29 +0200 Subject: [PATCH] Documentation update --- CHANGELOG.md | 1 + CREDITS.md | 12 +++--- FAQ.md | 2 +- INSTALL-DEV.md | 25 +++++++------ THEMES-DEV.md | 96 +++++++++++++++++++++++++----------------------- USERGUIDE-DEV.md | 86 ++++++++++++++++++++++++------------------- 6 files changed, 120 insertions(+), 102 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9deb4b94e..0e4526039 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ * Enabled the setting "Show hidden files and folders" to be changed without requiring an application restart * Enabled the setting "Show hidden games" to be changed without requiring an application restart * Enabled the setting "Only show ROMs from gamelist.xml files" to be changed without requiring an application restart +* Renamed the setting "Only show ROMs from gamelist.xml files" to "Only show games from gamelist.xml files * Added support for deleting installed themes from the theme downloader interface * Added ares standalone as an alternative emulator for the gamegear, gb, gba, gbc and satellaview systems * Removed atarijaguarcd as an extra platform for the atarijaguar system as it actually made scraping worse diff --git a/CREDITS.md b/CREDITS.md index a348471e7..da3487630 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -2,17 +2,17 @@ # Programming -**Original version**\ -Alec Lofquist - -**RetroPie fork**\ -RetroPie community - **Desktop Edition**\ Leon Styhre \ Sophia Hadash \ Joseph Geumlek +**RetroPie fork**\ +RetroPie community + +**Original version**\ +Alec Lofquist + # UI Art & Design Nils Bonenberger diff --git a/FAQ.md b/FAQ.md index 279aed2ff..206b87e6f 100644 --- a/FAQ.md +++ b/FAQ.md @@ -10,7 +10,7 @@ The correct name is EmulationStation Desktop Edition, which is for practical rea ## Is this software available for free, and is it open source? -ES-DE is available for free, and will continue to be available for free. It's released under the MIT open source license with the source code being publicly and freely available. Voluntary donations to support the project are however very welcome. +ES-DE is available for free, and will continue to be available for free, if someone is asking you to pay money to use ES-DE in any form then you are being scammed. The software is released under the MIT open source license with the source code being publicly and freely available. Voluntary donations to support the project are however very welcome. ## Which operating systems are supported? diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 0e01bd6be..890f6eab3 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1076,7 +1076,7 @@ You can use **--help** or **-h** to view the list of command line options, as sh --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 --no-update-check Don't check for application updates during startup ---gamelist-only Skip automatic game ROM search, only read from gamelist.xml +--gamelist-only Skip automatic game search, only read from gamelist.xml --ignore-gamelist Ignore the gamelist.xml files --show-hidden-files Show hidden files and folders --show-hidden-games Show hidden games @@ -1114,7 +1114,7 @@ For the following options, the es_settings.xml file is immediately updated/saved As well, passing the option --ignore-gamelist will disable the ParseGamelistOnly setting controlled by --gamelist-only and immediately save the es_settings.xml file. If passing both the --ignore-gamelist and --gamelist-only parameters then --ignore-gamelist will take precedence and --gamelist-only will be ignored. -The --ignore-gamelist option is only active during the program session and is not saved to es_settings.xml. But --gamelist-only is however saved, so in order to return to the normal operation of parsing the gamelist.xml files after starting ES-DE with the --gamelist-only option, you will need to disable the setting _Only show ROMs from gamelist.xml files_ in the _Other settings_ menu (or manually change the ParseGamelistOnly entry in es_settings.xml). +The --ignore-gamelist option is only active during the program session and is not saved to es_settings.xml. But --gamelist-only is however saved, so in order to return to the normal operation of parsing the gamelist.xml files after starting ES-DE with the --gamelist-only option, you will need to disable the setting _Only show games from gamelist.xml files_ in the _Other settings_ menu (or manually change the ParseGamelistOnly entry in es_settings.xml). ## Settings not configurable via the GUI @@ -1126,11 +1126,11 @@ Enabling this will skip all input event logging (button and key presses). Defaul **DebugSkipMissingThemeFiles** -Enabling this will skip all debug messages about missing files when loading a theme set. Default value is false. +Enabling this will skip all debug messages about missing files when loading a theme. Default value is false. **DebugSkipMissingThemeFilesCustomCollections** -Enabling this will skip all debug messages about missing files specifically for custom collections when loading a theme set. Note that DebugSkipMissingThemeFiles takes precedence, so if that setting is set to true then the DebugSkipMissingThemeFilesCustomCollections setting will be ignored. Default value is true. +Enabling this will skip all debug messages about missing files specifically for custom collections when loading a theme. Note that DebugSkipMissingThemeFiles takes precedence, so if that setting is set to true then the DebugSkipMissingThemeFilesCustomCollections setting will be ignored. Default value is true. **LegacyGamelistFileLocation** @@ -1299,10 +1299,9 @@ Below is an overview of the file layout with various examples. For the command t You can use multiple platforms too, delimited with any of the whitespace characters (", \r\n\t"), e.g. "megadrive, genesis". --> snes - + snes @@ -1463,6 +1462,8 @@ Here is yet another example with the addition of the `snes` system where some fi This file makes it possible to apply a custom systems sorting without having to modify the es_systems.xml file directly. It should be placed in the custom_systems directory, e.g. `~/.emulationstation/custom_systems/es_systems_sorting.xml` +Note that in order for ES-DE to load this file you'll need to set the _Systems sorting_ option in the _Other settings_ menu to _Full names or custom_. + The structure of this file is essentially a simplified version of the es_systems.xml file, but with only the `` and `` tags present per system. Here's an example where three systems have been sorted by release year instead of the default full system name: @@ -1493,10 +1494,12 @@ There are also four complete sorting files bundled with ES-DE, you can find them These files include all systems supported by ES-DE and provide the following sorting options: +* Release year +* Manufacturer, release year * Hardware type, release year * Manufacturer, hardware type, release year -* Manufacturer, release year -* Release year + +You can apply any of these sorting files via the _Systems sorting_ option in the _Other settings_ menu. Note that in order to load a es_systems_sorting.xml file placed in the custom_systems directory you'll need to set this option to _Full names or custom_. ## es_find_rules.xml @@ -1999,7 +2002,7 @@ There are up to four parameters that will be passed to these scripts, as detaile | config-changed | | On saving application settings or controller configuration | | settings-changed | | On saving application settings (config-changed event triggered as well) | | controls-changed | | On saving controller configuration (config-changed event triggered as well) | -| theme-changed | New theme name, old theme name | When manually changing theme sets in the UI Settings menu | +| theme-changed | New theme name, old theme name | When manually changing themes in the UI Settings menu | | game-start | ROM path, game name, system name, system full name | On game launch | | game-end | ROM path, game name, system name, system full name | On game end (or on application wakeup if running in the background) | | screensaver-start | _timer_ or _manual_ | Screensaver started via timer or manually | diff --git a/THEMES-DEV.md b/THEMES-DEV.md index df9b63f55..3f94f36db 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -2,9 +2,9 @@ **Note:** This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead. -If creating theme sets specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Because ES-DE theme engine functionality has deviated greatly from the RetroPie EmulationStation fork on which it was originally based, any newer themes will not work on such older forks. At least the -es-de extension is an indicator that it's an ES-DE specific theme set. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting theme sets from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu. +If creating themes specifically for ES-DE, please add `-es-de` to the repository/directory name, as in `slate-es-de`. Themes made for ES-DE are not compatible with any other EmulationStation forks (and vice versa) and the -es-de extension makes it clear that it's an ES-DE theme. The actual theme name as defined using the `themeName` tag in capabilities.xml does of course not need to include the `-es-de` extension as that's the actual theme name that will be displayed when selecting themes from the _UI Settings_ menu. For example slate-es-de will be listed simply as _Slate_ in this menu. -Before your start, make sure to download the _Theme engine examples_ theme set that contains a number of example variants for things like vertical and horizontal carousels, wheel carousels, system view textlists, grids etc: +Before your start, make sure to download the _Theme engine examples_ theme that contains a number of example variants for things like vertical and horizontal carousels, wheel carousels, system view text lists, grids etc: https://gitlab.com/es-de/themes/theme-engine-examples-es-de @@ -16,7 +16,7 @@ There is also some documentation written by lilbud covering general tips and tri https://github.com/lilbud/es-de-theme-stuff -To test whether your theme set includes support for all ES-DE systems, download one of the following archives which contain ROMs directory structures fully populated with dummy files: +To test whether your theme includes support for all ES-DE systems, download one of the following archives which contain ROM directory trees fully populated with dummy files: [ROMs_ALL_Unix.zip](tools/system-dirs-dummy-files/ROMs_ALL_Unix.zip)\ [ROMs_ALL_macOS.zip](tools/system-dirs-dummy-files/ROMs_ALL_macOS.zip)\ @@ -36,22 +36,22 @@ Table of contents: ## Introduction -ES-DE allows the grouping of themes for multiple game systems into a **theme set**. A theme is a collection of **elements**, each with their own **properties** that define the way they look and behave. These elements include things like text lists, carousels, images and animations. +An ES-DE theme is a collection of assets like images, videos and fonts as well as XML configuration files which contain various **elements**, each with their own **properties** that define the way the theme looks and behaves. These elements include things like text, images, videos, animations, carousels, grids etc. Internally ES-DE uses the concept of **components** to actually implement the necessary building blocks to parse and render the elements, and although this is normally beyond the scope of what a theme author needs to consider, it's still good to be aware of the term as it's sometimes used in the documentation. -Every game system has its own subdirectory within the theme set directory structure, and these are defined in the systems configuration file `es_systems.xml` either via the optional `` tag, or otherwise via the mandatory `` tag. When ES-DE populates a system on startup it will look for a file named `theme.xml` in each such directory. +Every game system may have its own subdirectory within the theme directory tree, and these directory names are defined in the systems configuration file `es_systems.xml` either via the optional `` tag, or otherwise via the mandatory `` tag. When ES-DE populates a system on startup it will look for a file named `theme.xml` in each such directory. -By placing a theme.xml file directly in the root of the theme set directory, that file will be processed as a default if there is no system-specific theme.xml file available. +By placing a theme.xml file directly in the root of the theme directory, that file will be processed as a default if there is no system-specific theme.xml file available. This means that the structure of having a separate directory per supported game system is entirely optional. -In the example below, we have a theme set named `mythemeset-es-de` which includes the `snes` and `nes` systems. Assuming you have some games installed for these systems, the files `mythemeset-es-de/nes/theme.xml` and `mythemeset-es-de/snes/theme.xml` will be processed on startup. If there are no games available for a system, its theme.xml file will be skipped. +In the example below, we have a theme named `mytheme-es-de` which includes the `snes` and `nes` systems. Assuming you have some games installed for these systems, the files `mytheme-es-de/nes/theme.xml` and `mytheme-es-de/snes/theme.xml` will be processed on startup. If there are no games available for a system, its theme.xml file will be skipped. -The directory structure of our example theme set could look something like the following: +The directory structure for our example theme could look something like the following: ``` ... themes/ - mythemeset-es-de/ + mytheme-es-de/ core/ font.ttf bold_font.ttf @@ -73,20 +73,24 @@ The directory structure of our example theme set could look something like the f theme.xml ``` -The theme set approach makes it easy for users to install different themes and choose between them from the _UI Settings_ menu. +The ES-DE theme functionality makes it easy for users to install different themes and to choose between them from the _UI Settings_ menu. -There are two places that ES-DE can load theme sets from: -* `[HOME]/.emulationstation/themes/[THEME_SET]/` -* `[INSTALLATION PATH]/themes/[THEME_SET]/` +There are two places that ES-DE can load themes from: +* `[HOME]/.emulationstation/themes/` +* `[INSTALLATION PATH]/themes/` -An example installation path would be: \ -`/usr/share/emulationstation/themes/slate-es-de/` +An installation path could be something like this: +``` +/usr/share/emulationstation/themes/slate-es-de/ +/Applications/EmulationStation Desktop Edition.app/Contents/Resources/themes/ +C:\Program Files\EmulationStation-DE\themes\ +``` -If a theme set with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped. +If a theme with the same name exists in both locations, the one in the home directory will be loaded and the other one will be skipped. ## Differences to legacy RetroPie themes -If you are not familiar with theming for RetroPie or similar forks of EmulationStation then you can skip this section as it only describes the key differences between the updated ES-DE themes and these legacy theme sets. The term _legacy_ is used throughout this document to refer to this older style of themes. ES-DE as of 2.2.0 can no longer load legacy themes, so if you need to view them when porting them to ES-DE, either use a legacy EmulationStation fork or ES-DE 2.1.1. +If you are not familiar with theming for RetroPie or similar forks of EmulationStation then you can skip this section as it only describes the key differences between the updated ES-DE themes and these legacy themes. The term _legacy_ is used throughout this document to refer to this older style of themes. ES-DE as of 2.2.0 can no longer load legacy themes, so if you need to view them when porting them to ES-DE, either use a legacy EmulationStation fork or ES-DE 2.1.1. With ES-DE 2.0.0 a new theme engine was introduced that fundamentally changed some aspects of how theming works. The previous design used specific view styles (basic, detailed, video and grid) and this was dropped completely and replaced with _variants_ that can accomplish the same thing while being much more powerful and flexible. @@ -113,7 +117,7 @@ As for more specific changes, the following are the most important ones compared * Many property names for the carousel have been renamed, with _logo_ being replaced by _item_ as this element can now be used in both the gamelist and system views. As well, setting the alignment will not automatically add any margins as is the case for legacy themes. These can still be set manually using the `horizontalOffset` and `verticalOffset` properties if needed. The way that alignment works in general for both carousel items and the overall carousel has also changed * The rating elements were previously not sized and overlaid consistently, this has now been fixed and rating images should now be centered on the image canvas in order for this element to render correctly rather than being left-adjusted as has previously been done by some theme authors (likely as a workaround for the previous buggy implementation). Images of any aspect ratios are now also supported where previously only square images could be used * The carousel text element hacks `systemInfo` and `logoText` have been removed and replaced with proper carousel properties -* The carousel property `maxItemCount` (formerly named 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. As well carousels of the wheel type now have the amount of entries controlled by the two new properties `itemsBeforeCenter` and `itemsAfterCenter`. This provides more exact control, including the ability to setup asymmetric wheels. +* The carousel property `maxItemCount` (formerly named 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 themes to the new theme engine. As well carousels of the wheel type now have the amount of entries controlled by the two new properties `itemsBeforeCenter` and `itemsAfterCenter`. This provides more exact control, including the ability to setup asymmetric wheels. * The full names of unthemed systems (or systems where the defined staticImage file is missing) will now be displayed in the system carousel instead of the short names shown for legacy themes. So for instance, instead of "cps" the full name "Capcom Play System" (as defined in es_systems.xml) will be displayed. * The carousel now has a zIndex value of 50 instead of 40. This means it's aligned with the textlist element which already had a zIndex value of 50. * The textlist property `selectorOffsetY` has been renamed to `selectorVerticalOffset` and a `selectorHorizontalOffset` property has been added as well. @@ -209,7 +213,7 @@ Here is a very simple theme that changes the color of the game name text: ## How it works -All configuration must be contained within a `` tag pair. That is true for each separate .xml file used to build the completely theme set. +All configuration must be contained within a `` tag pair. That is true for each separate .xml file used to build the completely theme. The `` tag pair refers to the available views within ES-DE, which is either _system_ or _gamelist_. There is a special _all_ view available as well, but that is only used for defining the navigation sounds as these are always applied globally to both view types. @@ -317,10 +321,10 @@ emulationstation --debug --resolution 1280 720 Enforcement of a correct theme configuration is quite strict, and most errors will abort the theme loading, leading to an unthemed system. In each such situation the log output will be very clear of what happened, for instance: ``` -Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/.emulationstation/themes/mythemeset-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections") +Jan 28 17:17:30 Error: ThemeData::parseElement(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml": Property "origin" for element "image" has no value defined (system "collections", theme "custom-collections") ``` -Note that an unthemed system means precisely that, the specific system where the error occured will be unthemed but not necessarily the entire theme set. The latter can still happen if the error is global such as a missing variable used by all XML files or an error in a file included by all XML files. The approach is to only untheme relevant sections of the theme set to be able to pinpoint precisely where the problem lies. +Note that an unthemed system means precisely that, the specific system where the error occured will be unthemed but not necessarily the entire theme. The latter can still happen if the error is global such as a missing variable used by all XML files or an error in a file included by all XML files. The approach is to only untheme relevant sections of the theme to be able to pinpoint precisely where the problem lies. Sanitization for valid data format and structure is done in this manner, but verification that property values are actually correct (or reasonable) is handled by the individual component that takes care of creating and rendering the specific theme element. What happens in many instances is that a warning log entry is created and the invalid property is reset to its default value. So for these situations, the system will not become unthemed. Here's an example where a badges element accidentally had its horizontalAlignment property set to _leftr_ instead of _left_: ``` @@ -338,12 +342,12 @@ Jan 28 17:29:11 Error: VideoComponent: Invalid theme configuration, property "i Error handling for missing files is handled a bit differently depending on whether the paths have been defined explicitly or via a variable. For explicitly defined paths a warning will be logged for element properties and an error will be triggered for include files. Here's an example of the latter case: ``` -Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mythemeset-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/.emulationstation/themes/mythemeset-es-de/colors_dark.xml") +Jan 28 17:32:29 Error: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml" -> "./colors_dark.xml" not found (resolved to "/home/myusername/.emulationstation/themes/mytheme-es-de/colors_dark.xml") ``` However, if a variable has been used to define the include file, only a debug message will be generated if the file is not found: ``` -Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mythemeset-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/.emulationstation/themes/mythemeset-es-de/amiga/colors.xml" +Jan 28 17:34:03 Debug: ThemeData::parseIncludes(): "/home/myusername/.emulationstation/themes/mytheme-es-de/theme.xml": Couldn't find file "./${system.theme}/colors.xml" which resolves to "/home/myusername/.emulationstation/themes/mytheme-es-de/amiga/colors.xml" ``` It works essentially the same way for element path properties as for include files. This distinction between explicit values and variables makes it possible to create a theme configuration where both include files and files for fonts, images, videos etc. will be used if found, and if not found a fallback configuration can still be applied so the system will be themed. @@ -352,19 +356,19 @@ By default all debug messages regarding missing files will be logged for regular ## Variants -A core concept of ES-DE is the use of theme set _variants_ to provide different theme profiles. These are not fixed presets and a theme author can instead name and define whatever variants he wants for his theme (or possibly use no variants at all as they are optional). +A core concept of ES-DE is the use of theme _variants_ to provide different theme profiles. These are not fixed presets and a theme author can instead name and define whatever variants he wants for his theme (or possibly use no variants at all as they are optional). -The variants could be purely cosmetic, such as providing different designs for a theme set, or they could provide distinctive functionality by for instance using different primary elements like a carousel or a text list. +The variants could be purely cosmetic, such as providing different designs for a theme, or they could provide distinctive functionality by for instance using different primary elements like a carousel or a text list. -Before a variant can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detail later in this document. +Before a variant can be used it needs to be declared, which is done in the `capabilities.xml` file that must be located in the root of the theme directory tree. How to setup this file is described in detail later in this document. The use of variants is straightforward, a section of the configuration that should be included for a certain variant is enclosed inside the `` tag pair. This has to be placed inside the `` tag pair, and it can only be used at this level of the hierarchy and not inside a `` tag pair for example. The mandatory _name_ attribute is used to specificy which variants to use, and multiple variants can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). It's also possible to use the special _all_ variant that will apply the configuration to all defined variants (although this is only a convenient shortcut and you can explicitly define every variant individually if you prefer that). Note that _all_ is a reserved name and attempting to use it in the capabilities.xml file will trigger a warning on application startup. -It could sometimes be a good idea to separate the variant configuration into separate files that are then included from the main theme file as this could improve the structure and readability of the theme set configuration. +It could sometimes be a good idea to separate the variant configuration into separate files that are then included from the main theme file as this could improve the structure and readability of the theme configuration. -It's also possible to apply only portions of the theme configuration to the variants and keep a common set of elements that are shared between all variants. This is accomplished by simply adding the shared configuration without specifying a variant, as is shown in the first example below for the `infoText01` text element. Just be aware that the variant-specific configuration will always be loaded after the general configuration even if it's located above the general configuration in the XML file. As this is potentially confusing and error-prone it's instead generally recommended to use the special _all_ variant to define common configuration used by all variants in the theme set rather than mixing variants configuration with non-variants configuration. +It's also possible to apply only portions of the theme configuration to the variants and keep a common set of elements that are shared between all variants. This is accomplished by simply adding the shared configuration without specifying a variant, as is shown in the first example below for the `infoText01` text element. Just be aware that the variant-specific configuration will always be loaded after the general configuration even if it's located above the general configuration in the XML file. As this is potentially confusing and error-prone it's instead generally recommended to use the special _all_ variant to define common configuration used by all variants in the theme rather than mixing variants configuration with non-variants configuration. Here are some example uses of the `` functionality: @@ -475,13 +479,13 @@ Color schemes are essentially a collection of variables that can be selected bet To understand the basics on how to use variables, make sure to read the _Theme variables_ section elsewhere in this document. -Before a color scheme can be used it needs to be declared, which is done in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detail later in this document. +Before a color scheme can be used it needs to be declared, which is done in the `capabilities.xml` file that must be located in the root of the theme directory tree. How to setup this file is described in detail later in this document. The `` tag pair can be placed directly inside the `` tags, inside the `` tags or inside the `` tags. The mandatory name attribute is used to specificy which color scheme to use, and multiple values can be specified at the same time by separating them by commas or by whitespace characters (tabs, spaces or line breaks). -Note that the use of color schemes for a theme set is entirely optional. +Note that the use of color schemes for a theme is entirely optional. Here's an example configuration: @@ -525,9 +529,9 @@ Here's an example configuration: ## Aspect ratios -The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme set can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries. +The aspect ratio support works almost identically to the variants and color schemes with the main difference that the available aspect ratios are hardcoded into ES-DE. The theme can still decide which of the aspect ratios to support (or none at all in which case the theme aspect ratio is left undefined) but it can't create entirely new aspect ratio entries. -In the same manner as for the variants and color schemes, the aspect ratios that the theme set provides need to be declared in the `capabilities.xml` file that must be stored in the root of the theme set directory tree. How to setup this file is described in detailed later in this document. +In the same manner as for the variants and color schemes, the aspect ratios that the theme provides need to be declared in the `capabilities.xml` file that must be located in the root of the theme directory tree. How to setup this file is described in detailed later in this document. The `` tag pair can be placed directly inside the `` tags or inside the `` tags. @@ -681,9 +685,9 @@ Finally it's possible to apply theme-defined transition profiles on a per-varian ## capabilities.xml -Variants, variant triggers, color schemes, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme set configuration files and that is done in the `capabilities.xml` file. This file needs to be placed in the root of the theme directory, for example: +Variants, variant triggers, color schemes, aspect ratios and transition animation profiles need to be declared before they can be used inside the actual theme configuration files and that is done in the `capabilities.xml` file. This file needs to be located in the root of the theme directory, for example: ``` -~/.emulationstation/themes/mythemeset-es-de/capabilities.xml +~/.emulationstation/themes/mytheme-es-de/capabilities.xml ``` The capabilities.xml file is mandatory and if it doesn't exist ES-DE will not attempt to load the theme. @@ -691,9 +695,9 @@ The capabilities.xml file is mandatory and if it doesn't exist ES-DE will not at The structure of the file is simple, as can be seen in this example: ```xml - + - My theme set + My theme 16:9 4:3 @@ -742,7 +746,7 @@ The structure of the file is simple, as can be seen in this example: ``` The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes, one transition animation profile and three variants, one of which is a variant trigger override. The `