diff --git a/CHANGELOG.md b/CHANGELOG.md index 268fdabf7..a21ba07b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,10 +10,14 @@ * Added support for a dedicated es_systems_sorting.xml file to change systems sorting without having to modify es_systems.xml * Placing an es_find_rules.xml file in custom_systems will now complement rather than override the bundled file +* Added support for changing between light and dark color schemes for the menu system * Added the SameBoy RetroArch core as an alternative emulator for the sgb system * Added the .sh file extension to the ags system on Unix and macOS and set the %STARTDIR% variable to the game directory +* (Linux) Added "AppImage (Suspend ES-DE)" and "AppImage (Keep ES-DE running)" as alternative emulators for the windows system +* (Linux) Added the .AppImage file extension to the windows system * (Linux) Added support for the official Citra AppImage release * Removed the experimental status for the theme downloader +* Improved resilience to buggy controller drivers which would sometimes crash the application (mostly relevant for macOS) * Changed the default OpenGL version from 4.6 to 3.3 when building for RetroDECK ### Bug fixes @@ -46,7 +50,7 @@ Catch-up release which implements some things that didn't make it into 2.0.0. Mo * (Unix) Added the .desktop and .sh file extensions to the arcade and mame systems * (macOS) Added the .app and .sh file extensions to the arcade and mame systems * (Windows) Added the .bat and .lnk file extensions to the arcade and mame systems -* Added the .app file extensions to the nds system +* Added the .app file extension to the nds system * Added the .7z and .zip file extensions to the 3do system * Changed the platform from pc to pcwindows for the desktop and kodi systems * (Linux) Dropped support for prebuilt RPM packages diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 4067cfea4..7f877031b 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -133,13 +133,17 @@ Note that the legacy theme engine had quite inaccurate text sizing and font rend * The defined line spacing was not always applied for automatically sized text elements * Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly) -## System metadata repository +## System metadata and logos repositories -There is a very useful system metadata repository available that you can use for populating information like descriptions, release dates, per-system color palettes etc. It can be found here: +There are two useful repositories hosted by the ES-DE project that provide system metadata and system logotypes. These greatly simplifies the work of adding support for all systems that ES-DE supports. + +**Metadata** + +The metadata repository provides descriptions, release dates, per-system color palettes etc. and it can be found here: https://gitlab.com/es-de/themes/system-metadata -By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done regularly. Also check the README.md file in that repository for more details on how to actually use the variables. +By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done continuously. Also check the README.md file in the repository for more details on how to actually use the variables. Here's how to add this repository as a subtree inside your theme's Git repository: ``` @@ -147,19 +151,42 @@ git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.g git subtree add --prefix=system-metadata --squash system-metadata master ``` -To later pull in updates made to the system metadata repository, you'll run the following: +To later pull in repository updates you'll run the following: ``` git subtree pull --prefix=system-metadata --squash system-metadata master ``` The directory name can be changed to whatever you like using the --prefix flag. -Note that the remote is only present on your local repository, so if you clone a theme you'll need to manually add the system-metadata remote to be able to pull from the subtree, i.e. you'll need to run this command on a freshly cloned theme repository: +**Logos** + +Likewise there's a repository of system logotypes that can also be added and used in the same fashion as the metadata. It can be found here: + +https://gitlab.com/es-de/themes/system-logos + +Here's how to add this repository as a subtree inside your theme's Git repository: ``` -git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git +git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git +git subtree add --prefix=system-logos --squash system-logos master ``` -## Simple example +To later pull in repository updates you'll run the following: +``` +git subtree pull --prefix=system-logos --squash system-logos master +``` + +The directory name can be changed to whatever you like using the --prefix flag. + +**Adding remotes** + +Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the system-metadata and/or system-logos remotes to be able to pull to these subtrees. That means you'll need to run the following commands on a freshly cloned theme repository: +``` +git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git +git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git +``` +After doing this you'll be able to pull repository updates as described above. + +## Simple example theme Here is a very simple theme that changes the color of the game name text: diff --git a/THEMES.md b/THEMES.md index 19e7a6235..bb0b97430 100644 --- a/THEMES.md +++ b/THEMES.md @@ -131,13 +131,17 @@ Note that the legacy theme engine had quite inaccurate text sizing and font rend * The defined line spacing was not always applied for automatically sized text elements * Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly) -## System metadata repository +## System metadata and logos repositories -There is a very useful system metadata repository available that you can use for populating information like descriptions, release dates, per-system color palettes etc. It can be found here: +There are two useful repositories hosted by the ES-DE project that provide system metadata and system logotypes. These greatly simplifies the work of adding support for all systems that ES-DE supports. + +**Metadata** + +The metadata repository provides descriptions, release dates, per-system color palettes etc. and it can be found here: https://gitlab.com/es-de/themes/system-metadata -By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done regularly. Also check the README.md file in that repository for more details on how to actually use the variables. +By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done continuously. Also check the README.md file in the repository for more details on how to actually use the variables. Here's how to add this repository as a subtree inside your theme's Git repository: ``` @@ -145,19 +149,43 @@ git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.g git subtree add --prefix=system-metadata --squash system-metadata master ``` -To later pull in updates made to the system metadata repository, you'll run the following: +To later pull in repository updates you'll run the following: ``` git subtree pull --prefix=system-metadata --squash system-metadata master ``` The directory name can be changed to whatever you like using the --prefix flag. -Note that the remote is only present on your local repository, so if you clone a theme you'll need to manually add the system-metadata remote to be able to pull from the subtree, i.e. you'll need to run this command on a freshly cloned theme repository: +**Logos** + +Likewise there's a repository of system logotypes that can also be added and used in a similar fashion as the metadata. It can be found here: + +https://gitlab.com/es-de/themes/system-logos + +Here's how to add this repository as a subtree inside your theme's Git repository: ``` -git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git +git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git +git subtree add --prefix=system-logos --squash system-logos master ``` -## Simple example +To later pull in repository updates you'll run the following: +``` +git subtree pull --prefix=system-logos --squash system-logos master +``` + +The directory name can be changed to whatever you like using the --prefix flag. + +**Adding remotes** + +Note that the remotes are only setup for your local repository, so if you clone a theme you'll need to manually add the system-metadata and/or system-logos remotes to be able to pull to these subtrees. That means you'll need to run the following commands on a freshly cloned theme repository: +``` +git remote add system-metadata https://gitlab.com/es-de/themes/system-metadata.git +git remote add system-logos https://gitlab.com/es-de/themes/system-logos.git +``` + +After doing this you'll be able to pull repository updates as described above. + +## Simple example theme Here is a very simple theme that changes the color of the game name text: diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 3a5c1538f..055ebc08b 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -264,9 +264,11 @@ As macOS does not support Vulkan some emulators are not available, and some that Lack of controller support is a bit of a problem on macOS, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investigate the macOS support as it seems to differ quite a lot. +There is a very annoying default configuration when using Sony controllers like the DualShock 4 and DualSense (and possibly others) where double tapping the Share button starts the screen recording functionality of the operating system. This normally presents a popup window for whether to approve the screen recording. To disable this functionality you need to create a custom controller profile and assign that to your specific controller. This is done via _System Settings_ and then the _Game Controllers_ entry. You'll find the relevant setting under the _Share Gestures_ section of the controller profile configuration screen. Refer to your operating system documentation for more details about this topic. + One macOS-specific requirement is that the RetroArch setting _Start in Fullscreen mode_ is enabled or ES-DE will not be able to switch to the emulator window when launching games. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. This issue has not been observed with any other emulators. -At the time of writing there is an additional issue with the ARM release of RetroArch where ES-DE will not be able to consistently switch to its window on game launch if the setting _Close windows when closing an app_ under the General entry in the macOS System Preferences has been set to disabled. This error does not occur for the Intel/x86 release of RetroArch or with any other standalone emulators (including those built specifically for the ARM architecture). +At the time of writing there is an additional issue with the ARM release of RetroArch where ES-DE will not be able to consistently switch to its window on game launch if the setting _Close windows when quitting an application_ under the _Desktop & Dock_ entry in the macOS _System Settings_ has been set to disabled. This error does not occur for the Intel/x86 release of RetroArch or with any other standalone emulators (including those built specifically for the ARM architecture). The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: @@ -274,7 +276,7 @@ The first time you launch a RetroArch-emulated game from within ES-DE the operat If you don't allow this, you will not be able to place system BIOS ROMs in the RetroArch default system directory `~/Documents/RetroArch/system` even if you've already given RetroArch access to this folder. This is so because RetroArch runs as a subprocess to ES-DE and therefore inherits the security settings from the parent application. Attempting to launch a game without enabling the access will simply display an error message in the emulator that the BIOS files are missing. This of course only applies to emulators that require BIOS ROMs, all other games should work fine regardless of this security setting. -If you accidentally refused ES-DE the folder access, you can fix this by opening _System Preferences_, selecting _Security & Privacy_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. +If you accidentally refused ES-DE the folder access, you can fix this by opening _System Settings_, selecting _Privacy & Security_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. By default files and directories starting with a dot are hidden on macOS, so to show the .emulationstation directory in your home directory you need to enable hidden files in Finder. You do this using the keyboard combination Shift + Command + . (dot). @@ -3205,7 +3207,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed | wasm4 | WASM-4 Fantasy Console | WASM-4 | | No | Single .wasm file | | wii | Nintendo Wii | Dolphin | Dolphin **(Standalone)**,
PrimeHack **(Standalone)** [UW] | No | | | wiiu | Nintendo Wii U | Cemu **(Standalone)** | | No | See the specific _Nintendo Wii U_ section elsewhere in this guide | -| windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_ | | Shortcut (.desktop/.app/.lnk) file or script | +| windows | Microsoft Windows | _Suspend ES-DE_ | _Keep ES-DE running_,
_AppImage (Suspend ES-DE)_ [U],
_AppImage (Keep ES-DE running)_ [U] | No | Shortcut (.desktop/.app/.lnk) file or script | | wonderswan | Bandai WonderSwan | Beetle Cygne | Mednafen **(Standalone)**,
ares **(Standalone)** | No | | | wonderswancolor | Bandai WonderSwan Color | Beetle Cygne | Mednafen **(Standalone)**,
ares **(Standalone)** | No | | | x1 | Sharp X1 | x1 | | | Single archive or ROM file | diff --git a/USERGUIDE.md b/USERGUIDE.md index e7177bc6d..22bd95b63 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -262,9 +262,11 @@ As macOS does not support Vulkan some emulators are not available, and some that Lack of controller support is a bit of a problem on macOS, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investigate the macOS support as it seems to differ quite a lot. +There is a very annoying default configuration when using Sony controllers like the DualShock 4 and DualSense (and possibly others) where double tapping the Share button starts the screen recording functionality of the operating system. This normally presents a popup window for whether to approve the screen recording. To disable this functionality you need to create a custom controller profile and assign that to your specific controller. This is done via _System Settings_ and then the _Game Controllers_ entry. You'll find the relevant setting under the _Share Gestures_ section of the controller profile configuration screen. Refer to your operating system documentation for more details about this topic. + One macOS-specific requirement is that the RetroArch setting _Start in Fullscreen mode_ is enabled or ES-DE will not be able to switch to the emulator window when launching games. As a workaround you can switch to the window manually using Command + Tab but it probably doesn't make sense to run emulators in windowed mode anyway. This issue has not been observed with any other emulators. -At the time of writing there is an additional issue with the ARM release of RetroArch where ES-DE will not be able to consistently switch to its window on game launch if the setting _Close windows when closing an app_ under the General entry in the macOS System Preferences has been set to disabled. This error does not occur for the Intel/x86 release of RetroArch or with any other standalone emulators (including those built specifically for the ARM architecture). +At the time of writing there is an additional issue with the ARM release of RetroArch where ES-DE will not be able to consistently switch to its window on game launch if the setting _Close windows when quitting an application_ under the _Desktop & Dock_ entry in the macOS _System Settings_ has been set to disabled. This error does not occur for the Intel/x86 release of RetroArch or with any other standalone emulators (including those built specifically for the ARM architecture). The first time you launch a RetroArch-emulated game from within ES-DE the operating system will present you with a security option with the following description: @@ -272,7 +274,7 @@ The first time you launch a RetroArch-emulated game from within ES-DE the operat If you don't allow this, you will not be able to place system BIOS ROMs in the RetroArch default system directory `~/Documents/RetroArch/system` even if you've already given RetroArch access to this folder. This is so because RetroArch runs as a subprocess to ES-DE and therefore inherits the security settings from the parent application. Attempting to launch a game without enabling the access will simply display an error message in the emulator that the BIOS files are missing. This of course only applies to emulators that require BIOS ROMs, all other games should work fine regardless of this security setting. -If you accidentally refused ES-DE the folder access, you can fix this by opening _System Preferences_, selecting _Security & Privacy_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. +If you accidentally refused ES-DE the folder access, you can fix this by opening _System Settings_, selecting _Privacy & Security_ and within the GUI choose _Files and Folders_. The option you need to enable is _Documents Folder_ under _EmulationStation Desktop Edition_. By default files and directories starting with a dot are hidden on macOS, so to show the .emulationstation directory in your home directory you need to enable hidden files in Finder. You do this using the keyboard combination Shift + Command + . (dot).