Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-21 21:55:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2022-09-12 19:19:09 +02:00
parent 7aa1b1bf5d
commit ee3d32990d
3 changed files with 54 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
CHANGELOG.md
View file

@ -19,8 +19,12 @@
* Added support for sizing SVG images arbitrarily (overriding the image aspect ratio by stretching and squashing)
* (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
* (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
* (Linux) Added Rosalie's Mupen GUI standalone as an alternative emulator for the n64 system
* Added VICE standalone as an alternative emulator for the c64 (x64sc only) and vic20 systems
* (Windows) Added PrimeHack as an alternative emulator for the gc and wii systems
* (Windows) Added Project64 as an alternative emulator for the n64 system
@ -34,6 +38,7 @@
* Added support for folder links, used for launching game files inside folders without having to enter them
* Added a folder badge, including a folder link overlay in case a link has been configured
* Added a collection badge, shown when editing custom collections to indicate that a game is part of the collection
* Adjusted the splash screen sizing to be more consistent across various screen aspect ratios
* Modernized the OpenGL renderer by replacing the fixed function pipeline with shaders
* Unified the desktop OpenGL and OpenGL ES renderers and upgraded to OpenGL 3.3 (as default) and OpenGL ES 3.0 respectively
* OpenGL: Added an OpenGLVersion setting for choosing between OpenGL 3.3, 4.2 and 4.6 (has to be manually set in es_settings.xml)

32
THEMES-DEV.md
View file

@ -744,11 +744,7 @@ Nesting of variables is supported, so the following could be done:
</variables>
```
## Reference
This section describes each element and their properties in detail and also contains example configuration snippets.
### Property data types
## Property data types
* NORMALIZED_PAIR - two decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5`. Most commonly used for position (x and y coordinates) and size (width and height).
* NORMALIZED_RECT - four decimals, in the range [0..1], delimited by a space. For example, `0.25 0.5 0.10 0.30`. Most commonly used for padding to store top, left, bottom and right coordinates.
@ -759,13 +755,13 @@ This section describes each element and their properties in detail and also cont
* FLOAT - a decimal.
* STRING - a string of text.
### Element types and their properties
## Element types and their properties
Common to almost all elements is a `pos` and `size` property of the NORMALIZED_PAIR type. They are normalized in terms of their "parent" object's size; 99% of the time this is just the size of the screen. In this case, `<pos>0 0</pos>` would correspond to the top left corner, and `<pos>1 1</pos>` the bottom right corner (a positive Y value points further down). You can also use numbers outside of the [0..1] range if you want to place an element partially or completely off-screen.
The order in which you define properties does not matter and you only need to define the ones where you want to override the default value.
#### image
### image
Displays a raster image or a scalable vector graphics (SVG) image.
@ -859,7 +855,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `30`
#### video
### video
Plays a video and provides support for displaying a static image for a defined time period before starting the video player. Although an unlimited number of videos could in theory be defined per view it's recommended to keep it at a single instance as playing videos takes a lot of CPU resources. But if still going for multiple videos, make sure to use the `audio` property to disable audio on all but one video as ES-DE currently has no audio mixing capabilities so the sound would not play correctly. To use videos in the `system` view, you either need to set a static video using the `path` property, or you need to create a `gameselector` element so game videos can be used.
@ -944,7 +940,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `30`
#### animation
### animation
GIF and Lottie (vector graphics) animations. The type of animation is automatically selected based on the file extension with `.gif` for GIF animations and `.json` for Lottie animations. Note that Lottie animations take a lot of memory and CPU resources if scaled up to large sizes so it's adviced to not add too many of them to the same view and to not make them too large. GIF animations on the other hand are not as demanding except if they're really long and/or high-resolution.
@ -1003,7 +999,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `35`
#### badges
### badges
Displays graphical symbols representing a number of metadata fields for the currently selected game. It's strongly recommended to use the same image dimensions for all badges as varying aspect ratios will lead to alignment issues. For the controller images it's recommended to keep to the square canvas size used by the default bundled graphics as otherwise sizing and placement will be inconsistent (unless all controller graphic files are customized of course).
@ -1126,7 +1122,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `35`
#### text
### text
Displays text. This can be literal strings or values based on game metadata or system variables, as described below. For the `gamelist` view it's also possible to place the text inside a scrollable container which is for example useful for longer texts like the game descriptions.
@ -1232,7 +1228,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `40`
#### datetime
### datetime
Displays a date and time as a text string. The format is ISO 8601 (YYYY-MM-DD) by default, but this can be changed using the `format` property. The text _unknown_ will be shown by default if there is no time stamp available. If the property `displayRelative` has been set, the text will be shown as _never_ in case of no time stamp.
@ -1310,7 +1306,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `40`
#### gamelistinfo
### gamelistinfo
Displays the game count (all games as well as favorites), any applied filters, and a folder icon if a folder has been entered. If this text is left aligned or center aligned, the folder icon will be placed to the right of the other information, and if it's right aligned, the folder icon will be placed to the left.
@ -1363,7 +1359,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `45`
#### rating
### rating
Displays a graphical representation of the game rating, from 0 to 5.
@ -1419,7 +1415,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `45`
#### carousel
### carousel
A carousel for navigating and selecting games or systems.
@ -1552,7 +1548,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50`
#### textlist
### textlist
A text list for navigating and selecting games or systems.
@ -1624,7 +1620,7 @@ Properties:
- z-index value for element. Elements will be rendered in order of zIndex value from low to high.
- Default is `50`
#### gameselector
### gameselector
Selects games from the gamelists when navigating the `system` view. This makes it possible to display game media and game metadata directly from this view. It's possible to make separate gameselector configurations per game system, so that for instance a random game could be displayed for one system and the most recently played game could be displayed for another system. It's also possible to define multiple gameselector elements with different selection criterias per game system which makes it possible to for example set a random fan art background image and at the same time display a box cover image of the most recently played game. The gameselector logic can be used for the `image`, `video`, `text`, `datetime` and `rating` elements.
@ -1644,7 +1640,7 @@ Properties:
- Minimum value is `1` and maximum value is `30`
- Default is `1`
#### helpsystem
### helpsystem
The helpsystem is a special element that displays a context-sensitive list of actions the user can take at any time. You should try and keep the position constant throughout every screen. Note that this element does not have a zIndex value, instead it's always rendered on top of all other elements.

41
USERGUIDE-DEV.md
View file

@ -921,6 +921,35 @@ The EMULATOR.INI file is found in the _Model 2 Emulator_ installation directory.
Also note that Model 2 Emulator is a bit broken and on most GPU drivers it will only work correctly if ES-DE keeps running in the background while the game is launched. However, for some GPU drivers the opposite is true and the emulator will only work if ES-DE is suspended. To use the latter setup, switch to the alternative emulator entry _Model 2 Emulator [Suspend ES-DE] (Standalone)_.
#### Nintendo Game and Watch
There are two ways to play these games, either via simulation or via emulation.
**Method 1, simulation:**
Simulation is done via the Handheld Electronic (GW) RetroArch core, in which case games come with the .mgw file extension. You simply place these files in the `gameandwatch` directory and they can be launched and played. The filenames will probably be verbose and include the complete game name, for example `Donkey Kong (Nintendo, Multi Screen).mgw` so both ScreenScraper and TheGamesDB should be able to find the game entries when scraping. Here's an example:
```
~/ROMs/gameandwatch/Donkey Kong (Nintendo, Multi Screen).mgw
```
**Method 2, emulation:**
Proper emulation is done via the MAME standalone emulator. The games need to be in the MAME format and follow the MAME naming conventions, i.e. it will not be possible to run .mgw games with this emulator. The example game _Donkey Kong_ would have the filename `gnw_dkong.zip` and you'll place this file in the `gameandwatch` directory.
However the game is only half of what's needed to properly emulate these games as you'll also need the artwork to see an image of the actual physical device when running the game. The artwork would also come in a .zip file with the same name as the game itself, e.g. `gnw_dkong.zip` and it must be located in the MAME artwork directory so it can be found by MAME.
For the artwork there are two options. There are two MAME alternative emulator entries available, _MAME (Standalone)_ and _MAME Local Artwork (Standalone)_. The former will require the artwork files to be placed in the default MAME artwork directory. This location differs between operating systems and distributions so refer to the MAME documentation on where to find this folder. The _MAME Local Artwork (Standalone)_ emulator entry will however let you place the artwork inside the `gameandwatch` directory tree which can be quite convenient as it's then bundled with the game files. Simply create an `artwork` subdirectory and place the files there. Here's an example of what _Donkey Kong_ would look like when going for the latter option:
```
~/ROMs/gameandwatch/gnw_dkong.zip
~/ROMs/gameandwatch/artwork/gnw_dkong.zip
```
As the artwork files also come with the .zip file extension they will show up inside ES-DE as if they were game files, so it's recommended to hide the entire artwork directory using the _Hidden_ option in the metadata editor.
Be aware that neither ScreenScraper or TheGamesDB currently support these MAME short names natively so you'll need to refine the searches or the scraper services are unlikely to return any results at all (or very inaccurate results at best).
#### Nintendo Switch
The Nintendo Switch emulator Yuzu is distributed as a Snap package, Flatpak package or AppImage on Linux and as a regular installer on Windows. At the moment there is unfortunately no macOS release of this emulator and it's unclear if it can run on BSD Unix.
@ -2955,7 +2984,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| fds | Nintendo Famicom Disk System | Mesen | Nestopia UE,<br>Nestopia UE **(Standalone)** [U],<br>FCEUmm,<br>Mednafen **(Standalone)** [UMW*],<br>ares **(Standalone)** [UMW*] | Yes | Single archive or ROM file in root folder |
| flash | Adobe Flash | Ruffle **(Standalone)** [UMW*] | Lightspark **(Standalone)** [U],<br>ArcadeFlashWeb **(Standalone)** [W*] | No | Single .swf file in root folder |
| fmtowns | Fujitsu FM Towns | Tsugaru **(Standalone)** [UW*] | | Yes | See the specific _Fujitsu FM Towns_ section elsewhere in this guide |
| gameandwatch | Nintendo Game and Watch | GW | | | |
| gameandwatch | Nintendo Game and Watch | Handheld Electronic (GW) | MAME **(Standalone)** [UMW*],<br>MAME Local Artwork **(Standalone)** [UMW*] | No | See the specific _Nintendo Game and Watch_ section elsewhere in this guide |
| gamegear | Sega Game Gear | Genesis Plus GX | Genesis Plus GX Wide,<br>Gearsystem,<br>SMS Plus GX,<br>Mednafen **(Standalone)** [UMW*] | | |
| gb | Nintendo Game Boy | Gambatte | SameBoy,<br>Gearboy,<br>TGB Dual,<br>Mesen-S,<br>bsnes,<br>mGBA,<br>mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** | No | Single archive or ROM file in root folder |
| gba | Nintendo Game Boy Advance | mGBA | mGBA **(Standalone)**,<br>VBA-M,<br>VBA-M **(Standalone)** [UMW*],<br>VBA Next,<br>gpSP | No | Single archive or ROM file in root folder |
@ -2982,16 +3011,16 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
| model3 | Sega Model 3 | Supermodel **(Standalone)** [W*] | | | See the specific _Arcade and Neo Geo_ section elsewhere in this guide |
| moonlight | Moonlight Game Streaming | _Placeholder_ | | | |
| moto | Thomson MO/TO Series | Theodore | | | |
| msx | MSX | blueMSX | fMSX,<br>ares **(Standalone)** [UMW*] | | |
| msx1 | MSX1 | blueMSX | fMSX,<br>ares **(Standalone)** [UMW*] | | |
| msx2 | MSX2 | blueMSX | fMSX,<br>ares **(Standalone)** [UMW*] | | |
| msxturbor | MSX Turbo R | blueMSX | | | |
| msx | MSX | blueMSX | fMSX,<br>openMSX **(Standalone)** [UMW*],<br>openMSX No Machine **(Standalone)** [UMW*],<br>ares **(Standalone)** [UMW*] | Yes | |
| msx1 | MSX1 | blueMSX | fMSX,<br>openMSX **(Standalone)** [UMW*],<br>openMSX No Machine **(Standalone)** [UMW*],<br>ares **(Standalone)** [UMW*] | Yes | |
| msx2 | MSX2 | blueMSX | fMSX,<br>openMSX **(Standalone)** [UMW*],<br>openMSX No Machine **(Standalone)** [UMW*],<br>ares **(Standalone)** [UMW*] | Yes | |
| msxturbor | MSX Turbo R | blueMSX | openMSX **(Standalone)** [UMW*],<br>openMSX No Machine **(Standalone)** [UMW*] | Yes | |
| mugen | M.U.G.E.N Game Engine | M.U.G.E.N **(Standalone)** [W] | | No | See the specific _M.U.G.E.N Game Engine_ section elsewhere in this guide |
| multivision | Othello Multivision | Gearsystem | | | |
| naomi | Sega NAOMI | Flycast | Flycast **(Standalone)** [UMW*] | | |
| naomigd | Sega NAOMI GD-ROM | Flycast | Flycast **(Standalone)** [UMW*] | | |
| n3ds | Nintendo 3DS | Citra [UW],<br>Citra **(Standalone)** [M] | Citra 2018 [UW],<br>Citra **(Standalone)** [UW*] | No | Single ROM file in root folder |
| n64 | Nintendo 64 | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | Mupen64Plus **(Standalone)** [UMW*],<br>ParaLLEl N64 [UW],<br>Project64 **(Standalone)** [W*],<br>ares **(Standalone)** [UMW*],<br>sixtyforce **(Standalone)** [M] | No | Single archive or ROM file in root folder |
| n64 | Nintendo 64 | Mupen64Plus-Next [UW],<br>ParaLLEl N64 [M] | Mupen64Plus **(Standalone)** [UMW*],<br>ParaLLEl N64 [UW],<br>simple64 **(Standalone)** [UW*],<br>Rosalie's Mupen GUI **(Standalone)**,<br>Project64 **(Standalone)** [W*],<br>ares **(Standalone)** [UMW*],<br>sixtyforce **(Standalone)** [M] | No | Single archive or ROM file in root folder |
| n64dd | Nintendo 64DD | ParaLLEl N64 | Mupen64Plus-Next [UW] | Yes | See the specific _Nintendo 64DD_ section elsewhere in this guide |
| nds | Nintendo DS | DeSmuME | DeSmuME 2015,<br>DeSmuME **(Standalone)** [U],<br>melonDS,<br>melonDS **(Standalone)** [UMW*] | No | |
| neogeo | SNK Neo Geo | FinalBurn Neo | | Yes | See the specific _Arcade and Neo Geo_ section elsewhere in this guide |