From b1dbd28be0f599bfe14ca6ba3d89d47c01bbf27e Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Wed, 4 Jan 2023 19:35:55 +0100 Subject: [PATCH] Documentation update. --- FAQ.md | 4 ++++ INSTALL-DEV.md | 2 +- INSTALL.md | 4 +++- THEMES-DEV.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++--- 4 files changed, 60 insertions(+), 5 deletions(-) diff --git a/FAQ.md b/FAQ.md index 0a165b571..0284d7668 100644 --- a/FAQ.md +++ b/FAQ.md @@ -60,6 +60,10 @@ This is almost always caused by either corrupt ROMs/disc images or by missing em This is related to the two questions above, ES-DE does not perform any emulator configuration or general system configuration. So you would either need to configure an exit button combination inside your emulator, or use a third party tool to map for instance Alt + F4 or Command + Q to a certain button combination on your controller. If you use RetroArch then it's easy to setup a button combination to exit back to ES-DE, which will apply to all cores. Refer to the RetroArch documentation or their support channels on how to accomplish this. +## Why does it take a long time for ES-DE to resume after I've exited a game? + +With a few notable exceptions like the Valve Steam system on all platforms and the MAME standalone emulator on Windows, ES-DE will wait for emulators and games to fully exit before it resumes. Some emulators take quite some time to fully exit (sometimes even after their application windows have been destroyed). This may make it seem as if ES-DE is hanging although it's actually waiting for the launched child process to exit. Another reason for a delayed resume is if a custom event script is executed on game end which itself takes a long time to run. If you have such a custom setup then there is a way to work around this by executing scripts as background processes, which is documented [here](INSTALL.md#custom-event-scripts). + ## I have many games with multiple files, is there a way to show these as single entries? Yes this is supported for both single-disc games using a .bin/.cue structure for instance, or for multi-file/multi-disc games where .m3u files are used for emulator disc swapping. See the _Directories interpreted as files_ section of the [User guide](USERGUIDE.md#directories-interpreted-as-files) for details on how to configure this. diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index a1f478130..883b1f6d6 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -1909,7 +1909,7 @@ Just make sure to not place the portable installation on a network share that us There are numerous locations throughout ES-DE where custom scripts can be executed if the option to do so has been enabled in the settings. You'll find the option _Enable custom event scripts_ on the Main menu under _Other settings_. By default this setting is deactivated so make sure to enable it to use this feature. -The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. If you want to have the scripts executed in a certain order you can name them accordingly as they will be sorted and executed in lexicographic order. The sorting is case-sensitive on Unix/Linux and case-insensitive on macOS and Windows. ES-DE will wait for each script to finish its execution before moving on to the next one, so the application will suspend briefly when whatever the script is doing is executing. If you want to avoid this you can setup a wrapper script that executes another script outside the ES-DE scripts directory as a background process. +The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. If you want to have the scripts executed in a certain order you can name them accordingly as they will be sorted and executed in lexicographic order. The sorting is case-sensitive on Unix/Linux and case-insensitive on macOS and Windows. ES-DE will wait for each script to finish its execution before moving on to the next one, so the application will suspend briefly when whatever the script is doing is executing. If you want to avoid this you can setup a wrapper script that executes another script outside the ES-DE scripts directory as a background process. Refer to your operating system documentation on how to accomplish this. There are up to four parameters that will be passed to these scripts, as detailed below: diff --git a/INSTALL.md b/INSTALL.md index 350417a8c..74a115b7a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2140,7 +2140,9 @@ Just make sure to not place the portable installation on a network share that us There are numerous locations throughout ES-DE where custom scripts can be executed if the option to do so has been enabled in the settings. You'll find the option _Enable custom event scripts_ on the Main menu under _Other settings_. By default this setting is deactivated so make sure to enable it to use this feature. -The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. There are up to four parameters that will be passed to these scripts, as detailed below: +The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files. It will wait for each script to finish its execution before moving on to the next one, so the application will suspend briefly when whatever the script is doing is executing. If you want to avoid this you can setup a wrapper script that executes another script outside the ES-DE scripts directory as a background process. Refer to your operating system documentation on how to accomplish this. + +There are up to four parameters that will be passed to these scripts, as detailed below: | Event | Parameters* | Description | | :----------------------- | :------------------------------------------------- | :-------------------------------------------------------------------------- | diff --git a/THEMES-DEV.md b/THEMES-DEV.md index d07f7a112..3c4c9d984 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -356,6 +356,40 @@ Here are some example uses of the `` functionality: ``` + +## Variant triggers (overrides) + +Variant triggers is an optional feature which can be used to replicate the automatic view style switching functionality of the legacy theme engine. This can be used to automatically override the selected variant based on two triggers, either when there are no game videos found for a system, or if there are no game media files of some specified types found for a system. These two trigger types are named `noVideos` and `noMedia` respectively. + +For the `noMedia` trigger there's an optional `mediaType` tag that can be used to specify precisely which media files should be checked for to determine whether to switch to the override variant. Valid values are `miximage`, `marquee`, `screenshot`, `titlescreen`, `cover`, `backcover`, `3dbox`, `physicalmedia`, `fanart` and `video`. Multiple values can be defined, in which case they are separated by a comma, or by a whitespace character (tab, space or line break). If no value is defined, it will be set to `miximage`. + +The `useVariant` tag specifies which variant to use to override the selected variant. + +You'll probably rarely need to use the `noVideos` trigger as `video` can be defined also when using the `noMedia` trigger. The reason for including both trigger types is that it makes it possible to apply a specific variant only when videos are missing and another variant when no media files at all are present. + +The following example (from the `capabilities.xml` file) defines a `noGameMedia` variant which is used as the override for the `withVideos` variant if no miximages, screenshots, covers and videos are found for any game in a system. For this example the `noGameMedia` variant has been set as non-selectable from the _UI Settings_ menu. + +As can be seen here, the overall variant trigger configuration needs to be enclosed within an `override` tag pair + +```xml + + + true + + noMedia + miximage, screenshot, cover, video + noGameMedia + + + + + + false + +``` + +Note that variant triggers will only apply to the gamelist view and not the system view. Also be aware that it will add a potentially noticeable application slowdown as game media files need to be scanned for at various points when using the application, as well as during startup. The impact of the performance penalty depends on multiple factors such as the game collection size, how many games have been scraped and disk I/O and filesystem performance. So only use variant triggers if really necessary for your theme design. As well, specifying many values for the `mediaType` tag will lead to more files potentially being scanned which could introduce further lag and latency. + ## Color schemes Color schemes are essentially a collection of variables that can be selected between from the _UI Settings_ menu. This makes it possible to define different values that will be applied to the overall theme configuration based on this menu selection. Only variables can be used for the color schemes, but since variables can be used for almost everything this makes the functionality very flexible. In most cases you'll probably want to apply different color values to `` properties and similar, but it's also possible to apply different images, animations, fonts etc. per color scheme. @@ -493,7 +527,7 @@ Once the aspect ratios have been defined, they are applied to the theme configur ## capabilities.xml -Variants, color schemes and aspect ratios 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 exist in the root of the theme directory, for example: +Variants, variant triggers, color schemes and aspect ratios 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 exist in the root of the theme directory, for example: ``` ~/.emulationstation/themes/mythemeset-DE/capabilities.xml ``` @@ -520,15 +554,30 @@ The structure of the file is simple, it just contains declarations for the varia true + + noMedia + miximage, screenshot, cover, video + noGameMedia + true + + noMedia + miximage, screenshot, cover + noGameMedia + + + + + + false ``` -The file format is hopefully mostly self-explanatory; this example provides three aspect ratios, two color schemes and two variants. The `