Add Non Steam Game
Adding a Non-Steam Game to Steam using SteamTinkerLaunch can be done either completely via Command Line or via GUI.
Ensure that the Steam Client is closed before attempting to add any shortcuts.
SteamTinkerLaunch takes in information about the shortcut you want to add, and writes it out to the shortcuts.vdf file. This is a binary file using Valve's proprietary Valve Data Format (VDF), and is not easily editable. You can find this file by running steamtinkerlaunch opengridfolder and going one directory up.
In the majority of cases, SteamTinkerLaunch's Non-Steam Game defaults will attempt to match the Steam Client's default behaviour, including from the UI. The only required field to pass to SteamTinkerLaunch is the EXE, the other fields will be inferred when the shortcut is created. Every other field is optional!
Non-Steam Games by default will not use any compatibility tool, including SteamTinkerLaunch. In fact, once added, these tools don't need to use SteamTinkerLaunch at all. You can use any compatibility tool you like to run your game.
If you modify the "Start In" path (or StartDir field in shortcuts.vdf), please make sure that it has quotes around it, otherwise some tools including SteamTinkerLaunch may fail to start the game in the correct directory.
The GUI can either be started via commandline steamtinkerlaunch addnonsteamgame or steamtinkerlaunch ansg without any further arguments, or with the additional -ep=|--exepath= parameter plus a gui parameter.
There is also an option on the Main Menu as an Extra Button to launch the Add Non-Steam Game GUI.
The only field you have to specify here is the EXE. You can also drag the executable into window and drop it on top of the file picker box. The game name will be inferred from the EXE name, and the Start Directory will be set as the executable's directory. For example, if the executable is in /home/gaben/Games/GOG/Cat Quest/CatQuest.exe. the StartDir will be /home/gaben/Games/GOG/Cat Quest.
The executable does not have to be a Windows executable, it can be a native Linux binary, a script, an AppImage, and so on.
When setting the game artwork, SteamTinkerLaunch will change the name so that it uses the correct format expected by Steam, including adding the AppID. Therefore, it doesn't really matter what name you give your source artwork files, as they will get renamed and moved into the Steam Grid artwork folder.
All SteamGridDB artwork is downloaded based on the settings on the Global Menu. To use SteamGridDB, you must have configured a SteamGridDB API key globally for SteamTinkerLaunch. For more information on SteamGridDB usage with SteamTinkerLaunch, see the SteamGridDB wiki page.
If the SteamGridDB checkbox is not enabled, no artwork will be fetched from service. Unlike on the commandline, you must enable the checkbox in order to fetch artwork from SteamGridDB.
If only the checkbox to use SteamGridDB is enable and no other fields are passed, SteamTinkerLaunch will search SteamGridDB using the App Name. This may not always return any artwork, so if no artwork is found, no artwork will be downloaded. Therefore, it is a good idea to pass at least a fallback ID.
When no match is found on the Custom Search Name
When passing fields, the order of priority is as follows:
- If a Custom Search Name is entered, the App Name will be ignored.
- If no artwork is found on Custom Game Name, or if it is not passed, fall back to the Steam AppID.
- If no artwork is found for Steam AppID, no artwork will be downloaded.
- If Steam AppID is not passed, search on SteamGridDB Game ID.
- If no artwork is found on SteamGridDB Game ID, no artwork will be downloaded.
Simply enabling SteamGridDB and allowing it to fall back to searching on the App Name is very useful for getting artwork quickly with as little friction as possible. If your game is very exact, such as "Tokyo Xanadu eX+", it makes sense to just check the box and add the shortcut, as SteamGridDB is likely to find it. However it may not always return artwork, or it may find the wrong game. As a result, the name you want to search SteamGridDB on for artwork may not match the name you want to show up in your Steam Library. You may even want to name your Non-Steam Games differently. For this reason, we have the Custom Name Search option.
One reason for using the Custom Search Name is if you want to give your game one name, but you want to do a fuzzy search on another. For example, if you're adding "Sonic Colors: Ultimate" (PC game) as a Non-Steam Game, but you want to download artwork for "Sonic Colours" (PAL Wii game), you can tell SteamTinkerLaunch to search on the name "Sonic Colours" which will return different artwork. Some editions of games may have different artwork that you prefer, or you may want artwork from an edition of a game that is different than the one you are adding. Using a fuzzy-name search is easy, but may not always be exact.
If you want an exact game match, that's where the Steam AppID and SteamGridDB Game ID come in. If no match is found on the Custom Search Name, it will fall back to the Steam AppID, or if that is not specified it will use the SteamGridDB Game ID. This can be good as a backup. For example if you want to search on "The Elder Scrolls IV: Oblivion", but if no artwork is found, you can fall back to searching on the Steam AppID 22330.
You can find the AppID for an installed game in your library with steamtinkerlaunch getid "Game Name". You can also see it when you launch a game with SteamTinkerLaunch in brackets beside the name, i.e. Half-Life (70). Another place you find the Steam AppID is in the URL for the store page, for example the 70 in the URL for the "Half-Life" store page: https://store.steampowered.com/app/70/HalfLife/.
To find the SteamGridDB Game ID, you can use steamtinkerlaunch sgdbid "Game Name", which will return the best-match SteamGridDB Game ID based on the entered name. You can check which game this corresponds to from the SteamTinkerLaunch log, or by pasting it into the URL https://steamgriddb.com/game/<id>.
The artwork folder is typically located at ~/.local/share/Steam/userdata/<userid>/config/grid. You can open it with a SteamTinkerLaunch command: steamtinkerlaunch opengridfolder, or simply steamtinkerlaunch ogf. If you really want to, you can set artwork manually by copying over your own artwork with the AppID SteamTinkerLaunch uses after-the-fact using the file names that Steam expects, for example (replace 1234 with the actual AppID)
-
1234_hero.jpg- Hero artwork -
1234_logo.jpg- Logo artwork -
1234p.jpg- Boxart (Horizontal Grid) artwork -
1234.jpg- Tenfoot (Vertical Grid) artwork
To change an icon, you can opeen the Steam Properties dialog and click on the icon box under the "Shortcuts" tab. It is the box to the left of the game name textbox.
For Command Line usage, you can use steamtinkerlaunch addnonsteamgame or steamtinkerlaunch ansg, followed by some of these parameters. Again, the only required field here is the EXE, the other fields requried by Steam (App Name and Start Dir) will be inferred from the EXE path. Many of these do not need to be given, but can be useful for some advanced use-cases.
These settings can be updated from the Steam Client if you need to change them in future, or if you make a mistake. Note that all paths passed to this command from the commandline should be absolute paths.
Adding games from the commandline can be useful for advanced users to quickly add games without navigating a UI, and can also be used for custom automated scripts. For example, third-party projects such as Horizon Scripts use SteamTinkerLaunch's Non-Steam Game command as part of a larger program!
Below is a table detailing the flags for configuring the Non-Steam Games properties, such as the Game EXE, StartDir, and compatibility tool. These are equivalent to the options that would be used
| Flag | Description | Example |
|---|---|---|
-an=, --appname=
|
Name to display in Steam. Defaults to executable name | --app-name="Carmageddon Max Pack" |
-ep=, --exepath=
|
Absolute path to executable | --exepath="/home/gaben/Games/GOG/Carmageddon Max Pack/DOSBOX/dosbox.exe" |
-sd=, --startdir=
|
Directory for the executable to run inside of. Defaults to same directory as executable, which Steam also uses. This is safe to leave blank | --startdir="/home/gaben/Games/GOG/Carmageddon Max Pack" |
-ip=, --iconpath=
|
Absolute path to icon file. Filetype should be .ico, .jpg, or .png. |
--iconpath="/home/gaben/Games/GOG/Carmageddon Max Pack/goggame-1207659047.ico" |
-lo=, --launchoptions=
|
Launch options string to use for the game. | --launchoptions="gamemoderun" |
-hd=, --hide=
|
Mark a game as "Hidden" in your Steam library. | --hide=1 |
-adc=, --allowdesktopconf=
|
Use Desktop Controller Configuration in Launcher, equivalent to the same Steam Properties setting (under Properties -> Controller). Default is enabled. | --allowdesktopconf=0 |
-ao=, --allowoverlay=
|
Enable Steam Overlay. Default is enabled. | --allowoverlay=0 |
-vr=, --openvr=
|
Include game in VR Library. Default is disabled. | --openvr=1 |
-t=, --tags=
|
Comma-separated tags/categories to set for the Non-Steam Game. | --tags="Shortcuts" |
-ct=, --compatibilitytool
|
Internal name of the compatibility tool to set for the Non-Steam Game. If not specified, no tool will be used, meaning Windows programs will not run. You can specify a tool name such as GE-Proton8-20, Proton-stl for SteamTinkerLaunch, or default for the global default Proton version. |
--compatibilitytool="proton_8" |
When adding a Non-Steam Game, you can addd some artwork to be displayed for the game in your Steam library. This can be done by either manually specifying paths to specific artwork files, by telling SteamTinkerLaunch to look in the same folder as the game executable for artwork to use based on the filename, or by searching on SteamGridDB to automatically download the best-match artwork to use.
By default, no artwork will be used, so this is useful for adding some color to the games added to your library. Just like the shortcuts themselves, this artwork is local to the machine you're using and will not sync across devices.
You can specify the location of artwork files for SteamTinkerLaunch to use. It can copy, move, or symlink these files into Steam's internal grids folder, where it looks for artwork to display. Such artwork includes heroes (banner), logos, icons, and tenfoot (horizontal grids).
If you specify the --auto-artwork option, SteamTinkerLaunch will look for image files in the same folder as the game executable named hero, logo, boxart, icon, tenfoot and will use it for the respective artwork types. The default method is to copy these files, but you can specify if you want to use symlinks, which may make it easier to update artwork later on, or if you want to move the files entirely.
Sometimes games come with some artwork, for example many GOG games will include icon files. Outside of this, one place you can manually get artwork from is SteamGridDB. Although SteamTinkerLaunch does offer automatic downloading, you may wish to search for and download specific artwork yourself.
Many of these flags are identical to the ones for the Custom Game Artwork function.
| Flag | Description | Example |
|---|---|---|
-hr, --hero=
|
Absolute path to Hero / Banner image to use in Steam library for the game. | --hero="/home/Gaben/Pictures/Steam Grids/Carmageddon/cmdn_banner.jpg" |
-lg, --logo=
|
Absolute path to Logo image to use in Steam library for the game. This is displayed overtop the hero in the Steam library. | --logo="/home/Gaben/Pictures/Steam Grids/Carmageddon/761204.jpg" |
-ba, --boxart
|
Absolute path to Boxart / Vertical Grid image to use in Steam library for the game. This is displayed in the Steam library home screen as the horizontal artwork. | --boxart="/home/Gaben/Pictures/Steam Grids/Carmageddon/cover.jpg" |
-tf, --tenfoot=
|
Absolute path to Tenfoot / Horizontal Grid image to use in Steam library for the game. This is displayed as the banner on the Steam library home screen as the most recently played horizontal banner artwork. | --tf="/home/Gaben/Pictures/Steam Grids/Carmageddon/banner_xs.jpg" |
--auto-artwork |
Automatically use artwork from the same folder as the game executable as the Hero, Logo, Boxart, and Tenfoot. If there are files named hero, logo, boxart, tenfoot, they will be picked up and used as the respective artwork types, which means you don't have to specify the paths manually. |
--auto-artwork |
--copy |
Specify that source artwork files should be copied to the Steam grids folder. | --copy |
--move |
Specify that source artwork files should be moved to the Steam grids folder. | --move |
--symlink |
Specify that source artwork files should be symlinked to the Steam grids folder. | --symlink |
SteamGridDB artwork is downloaded following the configuration options set on the Global Menu, including the required API key. For more information about configuring SteamGridDB, see the SteamGridDB wiki page. By default, all SteamGridDB integration is disabled when adding Non-Steam Games.
When adding a Non-Steam Game, if you only enable SteamGridDB but don't pass any other parameters (such as ID or name), it will default to searching on the --appname. This can be useful if you want to quickly add a lot of games, but keep in mind that this will search SteamGridDB and return the best match, which may not always be exact. Sometimes, no match will be found at all. Therefore, it is useful to pass at least one ID to search on as a fallback if no ID is found for the given name.
The order of priority with how artwork is searched is the exact same as on the GUI, where the following will be prioritised:
- First will attempt to search on Custom Search Name.
- If Custom Search Name is blank or no Game ID is found, we will search on either the Steam AppID.
- If no Steam AppID is specified, we will search on SteamGridDB Game ID.
- If no Custom Search Name, Steam AppID, or SteamGridDB Game ID is passed, we will fall back to the app name.
One thing to note which is different from the GUI is that if you pass any SteamGridDB field (Search Name, Steam AppID, SteamGridDB Game ID), then SteamGridDB will be enabled by default. You do not have to explicitly specify --use-steamgriddb if you pass any of these options. However, if you don't want to specify any options and simply wish to search for artwork based on --appname,, you will need to pass --use-steamgriddb.
| Flag | Description | Example |
|---|---|---|
--use-steamgriddbb |
Used to enable searching for artwork on SteamGridDB. This is not necessary if any of the below flags are used, but if none are specified, this flag is required in order to fall back to --appname. |
--use-steamgriddb |
--steamgriddb-game-name= |
Custom name to search for on SteamGridDB. This is useful if you want artwork for, say, "The Elder Scrolls IV: Oblivion - Game of the Year Edition", but you simply want the name of your game in your library to be The Elder Scrolls IV: Oblivion. The more precise you can make this name, the better. It is equivalent to taking the first result from the search box of SteamGridDB.This artwork will take priority over --appname, but if no artwork is found using this name, it will fall back to either Steam AppID or SteamGridDB Game ID, in that order, but not both. |
--steamgriddb-game-name="The Elder Scrolls IV: Oblivion" |
--steamgriddb-steam-appid |
Search SteamGridDB for artwork using Steam Store AppID. This is useful for being explicit and matching exact game artwork, so instead of searching on a fuzzy name, you can match an exact version of a game using the Steam Store AppID. If this option is specified with a SteamGridDB Game ID, this AppID will take priority over the SteamGridDB Game ID. |
--steamgriddb-steam-appid="1961950" |
--steamgriddb-game-id |
Search SteamGridDB for artwork using the SteamGridDB Game ID. This is useful for matching an exact version of a game as hosted on SteamGridDB, such as getting artwork for "Sonic Colors" (Wii game) instead of "Sonic Colors: Ultimate" (PC port), where the former may have more artwork available. It is also good for being explicit in place of a Steam AppID, when a game may not be available on Steam, or when a different version of game than the one on Steam has a better selection of artwork. | --steamgriddb-game-id="5250151" |
When using SteamGridDB, all configuration options from the Global Menu will apply. However, because you can set icons for Non-Steam Games (this is not possible with Steam games), SteamTinkerLaunch will attempt to download and set the icon for the game from SteamGridDB. This cannot be toggled currently.
It would be possible to integrate these options into a script, where perhaps you bulk-add games and use the folder name as the name to search SteamGridDB on. Or you could have a big CSV file and loop through that, with the SteamGridDB Game ID/Steam AppID specified already. You could plug that into one of the ID flags and automatically get artwork for your bulk-added Steam games. Just keep in mind potential rate/usage limits with SteamGridDB. Bandwidth is expensive!
A working example for a bare minimum command line is:
steamtinkerlaunch ansg -ep=/media/B4-1/GOG/Pirates\!/start.shHere, the game will be added with the title "start.sh" to the Steam Library, as no -an was provided. The Start Directory (-sd) will default to the game directory will be used automatically.
A more in-depth example would be the following:
# Add the game "Cake Mania" to Steam with manual artwork paths
steamtinkerlaunch addnonsteamgame --appname="Cake Mania" --exepath="/home/gaben/games/Cake Mania/CakeMania_data.exe" --startdir="/home/gaben/games/Cake Mania" --iconpath="/home/gaben/games/Cake Mania/icon.png" --compatibilitytool="default" --hero="/home/gaben/games/Cake Mania/hero.png" --logo="/home/gaben/games/Cake Mania/logo.png" --boxart="/home/gaben/games/Cake Mania/boxart.png" --tenfoot="/home/gaben/games/Cake Mania/tenfoot.png" --copyIf no compatibility tool is provided, then no compatibility tool will be selected for the game when it is added to Steam, even if you have added what might be a Windows program that you would expect to use under Wine. The Steam Client does not set a compatibility tool automatically for Non-Steam Games, therefore SteamTinkerLaunch also does not.
If you try to run a Windows program without setting the compatibility tool, it will attempt to launch it with whatever program your system would default to launching it with. In the case of Windows EXEs, it will try to use your system Wine. This may be desirable in some advanced circumstances!
# Adding the game "Diablo" to Steam with the compatibility tool "Luxtorpeda" set by default
steamtinkerlaunch addnonsteamgame --appname="Diablo" --exepath"/home/gaben/games/GOG/Diablo/Diablo.exe" --compatibilitytool="Luxtorpeda" --use-steamgriddbIf the checkbox is enabled on the GUI, or if --auto-artwork is passed to the command, SteamTinkerLaunch will look for and prioritise artwork found in the same folder as the game executable. The filenames it looks for are icon, hero, logo, boxart, and tenfoot, which match the names of the selection boxes on the GUI as well as the internal Steam names. This option will respect the Game Artwork Copy method.
This artwork, if found, will take priority over the selected/entered artwork. So if you were to select a logo file, but there is a logo.png in the game EXE directory already, the selected one will be ignored in favour of the one in the EXE directory. If the artwork is not found, the selected file will be used.
SteamTinkerLaunch will try to ensure that these files are image files, but will not check whether Steam will accept them. If in doubt, make sure you use standard image formats like png, jpg, or gif.
# Add the same game as above, but try to automatically pick up artwork in the executable's folder
steamtinkerlaunch addnonsteamgame --appname="Cake Mania" --exepath="/home/gaben/games/Cake Mania/CakeMania_data.exe" --startdir="/home/gaben/games/Cake Mania" --auto-artwork --copyWhen passing game artwork, any existing files will be preserved and will not be overwritten.
When displaying artwork, Steam will prefer JPEG image files over PNG image files (including APNG) for hero/logo/banner/artwork, and ICO files over other icon files. If you are not seeing expected artwork you may want to check the Steam grids folder (can be easily done with steamtinkerlaunch ogf) and check which image files are there.
It should also be noted that Steam does not display files other than JPEG and PNG files. They will not be read by the Steam Client if put in the grids folder, and Steam will tell you the file type is invalid if you try to set this manually.
This preference is my own observation during tests, and is not documented by Steam as far as I know, so it is subject to change in the future. In general though, it's best to only have one set of artwork in a consistent format.
Some examples of using SteamGridDB to add artwork when adding a Non-Steam Gameare below:
# Search with Game Name and fall back to SteamGridDB Game ID
steamtinkerlaunch addnonsteamgame --appname="Cake Mania" --exepath="/home/gaben/games/Cake Mania/CakeMania_data.exe" --startdir="/home/gaben/games/Cake Mania" --steamgriddb-game-name="Cake Mania" --steamgriddbb-game-id="7258"
# Search just on app name "Cake Mania", and if no artwork is found no art will be saved
steamtinkerlaunch addnonsteamgame --appname="Cake Mania" --exepath="/home/gaben/games/Cake Mania/CakeMania_data.exe" --startdir="/home/gaben/games/Cake Mania" --use-steamgriddbNOTE: Providing the Steam AppID will NOT work here!! Make sure you are providing the SteamGridDB Game ID.
All games on Steam have an internal, unique "AppID" that Steam uses to keep track of them. For games available for purchase on Steam, this is a fixed ID that is the same for everyone and all devices. However, Non-Steam Games do not have such a limitation. The AppID for Non-Steam Games is not fixed and is controlled by a setting in the binary shortcuts.vdf file. This Non-Steam AppID is stored in hexadecimal, and represents a 32bit little endian signed integer.
When you add a Non-Steam Game using the Steam Client, it will generate a random AppID each time and write it to shortcuts.vdf. This can be seen by launching the game with SteamTinkerLaunch and noting the AppID each time. It can also be seen in the prefix name (see below).
However, when adding a Non-Steam Game using SteamTinkerLaunch, we generate a fixed AppID based on the game name and path. This means the AppID should always be unique, but will also be consistent each time you add the shortcut. This has the advantage of generating a predictable AppID each time. We generate it and convert it into the format expected by the shortcuts.vdf file, and Steam is then able to use that AppID for controlling things like game artwork, Proton prefix name, etc. Being able to control this AppID is how SteamTinkerLaunch is able to do things like set artwork and the compatibility tool of a shortcut.
This AppID is written out just like all other Non-Steam Game fields as an entry of the shortcuts.vdf file.
To see the code for installing Non-Steam Games, check addNonSteamGame for the core logic, and addNonSteamGameGui for the UI portion of the code. There are also various helper utilities for parsing and writing out to VDF files which you can check out too if you'd like.
You could use these functions to write your own script to generate the Non-Steam AppID that SteamTinkerLaunch would ahead-of-time, if you need to know it. For example, if you're writing an automated script to use a Non-Steam Game at a fixed path with a fixed name (such as on Steam Deck, where the user is always deck), this could be used to have the AppID SteamTinkerLaunch will use before you even add the shortcut.
If you know how to modify the shortcuts.vdf file, this means you could generate your own AppID and overwrite the file.
There is a GitHub Gist (written by me, sonic2kk) that allows you to get all of the AppIDs for Non-Steam Game shortcuts. You can find out what games these correspond to by pasting the AppID into the Steam Client search bar, as Steam also allows you to search for games by AppID.
In future, functionality related to this is planned to be incorporated into SteamTinkerLaunch.
Proton prefixes for Non-Steam Windows games are always stored on your base Steam library path, for example, /home/gaben/.local/share/Steam/steamapps/compatdata. These directories are not removed when a shortcut is removed automatically.
The Steam Client will generate a different AppID each time, so you can end up with many useless prefixes. You will have to manually remove them if you want to save some disk space.
When using SteamTinkerLaunch to add Non-Steam Games, if the name and path is exactly the same each time, the AppID will remain the same and so Steam will re-use the Proton prefix. This can be useful if you need to re-add a game but want to keep the prefix around, but could lead to unexpected behaviour if you want to simulate a full re-install of a game.
In short, if you want to remove a Non-Steam Windows game entirely, you'll have to not only remove the shortcut but also remove the compatdata directory as well.
Since the Non-Steam AppID that SteamTinkerLaunch generates is the same each time, this means that just like the prefix name being the same each time, the entry in config.vdf will be the same. However it is important to note that if you remove shortcuts.vdf to remove all shortcuts instead of doing it from the Steam Client, the compatibility tool mappings will not update.
As a result, if you try to add a game in future with the same name and path, the same compatibility tool from before will be used. If you used proton_8 before, and try to add the same game again but with GE-Proton8-20 as the compatibility tool, the entry will already exist in config.vdf and SteamTinkerLaunch will not overwrite it. Therefore your Non-Steam Game will still use the previous proton_8 compatibility tool, and you'll have to manually update it from the Steam Properties dialog.
When a Non-Steam Game is added, you must restart Steam to make the newly added shortcut available. This is because Steam does not re-check the contents of various VDF files (including shortcuts.vdf) until after the Steam Client is restarted.