runi-dist/docs/ubisoft-connect.md

Ubisoft Connect integration

User flow

Use + → Ubisoft Connect for the shortest path, or Tools → Stores to return to the same manager later.

1. Choose Install Automatically to download the official Ubisoft Connect installer and run its silent install into a dedicated managed prefix, or choose Import Existing Prefix. Imported prefixes remain user-owned.
2. Open Ubisoft Connect. The real client UI appears for login and game installation; Runi neither stores credentials nor copies login tokens.
3. Close the client. Runi scans its local Wine registry, configuration catalogue and local launcher storage, then shows every detected game for review. Nothing is imported without that review.
4. Imported titles appear under platform PC and store Ubisoft. Play uses the Ubisoft deeplink directly; routine game launches do not require navigating the store UI.

The integration is launcher-light, not fully headless: authentication, account security prompts, updates and game installation still belong to Ubisoft Connect. Once authenticated, a normal game launch only sends the deeplink.

Shared prefix and runner

One Ubisoft installation owns one dedicated prefix. Every linked Ubisoft game stores only a [store_binding] reference to it. The manager's Change Runner action therefore changes the runtime for all linked games together. Runi does not mix standalone Windows games into this prefix.

This ownership boundary has deliberate safeguards:

• only one game may be active in the shared prefix at a time;
• deleting a game never deletes the shared prefix;
• the integration cannot be removed while games still reference it;
• per-game .pfy export refuses shared store prefixes;
• Doctor reports a missing binding, prefix, launcher or provider mismatch;
• a managed prefix is deleted only through a separate explicit confirmation;
• an imported external prefix is never deleted by Runi.

Removing a linked game from the GUI removes only its Runi registration by default. An optional Open Ubisoft Connect to uninstall the game action sends uplay://uninstall/<install-id> to the launcher in the shared prefix. Ubisoft Connect remains responsible for the confirmation and file removal; Runi never deletes the game's directory directly. If that flow cannot be opened, the registration is kept so the operation can be retried.

Launch and cloud sync lifecycle

Play resolves the store installation and runs upc.exe uplay://launch/<ubisoft-id>/0 through its selected Proton runner. The bootstrap process is not considered the game. Runi watches the executable names recorded during discovery and scopes them to the shared prefix when process environment data is available.

Once a real game process has been seen and then exits, the library shows a 30-second cloud-sync countdown. At the end Runi closes the launch session. Choose Keep Open to leave Ubisoft Connect running and release the game card immediately. If no game process is ever detected, Runi does not guess that cloud sync has begun; the user can stop the session explicitly.

After a session closes, local data is scanned in the background. The review dialog appears only when genuinely new games are found.

Cover discovery asks the Ubisoft Store for the exact master product first and uses its official vertical boxshot. The resolved ecommerceMasterId is kept as identity.ubisoft_store_product_id; it identifies the installed store edition without replacing the canonical Runi game identity. If the store has no unique exact product, Runi tries an exact SteamGridDB match and then an exact Steam Store match. The horizontal Ubisoft Connect background is not used as a cover, and vague title matches are never accepted merely to fill a card.

Local identities

Each registration keeps two different identities:

• game.installation_id: the UUID for this concrete Runi registration;
• identity.runi_game_id: Runi's canonical game identity, reused across reinstalls and store aliases.

Ubisoft's launch, space and installation IDs are aliases attached to the canonical identity. Removing and re-adding a title can therefore reconnect to the same game identity without depending on its old config filename. The Ubisoft Store product ID is a separate edition-level alias: Standard, Deluxe and other commercial editions may have different product IDs while sharing the same canonical game.