> For the complete documentation index, see [llms.txt](https://docs.kouch.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kouch.dev/docs/game_menu_export_plan.md). # The game menu on the pause button, per-game and per-emulator exports Owner requests, 2026-09-27 (quoted where short). This addendum doesn't replace `PLAN_V2.md`, `HOME_LIBRARY_PLAN.md` or `KOD_PLATFORMS_PLAN.md`; it builds on the card menu (`d66c44a`), the `.kod` container and the export picker (`33bb659`). ## G1 The game menu on the pause button *"hitting the pause button on a controller should pop a menu to play the game, favorite it, go to emulator, add to collection, change artwork, change profile, export game data and mods, etc"* * **The pause button** (the pad's Start / Options / Menu, `NavAction "menu"`) on a focused game opens the game menu. That covers any game card (Home, Grid A–Z, Shelf, Playtime, collections, All games), a Library row, and the game page. Hold X keeps opening the same menu. * **Anywhere else** the pause button opens the main menu as today, and the top bar's ≡ opens it everywhere. * **Items, in order:** * Play; * Favorite / Unfavorite; * Add to collection…; * Tags…; * Change artwork…; * Change emulator profile… (which of the profiles for this system runs it, `rom.profile_id`); * Go to emulator (Settings › Emulators on that emulator); * Export game data and mods…; * Mark as finished; * Hide from the Library; * Game page. * **Change artwork:** candidates from SteamGridDB (the user's own key), a local image, or back to automatic. Separate slots for cover, hero, logo and icon. ## G2 Export one game (a `.kod` for a game) *"export game data and mods … the mods will export the workshop item to subscribe to, and mods not in workshop"* * **Game data:** a profile can declare which files belong to one game with `user_data.game_files`, templates over its folders (e.g. `saves/{title_id}/**`, `states/{rom_stem}*`, `config/game/{title_id}.ini`). Only those are packed. A profile without them can't split one game's saves from the rest; the sheet says so and offers the emulator export instead. * **Mods:** * Workshop mods go in as **references** (item id + the version the user has), so the importer subscribes to them. * Mods not on the Workshop are **packed as files**, data only, with the same checks as today. * **Also packed:** the game's per-game options. * **Never packed:** the game itself, `system`, `bios`, private files. * **Importing a game `.kod`** restores the files into the right paths, installs the local mods and subscribes to the Workshop ones. That needs Kouch's own app id; until then it lists them with their Workshop pages. ## G3 Export an emulator (extends the export picker) *"per emulator export data and config too, able to be choosen"*, and *"not the install files, but rather the installation source like a github repo"* (ADR 0019, as corrected) * Per emulator, choose its data folders (saves / states / screenshots) and its config, separately (the picker from `33bb659`). * **Installation sources for every platform:** the exported profile keeps every OS section's `source` (GitHub/GitLab repo + asset, a feed, Flathub). **No emulator files are ever packed.** * **The version travels as a suggestion:** `exported_version`. The import offers "Install 2.6 (the version this was exported with)" or "Install the latest". * **Windows and Linux are required in every export** (owner: "not optional, required, since a linux user might want to install"). A missing OS is filled in from the same GitHub/GitLab release, or for Linux the emulator's Flathub app. * **One clear match:** added automatically, and can be changed. * **Several matches, or an archive with an unknown program name:** the user must pick. * **No build for that OS:** the sheet says so, and the user confirms the file won't install there. * **macOS:** added when found, never required. * **Hand-installed emulators** export their path; the import asks where the emulator is. ## G4 Where exports go *"default path for exporting is the downloads folder, able to be changed by the user, and also copied to clipboard by default (the .kod file)"* * **Default folder:** the user's **Downloads** folder (not Documents\Kouch), file name `-.kod`. It changes the default path from `33bb659`. * **Settings:** * Settings › Storage (or Emulators) › **Export folder**, changeable; * **Copy exported files to the clipboard**, on by default. After an export the `.kod` is on the clipboard *as a file*, ready to paste into a chat or a folder: Windows CF\_HDROP, Linux `text/uri-list`, through a crate with a safe API (no new `unsafe`). The toast says "Saved to Downloads and copied". ## G6 Easy graphics settings, per emulator and per game *"easy changes for graphical settings inside of kouch, per emulator and per game"* * **Already built (Plan v2 Phase 7):** * A profile's `options` (tab `graphics`: resolution scale, filters, aspect, frame limit…) are applied at launch through args and config edits. * Per-emulator values live in Settings › Emulators › Options, and per-game overrides in the game page's Options tab. * **Make it easy:** * **A "Graphics…" item in the game menu (G1)** and in the Quick Menu: a short sheet with only that game's graphics options, each marked "Emulator default" or overridden, and one **Reset to emulator default**. * **In the Quick Menu,** a change applies at the next launch, with a "Restart game to apply" action. The emulator is closed gracefully and relaunched, and saving first is the user's call. * **Quality presets:** a profile can declare `presets` (e.g. Performance / Balanced / Quality) mapping to its graphics options. One choice sets them all, and individual options stay adjustable ("Custom" once changed). * **Settings › Emulators › an emulator › Graphics:** the same sheet for the emulator-wide values. * Profiles without graphics options show "This emulator's profile has no graphics settings" and a link to the creators' guide. * **Every graphics setting the emulator has** (owner, 2026-09-27, with screenshots of an emulator's own Enhancements tab): not a curated few. Each profile maps all of its emulator's graphics settings to the emulator's config, so the user changes them in Kouch without opening the emulator. They're shown in sections with the same labels across emulators: * **Renderer:** backend (Vulkan / Direct3D 11 / Direct3D 12 / OpenGL / software, whatever the emulator has), shader compilation and cache. * **Resolution:** internal resolution (native, 2x…8x, "for 1080p / 1440p / 4K"), upscaling and downscaling filters (output resampling, bilinear, bicubic, sharp, area…), aspect ratio, widescreen hack, crop. * **Image quality:** anti-aliasing (off / 2x / 4x / 8x MSAA, SSAA), texture filtering (default / 2x / 4x / 8x / 16x anisotropic), post-processing effect, colour correction, HDR, the emulator's enhancement toggles (true colour, copy filter, fog, per-pixel lighting, mipmap detection…). * **Display:** **V-Sync, off by default in every Kouch profile**, frame limit / speed, FPS counter, fullscreen mode. * **Screens and modes:** docked or handheld (consoles that have both modes), which screen is the main one and how two screens are laid out (TV / second screen, side by side, top/bottom, single), stereoscopic 3D. * **Profile schema (B):** * each option carries a `role` from a small shared vocabulary: `renderer`, `internal_resolution`, `output_filter`, `aspect`, `anti_aliasing`, `anisotropic`, `vsync`, `frame_limit`, `post_processing`, `hdr`, `docked_mode`, `screen_layout`, `stereo_3d`, `enhancement`, `other`; * an optional `section` for grouping; * `restart`: whether a change needs a restart; * `presets`. * The roles let the sheet group options, keep labels consistent, and let G5 map device presets later. * **Authoring (the private test profiles, verified live):** * Every graphics setting of each of the four test emulators is mapped to its config keys. * Each mapping is checked against the real emulator: set a value in Kouch, launch on the isolated build, read the emulator's own config back and, for resolution-type options, its screenshot. * Values the emulator writes in a different form (an exponent, an index) are mapped by the profile, never guessed. * **G5** later adds a device-class preset on top: a Deck gets Balanced, a desktop Quality, and so on. ## G5 Future: automatic graphics settings per device *"per system auto graphics settings for the future, like for steam deck too, pcs, laptops, handhelds"* * **A future update, not built now:** * Kouch detects the device class (Steam Deck / other handheld, laptop, desktop PC) from its hardware: GPU, screen and battery. * A profile can carry option presets per class, e.g. `options` presets keyed `deck` / `handheld` / `laptop` / `desktop`. * They're applied automatically unless the user has set their own values. * Designed with the Phase 7 options when it comes up. ## G7 A complete transfer: everything, to another system, chosen on arrival (the owner's goal) *"make sure .kod files can be really complete and transfer to another system, with everything mentioned like mods, graphical settings, emulators, game save data (if checked) and able to be imported to another system and that system can choose which data it wants, also able to transfer all emulators at once with the mentioned data"* * **Export (one emulator, several, or all at once).** One `.kod` holds, per emulator: * the profile with every platform's install source (Windows + Linux required, G3) and `exported_version`; * its emulator-wide settings (graphics and every other option value); * **per-game settings** (each game's option overrides); * **mods** (Workshop ones as references, the rest as files, G8); * the data folders the user checked (saves / states / screenshots / config; never `system`). * Games are identified portably (G8), never by this PC's row ids or paths. * **Import on another system (Windows ↔ Linux / Deck), choosing what to take.** The sheet lists everything in the file, emulator by emulator, each part with a checkbox and its size: * install the emulator (the latest, or the exported version); * which data folders; * emulator settings; * per-game settings; * mods. * "Take everything" is one press; nothing already there is overwritten without a prompt ("Keep mine / Replace / Keep both"). * **Games that don't match:** per-game settings and mods are matched to the importing system's own copies of the games (G8). Unmatched ones are kept aside and applied when the game shows up in a later scan. * **Verified live across systems (central):** export on Windows → import on the Deck, and back. Check the emulator installs from the other OS's source, saves land in the right folders, settings apply, and mods sit in the right per-game folders. ## G8 Mods keyed by game id and game version *"please make sure mods use game ids and versions on the data to be imported … you just put on a folder, make sure to cover this correctly"* * **Game identity:** the library records, per game, a **title id** where the system has one, and the **game version** where it can be known. Today it only has `{rom_stem}` and `{game_hash}`. * A profile declares how to read the id: from the file name (a pattern, e.g. a 16-hex-digit id in brackets), from a fixed place in the disc or file header, or from a metadata file inside a folder game. * The game version comes from the file name tag or header, when present. * Kouch reads only the game files the user pointed it at, never `system` / `bios` or the emulator's system storage. * **Placement:** the `mods.dir` template gains `{title_id}` (and `{game_version}`). Mods for emulators that load them from `//<mod name>/` go exactly there. * **In a `.kod`:** each mod records its target title id, the game version it was made for (when known), the game's hash, and the mod's own name and version. * On import it's matched by title id first, then hash. * A version mismatch is shown, not hidden: *"Made for version 1.0.2, you have 1.1.0"*. The user can still install it. * Workshop mods carry the same keys in their tags. * **Tests:** placement for title-id folders, matching by id vs hash, the version warning, an unmatched mod kept aside. ## G9 Dropping system files onto Kouch (keys, BIOS, firmware), ADR 0020 *"can we do auto import from drag and dropping into the program? for keys at least for specific emulators/systems"*, then *"i mean if the user is providing it it should be fine"* and *"research for all emus bioses, keys, etc that could be potentially auto imported from drag and drop"* * **The owner overruled part of ground rule 2** (ADR 0020). Kouch places the files the user drops, matched by name (and size where known) against the installed emulators' `user_data.system_files`, into that emulator's `system` folder, after one confirm. It copies and never moves; a name clash asks Replace / Keep mine. * **Firmware packages** go through the emulator's own installer (a declared install command, or its install dialog). * **Every other path keeps refusing `system`.** Nothing is synced, sent, packed or downloaded. There's a switch (`settings.system_files.drop_import`, default on). * **Research (central, private):** a catalogue, per common emulator, of the system files it uses: names, sizes, required or optional, region, the sub-path it expects, and whether it's a drop-in file or an installer package. It's kept as private data in `profiles/local/` and feeds each profile's `system_files`. Kouch's code only reads the profile data. ## Who and status | Part | Owner | Status | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | G1 game menu on the pause button, Change artwork / Change profile sheets | A (UI); B for `library.set_profile` and the art commands if missing | **done**: the menu (A, `6b8ba6b`), Change artwork (B `e189fde`/`0dc5291`, A `2426b45`). Live on the verify build: a local picture set as the cover, "Back to automatic", the earlier pick kept on offer, a non-image refused; the SteamGridDB half needs the owner's key and waits for them | | G2 game `.kod`: `user_data.game_files`, packing, Workshop refs + local mods, import | B (Rust); A (sheets) | **done and verified live 2026-09-27**: contract `51ede2d`, shell `1bc894a` (with \`{key | | G3 per-emulator choices, every platform's install source, `exported_version`, optional fill-in from the same release (ADR 0019 as corrected) | B (Rust) + A (sheet) | done: contract `a7ac088`, export `e806479` (Windows and Linux required, `ack_missing`, Flathub/release candidates), the export picker (A, `3e13b06`). Verified live across systems: a Windows export installed the Linux build of the same version on the Deck (`448040a`) | | G4 Downloads default, export-folder setting, clipboard file copy | C (clipboard, platform code) + B (setting) + A (UI) | done: setting + `copied` (B, 2342d58), clipboard copy (C, c6c2c1e), toast and settings (A, 3e13b06, 3e3e354) | | G6 easy graphics: the Graphics sheet (game menu, Quick Menu, emulator), sections, presets, restart-to-apply | A (UI) + B (`role` / `section` / `restart` / `presets` in the schema, restart-to-apply) | done: schema + restart (B, `69a7131`), the sheet (A, `d07528d`). Checked in the mock at 1280×800: sections, the preset and its description, V-Sync off, LB/RB, fit and align clean | | G6 profiles: every graphics setting of the four test emulators, V-Sync off by default, verified live | central (the reference emulator) + C (the other three, after G4) | central: the reference emulator **verified live 2026-09-27**: 27 graphics options from its source + a config it wrote; set in Kouch → the emulator wrote every key back exactly (Vulkan, 3×, 4× MSAA, 16×, sharp bilinear, V-Sync off, widescreen, FPS) and its screenshot is 2480×1440 = 3× of 480 lines; the owner's own emulator config untouched. C: the other three mapped (36, 43 and 16 options, with roles, sections, restart and three presets each), every key checked live by setting it, launching on the isolated build and reading the emulator's own rewritten config back; the resolution option confirmed in a screenshot. One emulator sets resolution per game through graphic packs, so it has no global resolution option. | | G7 complete transfer: all/some emulators, per-game settings, mods, chosen data; the import chooses per part; conflict prompts | B (Rust) + A (sheets) | done: contract (B, `73384cc`), the shell (B, `94a7515`), import choices and the Imported report (A, `413de85`); saving a profile or setting no longer drops fields it didn't name (B, `fd316e2`, found in the live run) | | G8 game ids + versions: per-profile id readers, `{title_id}` / `{game_version}` in mods.dir, mods matched by id then hash, version warnings | B (library + mods) + C (the profiles' readers and mods.dir) | done in the shell: identity readers (B, `a926d9a`), mods and per-game settings keyed by title id, then hash, then name (B, `94a7515`); the four test profiles' readers next (C). **Graphic-pack emulators, 2026-09-28:** mods as list entries in the emulator's own settings file (B `1e1b16c`, first-launch order `295fcb4`, children valued from the game's options `0b4dd74`; profile C `11fc1c7`). Verified live on a fresh install's first launch: the pack linked and listed with the per-game `<Preset category="Resolution" preset="1920x1080"/>` during the session; after quit only Kouch's entry removed (the emulator's rewrite kept) and the pack unlinked | | G7/G8 live: Windows → Deck and back, mods in per-game folders | central | **passed 2026-09-27**, with a three-platform test profile (file-name id reader, `{title_id}` mods, two options), a dummy game file with the same bytes on both systems, emulator values, a per-game value, a local mod, saves and config. Windows export → the Deck installed the exported version's Linux build; saves, config and the mod arrived; the game's settings waited for it and applied after the scan by title id; at launch the mod sat in the title id's folder and the emulator's config had the per-game value; quit reverted the mod. Changes made on the Deck came back to a fresh Windows instance the same way. **All emulators at once, 2026-09-27:** the four private test emulators (each installed on Windows from its real source) exported in one file after each got its Linux source (two release AppImages, two Flathub apps); on the Deck one import brought all four: the AppImages installed at the exported versions, the Flathub ones saved without touching the Deck's own Flatpaks, and every emulator's settings and saves arrived. Found there: the Flathub search called a same-named file manager the clear pick for one emulator (fixed, B `8dc20a6`: only a game/emulator app tied to the profile's own project is clear; an already-installed Flathub app is adopted, never installed twice). **The four real test emulators on Linux, 2026-09-28** (`5d69188`: C's `platforms.linux` sections, plus `read_at` system files for the two that read them from config): on the Deck each installed or adopted emulator writes its whole tree into Kouch's own `config` folder, so saves, settings and G2 game files travel from and to it. The two release AppImages go through a portable link and a working-folder `user` link. The owner's installed Flatpak of the reference emulator was adopted, not reinstalled, and runs with `-u` and per-run grants. A dummy key file sat in `config` only during the session. The owner's own emulator folders, Flatpak overrides and version were unchanged, and the Flatpak's own run cache was restored from backup. The fourth emulator (the encrypted-format system, Flathub app) was then installed through Kouch with the owner's standing OK (2026-09-28): it runs its whole tree in Kouch's `config` through a working-folder `user` link, with the owner's older emulator folders and Flatpak overrides untouched | | G9 system-file drop (ADR 0020): `user_data.system_files`, drop routing + copy into the matched emulator's system folder, installer packages via the emulator, the switch; the research catalogue | B (schema, command, tests) + A (drop sheet) + central (research) + C (the test profiles' lists) | **done and verified live 2026-09-27**: schema, drop routing and placing (B, `6715756`), the sheet with its pinned confirm row (A, `eb944b7`, `b37425a`), the research catalogue `profiles/local/system-files.catalogue` (central). Live, on the verify build through the native picker with dummy files only: name matches, a region folder, a size-only match (unticked until the user ticks it), a package routed to the emulator, an unmatched file, Keep mine, copies (the dropped files stay put); an export asked for `system` writes none of it; with the switch off the picker does not open. Next: the four test profiles' lists (C), two wording nits (A). **ADR 0020 follow-up (B `f00cb73`) verified live 2026-09-28** with a dummy key file and `read_at: "config"`: kept in `system`, copied into `config` only while the game runs (manifest written first), left out of an export of `config` made during the session, removed after quit; after Kouch was killed mid-session the leftover copy was reverted at the next start | | G5 per-device graphics presets | later | future | | Verify: exports/imports on this PC and the Deck; a carried file with a wrong hash is refused; offline warning | central | not started | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kouch.dev/docs/game_menu_export_plan.md?ask=<question>&goal=<endgoal> ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.