SteamGridDB
(Project Website) (Project API Documentation)
SteamTinkerLaunch v14.0.20231018-1 and above offers significant integration with SteamGridDB, a service that hosts artwork for many games. This artwork includes hero (banner) artwork, logos, icons, boxart, and tenfoot (horizontal grid), and is not limited to Steam games.
SteamGridDB offers a number of filters when searching for game art, and SteamTinkerLaunch allows you to set these filters on the Global Menu.
When downloading artwork, SteamTinkerLaunch will search SteamGridDB for the best match and return the first one it gets back each time. If you are unhappy with the artwork chosen, you can manually overwrite it in the Steam grids folder, which you can access with steamtinkerlaunch opengridfolder.
If you make frequent use of SteamGridDB and enjoy their service, please consider supporting them! This integration would not be possible without their awesome endpoints and the community that submit artworks.
Once artwork is downloaded, Steam will have to be restarted before it can pick up any new artwork to display in your library. Be sure to check the SteamTinkerLaunch log file beforehand to see if any artwork failed to download (for example, invalid API key, no artwork found, etc).
To use the integration of the mighty SteamGridDB an individual API key has to be created. This is free, though requires a SteamGridDB account, and can be done on your SteamGridDB Profile Preferences section.
You can enter this API key on the Global Menu, under the "SteamGridDB Api Key" field, or by setting the SGDBAPIKEY variable in the Global Config. It can also be set via the commandline with steamtinkerlaunch set SGDBAPIKEY global <apikey>.
SteamGridDB integration requires the jq dependency. Make sure you have this installed before trying to use SteamGridDB. On many distributions including SteamOS, this should already be installed.
Internally, SteamTinkerLaunch uses the SteamGridDB API to fetch the artwork. For games available on Steam, we can search using the Steam AppID. Otherwise, for games not available on Steam (i.e. indie games on itch.io), we can search using SteamGridDB's Game ID. This ID can be found in the URL when selecting a game on the SteamGridDB website, for example 5331220 for Touhou Fumo Racing. When searching for artwork for Non-Steam Games, be sure to enter this SteamGridDB Game ID.
When adding artwork for a specific game, make sure you have its Steam AppID on hand. For Steam games, you only need the AppID, but if you're searching by SteamGridDB Game ID, such as for Non-Steam Games or to get artwork for a different version of your game (i.e. "Sonic Colours" for the PAL region Wii game instead of "Sonic Colors: Ultimate" which is the Steam name), you'll need to provide both the Game ID to search SteamGridDB and the AppID to name the grid file so Steam can identify it.
In future, I'm hoping to add a command to search and return the Game ID from SteamGridDB, and for Non-Steam Games, add the option to search SteamGridDB by both the name entered for the Non-Steam Game as well as a custom name to search on.
By default, SteamGridDB artwork saved by SteamTinkerLaunch is not saved to Steam. Be sure to read the configuration section below for more background on how to set this up.
You can tell SteamTinkerLaunch to download SteamGridDB artwork for each game launched with it, either before the launch, after the launch, or only for games with no metadata found. This can be configured on the Global Menu. Please note that this option only applies for games purchased on Steam and launched with SteamTinkerLaunch.
You can also tell SteamTinkerLaunch how to manage gams which already have grids in the destination folder. These options are to skip artwork that already exists so it won't be overwritten, to back up artwork into a subdirectory of the same folder it is saved to (so it can be recovered later) and then replace it, or to replace any existing artwork files entirely.
NOTE: When SteamTinkerLaunch sets its own internal game picture (seen on the Main Menu, Game Menu, and other places), this is downloaded directly from Steam. However, for Non-Steam Games, it will use the game's hero artwork in the Steam grid folder if it exists.
There is a command to open a GUI to download SteamGridDB artwork for a given game. Running steamtinkerlaunch sgdb <appid> will open a GUI.
This GUI is a frontend for the below commandline usage, the information entered here is automatically passed as parameters to the command. It functions identically to the commandline usage.
You can download artwork from SteamGridDB for all owned games, all installed games, or on a per-game basis from the commandline.
Commandline usage will respect any configuration set in the Global Menu, but some settings can be overwritten, such as how to manage existing files and to apply artwork to Steam even if this option is not enabled globally.
This command will search for and download all artwork types enabled on the Global Menu from SteamGridDB, that it can find. If you have disabled, for example, hero artwork, then this command will not download that artwork type. Make sure you configure your artwork preferences on the Global Menu beforehand.
To download artwork for a single game, you can use the steamgriddb command, or its sgdb shorthand. Below are the list of flags that can be passed to the command and some background on them. You can also review this at any time from the help screen using steamtinkerlaunch help.
| Flag | Description | Example |
|---|---|---|
--search-id |
The ID to search SteamGriDB with. Assumed to be a Steam Store AppID by default. | --search-id="22330" |
--search-name |
Search SteamGridDB for a Game ID and return its best match using this name. This will automatically apply the --nonsteam option, however you must specify the --filename-appid when using this option since it will search using the SteamGridDB Game ID internally. |
--search-name="A Hat in Time" |
--filename-appid |
The ID to use in the filename. If searching on SteamGridDB Game ID, you'll need to give the Steam AppID of a game (for Non-Steam Games, this is the AppID of the game in your library, not the store AppID). | --filename-appid="402857602" |
--steam |
Tell SteamGridDB that you're searching on Steam Store AppID. This is set by default, but you may want to explicitly set this every so often. This flag takes no values. | N/A. |
--nonsteam |
Tell SteamGridDB that you're searching on SteamGridDB Game ID. This needs to be set if, for example, you're setting artwork for a Non-Steam Game. This flag takes no values. | N/A. |
--apply |
Save this artwork to Steam |
Here is a very basic example to show how to download artwork for the game "Geometry Wars: Retro Evolved" and apply it immediately to the Steam Client. This game currently has very little artwork by default on Steam which is why it has been chosen for this example. The command assumes no artwork is already downloaded for the game.
steamtinkerlaunch sgdb --search-id="8400" --applyBelow are some examples of the command, to better illustrate how you might want to use it.
Get artwork for game in Steam library using Steam AppID
# Download artwork for "The Elder Scrolls IV: Oblivion Game of the Year Edition" using its Steam AppID
# Note that the filename AppID is not specified. We use Search ID to name the file automatically as it is the Steam AppID
steamtinkerlaunch sgdb --search-id="22330" --steam --apply --skip-existingGet artwork for game in Steam library using SteamGridDB Game ID
# Download artwork for "The Elder Scrolls IV: Oblivion Game of the Year Edition" using its SteamGridDB Game ID
# Searches using the SteamGridDB Game ID but since the game is owned on Steam, name it after the actual Steam AppID
steamtinkerlaunch sgdb --search-id="5258102" --filename-appid="22330" --nonsteam --apply --skip-existingGet artwork for Non-Steam Game that is available on Steam using Steam AppID
# Download artwork for "The Elder Scrolls IV: Oblivion Game of the Year Edition" using its Steam AppID despite it being added as a shortcut
# Assumes this is a Non-Steam Game (shortcut) but we're searching on the Steam AppID, yet naming the file after the Non-Steam AppID in the library
steamtinkerlaunch sgdb --search-id="22330" --filename-appid="12123123" --steam --apply --skip-existingGet artwork for Non-Steam Game using SteamGridDB Game ID
# Download artwork for "The Elder Scrolls IV: Oblivion Game of the Year Edition", added as a Steam shortcut, using the SteamGridDB Game ID
# We search using SteamGridDB's Game ID and then name the downloaded file after the Steam shortcut ID
steamtinkerlaunch sgdb --search-id="5258102" --filename-appid="12123123" --nonsteam --apply --skip-existingYou can bulk-download grids for three different types of games: All owned games, all installed games, or all Non-Steam Games. The distinction for Non-Steam Games may seem odd at first, but they are tracked separately by Steam, so the command differentiates between them accordingly.
# Note that all of this usage is also documented on the help screen, `steamtinkerlaunch help`
#
## Download grids for all owned games
steamtinkerlaunch update grid owned
## Download grids for all installed games
steamtinkerlaunch update grid installed
## Download grids for all Non-Steam Games
steamtinkerlaunch update grid nonsteam # alternatively, you can use "shortcuts" instead of "nonsteam"When bulk-adding for Non-Steam Games, SteamTinkerLaunch will also download and update the icon for Non-Steam Games, something which is not possible to update for Steam games.
Keep in mind that for many games, you may be rate-limited by the SteamGridDB API. Please keep API usage in mind and be considerate of bandwidth!
(See also the Add Non-Steam Game wiki page)
When adding games from the SteamTinkerLaunch Add Non-Steam Game GUI, you can pass the SteamGridDB Game ID. When adding the game, SteamTinkerLaunch can search for the artwork and download it before adding the shortcut to Steam. When adding games using the addnonsteamgame command, you can pass the --steamgriddb-game-id option to give the SteamGridDB Game ID to search on.
One distinction to make for Non-Steam games is that SteamTinkerLaunch will download icons from SteamGridDB. This is only possible for Non-Steam Games because Steam allows you to set icons for these, whereas there is no permanent way to set the icon for a Steam game.
Any found artwork will always be applied to Non-Steam Games, even if this option is disabled on the Global Menu. So if you pass the SteamGridDB Game ID and artwork is found, it will always be put into the Steam grids folder so it will be applied automatically.
The SteamGridDB API which SteamTinkerLaunch uses takes a number of options in order to find the best matching artwork.
In order to set the filters for how to search SteamGridDB, you must update the values either on the Global Menu on in the Global Config file. From the Global Menu, you can also enable and disable various grids, so if you only want to download boxart for example, you can disable the other grid types.
Make sure you review the defaults before continuing, in case you want different settings. For example, animated artwork will not be returned by default as the APNG file sizes can be very large, but if you want animated artwork you can enable it in the Global Menu.
Here is a table outlining the general SteamGridDB configuration options. Information on the configuration options available for game artwork is outlined later in this section.
| Global Config Variable | Global Menu Name | Description | Default Value |
|---|---|---|---|
SGDBDLTOSTEAM |
Download grid to Steam | Download artwork to the Steam internal grids folder, which will apply it to the game immediately and save it with the Steam AppID. | False |
SGDBAPIKEY |
SteamGridDB API Key | The API key to access the SteamGridDB API. This must be generated from your SteamGridDB account preferences, and then set here. | (blank) |
SGDBHASFILE |
Existing Grid File | Determines how to handle if a downloaded grid with the same name already exists in the destination folder, for example if you have previously set grid artwork for this game. You could set this to, for example, replace so that it will overwrite the existing artworks. This option will apply to all downloaded grids for this game. |
skip |
SGDBAUTODL |
Auto download grid | Determines when, if ever, to automatically download artwork for a game from SteamGridDB. This can be set to download artwork as soon as a game is launched with SteamTinkerLaunch, after a game is started, only if a game has no SteamTinkerLaunch metadata, or never automatically download artwork. | none |
By default, SteamTinkerLaunch will not use SteamGridDB at all. In order to use it you must configure it in the Global Menu, or use the commandline. Also, it will not by default save grids to Steam. This is useful if you simply want to download grids. By default, they will be saved to the SteamTinkerLaunch grids folder, which is inside the SteamTinkerLaunch configuration folder, under downloads/steamgriddb (ex: ~/.config/steamtinkerlaunch/downloads/steamgriddb).
Below is a table of each configuration option available for the different artwork types, their default values, and information about them. Note that while artworkk can be configured from the Steam Client, this does not apply to Big Picture Mode (or "Game Mode" on SteamOS), so you can only adjust artwork from the Desktop client view (or "Desktop Mode" on SteamOS). The default dimensions chosen for hero, boxart, and tenfoot are the recommended sizes from SteamGridDB and should best fit the Steam Client, but if you'd like (or if no matching artwork is found) you can adjust or remove the dimensions.
Blank values will not be passed to the API, meaning you will get back any result, which is useful for games which may not have very much artwork (i.e. very new or obscure games), but also means you may get artwork that does not exactly fit with the Steam recommended artwork dimensions. On this note, when adjusting values, keep in mind that some games may not return any artwork if the filters are too strict. For example, forcing animated artwork on a game that may not have any such art. Also note that some games may not have any artwork on SteamGridDB even if they have a valid Game ID.
Configure the Hero (banner) artwork settings here. You can change the dimensions here if you're looking for a grid of specific dimensions.
| Global Config Variable | Global Menu Name | Description | Default Value |
|---|---|---|---|
SGDBDLHERO |
Download Hero Artwork | Search SteamGridDB for Hero Artwork | True |
SGDBHERODIMS |
Dimensions | Dimensions of Hero Artwork to search for | 3840x2160,1920x620 |
SGDBHEROTYPES |
Types | Type of Hero Artwork images to search for (animated, static, both), in order of preference | static |
SGDBHEROSTYLES |
Styles | Hero Artwork Styles to search for (can reduce to refine search) | alternate,blurred,material |
SGDBHERONSFW |
Styles | Allow Not Safe for Work (NSFW) artwork, which may contain nudity | any |
SGDBHEROHUMOR |
Humor | Allow searching for artwork tagged with "Humor" | any |
SGDBHEROEPILEPSY |
Epilepsy | Allow searching for art which may not be safe for epilepsy | False |
The "Logo" is what appears overtop the hero artwork. The position and size of this can be adjusted from the Steam client. The default position is on the left and the default is to render the logo full size, however many grids by default keep space to the left for this reason. Sometimes you may prefer a logo elsewhere though, so from the Steam client you can right click and select "Adjust Logo Position".
Various logo settings can be changed, one useful one to toggle may be the logo style. Refining searches such as to remove "official" logos could allow more creative results to be returned, and removing "white" or "black" is useful for getting artwork that may more suited to certain types of heroes. For example on a darker hero, you could set a white logo, which could be more legible.
| Global Config Variable | Global Menu Name | Description | Default Value |
|---|---|---|---|
SGDBDLLOGO |
Download Logo Artwork | Search SteamGridDB for Boxart Artwork | True |
SGDBLOGOTYPES |
Types | Type of Logo Artwork images to search for (animated, static, both), in order of preference | static |
SGDBLOGOSTYLES |
Styles | Logo Artwork Styles to search for (can reduce to refine search) | official,white,black,custom |
SGDBLOGONSFW |
Styles | Allow Not Safe for Work (NSFW) artwork, which may contain nudity | any |
SGDBLOGOHUMOR |
Humor | Allow searching for artwork tagged with "Humor" | any |
SGDBLOGOEPILEPSY |
Epilepsy | Allow searching for art which may not be safe for epilepsy | False |
Also known as "Vertical Grid", this is the tall artwork resembling a physical game's cover artwork on the box and is used all over the Steam client.
One useful value to adjust may be the styles. For example, you could remove "no_logo" in order to force artwork to always have a logo. Play around with the styles and set the ones that you think may best match the style you're going for in your library.
| Global Config Variable | Global Menu Name | Description | Default Value |
|---|---|---|---|
SGDBDLBOXART |
Download Boxart Artwork | Search SteamGridDB for Boxart Artwork | True |
SGDBBOXARTDIMS |
Dimensions | Dimensions of Boxart Artwork to search for | 600x9000 |
SGDBBOXARTTYPES |
Types | Type of Boxart Artwork images to search for (animated, static, both), in order of preference | static |
SGDBBOXARTSTYLES |
Styles | Boxart Artwork Styles to search for (can reduce to refine search) | alternate,blurred,white_logo,material,no_logo |
SGDBBOXARTNSFW |
Styles | Allow Not Safe for Work (NSFW) artwork, which may contain nudity | any |
SGDBBOXARTHUMOR |
Humor | Allow searching for artwork tagged with "Humor" | any |
SGDBBOXARTEPILEPSY |
Epilepsy | Allow searching for art which may not be safe for epilepsy | False |
The name "tenfoot" is what Steam uses to describe the horizontal artwork that is displayed for the most recently played game. SteamGridDB refers to this as the "Horizontal Grid". Internally, SteamTinkerLaunch hits the same grid endpoint to get this tenfoot artwork, but with different dimensions specifications. We basically internally tell SteamGridDB that we're looking for boxart, but with tenfoot dimensions.
For cosmetic reasons, SteamTinkerLaunch enforces that tenfoot artwork must have a logo. This is to make it more obvious what the most recently played game is on the Desktop Steam Client, as if it was just a banner, it may not be very obvious and could be quite generic. It is possible that there may not be any matching artwork with a logo though, so if you need the maximum number of matches, you can manually append no_logo to the list of styles.
Likewise, the default dimensions here are the ones that should best match Steam. It is not exact so some artwork may get cut off or look too small, so you could specify other dimensions, or leave this option blank and return any dimensions of artwork, though keep in mind you may end up with tenfoot artwork that is intended to be used as boxart!
| Global Config Variable | Global Menu Name | Description | Default Value |
|---|---|---|---|
SGDBDLTENFOOT |
Download tenfoot Artwork | Search SteamGridDB for tenfoot Artwork | True |
SGDBTENFOOTDIMS |
Dimensions | Dimensions of tenfoot Artwork to search for | 920x430,460x215 |
SGDBTENFOOTTYPES |
Types | Type of tenfoot Artwork images to search for (animated, static, both), in order of preference | static |
SGDBTENFOOTSTYLES |
Styles | Tenfoot Artwork Styles to search for (can reduce to refine search) | alternate,blurred,white_logo,material |
SGDBTENFOOTNSFW |
Styles | Allow Not Safe for Work (NSFW) artwork, which may contain nudity | any |
SGDBTENFOOTHUMOR |
Humor | Allow searching for artwork tagged with "Humor" | any |
SGDBTENFOOTEPILEPSY |
Epilepsy | Allow searching for art which may not be safe for epilepsy | False |