1 files changed, 39 insertions, 0 deletions
diff --git a/games/README.md b/games/README.md
new file mode 100644
index 0000000..26e592e
--- /dev/null
+++ b/games/README.md
@@ -0,0 +1,39 @@
+# games
+
+A game launcher on DP-1: an endless horizontal strip of small slanted
+tiles along the bottom, and the selected game, the one at the centre,
+shown large above it in Steam's wide hero art with its title. Installed
+games come first, most recently played first; owned games that are not
+installed follow, greyed and framed in peach. Non-Steam shortcuts added to
+Steam count as installed. A short library repeats to fill the loop.
+
+Left and Right or the wheel move, Enter or a click on the centre tile
+launches, a click on another tile selects it. Typing filters by name.
+Escape or a click on the background closes. Everything goes through
+`steam -silent steam://...`, so the Steam window stays down: `rungameid`
+for an installed game or shortcut (keeping its Proton and launch options),
+`install` for one that is not.
+
+`games.py` reads, on every opening:
+
+- installed games from the `appmanifest_*.acf` files of every library in
+  `steamapps/libraryfolders.vdf`, leaving out Proton and the runtimes;
+- shortcuts from the binary `userdata/<account>/config/shortcuts.vdf`,
+  whose game id is `appid << 32 | 0x02000000`;
+- covers and hero art from Steam's own `appcache/librarycache`, so
+  nothing is fetched for them. A tile with no cover shows the initial.
+
+Owned games need the Steam Web API (`IPlayerService/GetOwnedGames`), so
+they come from `~/.cache/keystone/games/owned.json`, which
+`games.py --refresh` rewrites in the background on every opening. The API
+key is read with `pass show "$GAMES_PASS_ENTRY"`; the SteamID is derived
+from the userdata account directory.
+
+## Running
+
+    qs -p ./games
+    qs -p ./games ipc call games toggle    # bound to XF86Search
+
+## Check
+
+    /usr/bin/python3 games/games.py --check