From 41293a4d93eacf6e3df8ccccb6d207e121e8231b Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sun, 9 Jul 2023 22:41:19 +0200 Subject: [PATCH] Documentation update --- FAQ.md | 2 +- INSTALL-DEV.md | 18 +++--- USERGUIDE-DEV.md | 69 +++++++++++------------ es-app/assets/Windows_Portable_README.txt | 2 +- 4 files changed, 43 insertions(+), 48 deletions(-) diff --git a/FAQ.md b/FAQ.md index f9d80ea77..0a22c8341 100644 --- a/FAQ.md +++ b/FAQ.md @@ -18,7 +18,7 @@ ES-DE runs on Windows, macOS and BSD Unix as well as on multiple Linux distribut ## What is the relationship between ES-DE and EmuDeck? -[EmuDeck](http://www.emudeck.com) is an installer that installs ES-DE and a number of emulators. It's a completely separate project and it's not required in order to use ES-DE. +[EmuDeck](http://www.emudeck.com) is an installer that installs ES-DE and a number of emulators. There is no relationship between the two projects apart from this, and it's generally not recommended to use EmuDeck as this will lead to a non-standard installation. There are few tangible benefits to using EmuDeck over a manual installation apart from some convenience for the initial setup. Instead it's recommended to setup your emulators manually which will allow you to configure everything exactly to your liking. That is also a fun and interesting experience. ## What is the relationship between ES-DE and RetroDECK? diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index dd361d52c..d2b70b524 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -351,19 +351,19 @@ CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package CPackDeb: - Generating dependency list -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.2.0-x64.deb generated. +CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.1.0-x64.deb generated. ``` You may want to check that the dependencies look fine, as they're (mostly) automatically generated by CMake: ``` -dpkg -I ./emulationstation-de-1.2.0-x64.deb +dpkg -I ./emulationstation-de-2.1.0-x64.deb ``` The package can now be installed using a package manager, for example apt: ``` -sudo apt install ./emulationstation-de-1.2.0-x64.deb +sudo apt install ./emulationstation-de-2.1.0-x64.deb ``` To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: @@ -382,7 +382,7 @@ CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/emulationstation-de.spec -CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.2.0-x64.rpm generated. +CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-2.1.0-x64.rpm generated. ``` On Fedora, you need to install rpmbuild before this command can be run: @@ -392,17 +392,17 @@ sudo dnf install rpm-build After the package generation you can check that the metadata looks fine using the `rpm` command: ``` -rpm -qi ./emulationstation-de-1.2.0-x64.rpm +rpm -qi ./emulationstation-de-2.1.0-x64.rpm ``` To see the automatically generated dependencies, run this: ``` -rpm -q --requires ./emulationstation-de-1.2.0-x64.rpm +rpm -q --requires ./emulationstation-de-2.1.0-x64.rpm ``` And of course, you can also install the package: ``` -sudo dnf install ./emulationstation-de-1.2.0-x64.rpm +sudo dnf install ./emulationstation-de-2.1.0-x64.rpm ``` **Creating an AppImage** @@ -639,7 +639,7 @@ CPack: Install projects CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package -CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.2.0-x64.dmg generated. +CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-2.1.0-x64.dmg generated. ``` ## Building on Windows @@ -835,7 +835,7 @@ CPack: Install projects CPack: - Run preinstall target for: emulationstation-de CPack: - Install project: emulationstation-de [] CPack: Create package -CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.2.0-x64.exe generated. +CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-2.1.0-x64.exe generated. ``` The default installation directory suggested by the installer is `C:\Program Files\EmulationStation-DE` but this can of course be changed by the user. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index a76ddb05f..5b49348bd 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -39,23 +39,7 @@ The installation procedure is just covered briefly here and may differ a bit for The .deb package is intended for Ubuntu but may work on other Debian-based distributions like Linux Mint and vanilla Debian. Your distribution should include a graphical package installer, but if you prefer to use the command line, run the following which will install ES-DE and resolve any dependencies: ``` -sudo apt install ./emulationstation-de-2.0.0-x64.deb -``` - -**Installing the Linux .rpm package** - -On Fedora the RPM Fusion repository is a prerequisite for the installation, it can be installed like this: - -``` -sudo dnf install \ -https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \ -https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm -``` - -Then you can use the graphical package installer or run this command, either method should automatically resolve the dependencies: - -``` -sudo dnf install ./emulationstation-de-2.0.0-x64.rpm +sudo apt install ./emulationstation-de-2.1.0-x64.deb ``` **Running the Linux AppImage** @@ -65,6 +49,11 @@ The AppImage release should be usable on most modern x86 64-bit Linux distributi chmod +x EmulationStation-DE-x64.AppImage ``` +Or if you're using the Steam Deck AppImage: +``` +chmod +x EmulationStation-DE-x64_SteamDeck.AppImage +``` + To run AppImage files you need libfuse2 installed, but some newer distributions like Ubuntu 22.04 LTS no longer ship with this library preinstalled. You can however easily install it like this: ``` sudo apt install libfuse2 @@ -88,30 +77,31 @@ There's an application log file created in the ES-DE home directory named `es_lo After ES-DE finds at least one game file, it will populate that game system and the application will start. If there are no game files, a dialog will be shown explaining that you need to install your game files into your ROMs directory. You will also be given a choice to change that ROMs directory path if you don't want to use the default one. As well you have the option to generate the complete game systems directory structure based on information in es_systems.xml. -When generating the directory structure, a file named systeminfo.txt will be created in each game system folder which will provide you with some information about the system. Here's an example for the _gc_ system as seen on Unix: +When generating the directory structure, a file named systeminfo.txt will be created in each game system folder which will provide you with some information about the system. Here's an example for the _dos_ system as seen on Unix: ``` System name: -gc +dos Full system name: -Nintendo GameCube +DOS (PC) Supported file extensions: -.ciso .CISO .dff .DFF .dol .DOL .elf .ELF .gcm .GCM .gcz .GCZ .iso .ISO .json .JSON .m3u .M3U .rvz .RVZ .tgc .TGC .wad .WAD .wbfs .WBFS .wia .WIA .7z .7Z .zip .ZIP +.bat .BAT .com .COM .conf .CONF .cue .CUE .dosz .DOSZ .exe .EXE .iso .ISO .7z .7Z .zip .ZIP Launch command: -%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dolphin_libretro.so %ROM% +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_pure_libretro.so %ROM% Alternative launch commands: -%EMULATOR_DOLPHIN% -b -e %ROM% -%EMULATOR_PRIMEHACK% -b -e %ROM% -%EMULATOR_TRIFORCE% -b -e %ROM% +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_core_libretro.so %ROM% +%EMULATOR_RETROARCH% -L %CORE_RETROARCH%/dosbox_svn_libretro.so %ROM% +%STARTDIR%=%GAMEDIR% %EMULATOR_DOSBOX-X% %ROM% +%STARTDIR%=%GAMEDIR% %EMULATOR_DOSBOX-STAGING% %ROM% Platform (for scraping): -gc +dos Theme folder: -gc +dos ``` This file is not needed to run ES-DE, it's only a convenience to easily see which emulators and file extensions are supported per system. @@ -121,12 +111,15 @@ In addition to this, a file named systems.txt will be created in the root of the For example: ``` -gc: Nintendo GameCube -genesis: Sega Genesis -gx4000: Amstrad GX4000 +dos: DOS (PC) +dragon32: Dragon Data Dragon 32 +dreamcast: Sega Dreamcast +easyrpg: EasyRPG Game Engine +epic: Epic Games Store +famicom: Nintendo Family Computer ``` -If a custom es_systems.xml file is present in ~/.emulationstation/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the GameCube system in the example above would be present in the custom systems configuration file, the system would be shown as _gc (custom system)_ instead of simply _gc_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. +If a custom es_systems.xml file is present in ~/.emulationstation/custom_systems/ any entries from this file will have their names trailed by the text _(custom system)_. So if the _dos_ system in the example above would be present in the custom systems configuration file, the system would be shown as _dos (custom system)_ instead of simply _dos_. This is only applicable for the systems.txt and systeminfo.txt files, the trailing text is not applied or used anywhere else in the application. ![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup") _This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._ @@ -295,7 +288,7 @@ As the Steam Deck is essentially a Linux desktop computer with a custom user int Another way to install ES-DE is via [RetroDECK](http://retrodeck.net) which is shipped as a Flatpak and can be easily installed via Discover. As RetroDECK bundles both ES-DE and all its emulators inside the Flatpak you don't need to update any emulators separately or set Flatpak permissions manually. The drawback compared to running ES-DE standalone is that less systems and emulators are supported. Most popular systems should work fine though and more emulators are getting added continuously so the situation will improve over time. Also note that if going for RetroDECK you will have a non-standard ES-DE installation so some parts of this user guide will no longer apply. For documentation specific to RetroDECK, refer to their [wiki](https://github.com/XargonWan/RetroDECK/wiki). -It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific AppImage. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as their installer makes some customizations to paths and other settings. This guide only covers default installations so in case you see something mentioned that doesn't match your setup, make sure to contact the EmuDeck support. +It's also possible to install ES-DE using [EmuDeck](https://www.emudeck.com) which will automatically download the latest Steam Deck-specific AppImage. Just be aware that if using EmuDeck you will have a non-standard ES-DE installation as their installer makes some customizations to paths and other settings. For this and other reasons it's therefore not recommended to use EmuDeck, it's generally better to make a manual installation of ES-DE and your emulators and set everything up exactly to your liking. Unless RetroDECK is used, Flatpak releases of some emulators may need some extra permissions to be able to launch games placed on external devices such as a memory card. This is the case for instance for melonDS and RPCS3. The easiest way to do this is by using [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal). The option you need to enable is generally _All system files_ in the _Filesystem_ section. If using EmuDeck some of these settings will be applied automatically via their installer. @@ -309,6 +302,8 @@ If you are unfamiliar with Unix operating systems, make sure to at least read up ES-DE on the Raspberry Pi requires a desktop environment, or more specifically a window manager and a sound server (like PulseAudio or PipeWire). There are no plans to add support for direct hardware access to the framebuffer or to ALSA. If you want to use your Raspberry Pi as an appliance, take a look at [RetroPie](https://retropie.org.uk), [Recalbox](https://www.recalbox.com) or [Batocera](https://batocera.org) instead. +Also note that there are no prebuilt packages for the Raspberry Pi, so you will need to compile ES-DE yourself. Fortunately this is easy to do and the process is documented [here](INSTALL-DEV.md#building-on-unix). + The Raspberry Pi 4/400 is the minimum recommended version and earlier boards have not been tested. The GPU memory should be set to at least 256 MiB using `raspi-config` and the GL driver must be set to `GL (Fake KMS)` or the performance will be horrible. On Raspberry Pi OS 11 the KMS option is enabled by default. In general, 720p works fine with the RPi 4, and 1080p is tolerable but not really a nice and smooth experience. Due to the relative weakness of the Rasperry Pi GPU, the video scanline rendering options for the screensaver and media viewer have been disabled. These options can be re-enabled via the menu if you don't mind lower video framerates. @@ -483,12 +478,12 @@ Opens and closes the gamelist options menu in the gamelist view. **Left and right shoulder buttons**\ _(Page up / Page down)_ -Provides quick jumping in textlists and menus, jumps 10 games in the gamelists and 6 entries in the menus. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Also used as back and blankspace keys in text edit dialogs. +Provides quick jumping in textlists and menus, jumps 10 games in the gamelists and 6 entries in the menus. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Also used as back and blankspace keys in text edit dialogs and for zooming in and out when viewing PDF game manuals. **Left and right trigger buttons**\ _(Home / End)_ -Jumps to the first or last entries in carousels, grids and textlists as well as in menus and text edit dialogs. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. +Jumps to the first or last entries in carousels, grids and textlists as well as in menus and text edit dialogs. Navigates between gamelists if the _Quick system select_ option has been set to use these buttons and the primary element supports it. Also jumps to the first or last entry/page when using the media viewer. **Left and right thumbstick click**\ _(F2 / F3)_ @@ -646,7 +641,7 @@ The following emulators are supported in AppImage format when using the bundled | gc | Triforce | dolphin-emu-triforce*.AppImage | | macintosh | Basilisk II | BasiliskII*.AppImage | | macintosh | SheepShaver | SheepShaver*.AppImage | -| n3ds | Citra | citra-linux-*.AppImage | +| n3ds | Citra | citra-*.AppImage | | n64 | RMG | RMG*.AppImage | | n64dd | RMG | RMG*.AppImage | | ps2 | PCSX2 | pcsx2*-Qt.AppImage | @@ -866,7 +861,7 @@ Also in this case the directory will be displayed as a regular game file inside ### Folder flattening -**This functionality is experimental and may cause all sorts of issues including corrupting your gamelist.xml files, so make sure to have backups of your data prior to attempting to use this.** +**This functionality is experimental and may cause all sorts of issues like corrupting your gamelist.xml files, so make sure to have backups of your data prior to attempting to use this.** ES-DE works according to the filesystem paradigm used on most operating systems, meaning the file and directory structure of your ROMs directory is reflected inside the application. So if you create a directory on the filesystem and place some games in there, it will be reflected inside ES-DE as a folder that you can enter and launch games from. @@ -2432,7 +2427,7 @@ Controls positioning of the navigation help prompts. The available options are _ **Display media types** -Whether the help prompts should include the media type of the currently viewed entry. +Whether the help prompts should display the media type for the current entry, i.e. _video, box cover, box back cover, title screen, screenshot, fan art_ or _miximage_. **Keep videos running when viewing images** diff --git a/es-app/assets/Windows_Portable_README.txt b/es-app/assets/Windows_Portable_README.txt index 4434a426b..10a1d3606 100644 --- a/es-app/assets/Windows_Portable_README.txt +++ b/es-app/assets/Windows_Portable_README.txt @@ -2,7 +2,7 @@ EmulationStation Desktop Edition (ES-DE) - Portable installation on Windows --------------------------------------------------------------------------- ES-DE release: -2.1.0-alpha +2.1.0 Instructions: