diff --git a/CHANGELOG.md b/CHANGELOG.md index c4723a43c..660221e96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,7 @@ * (Windows) Made game launching more seamless by making the application window one pixel wider instead of one pixel less in height * Added ares standalone as an alternative emulator for many systems * Added MAME standalone as an alternative emulator for the gameandwatch system -* Added openMSX standalone as an alternative emulator for the msx, msx1, msx2 and msxturbor systems +* Added openMSX standalone as an alternative emulator for the colecovision, msx, msx1, msx2 and msxturbor systems * (Linux) Added support for the Nintendo Wii U (wiiu) game system * Added Triforce (Dolphin fork) standalone as an alternative emulator for the gc system on Linux and Windows * Added simple64 standalone as an alternative emulator for the n64 system on Linux and Windows @@ -55,6 +55,7 @@ * Removed the "Preload gamelists on startup" setting * Removed the "Play videos immediately (override theme)" setting * Renamed the sound menu option "Play audio for videos in the gamelist view" to "Play audio for gamelist and system view videos" +* Added an "Ignore keyboard input" option to the input device settings menu * The media viewer now always loads all images upfront to avoid audio stutter when browsing the files * Added support for defining which types of game media to use for all image elements (and also for the video component static image) * Added a legacy (backward compatibility) mode for still supporting older RetroPie EmulationStation themes @@ -128,6 +129,7 @@ * Added size restrictions to images and fonts so incorrect theme configuration would not lead to crashes or excessive memory utilization * Migrated the carousel code from SystemView to a separate new CarouselComponent * Changed the carousel properties to be more generic by renaming "logo" to "item", e.g. itemSize, maxItemCount etc. +* Added the properties "itemsBeforeCenter" and "itemsAfterCenter" to define entries for carousels of the wheel type * Added a wheelHorizontalAlignment property for aligning the carousel within the overall element area (horizontal/vertical wheel only) * Added reflections support to the carousel * Added carousel theme support for setting the opacity for unfocused entries @@ -188,6 +190,7 @@ * Abbreviations of long words in multiline text entries sometimes exceeded the designated text area * Navigation sounds would sometimes not play when browsing game media in the media viewer * The text debug overlay had the wrong size for scrollable containers +* The textlist debug overlay would sometimes get positioned incorrectly * StringUtil::delimitedStringToVector could return empty elements * (Windows) File paths would get escaped with quotation marks even if they did not contain any spaces * (Windows) The emulator binary path would sometimes not get escaped correctly in es_log.txt on game launch diff --git a/FAQ.md b/FAQ.md index 3c7adfd36..1e7a75b4e 100644 --- a/FAQ.md +++ b/FAQ.md @@ -26,7 +26,7 @@ See the _Supported game systems_ section at the bottom of the [User guide](USERG ## Why can't I press the up button in menus to jump to the bottom row and vice versa? -Menus in ES-DE are not lists but grids, sometimes there is only a list but sometimes there are buttons beneath the list. Enabling the up and down buttons to wrap around would therefore not work consistently as it would sometimes jump to the last row of the list and sometimes to a button, depending on the menu layout. This type of contextual navigation feels very weird in practice. The solution is instead to use the shoulder buttons (which will jump six rows), or the trigger buttons (which will jump to the first and last row). These buttons work consistently throughout the application and avoid the strange side effects just mentioned. If you observe this more closely you will also realize that "wrap around" is very rare in GUI design, you don't jump to the bottom of a web page when you scroll up from the top in your web browser and likewise the settings menus of your mobile phone will not wrap around. +Menus in ES-DE are not lists but grids, sometimes there is only a list but sometimes there are buttons beneath the list. Enabling the up and down buttons to wrap around would therefore not work consistently as it would sometimes jump to the last row of the list and sometimes to a button, requiring a different number of button presses depending on the menu layout. This type of contextual navigation feels very weird in practice, especially when you have to press the up button twice to get to the bottom of a list. The solution is instead to use the shoulder buttons (which will jump six rows), or the trigger buttons (which will jump to the first and last row). These buttons work consistently throughout the application and avoid the strange side effects just mentioned. ## I don't like the default emulator for a certain system, how can I choose an alternative? @@ -100,17 +100,23 @@ This functionality is planned but not yet implemented. It will probably be rolle ES-DE works very differently compared to all other EmulationStation forks when it comes to handling of game media. There are no links in the gamelist.xml files, instead media files are simply matched against the ROM/game file names which makes for a much simpler, faster and completely portable setup. Migrating game media from other EmulationStation forks (and potentially from other frontends as well) can be accomplished quite easily. See the next question below for more information. Make sure to also read the _Migrating from other EmulationStation forks_ section of the [User guide](USERGUIDE.md#migrating-from-other-emulationstation-forks) to avoid data loss if running ES-DE with existing data from another EmulationStation fork. +## Why do I sometimes get error messages when scraping stating that files are less than 350 bytes in size? + +This is caused by a ScreenScraper bug where their cache sometimes includes entries that no longer exist. When a media file is removed from the ScreenScraper database, the cached link to that file is retained for some time and will be returned as a valid media file URL to ES-DE. However, when attempting to scrape such a file, it will only contain the text string _NOMEDIA_ which will trigger this error in ES-DE. The cache bug only affects the multi-scraper API call, so a workaround is to manually scrape such games using the single-game scraper (reachable via the metadata editor). The invalid cache entries seem to disappear within 24 hours so waiting for a while and rescraping should also resolve the problem. The issue has been reported to the ScreenScraper team but it's unclear if and when it will be resolved. + ## Can I use an external scraper application instead of the built-in scraper? -Yes to a certain extent this is supported and at least [Skraper](https://www.skraper.net) and [Skyscraper](https://github.com/muldjord/skyscraper) have been used by some people. Few if any dedicated scraper applications are yet updated specifically to support ES-DE though, so you may need to do some manual renaming and moving of files and directories. See the _Manually copying game media files_ section of the [User guide](USERGUIDE.md#manually-copying-game-media-files) for more details about this. +Yes to a certain extent this is supported and at least [Skraper](https://www.skraper.net) and [Skyscraper](https://github.com/detain/skyscraper) have been used by some people. Few if any dedicated scraper applications are yet updated specifically to support ES-DE though, so you may need to do some manual renaming and moving of files and directories. See the _Manually copying game media files_ section of the [User guide](USERGUIDE.md#manually-copying-game-media-files) for more details about this. ## My controller isn't working in ES-DE, is there a way to fix this? -If the controller works in other applications and games but not in ES-DE, then you may be able to get it to run in ES-DE as well. The required setup is described in detail in the _Adding custom controller profiles_ section of the [Building and advanced configuration](INSTALL.md#adding-custom-controller-profiles) document. +If the controller works in other applications and games but not in ES-DE, then you may be able to get it to run in ES-DE as well. The required setup is described in detail in the _Adding custom controller profiles_ section of the [Building and advanced configuration](INSTALL.md#adding-custom-controller-profiles) document. Although not guaranteed to work, an alternative solution is to have Steam running in parallel to ES-DE and using the _Steam Controller_ functionality to present the controller as a virtual device in ES-DE. You don't need to launch ES-DE via Steam for this to work, it's enough if Steam is running in the background. If going for this, make sure to read the next question below, and also note that the Steam approach only seems to work on Linux and Windows, and not on macOS. -## Every controller button press is registered twice in ES-DE, should I file a bug report? +## Why is every controller button press registered twice in ES-DE? -Although this is for sure a bug it's not caused by ES-DE, rather some wireless controllers have buggy drivers and will register itself as two separate devices. And as ES-DE auto-configures all devices, every button press will in practice be received twice. The easiest solution to this problem is to enable the option _Only accept input from first controller_ in the _Input device settings_ menu, but the drawback of this is that all other attached controllers will also be ignored. A more proper workaround is to blacklist the redundant controller device, see the previous question above as blacklisting is essentially a custom controller profile entry. +There are two reasons why double input is received in ES-DE, either because Steam is running and the _Desktop Configuration_ of the Steam Controller functionality is enabled, or due to buggy controller drivers where two devices are registered in parallel by the operating system. In the former case, enabling the Steam Controller functionality will by default also enable keyboard input to be sent whenever a button is pressed on the controller. As ES-DE reads both the keyboard and controller events this will be registered as double or conflicting input. To disable this functionality, go into the Steam settings interface, then select the _Controller_ entry followed by the _DESKTOP CONFIGURATION_ button. Make sure to remove all keyboard mappings and the problem should disappear. An alternative solution is to add ES-DE as a Non-Steam game and launch it via the Steam application in which case the keyboard events will be automatically disabled (that's how it's normally done on the Steam Deck for instance). Making sure Steam is shut down while ES-DE is running is another possible solution. + +The second reason for double input is buggy controller drivers. This seems to only occur with wireless controllers but it's possible that it also happens with wired devices. As ES-DE auto-configures all devices, every button press will in practice be received twice. The easiest solution to this problem is to enable the option _Only accept input from first controller_ in the _Input device settings_ menu, but the drawback of this is that all other attached controllers will also be ignored. A more proper workaround is to blacklist the redundant controller device, see the previous question above as blacklisting is essentially a custom controller profile entry. Note that neither of these approaches will affect the emulators/games launched from ES-DE, it only applies to the ES-DE application itself. ## I'm missing a feature, how can I make a request to have it added? diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 959bed95d..90ff758f3 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -85,7 +85,7 @@ The following are the most important changes compared to the legacy theme struct * 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 +* 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 assymetric wheels. * The helpsystem `textColorDimmed` and `iconColorDimmed` properties (which apply when opening a menu) were always defined under the system view configuration which meant these properties could not be separately set for the gamelist views. Now these properties work as expected with the possibility to configure separate values for the system and gamelist views * Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail * Many additional elements and properties have been added, refer to the [Reference](THEMES-DEV.md#reference) section for more information @@ -1463,10 +1463,19 @@ Properties: * `defaultItem` - type: PATH - Path to the default image file which will be displayed if the image defined via the `staticItem` or `itemType` property is not found. Most common extensions are supported (including .svg, .jpg, .png, and unanimated .gif). * `maxItemCount` - type: FLOAT - - Sets the number of items to display in the carousel. + - Sets the number of items to display in the carousel when the `type` property has been set to "horizontal" or "vertical". Has no effect if the `type` has been set to "horizontal_wheel" or "vertical_wheel". - Minimum value is `0.5` and maximum value is `30` - Default is `3` +* `itemsBeforeCenter` - type: UNSIGNED_INTEGER + - Sets the number of items above the center position (the currently selected entry) when the `type` property has been set to "horizontal_wheel" or "vertical_wheel". 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. + - Minimum value is `0` and maximum value is `20` + - Default is `8` +* `itemsAfterCenter` - type: UNSIGNED_INTEGER + - Sets the number of items below the center position (the currently selected entry) when the `type` property has been set to "horizontal_wheel" or "vertical_wheel". 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. + - Minimum value is `0` and maximum value is `20` + - Default is `8` * `itemSize` - type: NORMALIZED_PAIR + - Both axes need to be defined. - Minimum value per axis is `0.05` and maximum value per axis is `1` - Default is `0.25 0.155` * `itemScale` - type: FLOAT. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 4cfcf6872..e7623ab9a 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -4,7 +4,7 @@ This document is intended as a quick start guide and as a reference for the appl This version of the user guide is only relevant for the current ES-DE development version, if you are using the latest stable release, refer to [USERGUIDE.md](USERGUIDE.md) instead. -It's generally recommended to read the [Frequently Asked Questions](FAQ.md) document prior to diving into the information in this guide. +It's generally recommended to read the [Frequently Asked Questions (FAQ)](FAQ.md) document prior to diving into the information in this guide. Table of contents: @@ -2398,6 +2398,10 @@ This setting gives the ability to choose between the controller types _Xbox, Xbo If enabling this option, only the first controller detected during startup will send its input to ES-DE (the keyboard input is unaffected by this setting and will be enabled regardless). This is a good way to limit potential chaos with multiple persons fighting over which games to play. Note that disconnecting and reconnecting controllers while ES-DE is running may change what is considered the first controller. This setting does not affect the emulators in any way, it's only applied to ES-DE. Another issue is that some wireless controllers have buggy drivers and will register as two devices, meaning all button presses will be registered twice inside ES-DE. Using this option is one solution to the problem, although it's also possible to blacklist the extra controller entry, as described [here](INSTALL-DEV.md#adding-custom-controller-profiles). +**Ignore keyboard input** + +If this setting is enabled then all keyboard input will be ignored, except the quit shortcut used to shut down the application. The main reason for ignoring keyboard input is if running Steam in parallel to ES-DE and you need to use the Steam Controller _Desktop Configuration_ functionality to send keyboard input using the controller. In this case double or conflicting input will be sent to ES-DE as both the controller and keyboard events are read by the application. It's however generally a better idea to disable this functionality altogether in Steam and leave the ES-DE setting untouched. If you accidentally enable this setting when using a keyboard as input device, then you'll either need to plug in a controller to disable it again, or you'll need to modify the _InputIgnoreKeyboard_ entry in the ~/.emulationstation/es_settings.xml configuration file. + **Configure keyboard and controllers** This tool provides configuration of button mappings for the keyboard and controllers, as explained [here](USERGUIDE-DEV.md#input-device-configuration). Normally this is not required as ES-DE automatically configures all input devices, but button customizations may be useful in some special situations. You may also need to run this tool if you have an unusual controller which could not be automatically configured. Be aware that custom button mappings will not change the help icons or help text. @@ -2968,7 +2972,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | chailove | ChaiLove Game Engine | ChaiLove | | | | | channelf | Fairchild Channel F | FreeChaF | | | | | coco | Tandy Color Computer | XRoar CoCo 2 NTSC **(Standalone)** [UMW*] | XRoar CoCo 2 PAL **(Standalone)** [UMW*] | Yes | See the specific _Tandy Color Computer_ section elsewhere in this guide | -| colecovision | ColecoVision | blueMSX | Gearcoleco,
ares **(Standalone)** [UMW*] | | | +| colecovision | ColecoVision | blueMSX | Gearcoleco,
openMSX **(Standalone)** [UMW*],
ares **(Standalone)** [UMW*] | Yes | Single archive or ROM file in root folder | | cps | Capcom Play System | MAME - Current | MAME 2010,
MAME 2003-Plus,
MAME 2000,
MAME **(Standalone)** [UMW*],
FinalBurn Neo,
FB Alpha 2012,
FB Alpha 2012 CPS-1,
FB Alpha 2012 CPS-2,
FB Alpha 2012 CPS-3 | Depends | See the specific _Arcade and Neo Geo_ section elsewhere in this guide | | daphne | Daphne Arcade LaserDisc Emulator | Hypseus [Daphne] **(Standalone)** [UW*] | Hypseus [Singe] **(Standalone)** [UW*] | Yes (Daphne games) | See the specific _Hypseus Singe (Daphne)_ section elsewhere in this guide | | desktop | Desktop Applications | _Suspend ES-DE_ | _Keep ES-DE running_ | | See the specific _Ports and desktop applications_ section elsewhere in this guide | diff --git a/USERGUIDE.md b/USERGUIDE.md index b1b4897be..3041ef8c4 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -2,7 +2,7 @@ This document is intended as a quick start guide and as a reference for the application settings and general functionality. For details on how to build ES-DE from source code and to perform more advanced configuration, please refer to [INSTALL.md](INSTALL.md). -It's generally recommended to read the [Frequently Asked Questions](FAQ.md) document prior to diving into the information in this guide. +It's generally recommended to read the [Frequently Asked Questions (FAQ)](FAQ.md) document prior to diving into the information in this guide. Table of contents: