From 12006d8d8873a6e871777493984fa9c331f0c8f0 Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Wed, 1 Jan 2025 14:12:46 -0500 Subject: [PATCH 1/9] Revised thumbnails user guide - Clarified phrasing on custom thumbnails and naming, e.g. matching thumbnail to displayed game name rather than "according to RA naming convention" etc per se. - Combined some redundancy wording and examples of thumbnail subfolder setup. - Minor bold/format changes to Thumbnail Update methods --- docs/guides/roms-playlists-thumbnails.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 1a14625d9b..1316651ae5 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -64,9 +64,10 @@ All menu drivers can display fullscreen thumbnails when pressing Start, and Y bu Thumbnails can be retrieved multiple ways: -* Playlist thumbnail downloader (recommended): under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com. -* Individual thumbnail downloader: there is a Download Thumbnails option for each entry in playlists. For RetroArch version 1.17.0 or later, you may hit download up to 3 times to try the flexible matches. -* On-demand thumbnail downloader: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions 1.17.0 or later, you may try flicking back and forth between entries up to 3 times to try the flexible matches. By default, on-demand thumbnail downloader does not try to fetch thumbnails based on ROM name, enable Settings / Playlist / Use filenames for thumbnail matching options for that. +* **Playlist thumbnail downloader (recommended)**: under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com and retrieve the available thumbnail. + - WARNING: the Playlist Thumbnails Updater process will over-write any custom thumbnails set by the user (see below) for any game name that matches a thumbnail on the server. +* **Individual thumbnail downloader**: there is a Download Thumbnails option for each entry in playlists. For RetroArch version 1.17.0 or later, you may hit download up to 3 times to try the flexible matches. +* **On-demand thumbnail downloader**: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions 1.17.0 or later, you may try flicking back and forth between entries up to 3 times to try the flexible matches. By default, on-demand thumbnail downloader does not try to fetch thumbnails based on ROM name, enable Settings / Playlist / Use filenames for thumbnail matching options for that. Thumbnail packs are no longer available, use one of the above methods, or see Custom thumbnails section below. @@ -173,16 +174,18 @@ Since playlists are managed in text-only JSON format, there are a few third-part ## Custom thumbnails -Users who wish to use their own thumbnails can do so by naming PNG image files according to the RetroArch naming convention. In RetroArch versions later than 1.19.1, other image formats can be also enabled (jpg, bmp, tga). +Users can set custom thumbnails (i.e. a thumbnail different from the one automatically provided by RetroArch) by naming PNG image files with the same base filename as a game title displayed in a playlist, and placing the PNG in the correct location for the relevant playlist. In RetroArch versions later than 1.19.1, other image formats can be also enabled (jpg, bmp, tga). ### Thumbnail paths and filenames -Thumbnails should be stored in subfolders within the configured RetroArch `thumbnails` directory within a subfolder named exactly the same as the playlist, except without `.lpl` at the end. **Example: If your playlist is named `Atari - 2600.lpl`, then your Atari 2600 root thumbnail folder should be called `thumbnails/Atari - 2600/`.** +Thumbnails must be stored in subfolders within the configured RetroArch `thumbnails` directory within a subfolder named exactly the same as the playlist, except without `.lpl` at the end. The thumbnail folder named after the playlist must then contain subfolders as follows: -Within this root thumbnail folder called `Atari - 2600`, you should then create subfolders named `Named_Boxarts`, `Named_Snaps`, or `Named_Titles` for boxart/cover art, in-game snapshots, and title screens, respectively. +- `Named_Boxarts`for boxart/cover art +- `Named_Snaps` for in-game snapshots +- `Named_Titles` for in-game introductory title screens -The thumbnail filename should exactly match the game's title as listed in the playlist with an important exception. **The following characters in playlist titles must be replaced with `_` in the corresponding thumbnail filename:** `` &*/:`<>?\| `` +**Invalid characters.** The thumbnail filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. -**Example: If your content is named `Q*bert's Qubes (USA)` in the playlist, then its thumbnails should be named `Q_bert's Qubes (USA).png` and stored at these paths:** +**Example of correct thumbnail file setup**: If your content is named `Q*bert's Qubes (USA)` in the playlist, then its thumbnails should be named `Q_bert's Qubes (USA).png` and stored at these paths: ``` thumbnails/ From 78a0696e4dd5bf72cf0b793c7061a2c86f93f903 Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Wed, 1 Jan 2025 17:03:12 -0500 Subject: [PATCH 2/9] Thumbnail Contribution How To, edits to roms-playlists-thumbnails.md - New guide section added for how users can contribute thumbnails to the github repository. (We probably want to split "Thumbnails" into separate page from Playlists at this point.) The guide has been tested and iterated and proven outside of this docs/github update (on reddit) and has created new thumbnail contributors. - Custom Thumbnail section: more revisions and re-phrasings and hierarchy and elegance (I hope) for readers - Named Logos section, revised wording so that the meaning is clearer, and clarified format references/alignment to thumbnail guide --- docs/guides/roms-playlists-thumbnails.md | 67 ++++++++++++++++++++---- 1 file changed, 56 insertions(+), 11 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 1316651ae5..5d350b2556 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -62,7 +62,7 @@ RetroArch can display three types of thumbnails (small still pictures) for games Most menu drivers support displaying two pictures when browsing the playlist. Displayed thumbnail types can be configured system-wide and also per playlist. All menu drivers can display fullscreen thumbnails when pressing Start, and Y button (left) can be used to cycle between available pictures. -Thumbnails can be retrieved multiple ways: +Thumbnails can be retrieved in multiple ways: * **Playlist thumbnail downloader (recommended)**: under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com and retrieve the available thumbnail. - WARNING: the Playlist Thumbnails Updater process will over-write any custom thumbnails set by the user (see below) for any game name that matches a thumbnail on the server. @@ -174,16 +174,23 @@ Since playlists are managed in text-only JSON format, there are a few third-part ## Custom thumbnails -Users can set custom thumbnails (i.e. a thumbnail different from the one automatically provided by RetroArch) by naming PNG image files with the same base filename as a game title displayed in a playlist, and placing the PNG in the correct location for the relevant playlist. In RetroArch versions later than 1.19.1, other image formats can be also enabled (jpg, bmp, tga). +Users can set a custom thumbnail (i.e. a thumbnail that is different from the one automatically provided by RetroArch) by following the process below. -### Thumbnail paths and filenames -Thumbnails must be stored in subfolders within the configured RetroArch `thumbnails` directory within a subfolder named exactly the same as the playlist, except without `.lpl` at the end. The thumbnail folder named after the playlist must then contain subfolders as follows: +- Name a PNG image file with a base filename that matches a game title displayed in a playlist. E.g. if the game name displayed in RetroArch in the playlist is `Game Name`, the intended image file must be named `Game Name.png` +- Place the PNG in the correct folder for the relevant playlist (see below). -- `Named_Boxarts`for boxart/cover art -- `Named_Snaps` for in-game snapshots -- `Named_Titles` for in-game introductory title screens +__Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). -**Invalid characters.** The thumbnail filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. +__Avoid invalid characters.__ The thumbnail filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. + +### Thumbnail folder paths and filenames +Thumbnail image files must be stored in subfolders within the configured RetroArch `thumbnails` directory as in the example below: + +- `thumbnails` directory within Retroarch folder (or in different location configured by user via Settings > Directory > Thumbnails) + - `Playlist Name` folder with the exact same name as the playlist, except without `.lpl` at the end. For example, `Atari - 2600` + - `Named_Boxarts` subfolder for boxart/cover art + - `Named_Snaps` subfolder for in-game snapshots + - `Named_Titles` subfolder for in-game introductory title screens **Example of correct thumbnail file setup**: If your content is named `Q*bert's Qubes (USA)` in the playlist, then its thumbnails should be named `Q_bert's Qubes (USA).png` and stored at these paths: @@ -201,8 +208,46 @@ For RetroArch versions 1.17.0 or later, flexible naming is applied, up to 3 opti - ROM file name with .png extension: `Q-Bert's Qubes (1983)(Parker Bros)[b].png` - Database entry / playlist label with .png extension, as explained above: `Q_Bert's Qubes (USA).png` - Short name: same as previous, but only up to first round bracket: `Q_Bert's Qubes.png` - -### Named logos -In RetroArch versions later than 1.19.1, there is an option for the XMB menu driver to display custom images in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). For this to work, create a folder called `Named_Logos` in the same structure as above, and put the logo images there using the same file name convention as above. + +## Contributing Thumbnails: How To +Thumbnails are an area where users who are not programmers can contribute to RetroArch and in a way that helps all users. If you are interested in addng a thumbnail that is missing, correcting a thumbnail that is inaccurate, or replacng an existing thumbnail with a more representative image, follow the steps below. + +### Overview +1. Make an account on github.com +2. "Fork" (copy) a [Libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) to your own working area in github +3. Make your image changes/uploads to your copy of the project (aka your fork), while following [libretro guidelines](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) +4. Request that the official project takes your proposed changes, aka create a Pull Request + +### Detailed Steps + +- __Fork the repository.__ Click the fork button in github.com when viewing the github thumbnail project directory that you want to contribute to. You must fork it at the level of specific console. The Fork button won't appear if you're viewing a lower level folder in the respository like "box art" or "snap.” For example, if you are doing GBA thumbnail work you should fork +[Nintendo_-_Game_Boy_Advance](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy_Advance/). + - **Why "Fork" your own**? If you try to directly edit an image in github libretro thumbnails, if you dig down to a certain thumbnail and click the pencil icon to edit, it's locked unless you are a member of the official project. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. + - _Warning_: You must visit and fork the _current_ gitHub project for the libretro thumbnail repository: for example [this one for SNES](https://github.com/libretro-thumbnails/Nintendo_-_Super_Nintendo_Entertainment_System), not to be confused with the similar-looking [archived version](https://github.com/libretro/libretro-thumbnails) which is inactive. +- __Adding / Uploading your new image file.__ When viewing a specific thumbnail type folder (e.g. Named_boxarts, Named_titles, Named_snaps) within *your fork* of the thumbnails repository, click the pulldown button (near top right) that says **Add file** to see 2 options: + - +Create new File + - Upload File. +- __Upload__. Select your new chosen image file. In this stage you are tentatively uploading to your fork/branch of the project. +- __Follow all guidelines for a proper contribution.__ + - Your choice of image file should meet the libretro thumbnail [ReadMe rules](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. 512px or smaller. + - Name your contribution image file correctly. If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. If uploading a thumbnail that has no prior existing one, research the naming conventions of libretro and how the game is named in databases. + - Use the correct path. Choose the correct console system folder and thumbnail type folder in the project. + - For snaps (in-game screenshots), choose a good clear artful image that shows the art, spirit, or action of the game. For good examples of well-chosen in-game screenshots, see the back-of-box marketing images for officially published games. +- __Commit.__ The "Commit" button will save your change to your copy of the repository. You should generally commit to your own _master_. +- __Pull Request (PR)__. Look for the button or option for a Pull Request when you Commit, though you may wait until you have finalized multiple changes (commits) and then include them all in a single PR. A Pull Request means sending a request to the official controllers of the project to take your contribution into the official project. Official members will review your proposed changes and decide whether to accept it. You will eventually see a confirmation that it was approved or a discussion message if changes are needed. It may take time before someone is able to review the request, so please be patient. +- __Verify that your Pull Request is active and correct.__ _Example_: if you made a Pull Request to contribute a Gameboy thumbnail you’d [see the request publicly listed at the official repository](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy/pulls). + - _Warning_: It is possible to accidentally send a Pull Request to yourself if you committed your changes to your sub-branch instead of your own "_master_". Your “master” is not the official project *master*. And your sub-branch is not the same as your master. You can hover on any abbreviated branch path label in GitHub to see a pop-up of the full path label. If needed, approve your PR to yourself to merge your sub-branch changes to your master, then do a Pull Request from your master to the official Libretro master project. + +### About "Syncing" +Thumbnail contribution work involves changing your copy of the project while other people may be changing the official repository _after_ you created your fork. Github provides options to keep both your copy ("downstream") and the official repository ("upstream") up-to-date with ongoing changes. + +- __Contribute__ button. If you make multiple changes within your fork, you can use Contribute button > Open Pull Request to send all your changes as one PR. +- __Sync__ button. Use the Sync button to update your fork with other people’s changes that have happened upstream. + +### The Thumbnail Server +RetroArch retrieves thumbnails from [a server](https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before you and other users will see your contribution in RetroArch playlists. + +## Custom logos/icons for playlist items +RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file/subfolder format follows the same pattern as thumbnails (described above): create a folder called `Named_Logos` alongside the `Named_Boxarts` (etc) thumbnail subfolder, and put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. Logo support is only possible with XMB menu driver, and the online thumbnail repositories do not contain logo collections. From 47c13c9ea861f79602227339f93fd355ba7a1bd6 Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Wed, 1 Jan 2025 19:58:41 -0500 Subject: [PATCH 3/9] WIP updates to Thumbnail Contrib Guide WIP updates to Thumbnail Contribution guide and also phrasing about custom thumbnails and custom icon/logos. --- docs/guides/roms-playlists-thumbnails.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 5d350b2556..a930aa2385 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -176,13 +176,18 @@ Since playlists are managed in text-only JSON format, there are a few third-part ## Custom thumbnails Users can set a custom thumbnail (i.e. a thumbnail that is different from the one automatically provided by RetroArch) by following the process below. -- Name a PNG image file with a base filename that matches a game title displayed in a playlist. E.g. if the game name displayed in RetroArch in the playlist is `Game Name`, the intended image file must be named `Game Name.png` +- Name a PNG image file with a base filename that matches a game title displayed in a playlist. E.g. if the game name displayed in RetroArch in the playlist is `Game Name`, the intended image file must be named `Game Name.png` _(See below for additional flexible name matching options.)_ - Place the PNG in the correct folder for the relevant playlist (see below). __Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). __Avoid invalid characters.__ The thumbnail filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. +**Flexible name matching.** RetroArch versions 1.17.0 or later will automatically attempt up to 3 different match formats for each playlist entry, in the following order: +- ROM file name with .png extension: `Q-Bert's Qubes (1983)(Parker Bros)[b].png` +- Database entry / playlist label with .png extension, as explained above: `Q_Bert's Qubes (USA).png` +- Short name: same as previous, but only up to first round bracket: `Q_Bert's Qubes.png` + ### Thumbnail folder paths and filenames Thumbnail image files must be stored in subfolders within the configured RetroArch `thumbnails` directory as in the example below: @@ -204,10 +209,6 @@ Thumbnail image files must be stored in subfolders within the configured RetroAr Named_Titles/ Q_bert's Qubes (USA).png ``` -For RetroArch versions 1.17.0 or later, flexible naming is applied, up to 3 options are tried for each playlist entry, in the following order: -- ROM file name with .png extension: `Q-Bert's Qubes (1983)(Parker Bros)[b].png` -- Database entry / playlist label with .png extension, as explained above: `Q_Bert's Qubes (USA).png` -- Short name: same as previous, but only up to first round bracket: `Q_Bert's Qubes.png` ## Contributing Thumbnails: How To Thumbnails are an area where users who are not programmers can contribute to RetroArch and in a way that helps all users. If you are interested in addng a thumbnail that is missing, correcting a thumbnail that is inaccurate, or replacng an existing thumbnail with a more representative image, follow the steps below. @@ -238,7 +239,7 @@ Thumbnails are an area where users who are not programmers can contribute to Ret - __Verify that your Pull Request is active and correct.__ _Example_: if you made a Pull Request to contribute a Gameboy thumbnail you’d [see the request publicly listed at the official repository](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy/pulls). - _Warning_: It is possible to accidentally send a Pull Request to yourself if you committed your changes to your sub-branch instead of your own "_master_". Your “master” is not the official project *master*. And your sub-branch is not the same as your master. You can hover on any abbreviated branch path label in GitHub to see a pop-up of the full path label. If needed, approve your PR to yourself to merge your sub-branch changes to your master, then do a Pull Request from your master to the official Libretro master project. -### About "Syncing" +__About "Syncing"__ #comment Thumbnail contribution work involves changing your copy of the project while other people may be changing the official repository _after_ you created your fork. Github provides options to keep both your copy ("downstream") and the official repository ("upstream") up-to-date with ongoing changes. - __Contribute__ button. If you make multiple changes within your fork, you can use Contribute button > Open Pull Request to send all your changes as one PR. @@ -248,6 +249,6 @@ Thumbnail contribution work involves changing your copy of the project while oth RetroArch retrieves thumbnails from [a server](https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before you and other users will see your contribution in RetroArch playlists. ## Custom logos/icons for playlist items -RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file/subfolder format follows the same pattern as thumbnails (described above): create a folder called `Named_Logos` alongside the `Named_Boxarts` (etc) thumbnail subfolder, and put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. +RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file/subfolder format follows the same pattern as [custom thumbnails](custom-thumbnails): create a folder called `Named_Logos` alongside the `Named_Boxarts` (etc) thumbnail subfolder, and put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. Logo support is only possible with XMB menu driver, and the online thumbnail repositories do not contain logo collections. From b9661e011e86ea803be19b9b6edee3590a7fdb2f Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Wed, 1 Jan 2025 19:59:25 -0500 Subject: [PATCH 4/9] Update roms-playlists-thumbnails.md Anchor link testing --- docs/guides/roms-playlists-thumbnails.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index a930aa2385..5a9d506604 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -249,6 +249,6 @@ Thumbnail contribution work involves changing your copy of the project while oth RetroArch retrieves thumbnails from [a server](https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before you and other users will see your contribution in RetroArch playlists. ## Custom logos/icons for playlist items -RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file/subfolder format follows the same pattern as [custom thumbnails](custom-thumbnails): create a folder called `Named_Logos` alongside the `Named_Boxarts` (etc) thumbnail subfolder, and put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. +RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file/subfolder format follows the same pattern as [custom thumbnails](#custom-thumbnails): create a folder called `Named_Logos` alongside the `Named_Boxarts` (etc) thumbnail subfolder, and put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. Logo support is only possible with XMB menu driver, and the online thumbnail repositories do not contain logo collections. From 5f5c5b1f8c0ca38e8e9f8c1b97e0fe8c79fc03ac Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Wed, 1 Jan 2025 21:22:04 -0500 Subject: [PATCH 5/9] WIP revisions to Custom Thumbnails & Contrib guide WIP revisions to Custom Thumbnails & Contrib guide --- docs/guides/roms-playlists-thumbnails.md | 52 ++++++++++++++++-------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 5a9d506604..d4a73b549c 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -69,7 +69,7 @@ Thumbnails can be retrieved in multiple ways: * **Individual thumbnail downloader**: there is a Download Thumbnails option for each entry in playlists. For RetroArch version 1.17.0 or later, you may hit download up to 3 times to try the flexible matches. * **On-demand thumbnail downloader**: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions 1.17.0 or later, you may try flicking back and forth between entries up to 3 times to try the flexible matches. By default, on-demand thumbnail downloader does not try to fetch thumbnails based on ROM name, enable Settings / Playlist / Use filenames for thumbnail matching options for that. -Thumbnail packs are no longer available, use one of the above methods, or see Custom thumbnails section below. +Thumbnail packs are no longer available, use one of the above methods, or see [Custom Thumbnails](#custom-thumbnails) section below. ## Playlist File Format Details @@ -176,20 +176,24 @@ Since playlists are managed in text-only JSON format, there are a few third-part ## Custom thumbnails Users can set a custom thumbnail (i.e. a thumbnail that is different from the one automatically provided by RetroArch) by following the process below. -- Name a PNG image file with a base filename that matches a game title displayed in a playlist. E.g. if the game name displayed in RetroArch in the playlist is `Game Name`, the intended image file must be named `Game Name.png` _(See below for additional flexible name matching options.)_ -- Place the PNG in the correct folder for the relevant playlist (see below). +!!! Terminology Note: "Game Name" + The term _Game Name_ refers to the name displayed within RetroArch and within a playlist, _not_ to the filename of the underlying file on the computer or device. _Game Name_ in this document is synonymous with playlist item label, playlist entry, or content name. Game names are often assigned automatically after a file import scan and a database lookup, though the user can manually game names by choosing a game in a playlist and using "Rename" in the menu. + +- Name a PNG image file with a base filename that matches a game title displayed in a playlist. _Example_: if the game name is `Q-Bert's Qubes`, the intended image file must be named `Q-Bert's Qubes.png` _(See below for additional flexible name matching options.)_ +- Place the PNG in the [correct folder](#thumbnail-folder-paths) for the relevant playlist. __Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). -__Avoid invalid characters.__ The thumbnail filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. +__Replace invalid characters.__ The thumbnail's base filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. + +**Flexible name matching.** RetroArch versions 1.17.0 or later will automatically attempt up to 3 different match techniques to associate a playlist item with a [properly located](#thumbnail-folder-paths) thumbnail image file, in the following order: -**Flexible name matching.** RetroArch versions 1.17.0 or later will automatically attempt up to 3 different match formats for each playlist entry, in the following order: -- ROM file name with .png extension: `Q-Bert's Qubes (1983)(Parker Bros)[b].png` -- Database entry / playlist label with .png extension, as explained above: `Q_Bert's Qubes (USA).png` -- Short name: same as previous, but only up to first round bracket: `Q_Bert's Qubes.png` +1. __ROM file name <-> .png file name match__. A ROM file `Q-Bert's Qubes (USA) (1983).a26` would receive the thumbnail `Q-Bert's Qubes (USA) (1983).png` if it exists, regardless of how the game name appears in the RetroArch interface. +2. __Game name <-> .png file name match__. `Q*Bert's Qubes (USA)` in a playlist would receive the thumbnail `Q_Bert's Qubes (USA).png` if it exists. `*` is an invalid character and must be replaced with `_` in the image filename. +3. __Short game name <-> .png file name match__. Same as method 2, but only up to first round bracket: `Q-Bert's Qubes (USA) (1983) (Parker Brothers) [h]` in a playlist would receive `Q_Bert's Qubes.png` thumbnail if it exists. -### Thumbnail folder paths and filenames -Thumbnail image files must be stored in subfolders within the configured RetroArch `thumbnails` directory as in the example below: +### Thumbnail folder paths +Thumbnail image files must be stored in subfolders according to this structure: - `thumbnails` directory within Retroarch folder (or in different location configured by user via Settings > Directory > Thumbnails) - `Playlist Name` folder with the exact same name as the playlist, except without `.lpl` at the end. For example, `Atari - 2600` @@ -211,24 +215,33 @@ Thumbnail image files must be stored in subfolders within the configured RetroAr ``` ## Contributing Thumbnails: How To -Thumbnails are an area where users who are not programmers can contribute to RetroArch and in a way that helps all users. If you are interested in addng a thumbnail that is missing, correcting a thumbnail that is inaccurate, or replacng an existing thumbnail with a more representative image, follow the steps below. +Thumbnails are an area where users who are not experienced in programming can contribute to RetroArch and in a way that helps all users. If you are interested in: + +- adding a thumbnail that you see is missing +- correcting a thumbnail that is inaccurate +- replacing an existing thumbnail with a more representative or more aesthetic image + +follow the steps below. ### Overview 1. Make an account on github.com 2. "Fork" (copy) a [Libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) to your own working area in github -3. Make your image changes/uploads to your copy of the project (aka your fork), while following [libretro guidelines](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) -4. Request that the official project takes your proposed changes, aka create a Pull Request +3. Make your image file changes to your copy of the project (aka your fork), while following [libretro guidelines](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) +4. Create a "Pull Request" to request that the official project takes your proposed changes ### Detailed Steps -- __Fork the repository.__ Click the fork button in github.com when viewing the github thumbnail project directory that you want to contribute to. You must fork it at the level of specific console. The Fork button won't appear if you're viewing a lower level folder in the respository like "box art" or "snap.” For example, if you are doing GBA thumbnail work you should fork +- __Fork the repository.__ Visit the github.com [libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) directory that you want to contribute to and click the fork button. You must fork it at the level of specific console. The Fork button won't appear if you're viewing a lower level folder in the respository like "boxart" or "snaps.” + - _Example_. If you are doing GBA thumbnail work you should fork [Nintendo_-_Game_Boy_Advance](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy_Advance/). - - **Why "Fork" your own**? If you try to directly edit an image in github libretro thumbnails, if you dig down to a certain thumbnail and click the pencil icon to edit, it's locked unless you are a member of the official project. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. + - **Why "Fork" your own**? If you try to directly edit an image file in github libretro thumbnails by digging down to a certain thumbnail and clicking the pencil icon to edit, it's locked unless you are a member of the official project. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. - _Warning_: You must visit and fork the _current_ gitHub project for the libretro thumbnail repository: for example [this one for SNES](https://github.com/libretro-thumbnails/Nintendo_-_Super_Nintendo_Entertainment_System), not to be confused with the similar-looking [archived version](https://github.com/libretro/libretro-thumbnails) which is inactive. -- __Adding / Uploading your new image file.__ When viewing a specific thumbnail type folder (e.g. Named_boxarts, Named_titles, Named_snaps) within *your fork* of the thumbnails repository, click the pulldown button (near top right) that says **Add file** to see 2 options: + - Correct: https://github.com/libretro-thumbnails/ + - Incorrect: https://github.com/libretro/libretro-thumbnails +- __Add / Upload your new image file.__ When viewing a specific thumbnail type folder (e.g. Named_boxarts, Named_titles, Named_snaps) within *your fork* of the thumbnails repository, click the pulldown button (near top right) that says **Add file** to see 2 options: - +Create new File - Upload File. -- __Upload__. Select your new chosen image file. In this stage you are tentatively uploading to your fork/branch of the project. +- __Choose "Upload File"__. Select your new chosen image file. In this stage you are uploading to your fork/branch of the project. - __Follow all guidelines for a proper contribution.__ - Your choice of image file should meet the libretro thumbnail [ReadMe rules](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. 512px or smaller. - Name your contribution image file correctly. If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. If uploading a thumbnail that has no prior existing one, research the naming conventions of libretro and how the game is named in databases. @@ -249,6 +262,9 @@ Thumbnail contribution work involves changing your copy of the project while oth RetroArch retrieves thumbnails from [a server](https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before you and other users will see your contribution in RetroArch playlists. ## Custom logos/icons for playlist items -RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file/subfolder format follows the same pattern as [custom thumbnails](#custom-thumbnails): create a folder called `Named_Logos` alongside the `Named_Boxarts` (etc) thumbnail subfolder, and put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. +RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file and subfolder format follows the same pattern as [custom thumbnails](#custom-thumbnails). + +- Create a folder called `Named_Logos` alongside the `Named_Boxarts` thumbnail subfolder for the intended playlist +- Put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. Logo support is only possible with XMB menu driver, and the online thumbnail repositories do not contain logo collections. From 9d23e7f80a67fc9fbefdc8e5b33a9626098ae73c Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Wed, 1 Jan 2025 22:31:38 -0500 Subject: [PATCH 6/9] WIP edits to new Contrib Guide and more edits to Custom Thumbnails etc phrasing, bullets, etc. --- docs/guides/roms-playlists-thumbnails.md | 54 ++++++++++++------------ 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index d4a73b549c..1f348e7a03 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -65,7 +65,7 @@ All menu drivers can display fullscreen thumbnails when pressing Start, and Y bu Thumbnails can be retrieved in multiple ways: * **Playlist thumbnail downloader (recommended)**: under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com and retrieve the available thumbnail. - - WARNING: the Playlist Thumbnails Updater process will over-write any custom thumbnails set by the user (see below) for any game name that matches a thumbnail on the server. + - _WARNING_: the Playlist Thumbnails Updater process will over-write any [custom thumbnails](#custom-thumbnails) set by the user for any game name that matches a thumbnail on the server. * **Individual thumbnail downloader**: there is a Download Thumbnails option for each entry in playlists. For RetroArch version 1.17.0 or later, you may hit download up to 3 times to try the flexible matches. * **On-demand thumbnail downloader**: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions 1.17.0 or later, you may try flicking back and forth between entries up to 3 times to try the flexible matches. By default, on-demand thumbnail downloader does not try to fetch thumbnails based on ROM name, enable Settings / Playlist / Use filenames for thumbnail matching options for that. @@ -177,20 +177,18 @@ Since playlists are managed in text-only JSON format, there are a few third-part Users can set a custom thumbnail (i.e. a thumbnail that is different from the one automatically provided by RetroArch) by following the process below. !!! Terminology Note: "Game Name" - The term _Game Name_ refers to the name displayed within RetroArch and within a playlist, _not_ to the filename of the underlying file on the computer or device. _Game Name_ in this document is synonymous with playlist item label, playlist entry, or content name. Game names are often assigned automatically after a file import scan and a database lookup, though the user can manually game names by choosing a game in a playlist and using "Rename" in the menu. + The term _Game Name_ refers to the name displayed [within a playlist in RetroArch](#retroarch-playlist-scanner), _not_ to the filename of the underlying file on the computer or device. _Game Name_ in this document is synonymous with playlist item label, playlist entry, content name, game title. -- Name a PNG image file with a base filename that matches a game title displayed in a playlist. _Example_: if the game name is `Q-Bert's Qubes`, the intended image file must be named `Q-Bert's Qubes.png` _(See below for additional flexible name matching options.)_ -- Place the PNG in the [correct folder](#thumbnail-folder-paths) for the relevant playlist. +- __File & Name__. Name a PNG image file with a base filename that matches a game title displayed in a playlist. _Example_: if the game name is `Q-Bert's Qubes`, the intended image file must be named `Q-Bert's Qubes.png` _(See below for additional flexible name matching options.)_ +- __Location.__ Place the PNG in the [correct folder](#thumbnail-folder-paths) for the relevant playlist. +- __Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). +- __Replace invalid characters.__ The thumbnail's base filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. -__Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). - -__Replace invalid characters.__ The thumbnail's base filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. - -**Flexible name matching.** RetroArch versions 1.17.0 or later will automatically attempt up to 3 different match techniques to associate a playlist item with a [properly located](#thumbnail-folder-paths) thumbnail image file, in the following order: +**Flexible name matching.** RetroArch versions 1.17.0 or later will attempt up to 3 different match techniques to associate a playlist item with a [properly located](#thumbnail-folder-paths) thumbnail image file, in the following order: 1. __ROM file name <-> .png file name match__. A ROM file `Q-Bert's Qubes (USA) (1983).a26` would receive the thumbnail `Q-Bert's Qubes (USA) (1983).png` if it exists, regardless of how the game name appears in the RetroArch interface. 2. __Game name <-> .png file name match__. `Q*Bert's Qubes (USA)` in a playlist would receive the thumbnail `Q_Bert's Qubes (USA).png` if it exists. `*` is an invalid character and must be replaced with `_` in the image filename. -3. __Short game name <-> .png file name match__. Same as method 2, but only up to first round bracket: `Q-Bert's Qubes (USA) (1983) (Parker Brothers) [h]` in a playlist would receive `Q_Bert's Qubes.png` thumbnail if it exists. +3. __Short game name <-> .png file name match__. Same as method 2, but only up to first round bracket: `Q-Bert's Qubes (USA) (1983) (Parker Brothers) [h]` in a playlist would receive `Q-Bert's Qubes.png` thumbnail if it exists. ### Thumbnail folder paths Thumbnail image files must be stored in subfolders according to this structure: @@ -226,15 +224,15 @@ follow the steps below. ### Overview 1. Make an account on github.com 2. "Fork" (copy) a [Libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) to your own working area in github -3. Make your image file changes to your copy of the project (aka your fork), while following [libretro guidelines](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) -4. Create a "Pull Request" to request that the official project takes your proposed changes +3. Make your image file changes to your copy of the project (aka your fork), while following [libretro thumbnail rules](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) and the detailed guidelines below +4. Create a "Pull Request" to request that the official project members take your proposed changes ### Detailed Steps - __Fork the repository.__ Visit the github.com [libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) directory that you want to contribute to and click the fork button. You must fork it at the level of specific console. The Fork button won't appear if you're viewing a lower level folder in the respository like "boxart" or "snaps.” - _Example_. If you are doing GBA thumbnail work you should fork [Nintendo_-_Game_Boy_Advance](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy_Advance/). - - **Why "Fork" your own**? If you try to directly edit an image file in github libretro thumbnails by digging down to a certain thumbnail and clicking the pencil icon to edit, it's locked unless you are a member of the official project. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. + - **Why "Fork" your own**? If you try to directly edit an image file in github libretro thumbnails by digging down to a certain thumbnail and clicking the pencil icon to edit, it's locked unless you are an official member/admin. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. - _Warning_: You must visit and fork the _current_ gitHub project for the libretro thumbnail repository: for example [this one for SNES](https://github.com/libretro-thumbnails/Nintendo_-_Super_Nintendo_Entertainment_System), not to be confused with the similar-looking [archived version](https://github.com/libretro/libretro-thumbnails) which is inactive. - Correct: https://github.com/libretro-thumbnails/ - Incorrect: https://github.com/libretro/libretro-thumbnails @@ -243,28 +241,28 @@ follow the steps below. - Upload File. - __Choose "Upload File"__. Select your new chosen image file. In this stage you are uploading to your fork/branch of the project. - __Follow all guidelines for a proper contribution.__ - - Your choice of image file should meet the libretro thumbnail [ReadMe rules](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. 512px or smaller. - - Name your contribution image file correctly. If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. If uploading a thumbnail that has no prior existing one, research the naming conventions of libretro and how the game is named in databases. - - Use the correct path. Choose the correct console system folder and thumbnail type folder in the project. - - For snaps (in-game screenshots), choose a good clear artful image that shows the art, spirit, or action of the game. For good examples of well-chosen in-game screenshots, see the back-of-box marketing images for officially published games. + - Your choice of image file should meet the libretro thumbnail [rules in the ReadMe](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. 512px or smaller. + - For snaps (in-game screenshots), choose a good clear artful image that shows the art, spirit, or action of the game in normal gameplay. For examples of well-chosen well-composed in-game screenshots, see the back-of-box images printed on officially published games. + - Name your image file correctly. + - If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. + - If uploading a new thumbnail that has no prior existing version, research the naming conventions of libretro and how the game is named in databases. Name the image file according to the game name that RetroArch assigns in the playlist. + - Use the correct path. Choose the correct console system folder and thumbnail type folder in the repository. - __Commit.__ The "Commit" button will save your change to your copy of the repository. You should generally commit to your own _master_. -- __Pull Request (PR)__. Look for the button or option for a Pull Request when you Commit, though you may wait until you have finalized multiple changes (commits) and then include them all in a single PR. A Pull Request means sending a request to the official controllers of the project to take your contribution into the official project. Official members will review your proposed changes and decide whether to accept it. You will eventually see a confirmation that it was approved or a discussion message if changes are needed. It may take time before someone is able to review the request, so please be patient. -- __Verify that your Pull Request is active and correct.__ _Example_: if you made a Pull Request to contribute a Gameboy thumbnail you’d [see the request publicly listed at the official repository](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy/pulls). - - _Warning_: It is possible to accidentally send a Pull Request to yourself if you committed your changes to your sub-branch instead of your own "_master_". Your “master” is not the official project *master*. And your sub-branch is not the same as your master. You can hover on any abbreviated branch path label in GitHub to see a pop-up of the full path label. If needed, approve your PR to yourself to merge your sub-branch changes to your master, then do a Pull Request from your master to the official Libretro master project. +- __Pull Request (PR)__. Look for the button or option for a Pull Request when you Commit, though you may wait until you have finalized multiple changes (commits) and then include them all in a single PR. A Pull Request means sending a request to the official members to take your contribution (i.e. merge your fork) into the RetroArch repository. Admins will review your proposed changes and decide whether to accept it. You will eventually see a confirmation that it was approved or a discussion message if changes are needed. It may take time (even weeks or months) before an admin is able to examine the request, so please be patient. +- __Verify that your Pull Request is active and correct.__ For example, if you made a Pull Request to contribute a Gameboy thumbnail then you can [view the request publicly listed at the official repository](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy/pulls). + - _Warning_: It is possible to accidentally send a Pull Request to yourself if you committed your changes to your sub-branch instead of your own _master_. If needed, approve your PR to yourself to merge your sub-branch changes to your master, then do a Pull Request from your master to the official Libretro master project. For clarity on github.com, you can hover on any abbreviated branch path label to see a pop-up of the full path label. -__About "Syncing"__ #comment -Thumbnail contribution work involves changing your copy of the project while other people may be changing the official repository _after_ you created your fork. Github provides options to keep both your copy ("downstream") and the official repository ("upstream") up-to-date with ongoing changes. - -- __Contribute__ button. If you make multiple changes within your fork, you can use Contribute button > Open Pull Request to send all your changes as one PR. -- __Sync__ button. Use the Sync button to update your fork with other people’s changes that have happened upstream. +__About "Syncing."__ Contribution work involves changing your copy of the project while other people may be changing the official repository _after_ you created your fork. Github provides options to keep both your copy ("downstream") and the official repository ("upstream") up-to-date with ongoing changes. If you make multiple changes within your fork, you can use the **Contribute button** > Open Pull Request to send all your changes as one PR. You can use the __Sync button__ button to update your fork with other people’s changes that have happened upstream. ### The Thumbnail Server +Thumbnail contribution flow [EDIT: use markdown DIAGRAM for A -> B -> C - >D for user fork to RA repos to Thumb server to Retroarch users + RetroArch retrieves thumbnails from [a server](https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before you and other users will see your contribution in RetroArch playlists. -## Custom logos/icons for playlist items -RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file and subfolder format follows the same pattern as [custom thumbnails](#custom-thumbnails). +## Custom icons/logos for playlist items +RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file format and subfolder structure follows the same pattern as [custom thumbnails](#custom-thumbnails): - Create a folder called `Named_Logos` alongside the `Named_Boxarts` thumbnail subfolder for the intended playlist - Put the logo image files there with base filenames that match the associated game's displayed name in the RetroArch playlist. -Logo support is only possible with XMB menu driver, and the online thumbnail repositories do not contain logo collections. +**Limitations.** Logo support is only possible with XMB menu driver. The online thumbnail repositories do not contain logo collections. From e34d792267afa083f6a34d58a52e6b69119e9e37 Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Thu, 2 Jan 2025 10:46:28 -0500 Subject: [PATCH 7/9] 2 word edit to roms-playlists-thumbnails.md Tiny wording edit --- docs/guides/roms-playlists-thumbnails.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 1f348e7a03..443802811b 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -65,7 +65,7 @@ All menu drivers can display fullscreen thumbnails when pressing Start, and Y bu Thumbnails can be retrieved in multiple ways: * **Playlist thumbnail downloader (recommended)**: under Online Updater menu, all available thumbnails can be downloaded for a playlist. RetroArch will connect to http://thumbnails.libretro.com and retrieve the available thumbnail. - - _WARNING_: the Playlist Thumbnails Updater process will over-write any [custom thumbnails](#custom-thumbnails) set by the user for any game name that matches a thumbnail on the server. + - _WARNING_: the Playlist Thumbnails Updater process will over-write [custom thumbnails](#custom-thumbnails) set by the user for any game that has an associated thumbnail on the server. * **Individual thumbnail downloader**: there is a Download Thumbnails option for each entry in playlists. For RetroArch version 1.17.0 or later, you may hit download up to 3 times to try the flexible matches. * **On-demand thumbnail downloader**: if the respective option is enabled, RetroArch will try to download each thumbnail as the playlist is browsed. For RetroArch versions 1.17.0 or later, you may try flicking back and forth between entries up to 3 times to try the flexible matches. By default, on-demand thumbnail downloader does not try to fetch thumbnails based on ROM name, enable Settings / Playlist / Use filenames for thumbnail matching options for that. From 57f9604f72328f0ebbfac03f36ec2bf45aecabb8 Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Thu, 2 Jan 2025 21:35:49 -0500 Subject: [PATCH 8/9] Editing Contribution Guide Also more small revisions to Custom Thumbnails --- docs/guides/roms-playlists-thumbnails.md | 29 +++++++++++++----------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index 443802811b..f16312226f 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -179,16 +179,16 @@ Users can set a custom thumbnail (i.e. a thumbnail that is different from the on !!! Terminology Note: "Game Name" The term _Game Name_ refers to the name displayed [within a playlist in RetroArch](#retroarch-playlist-scanner), _not_ to the filename of the underlying file on the computer or device. _Game Name_ in this document is synonymous with playlist item label, playlist entry, content name, game title. -- __File & Name__. Name a PNG image file with a base filename that matches a game title displayed in a playlist. _Example_: if the game name is `Q-Bert's Qubes`, the intended image file must be named `Q-Bert's Qubes.png` _(See below for additional flexible name matching options.)_ +- __File & Filename__. Name a PNG image file with a base filename that matches a game title displayed in a playlist. _Example_: if the game name is `Q-Bert's Qubes (USA)`, the intended image file must be named `Q-Bert's Qubes (USA).png` _(See below for additional flexible name matching options.)_ - __Location.__ Place the PNG in the [correct folder](#thumbnail-folder-paths) for the relevant playlist. - __Use a compatible image type.__ In RetroArch versions later than 1.19.1, image formats other than PNG can be enabled (jpg, bmp, tga). - __Replace invalid characters.__ The thumbnail's base filename should exactly match the game's title displayed in the playlist with an important exception. The characters `` &*/:`<>?\| `` in playlisted game titles must be replaced with `_` in the corresponding thumbnail filename. -**Flexible name matching.** RetroArch versions 1.17.0 or later will attempt up to 3 different match techniques to associate a playlist item with a [properly located](#thumbnail-folder-paths) thumbnail image file, in the following order: +**Flexible name matching.** RetroArch versions 1.17.0 or later will attempt up to 3 different match techniques to associate a playlist item with a [properly located](#thumbnail-folder-paths) local thumbnail image file, in the following order: 1. __ROM file name <-> .png file name match__. A ROM file `Q-Bert's Qubes (USA) (1983).a26` would receive the thumbnail `Q-Bert's Qubes (USA) (1983).png` if it exists, regardless of how the game name appears in the RetroArch interface. 2. __Game name <-> .png file name match__. `Q*Bert's Qubes (USA)` in a playlist would receive the thumbnail `Q_Bert's Qubes (USA).png` if it exists. `*` is an invalid character and must be replaced with `_` in the image filename. -3. __Short game name <-> .png file name match__. Same as method 2, but only up to first round bracket: `Q-Bert's Qubes (USA) (1983) (Parker Brothers) [h]` in a playlist would receive `Q-Bert's Qubes.png` thumbnail if it exists. +3. __Short game name <-> .png file name match__. RetroArch looks for a local thumbnail named after a shortened form of the game name ignoring all text starting at the first round bracket, in other words ignoring informational tags like Region etc. `Q-Bert's Qubes (USA) (1983) (Parker Brothers) [h]` in a playlist would receive `Q-Bert's Qubes.png` if that local image file exists. ### Thumbnail folder paths Thumbnail image files must be stored in subfolders according to this structure: @@ -198,8 +198,10 @@ Thumbnail image files must be stored in subfolders according to this structure: - `Named_Boxarts` subfolder for boxart/cover art - `Named_Snaps` subfolder for in-game snapshots - `Named_Titles` subfolder for in-game introductory title screens + +**Example** of a Windows path to a correctly set boxart folder: `RetroArch-Win64\thumbnails\Atari - 2600\Named_Boxarts` -**Example of correct thumbnail file setup**: If your content is named `Q*bert's Qubes (USA)` in the playlist, then its thumbnails should be named `Q_bert's Qubes (USA).png` and stored at these paths: +**Example** of correct thumbnail file setup for content named `Q*bert's Qubes (USA)` in a default Atari 2600 playlist: ``` thumbnails/ @@ -211,29 +213,30 @@ Thumbnail image files must be stored in subfolders according to this structure: Named_Titles/ Q_bert's Qubes (USA).png ``` +_Note the replacement of the playlist game name's `*` with `_` in the filenames, in accordance with invalid characters described above._ ## Contributing Thumbnails: How To -Thumbnails are an area where users who are not experienced in programming can contribute to RetroArch and in a way that helps all users. If you are interested in: +Thumbnails (along with [documentation](https://docs.libretro.com/meta/how-to-contribute/)) are an area where users who are not experienced in programming can contribute to RetroArch and in a way that helps all users. If you are interested in: - adding a thumbnail that you see is missing -- correcting a thumbnail that is inaccurate +- correcting a thumbnail that is inaccurate or mistaken - replacing an existing thumbnail with a more representative or more aesthetic image follow the steps below. ### Overview 1. Make an account on github.com -2. "Fork" (copy) a [Libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) to your own working area in github +2. "Fork" (copy) a [libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) to your own working area in github 3. Make your image file changes to your copy of the project (aka your fork), while following [libretro thumbnail rules](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md) and the detailed guidelines below -4. Create a "Pull Request" to request that the official project members take your proposed changes +4. Create a "Pull Request" to request that the official project members review your proposed changes in order to accept it into RetroArch ### Detailed Steps - __Fork the repository.__ Visit the github.com [libretro thumbnail repository](https://github.com/libretro-thumbnails/libretro-thumbnails) directory that you want to contribute to and click the fork button. You must fork it at the level of specific console. The Fork button won't appear if you're viewing a lower level folder in the respository like "boxart" or "snaps.” - _Example_. If you are doing GBA thumbnail work you should fork [Nintendo_-_Game_Boy_Advance](https://github.com/libretro-thumbnails/Nintendo_-_Game_Boy_Advance/). - - **Why "Fork" your own**? If you try to directly edit an image file in github libretro thumbnails by digging down to a certain thumbnail and clicking the pencil icon to edit, it's locked unless you are an official member/admin. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. - - _Warning_: You must visit and fork the _current_ gitHub project for the libretro thumbnail repository: for example [this one for SNES](https://github.com/libretro-thumbnails/Nintendo_-_Super_Nintendo_Entertainment_System), not to be confused with the similar-looking [archived version](https://github.com/libretro/libretro-thumbnails) which is inactive. + - **Why "Fork" your own**? Every part RetroArch's code and materials are open and accessible on github for input from any public volunteer (via Pull Request), but only official admins have direct edit access. Forking means copying your own copy of the project to freely draft changes in your own separate work area. Later you’ll send your proposed changes to the official project. + - _Warning_: You must visit and fork the _current_ github project for the libretro thumbnail repository, for example [this one for SNES](https://github.com/libretro-thumbnails/Nintendo_-_Super_Nintendo_Entertainment_System), not to be confused with the similar-looking [archived version](https://github.com/libretro/libretro-thumbnails) which is inactive. - Correct: https://github.com/libretro-thumbnails/ - Incorrect: https://github.com/libretro/libretro-thumbnails - __Add / Upload your new image file.__ When viewing a specific thumbnail type folder (e.g. Named_boxarts, Named_titles, Named_snaps) within *your fork* of the thumbnails repository, click the pulldown button (near top right) that says **Add file** to see 2 options: @@ -241,10 +244,10 @@ follow the steps below. - Upload File. - __Choose "Upload File"__. Select your new chosen image file. In this stage you are uploading to your fork/branch of the project. - __Follow all guidelines for a proper contribution.__ - - Your choice of image file should meet the libretro thumbnail [rules in the ReadMe](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. 512px or smaller. - - For snaps (in-game screenshots), choose a good clear artful image that shows the art, spirit, or action of the game in normal gameplay. For examples of well-chosen well-composed in-game screenshots, see the back-of-box images printed on officially published games. + - Your choice of image file should meet the libretro thumbnail [rules in the ReadMe](https://github.com/libretro-thumbnails/libretro-thumbnails/blob/master/README.md), e.g. width scaled down to 512px. + - For snaps (in-game screenshots), choose a good clear artful image that shows the art, spirit, or action of the game in normal or ideal gameplay. For examples of well-chosen well-composed in-game screenshots, see the back-of-box images printed on officially published games. - Name your image file correctly. - - If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. + - If replacing an existing image, name your new image file exactly as the previous one to guarantee that it will be matched to the relevant game name in RetroArch. (Unless your contribution is to correct an erroneous filename that doesn't match the game name database.) - If uploading a new thumbnail that has no prior existing version, research the naming conventions of libretro and how the game is named in databases. Name the image file according to the game name that RetroArch assigns in the playlist. - Use the correct path. Choose the correct console system folder and thumbnail type folder in the repository. - __Commit.__ The "Commit" button will save your change to your copy of the repository. You should generally commit to your own _master_. From 8f8eee0c054f7d36d702c0ec52334a930489cfd0 Mon Sep 17 00:00:00 2001 From: OctopusButtons <62315590+OctopusButtons@users.noreply.github.com> Date: Thu, 2 Jan 2025 21:53:03 -0500 Subject: [PATCH 9/9] finalized Contribute Guide How-To And more small edits. Except now I'm wondering about a disaster: is markdown viewable on the final libretro docs page/site, or is the markdown only correctly viewable on github itself? Hopefully what I saw is a false alarm. --- docs/guides/roms-playlists-thumbnails.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/roms-playlists-thumbnails.md b/docs/guides/roms-playlists-thumbnails.md index f16312226f..9feedd1400 100644 --- a/docs/guides/roms-playlists-thumbnails.md +++ b/docs/guides/roms-playlists-thumbnails.md @@ -258,9 +258,8 @@ follow the steps below. __About "Syncing."__ Contribution work involves changing your copy of the project while other people may be changing the official repository _after_ you created your fork. Github provides options to keep both your copy ("downstream") and the official repository ("upstream") up-to-date with ongoing changes. If you make multiple changes within your fork, you can use the **Contribute button** > Open Pull Request to send all your changes as one PR. You can use the __Sync button__ button to update your fork with other people’s changes that have happened upstream. ### The Thumbnail Server -Thumbnail contribution flow [EDIT: use markdown DIAGRAM for A -> B -> C - >D for user fork to RA repos to Thumb server to Retroarch users -RetroArch retrieves thumbnails from [a server](https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before you and other users will see your contribution in RetroArch playlists. +RetroArch retrieves thumbnails from a server (https://thumbnails.libretro.com/) that is updated periodically with imports from the Libretro thumbnail repository on github. After a pull request is approved for a contribution, some time may pass before the updates are sent to the server. The final server update must occur before users will see new image contributions in RetroArch playlists. ## Custom icons/logos for playlist items RetroArch versions later than 1.19.1 include an option for the XMB menu driver to display custom per-game icons/logos in the playlist, instead of the default content icon, see [this example](https://github.com/libretro/RetroArch/pull/16758#issuecomment-2211771227). The required file format and subfolder structure follows the same pattern as [custom thumbnails](#custom-thumbnails):