1.8 KiB
Game and installation identity
Runi keeps three identifiers with different lifetimes:
| Field | Scope | Example |
|---|---|---|
game.id |
Local registration and CLI name | doom-the-dark-ages |
identity.runi_game_id |
Canonical game across stores and reinstalls | pgid_… |
game.installation_id |
One concrete installation | UUID4 |
The canonical game catalog is bundled with Runi and extended locally in
~/.config/runi/game-catalog/. Entries map a PGID to strong aliases such
as Steam, GOG, Epic and UMU IDs, plus executable names used as weaker evidence.
Titles are never automatic identity evidence.
Game recipes, notes, compatibility knowledge and custom artwork use PGID. Receipts, manifests, logs, save backups and recipe drafts use installation ID. This allows two installations to share knowledge without sharing mutable state or rollback data.
Removing a registration archives its last configuration under
~/.local/share/runi/retired-installations/<installation-id>/. If the
same install directory is added again, Runi can reconnect that archived
state after validating the marker and canonical game identity. Starting fresh
creates a new installation ID and leaves the retired state untouched.
Schema v2/v3 game.uid and .runi-uid remain readable. Schema v4 writes
installation_id and .runi-installation-id; the previous config is
backed up before its first v4 save.
When a locally learned PGID is later promoted into the bundled catalogue, the bundled entry becomes authoritative for canonical metadata and collection placement while retaining the same PGID. This preserves references held by existing installations, artwork and future compatibility knowledge.