DroidDeck/docs/development/added-games.md

Added games

Windows games the user adds to DroidDeck's Games tab, each a non-Steam shortcut in the Steam client that runs under droiddeck-proton-arm64. They show with the Custom chip.

Adding

• + beside "Games N" opens the in-app picker (ExePickerDialog, never Android's system picker): the storage rows (Internal storage, each card, free space), then the chosen storage from its root: every folder A-Z (dot-folders hidden, unreadable ones greyed), .exe files only. The dialog keeps the width it opened with; long names are cut short; it grows to 70% of the screen and scrolls. Red X closes; B / Back goes up a folder, then closes.
• Picking an exe (AddedGames.addExe): the game it already is gets selected; an exe in a listed game's folder becomes that game's target; otherwise the exe's folder becomes a game (files/added-exes.json), registered at once (the listing the shortcuts writer reads, and a running client over DevTools) and selected. A path the session cannot see (internal storage maps to /root/Storage; cards only through Games folders, the Steam library and store roots) is refused with one line.
• "Add all games in this folder" (top row of a folder with subfolders, AddedGames.addFolder): each subfolder with an exe becomes a game with GameExePicker's best exe, kept as an entry of its own (not a Games folder); subfolders already listed are counted, not added. A summary follows: games added, how many were there already, one row per game (cover, name, exe, "?" when unsure); a row opens that game's editor, straight on Target when unsure, with back to the summary.
• Games folders added before this (Steam settings had a Games section) are migrated once (GamesFolderMigration, at app start and before any scan): each game in one becomes an entry as "Add all games in this folder" would make it, keeping everything keyed by its folder (the chosen exe, the shortcut appid, name, Start in, launch options, art, a removal). The folders stay bound into the session at the guest paths they had (/root/Games/<name>, SessionPrefs.gameFolderBinds), so no exe path or shortcut changes. They are no longer Steam libraries - the session's library list leaves them out and droiddeck-steam-library forgets them - unless Steam installed a game into one (a manifest in its steamapps/), which then stays a library. Log: games: migrated <root> → N games.

Exe and name

GameExePicker walks up to five folders down (nearest first, 400 entries, no symlinks, past installer / redistributable / extras folders), drops junk exe names and scores the rest (named after the folder, Unreal -Shipping and Binaries/Win64, bin/, launchers and junk lower, deeper lower, bigger higher). Best under 60, or a runner-up within 15: uncertain, shown as "?". GameIdentifier / PeVersionInfo give the title (Steam manifest by installdir, GOG info, the exe's version resource), else the folder name. The shortcut appid is stored per folder at the first scan and never changes after.

Editor

The ✎ on a Custom game's page (AddedGameEditor) mirrors Steam's Properties for a non-Steam game: Name, Target (ranked exes, "?", Other exe… opening the picker in the game's folder), Start in (automatic = the exe's folder), Launch options, Artwork (Cover, Wide cover, Background, Logo, Icon, each with its thumbnail and source), and Remove (two presses; the files stay; adding it again brings it back). AddedGameEdits writes each change through the same shortcut: the listing (name, exe, dir, launch, art, the stored appid) and, with a client running, SetShortcutName / Exe / StartDir / LaunchOptions and SetCustomArtworkForApp / SetShortcutIcon on that appid. A new target updates the existing shortcut; there is never a second one.

The shortcuts writer (droiddeck-steam-shortcuts) keeps what the user set in Steam: a field follows the app only while Steam still has what the app last asked for. It records Steam's AppName, Exe, StartDir and LaunchOptions in .droiddeck-shortcuts.json; a scan takes a Steam-side edit over as the app's own once (AddedGames.adoptSteamEdits), so one value holds on both sides.

Art

Automatic: the game folder's own images, then Steam (the appid the files name, else a store search whose result has the same name), then SteamGridDB, then the exe's icon. The art chooser (an Artwork row) shows the game folder's images, Steam's official piece and SteamGridDB's best few (fetched when it opens); a tap applies one, "Search SteamGridDB…" opens a search (it starts with the game's name and opens the match at once when one is exact; it lists every image SteamGridDB returns for the slot, up to four pages of 50), "Pick image…" takes a file through the same picker (png, jpg, jpeg, webp, ico), "Reset to automatic" drops the choice. A choice is a copy in files/added-art/<appid>/chosen-<slot>.<ext>, its source in the preferences.

SteamGridDB failures are told apart (SteamGridDb.Status: no key, key refused, rate limit, offline, server, no match for the game) and shown under the SteamGridDB images instead of leaving the row out. The SteamGridDB game id is remembered per game in added-art/<appid>/sgdb-id; "none" (SteamGridDB has no such game) is kept for a week, but a failed request is never written as "none", a "none" older than the saved key is asked again, and the chooser always asks again when the user opens it. A background pass stops asking SteamGridDB after its first failure.

Steam games (installed through Steam, not Custom) get the same ✎ on their page: an Artwork-only editor (SteamGameArtEditor) with the same rows and the same chooser (Steam's official piece, SteamGridDB's best few, "Search SteamGridDB…", "Pick image…", "Reset to automatic"), shared through ArtTarget. A choice is a copy in files/steam-art/<appid>/chosen-<slot>.<ext> (SteamGameArt); Library.steamGames shows it in place of the librarycache image, and with a client running the Cover / Wide cover / Background / Logo is also set in Steam (SetCustomArtworkForApp / ClearCustomArtworkForApp). Icon is launcher-only.

SteamGrid keeps both sides in step through the client's grid folder (userdata/<account>/config/grid, <appid>p, <appid> for the wide cover, _hero, _logo), for Steam and Custom games alike. A choice is written there at once, so it reaches Steam while the client is closed. Every library scan (Library.launchableGames) compares the folder with what was last written or read (grid-<slot> in the game's art folder): a file Steam changed becomes the choice (source Steam), a file removed in Steam drops it, and files the shortcuts writer placed itself (.droiddeck-art.json) are not mistaken for choices. A chosen image is stored as chosen-<slot>-<time>.<ext>, so a new choice has a new path and shows at once. Installed GOG, Epic and Amazon games get the same rows through StoreGameArtEditor.

"Adjust logo" (last row of every art editor, LogoPositionDialog) shows the game's Background with its Logo on top and lets the logo be pinned to one of Steam's five places (top left / top center / center / bottom left / bottom center) and resized (10-100 %). The value is Steam's own {"nVersion":1,"logoPosition":{"pinnedPosition","nWidthPct","nHeightPct"}} (LogoPosition). It is kept in the game's art folder (logo-position), written to <appid>.json in the grid folder (other keys in that file are kept; clearing the position removes the file only when nothing else is in it), and, with the client running, set through SetCustomLogoPositionForApp / ClearCustomLogoPositionForApp. SteamGrid.sync takes over a position changed or removed in Steam the same way it does for images (grid-json holds the last seen signature). Reset removes the custom position so Steam's default comes back.

Setup › Launcher › Games holds the Artwork switch (automatic fetching) and the SteamGridDB API key: the user's own, sealed with CredentialCipher, wins over the build's (BuildConfig.SGDB_API_KEY from the SGDB_API_KEY secret); with neither, SteamGridDB is skipped.

Tests

AddedExesTest, AddedGameEditsTest (bulk add and skip, edits to the listing on a stable appid, Steam-side read-back, art choice and reset), AddedGamesCandidatesTest, AddedGameArtLookupTest (key precedence), SteamGameArtTest (Steam game art choice and reset), SteamGridTest (grid folder both ways), GameIdentifierTest, PickListingTest, and tools/tests/test_steam_shortcuts.py for the writer.