Skip to content

Play your Steam library's Windows games on a jailbroken PS5.

C++
53.9 KB
Raw Blame
#pragma once
// runtime_host.hpp - Worker-owned composition of the per-game runtime services.
// Copyright (c) 2026 Playden contributors
// SPDX-License-Identifier: MIT
#include "platform/ps5/native_coordinator.h"
#include "platform/ps5/title_registry.h"
#include "platform/ps5/title_runtime.h"
#include "runtime/game_install.h"
#include "runtime/game_settings.h"
#include "runtime/install_service.h"
#include "runtime/launch_service.h"
#include "runtime/leftover_titles.h"
#include "runtime/package_installer.h"
#include "runtime/redist_install.h"

#include <algorithm>
#include <atomic>
#include <chrono>
#include <condition_variable>
#include "runtime/layout_migration.h"
#include <cstdint>
#include <filesystem>
#include <functional>
#include <map>
#include <set>
#include <memory>
#include <mutex>
#include <optional>
#include <pthread.h>
#include <string>
#include <unordered_map>
#include <vector>

namespace playden::homebrew {

// An admitted kit: the verified view and the capabilities its manifest declares.
struct RuntimeKit {
  runtime::VerifiedKitView view;
  std::vector<std::string> capabilities;
  std::string manifest_sha256;
  std::string expected_manifest_sha256;  // the kit this build was tested with
  std::string prospero_win_revision;     // what its PS5 titles were built from
  bool source_dirty = false;
};

// A game's private bottle kept after its PS5 title was removed: its saves and
// settings, until the game is prepared again or the player deletes it.
struct KeptBottleView {
  std::string install_id;
  std::uint32_t runtime_number = 0;
  GameId game;               // from the marker; one without "store"/"game" is Steam(runtime_number)
  std::string name;          // the game's name when it was kept
  std::int64_t kept_at = 0;  // Unix time
  std::uint64_t bytes = 0;   // size when it was kept
  std::string data_root;     // the kept bottle's folder (its library/prefixes/game holds the saves)
};

// What the one-shot title remover reported: whether it was sent, its result code
// when it answered, and a diagnostic.
struct TitleRemoverResult {
  bool sent = false;
  std::optional<int> code;
  std::string detail;
};

struct RuntimeHostConfig {
  // Existing trusted parent of state_root (for example /data).
  std::filesystem::path boundary;
  // Private 0700 OWNER state: installs.json and requests/ (settings requests).
  std::filesystem::path state_root;
  std::filesystem::path homebrew_root = "/data/homebrew";
  // Host-test namespace prefix for console paths; empty on the console.
  std::filesystem::path host_namespace_prefix;
  // Empty members use the native SQLite inventory and process activity readers.
  ps5::NativeCoordinatorOperations native;
  ps5::TitleRegistry::Transport registry_transport;
  // Verifies the installed kit on the worker, or returns nothing with a reason.
  std::function<std::optional<RuntimeKit>(std::string* reason)> admit_kit;
  // Package layer paths and base operations (hashing, sync, space, bottle
  // validation). The host adds cancellation.
  runtime::PackageInstallPaths package_paths;
  runtime::PackageInstallerOperations package_operations;
  // Bundled recipes/presets/input presets (<title>/runtime).
  std::string runtime_dir;
  // gbe_fork's steam_api DLLs; empty: <runtime_dir>/steamworks.
  std::string steamworks_dir;
  // The player's saved settings for a game; nothing means Playden defaults.
  std::function<std::optional<runtime::GameSettingsRecord>(const GameId& game)> settings_record;
  // Canonical lower-case UUID for a publication transaction, or nothing when no
  // secure random source is available. Empty uses /dev/urandom.
  std::function<std::optional<std::string>()> uuid;
  std::function<std::int64_t()> unix_time;
  // Diagnostic lines (no credentials): startup, each preparation step and refusals.
  std::function<void(const std::string&)> log;
  // Held around startup and each batch of work on the worker: while the token lives, nothing
  // else may raise root, which is process-wide and would fail the worker's ownership checks
  // (ps5::HoldEffectiveUid). Empty holds nothing.
  std::function<std::shared_ptr<void>()> hold_effective_uid;
  // hold_effective_uid without waiting, for RuntimeNumberFor's callers that would rather come back
  // later than wait for a batch: sets *busy and returns nothing when another thread holds it
  // (ps5::TryHoldEffectiveUid). Empty: RuntimeNumberFor waits, with hold_effective_uid.
  std::function<std::shared_ptr<void>(bool* busy)> try_hold_effective_uid;
  // Runs work with root raised (ps5::WithRoot), as UpdateConfig::as_root; used on the worker,
  // whose batch hold keeps other threads from raising root meanwhile. Empty: folders can't be fixed.
  std::function<bool(const std::function<bool()>& work)> as_root;
  // Console folders Prepare, Repair and Play check (and fix with as_root) before writing, with the
  // game's root and working folder (runtime/writable_folders.h). Missing ones are skipped.
  std::vector<std::string> writable_folders;
  // Receives each prepared title's newest wrapper session log (bounded tail) at
  // startup. The wrapper writes it inside the private bottle tree, which only
  // the app user can read.
  std::function<void(const std::string& title_id, const std::string& text)> title_log;
  // The game's PS5 title icon: a 512x512 PNG made from its store artwork, else from
  // the icon of `program` (the program the title starts, a host path; empty when
  // unknown), or nothing (the kit's icon stays). Runs on the worker; may use the
  // network. Named by the game, so a runtime number never reaches a store's artwork.
  std::function<std::optional<std::string>(const GameId& game, const std::filesystem::path& program)> title_icon;
  // The DLC of a Steam game this account owns, from the Library's license read and app lookups
  // (EntitledLibraryBackend::DlcOf). Each prepare adds them to what the download recorded, so DLC past
  // the 64 that Steam's listofdlc names, or bought after the download, reach the emulator; DLC the download
  // recorded as turned off doesn't. Empty: none.
  std::function<std::vector<std::uint32_t>(std::uint64_t steam_id, std::uint32_t app_id)> owned_dlc;
  // One ranged HTTPS GET for what Playden downloads for a game's bottle: Microsoft's Visual C++ redistributable,
  // for a game whose files import MFC (runtime/redist_install.h). Runs on the worker, only for work the player
  // started (Play, Prepare, maintenance), never at start-up; it should give up soon after cancel turns true
  // (Shutdown). Empty: nothing is downloaded, and such games start without MFC.
  std::function<std::optional<std::string>(const std::string& url, std::uint64_t offset, std::uint64_t length,
                                           const std::atomic<bool>& cancel, std::string* error)>
      fetch_range;
  // The redistributables MFC comes from, by architecture; kept under <console data>/playden/redist.
  std::vector<runtime::VcRedist> vc_redists = runtime::MicrosoftVcRedists();
  // How long a failed download is not tried again (a preparation runs its steps more than once).
  std::chrono::seconds redist_retry_wait{60};
  // Native start of a prepared title with its arguments ("session=<UUID>").
  // Called only on the application thread, from Handoff. Empty disables Play.
  std::function<ps5::TitleResult(const std::string& title_id, const std::vector<std::string>& arguments)> launch_title;
  // Unregisters a game's PS5 title through the one-shot title remover (worker
  // only; bounded). The nonce ties its answer to this request. Empty disables
  // removal of PS5 titles.
  std::function<TitleRemoverResult(const std::string& title_id, const std::string& nonce)> unregister_title;
  // Replaces the root-owned allow-list (runtime::kTitleRuleAllowList) that a kit's any-title
  // helper reads with these bytes: one title ID per line (worker only). Empty: a kit with one
  // shell for every game can't prepare games.
  std::function<bool(const std::string& contents, std::string* error)> write_title_allow_list;
  // How long removal waits for the console to drop an unregistered title.
  int removal_confirm_polls = 30;
  std::chrono::milliseconds removal_poll_interval{1000};
  // Canonical /data as this process sees it, for the wrapper's session records.
  std::filesystem::path session_data_root = "/data";
  std::function<std::int64_t()> now_ms;
  // How long a started title may take to report its session before Play gives up.
  std::int64_t launch_evidence_wait_ms = 60000;
  // The 0.6 layout's games move (runtime/layout_migration.h), finished on the worker.
  // moved_games_root: the old and new games root (console paths) while the journal is at
  // "games-moved"; nothing otherwise. finish_games_move: called once every moved Ready game is
  // republished; false keeps the move pending for the next start. Empty: LoadLayoutJournal and
  // MarkLayoutDone on state_root.
  std::optional<runtime::LayoutPaths> layout_paths;
  runtime::LayoutOps layout_operations;
  std::function<std::optional<std::pair<std::string, std::string>>()> moved_games_root;
  // Console path of the folder holding the games' Cloud indexes (.playden-saves on console storage).
  std::string cloud_saves_root;
  std::function<bool(std::string* error)> finish_games_move;
  // SQLite and the native readers run on this worker. PS5 std::thread stacks are
  // too small for them, so the worker uses an explicit stack size.
  std::size_t stack_bytes = 1024 * 1024;
};

struct RuntimeInstallView {
  std::string install_id;
  std::uint32_t runtime_number = 0;
  GameId game;
  std::string title_id;
  // The game folder the title starts (console path). When the game is installed again on another
  // drive it no longer matches, and Prepare makes the title again.
  std::string install_path;
  // Its title is being removed to follow the game to another drive; Prepare finishes that.
  bool moving = false;
  // The title moved to another folder and its publication there isn't done yet: what Home starts may still
  // name the old folder (the record's moved_from).
  bool republish_pending = false;
  // The game's private bottle (console path); Cloud saves under Windows
  // folders live here.
  std::string prefix_root;
  runtime::PreparationState state = runtime::PreparationState::kDownloaded;
  std::string step;     // current journal step, if any
  std::string failure;
  // A durable journal is present while no preparation runs. Recovery is
  // explicit; startup never resumes it.
  bool recovery_pending = false;
  // Staged and its registration submitted: ShadowMountPlus registers it once no
  // title runs, so the game is ready to play from the PS5 Home screen.
  bool awaiting_registration = false;
  // False when a Ready title was made from an earlier kit; Prepare updates it.
  bool title_current = true;
  // A Ready game whose files an update changed since its launch was set up (the update's marker in its
  // folder): Play refuses it until Prepare has made its launch again from the new files and published it.
  bool files_changed = false;
  // Whether the title runs the installed kit's runtime (its files and artifacts are the kit's). Unlike title_current,
  // a new game name or icon does not count. Settings only the newer runtime takes (120 Hz output) wait for Update.
  bool runtime_current = true;
  // A setup that stopped before Ready (Failed, Unavailable or Downloaded) left a title or bottle made with
  // another kit: Try again can't finish over it, and Prepare refuses. Recreate bottle (remove, then prepare)
  // does, keeping saves and settings.
  bool setup_other_kit = false;
  // Publication admission result for Ready titles ("ok" or the refusal); a
  // refusal means the next start would be refused, and Prepare repairs it.
  std::string admission = "ok";
  // The settings revision its published profile was made from, and the launch entry the
  // title was prepared with (a different Launch option needs the bottle made again).
  std::uint64_t settings_revision = 0;
  std::string launch_entry_id;
  std::string launch_path;               // its program, relative to the install root
  std::string launch_working_directory;  // its folder; empty: the program's own, or the install root:
  bool launch_in_install_root = false;    // a Steam entry that names no folder starts there
  // Save backups kept for the game, and when the newest was made (Unix time).
  std::size_t save_backups = 0;
  std::int64_t latest_save_backup = 0;
  std::string failure_code;  // Recorded preparation failure; the message remains available in diagnostics.
};

// Work on a prepared game's files, run while its PS5 title is stopped.
enum class RuntimeMaintenance {
  kApplySettings,     // publish the saved settings when they are newer than the title's
  kClearShaderCache,  // delete DXVK's pipeline cache for the launch program
  kRepair,            // fix the bottle's start files, then apply the settings
  kBackupSaves,       // copy the bottle's Windows user folders aside
};

// The newest maintenance request for one game.
struct RuntimeMaintenanceView {
  RuntimeMaintenance action = RuntimeMaintenance::kApplySettings;
  bool running = false;
  bool ok = false;
  std::string message;  // the outcome, for the player
};

// Play: the launch in progress, or how the last one ended.
struct RuntimeLaunchView {
  std::string install_id;
  std::uint32_t runtime_number = 0;
  GameId game;
  std::string title_id;
  runtime::LaunchState state = runtime::LaunchState::kIdle;
  std::string code;
  std::string message;
  std::optional<int> exit_code;
};

enum class RuntimeHostStatus { kStarting, kUnavailable, kReady, kStopped };

// A program one of Steam's launch options names, found in the game's folder.
struct SteamLaunchChoice {
  std::string path;     // as Steam names it, '/' separated
  bool helper = false;  // an installer or tool (the import rules)
};

// What Game settings needs to pick a game's program: the Windows programs in its folder and,
// for a game Playden could not prepare, a draft recipe to start the sheet from.
struct RuntimeGameSetup {
  std::vector<runtime::GameProgram> programs;
  bool scanned = false;  // programs is the folder's latest scan
  // Set when preparing was refused: the recipe the player's choices start from (it may list
  // no launch entry yet) and whether a choice (a program, "Try anyway") can get past the refusal.
  std::optional<runtime::GameRecipe> draft;
  bool refusal_soft = false;
  // Steam's options are all for other branches and more than one of their programs is in the game's
  // folder: preparing waits for the player to choose one (Game settings' steam_launch).
  std::vector<SteamLaunchChoice> steam_choices;
};


// The Steam app ID a game's Steamworks emulator is given (RuntimeSnapshot::steamworks_apps).
struct SteamworksAppView {
  enum class Source {
    kNone,      // none: the game keeps its own Steam files ("Steam features" acts as "game")
    kStore,     // a Steam game's own app ID
    kGameFile,  // the game's steam_appid.txt
    kSettings,  // the "Steam app ID" in Game settings
  };
  std::uint32_t app_id = 0;  // 0 with kNone
  Source source = Source::kNone;
  // Game settings names another app ID, which the game's own steam_appid.txt overrides.
  bool overridden = false;
  bool operator==(const SteamworksAppView&) const = default;
};

// A preparation that ended Ready. Queue lists it after the waiting games until the player dismisses it;
// a dismissal names the finish time, so preparing the game again lists it again.
struct PreparedGame {
  std::uint32_t runtime_number = 0;
  std::int64_t finished_at = 0;  // Unix seconds
  bool operator==(const PreparedGame&) const = default;
};
inline constexpr std::int64_t kPreparedDays = 7;
inline constexpr std::size_t kMaxPrepared = 20;

struct RuntimeSnapshot {
  std::uint64_t revision = 0;
  RuntimeHostStatus status = RuntimeHostStatus::kStarting;
  std::string reason;  // why the runtime services are unavailable
  bool kit_available = false;
  std::string kit_reason;  // why preparation is unavailable
  // Games published again in the background after their USB drive changed places: how many of how many.
  std::size_t drive_updates_done = 0;
  std::size_t drive_updates_total = 0;
  std::size_t drive_updates_failed = 0;  // of those done, the ones that could not be published
  std::optional<RuntimeKit> kit;  // the admitted kit, for display
  std::vector<RuntimeInstallView> installs;
  // False while the PS5 title records could not be read (after a failed write): `installs` is then
  // empty, which does not mean that no game has a PS5 title.
  bool installs_known = true;
  // Below, games are named by runtime number (RuntimeHost::RuntimeNumberFor): a Steam game's app ID.
  // The games of the other numbers, for the fields that carry no GameId.
  std::map<std::uint32_t, GameId> runtime_games;
  // Latest refused or failed request per runtime number, for presentation, and how many
  // preparation requests the worker has finished.
  std::map<std::uint32_t, std::string> refusals;
  std::uint64_t prepares_handled = 0;
  std::optional<std::uint32_t> preparing_app;  // the game being prepared now
  // Preparations that ended Ready at most kPreparedDays ago and were not dismissed, newest first, at most
  // kMaxPrepared; only games whose title is still Ready.
  std::vector<PreparedGame> prepared;
  // Games whose preparation is asked for but not started yet, in the order they will start: each
  // waits behind another game's preparation, or for the runtime to finish starting.
  std::vector<std::uint32_t> queued_prepares;
  // How far the current copy or deletion (including a leftover title) is, when
  // that is measurable; absent for steps whose progress is unknown.
  std::optional<float> work_progress;
  std::optional<RuntimeLaunchView> launch;
  // Settings requests no install record's journal names: left by an interrupted
  // preparation, a refused request or a finished publication. They grant nothing.
  std::size_t leftover_requests = 0;
  // Answers to CheckActivity: the title's activity per runtime number, with the
  // check's serial so a caller can tell a fresh answer from an older one.
  std::map<std::uint32_t, std::pair<runtime::NativeActivity, std::uint64_t>> activity;
  std::uint64_t activity_serial = 0;
  // Play requests the worker has finished handling (accepted or refused).
  std::uint64_t plays_handled = 0;
  // Latest refused Play per runtime number, for presentation.
  std::map<std::uint32_t, std::string> play_refusals;
  // A checked session waits for Handoff on the application thread.
  bool handoff_ready = false;
  // Recipes Playden generated (from Steam's launch options or the game's files), for the settings sheet.
  std::vector<runtime::GameRecipe> generated_recipes;
  // Program choices per runtime number, from ScanPrograms and from preparation.
  std::map<std::uint32_t, RuntimeGameSetup> game_setups;
  // Removal: the game whose PS5 title is being removed now, the latest refusal or
  // failure per runtime number, and how many removal requests the worker has finished.
  std::optional<std::uint32_t> removing_app;
  std::map<std::uint32_t, std::string> removal_failures;
  std::uint64_t removals_handled = 0;
  // Game data kept when a game was uninstalled (bottles with no install record).
  std::vector<KeptBottleView> kept_bottles;
  // Unrecorded PS5 titles, and their queued/running deletion or latest failure (keyed by title ID).
  std::vector<runtime::LeftoverTitle> leftover_titles;
  std::vector<std::string> queued_leftover_deletes;
  std::optional<std::string> deleting_leftover_title;
  std::string deleting_leftover_step;
  std::map<std::string, std::string> leftover_delete_failures;
  std::uint64_t leftover_deletes_handled = 0;
  // Maintenance per runtime number, and how many requests the worker has finished.
  std::map<std::uint32_t, RuntimeMaintenanceView> maintenance;
  std::uint64_t maintenance_handled = 0;
  // Bytes in each game's Windows user folders (installed and kept), from the latest MeasureSaves.
  std::map<std::uint32_t, std::uint64_t> save_bytes;
  // What Play does before the launch is requested, per runtime number, while it runs: a game whose
  // folder moved in Playden 0.6 is republished first (kPlayUpdatingForLayout).
  std::map<std::uint32_t, std::string> play_progress;
  // Games without the PhysX engine they need, by runtime number: the version, empty when it isn't known.
  std::map<std::uint32_t, std::string> physx_needed;
  // What the latest Play from Playden went ahead without, per runtime number (Microsoft's MFC that could not be
  // downloaded): Play still starts the game, and the player sees why it may stop.
  std::map<std::uint32_t, std::string> play_notices;
  // Games whose last run couldn't start a program in their folder: a launcher, without launcher mode. Told once.
  std::map<std::uint32_t, std::string> launcher_hints;
  // The Steam app ID each game from another store was last prepared with, by runtime number. Steam
  // games are not listed: theirs is their own.
  std::map<std::uint32_t, SteamworksAppView> steamworks_apps;
};

// Whether the game's preparation waits in the runtime's queue.
inline bool PrepareQueued(const RuntimeSnapshot& snapshot, std::uint32_t runtime_number) {
  return std::find(snapshot.queued_prepares.begin(), snapshot.queued_prepares.end(), runtime_number) !=
         snapshot.queued_prepares.end();
}

inline constexpr const char* kPlayUpdatingForLayout = "Updating this game for Playden 0.6…";
inline constexpr const char* kPlayInstallingPhysx = "Installing PhysX…";
inline constexpr const char* kPlayInstallingComponent = "Installing a component…";
inline constexpr const char* kPlayDownloadingMfc = "Downloading Microsoft's MFC for this game…";
inline constexpr const char* kPlayMfcNotDownloaded = "Microsoft's MFC could not be downloaded. Play again to retry.";
inline constexpr const char* kPlayMfcNotInstalled = "Microsoft's MFC could not be installed for this game.";

// A downloaded game to prepare. The game files stay at install_path.
struct RuntimePrepareRequest {
  // From RuntimeHost::RuntimeNumberFor(game).
  std::uint32_t runtime_number = 0;
  std::string install_path;  // console path of the Steam install
  std::string volume_id;
  std::string title_name;    // the game's name, shown for its PS5 title
  // Steam's Windows launch options (label = Steam's description), used when Playden
  // ships no recipe for the game. launch_reason says why they are missing.
  std::vector<runtime::LaunchEntry> launches;
  std::string launch_reason;
  // No option is for the public branch: `launches` are every branch's, and Steam doesn't say
  // which program starts the game.
  bool launches_any_branch = false;
  // The game; a default one stands for the Steam game runtime_number names.
  GameId game;
};

// An imported game's folder becoming its folder in Playden ("Copy into Playden" once the copy is
// verified, "Move into Playden" for a drop-folder game): RuntimeHost::Relocate.
struct RuntimeRelocation {
  std::uint32_t runtime_number = 0;  // 0: the game has no number yet, so no PS5 title
  std::string to;                    // console path of the game's folder in Playden
  std::string volume_id;             // the install volume of `to`
  // The move itself, run on the worker under the game's publication lease once its title is
  // stopped (and at once for a game without a title): empty, or why not. It must be safe to run
  // again after it succeeded (a restart in between). For a copy it copies again the files
  // changed since they were copied. Empty: the files are at `to` already.
  std::function<std::string()> move_files;
};

// What RuntimeHost::Relocate answers once Playden is closing (BeginClosing).
inline constexpr const char* kRelocationClosing = "Playden is closing.";

struct RuntimeRelocationResult {
  enum class Outcome {
    kDone,    // the game plays from `to` (its record names it; a marked republish may still wait)
    kBusy,    // nothing changed: its title runs or is unknown, or the runtime is busy; try again
    kFailed,  // nothing changed, or the files moved but the record could not follow (try again)
  };
  Outcome outcome = Outcome::kFailed;
  std::string message;  // for the player
  // The moved publication could not be verified: the old PS5 title was removed keeping its saves,
  // and the next Play prepares the game again where it is now.
  bool prepare_again = false;
};

// The worker constructs and owns every runtime collaborator, so durable work and
// native inventory never run on the main thread. The main thread reads snapshots
// and queues requests. Play is split the same way: the worker checks the game
// and prepares the launch session, and only Handoff, on the application thread
// that constructed this object, starts the title.
class RuntimeHost {
 public:
  explicit RuntimeHost(RuntimeHostConfig config);
  ~RuntimeHost();
  RuntimeHost(const RuntimeHost&) = delete;
  RuntimeHost& operator=(const RuntimeHost&) = delete;

  bool Start();
  void Shutdown();
  RuntimeSnapshot Snapshot() const;
  // Before any download service receives its games root.
  bool WaitForStartup();
  // The same state without a copy per call: shared and read-only, made again only after a change.
  // The UI reads it many times a frame; Snapshot() copies every field each time.
  std::shared_ptr<const RuntimeSnapshot> Shared() const;
  // A console path, as this process opens it (differs only in a host test's namespace).
  std::string HostFilePath(const std::string& console_path) const { return HostPath(console_path).string(); }
  // Queues preparation of a downloaded game, or a retry of a failed one. Games are prepared one
  // at a time, in the order asked; asking again for a queued game keeps its place.
  void Prepare(RuntimePrepareRequest request);
  // Moves a queued preparation to the front of the queue. The one running now finishes first.
  // False when the game is not queued (it started or was never asked for): nothing changes.
  bool PrepareNext(std::uint32_t runtime_number);
  // Takes a queued preparation out of the queue (its game is being uninstalled). False when it is not
  // queued: it started already, or was never asked for.
  bool WithdrawPrepare(std::uint32_t runtime_number);
  // While held, no queued preparation starts (a quit to Home waits for the running one only).
  void HoldPreparations(bool hold);
  // Takes a finished preparation off RuntimeSnapshot::prepared; ClearPrepared takes every one off,
  // including those past the kMaxPrepared the snapshot lists.
  void DismissPrepared(std::uint32_t runtime_number, std::int64_t finished_at);
  void ClearPrepared();
  // Asks the console whether a game's PS5 title runs (from any origin, Home
  // included). A game with no prepared title reports stopped.
  void CheckActivity(std::uint32_t runtime_number);
  // CheckActivity, waiting up to `timeout` for the answer (kUnknown without one). For other
  // threads, such as the Cloud worker checking a game just before moving its saves.
  runtime::NativeActivity ActivityNow(std::uint32_t runtime_number, std::chrono::milliseconds timeout);
  // Queues removal of the leftover settings requests (rechecked on the worker).
  void CleanUpRequests();
  // The names each game's PS5 title should carry. A Ready title whose installed
  // name differs reports an update, and Prepare applies the new name.
  void SetTitleNames(std::map<std::uint32_t, std::string> names);
  // Queues Play of a Ready game. With setup_program (a program in the game folder, relative to it), the title starts
  // that program once instead, with the Mouse controller preset, and the game's saved settings come back with the
  // next publication: the next Play, or the next start of Playden (RuntimeInstall::setup_program).
  void Play(std::uint32_t runtime_number, std::string setup_program = {});
  // A game's files changed outside the runtime (an update finished): the installs are checked again, so
  // RuntimeInstallView::files_changed follows.
  void RecheckInstalls();
  // The signed-in Steam account, for the Steamworks emulator's settings (empty when signed out).
  void SetSteamAccount(std::string account_name, std::uint64_t steam_id);
  // Queues removal of a game's PS5 title. Its bottle (saves and settings) is kept
  // unless delete_saves; an interrupted removal continues with its first choice.
  void Remove(std::uint32_t runtime_number, bool delete_saves);
  // Queues deletion of a game's kept bottle.
  void DeleteKeptBottle(std::uint32_t runtime_number);
  // Deletes only a scanned leftover's PS5 title and registration; its game files and saves stay.
  bool DeleteLeftoverTitle(const std::string& title_id, std::string* error = nullptr);
  // Queues a scan of a game folder for the Program picker (RuntimeSnapshot::game_setups).
  void ScanPrograms(std::uint32_t runtime_number, std::string install_path);
  // Measures each game's Windows user folders (where saves of games without Steam Cloud live).
  void MeasureSaves();
  // A kit was put in place while Playden runs (the first-run kit download): the worker stops its
  // services and starts them again to admit it, publishing kStarting in between, once no launch is
  // being handed off or followed. Queued requests wait for it.
  void ReloadKit();
  // Queues maintenance of a prepared game. Each action is refused while the game's
  // title runs or its state is unknown.
  void Maintain(std::uint32_t runtime_number, RuntimeMaintenance action);
  // A game's runtime number, which every call above takes: a Steam game's app ID; for a game from
  // another store, the number of its install record, or a new one, saved before it is returned.
  // Any thread. A new number is written to installs.json under the effective-UID hold, so it waits
  // while the worker starts up or works through a batch; with `busy`, it returns nothing at once
  // and sets *busy instead (ask again later). Nothing otherwise when the game is invalid, the
  // runtime records are not loaded (yet) or the write fails; the runtime log says which.
  // RuntimeSnapshot::runtime_games lists the number before it returns.
  std::optional<std::uint32_t> RuntimeNumberFor(const GameId& game, bool* busy = nullptr);
  // Makes `request.to` the game's folder, keeping its PS5 title, runtime number and bottle (the
  // 0.6 games move's republish, for one game): with the game's publication lease held and its title
  // stopped, move_files runs, then one record write names the new folder (moved_from the old one)
  // and the game is published again at its revision. A publication that can't be verified falls
  // back to removing the old title, keeping its saves (prepare_again). A record already naming `to`
  // (a restart after its write) only finishes the republish. A preparation queued for the game
  // answers kBusy (it names the old folder). Blocks the calling thread (never the worker's) until
  // the worker answers; a request the worker hasn't started within `timeout` is dropped and answers
  // kBusy. Once Playden is closing (BeginClosing), a request not started yet
  // answers kBusy with kRelocationClosing at once: the copy or move resumes at the next start.
  RuntimeRelocationResult Relocate(RuntimeRelocation request, std::chrono::milliseconds timeout);
  // Playden is quitting: callers waiting in Relocate for a relocation the worker hasn't started stop
  // waiting now, and new ones are refused, so the install and Local workers they block can be
  // joined before this host shuts down. Doesn't stop the worker (Shutdown does); safe to call twice.
  void BeginClosing();
  // Application thread only: starts the title of a prepared launch session.
  // Returns false when no session is waiting.
  bool Handoff();

 private:
  struct Composition;
  static void* Entry(void* self);
  void Run();
  // Starts the services and runs requests until Shutdown (false) or ReloadKit (true).
  bool RunServices();
  void Publish(const std::function<void(RuntimeSnapshot&)>& change);
  // With `only`, that install's title is checked again and the others keep their last
  // check (about two seconds per title on the console).
  void PublishInstalls(const Composition& composition, const std::string& only = {});
  // Empty when the title is Ready or, with *awaiting set, staged and waiting for the
  // console to register it; otherwise why not.
  std::string RunPrepare(Composition& composition, const RuntimePrepareRequest& request, bool* awaiting = nullptr);
  const runtime::GameRecipe* RecipeForPrepare(Composition& composition, const RuntimePrepareRequest& request,
                                              std::string* reason);
  void LoadGeneratedRecipes(Composition& composition);
  // A generated recipe set up with older defaults for its engine takes the current ones and its title is published
  // again. Nothing of the game may be running. A refusal leaves the game as it was, for the next try.
  void RefreshGeneratedRecipeDefaults(Composition& composition, const runtime::RuntimeInstall& record);
  void PublishRecipes(const Composition& composition);
  runtime::PackageActionResult DrivePublication(Composition& composition, const runtime::RuntimeInstall& record);
  // Moves *next (an install record) to the program and folder the saved settings choose, after checking
  // them on disk. Empty on success, otherwise why not (for the player). Call only while the game is stopped.
  std::string FollowChosenLaunch(const runtime::GameRecipe& recipe, const runtime::SettingsPreset* preset,
                                 const runtime::KitCapabilities& kit, const runtime::GameSettingsRecord& saved,
                                 runtime::RuntimeInstall* next);
  // Puts the saved settings into a Ready title when they are newer than its publication:
  // Steam files, then a journaled settings update (profile, dxvk.conf, registry). Call only
  // while the title is stopped. Empty on success or when nothing changed; *published says
  // whether an update ran. The title keeps the launch entry it was prepared with.
  // A moved game, or an owned publication with a kit that admits unowned folders
  // (NeedsUnownedPublication), is published again at its revision.
  // steam_account_known false (at startup): the Steam emulator's files wait for Play.
  // *prepare_again: refused for a reason only a new preparation gets past (recipe or settings).
  // The unowned upgrade alone (not moved, no newer settings) never refuses: its failure is in
  // *upgrade_deferred and the owned publication stays, as it played before.
  // `code`: the publication's failure code when the publication itself refused (empty otherwise).
  // With force, the settings are published again even when the title already has their revision:
  // after Update moved the title to another runtime, which may take different profile keys (120 Hz
  // output). Nothing is published when they write the same profile and dxvk.conf as before.
  // With setup_program, the saved settings are published with that program and the Mouse controller preset in
  // their place, for one run (Play). A title that publishes such a run gets its saved settings back from the next
  // call without it, whatever their revision.
  std::string RepublishSettings(Composition& composition, const runtime::RuntimeInstall& record,
                                bool* published = nullptr, bool steam_account_known = true,
                                bool* prepare_again = nullptr, std::string* upgrade_deferred = nullptr,
                                std::string* code = nullptr, bool force = false, const std::string& setup_program = {});
  // RepublishSettings without the upgrade's fallback.
  // `defaults_published`: with force, a game with no saved settings whose title has revision 0 was
  // published from Playden's defaults, so they are published again.
  std::string PublishSavedSettings(Composition& composition, const runtime::RuntimeInstall& record,
                                   bool* published, bool steam_account_known, bool* prepare_again,
                                   std::string* code = nullptr, bool force = false, bool defaults_published = false,
                                   const std::string& setup_program = {});
  // Records the program the title's profile starts once (RuntimeInstall::setup_program); empty: none.
  std::string MarkSetupProgram(Composition& composition, const std::string& install_id, const std::string& program);
  // Whether an update left its marker in the Ready game's folder (installs::kFilesChangedName).
  bool FilesChanged(const runtime::RuntimeInstall& record) const;
  // The Ready-path part of Prepare for a game whose files changed: its generated recipe is made again
  // from the request's launch options and the files (as a fresh preparation makes it), the saved
  // settings are published with it, and the marker goes. Empty, or why not (the marker stays).
  std::string RefreshChangedFiles(Composition& composition, const RuntimePrepareRequest& request,
                                  const runtime::RuntimeInstall& record);
  // A Ready game published owned (schema 2, before 0.6 or by a kit before 0.10) while the kit
  // admits unowned game folders: published again as unowned, so folders the player opened pass.
  bool NeedsUnownedPublication(const Composition& composition, const runtime::RuntimeInstall& record);
  // The request of an unowned upgrade alone (same revision, the game not moved) that failed before
  // its publication began: the record still carries the request arm, so the owned publication the
  // game played under is intact. Dropped (true), the game plays as before; Play, Update, Repair and
  // the next start try the upgrade again. Moved games and newer settings keep their request.
  bool DropUpgradeRequest(Composition& composition, const std::string& install_id, const std::string& why);
  // The 0.6 games move: rewrites the records and Cloud indexes under the old games root at startup,
  // and marks the move done once no moved Ready game is left to republish.
  bool MoveGames(Composition& composition, std::string* error);
  bool MoveGameRecords(Composition& composition);
  // USB drives can change places: records follow their games' folders. One publication still naming the old mount
  // is marked (moved_from), and the startup pass or Play publishes it again; the title itself is kept.
  void FollowUsbDrives(Composition& composition);
  // What a game's profile and descriptor should name: the search form for a USB game whose title can find its drive,
  // unless a copy on another drive would make the title refuse. Empty names install_path as it is.
  std::string UsbSearchRoot(const Composition& composition, const runtime::RuntimeInstall& record) const;
  // A Ready USB game whose publication names its folder the other way (see UsbSearchRoot).
  bool NeedsDrivePublication(const Composition& composition, const runtime::RuntimeInstall& record) const;
  bool RebaseUsbRecord(Composition& composition, runtime::RuntimeInstall record, const std::string& install_path);
  // One game of that background job. A busy console (a game running, a session Playden hasn't closed yet) makes it
  // try again shortly; a refusal is logged and left for Play.
  void RunDriveUpdateStep(Composition& composition);
  std::set<std::string> drive_update_tried_;  // install IDs, this session; worker only
  void FinishGamesMove(Composition& composition);
  // Relocate on the worker.
  RuntimeRelocationResult RunRelocate(Composition& composition, const RuntimeRelocation& request);
  struct PendingRelocation {
    RuntimeRelocation request;
    bool started = false;
    bool abandoned = false;  // the caller stopped waiting before it started
    std::optional<RuntimeRelocationResult> result;
  };
  // Empty when the game's Ready title is stopped with no launch pending, otherwise why not.
  std::string MaintenanceRefusal(Composition& composition, const runtime::RuntimeInstall& record);
  // Runs one maintenance action; empty message on refusal means none; *ok tells success.
  std::string RunMaintenance(Composition& composition, std::uint32_t runtime_number, RuntimeMaintenance action, bool* ok);
  std::filesystem::path SaveBackupRoot(const std::string& install_id) const;
  // A game's files and settings as the preparation steps see them.
  struct GameFiles;
  // Puts the game's files and bottle in the state its recipe and settings ask for, before it starts:
  // generic steps for every store, and Steam-file steps that act on the Steam files a game has,
  // whatever its store (the steam_api DLLs follow its "Steam features" setting). Call only while the
  // game is stopped; empty on success, otherwise why not (for the player).
  // steam_account_known false: the emulator's files (which name the account) are left as they are.
  std::string ApplyPreparationSteps(Composition& composition, const runtime::RuntimeInstall& record,
                                    bool steam_account_known = true);
  // Generic steps.
  void MediaStep(Composition& composition, const runtime::RuntimeInstall& record);
  std::string Ue3EulaStep(const GameFiles& files);
  std::string Direct3D12Step(Composition& composition, const GameFiles& files);
  void KitMonoStep(Composition& composition, const runtime::RuntimeInstall& record, const char* when);  // never stops the start
  void VcRuntimeStep(const GameFiles& files);  // never stops the start
  std::string BottleEnvironmentStep(const GameFiles& files);
  std::string RecipeRegistryStep(const GameFiles& files);
  std::string RecipeIniStep(const GameFiles& files);
  std::string RecipeFilesStep(const GameFiles& files);
  std::string DotnetHeapStep(const GameFiles& files);
  void MfcStep(const GameFiles& files);  // an upgrade: never stops the start
  // Steam-file steps.
  std::string SteamStubStep(const GameFiles& files);
  std::string SteamworksStep(const GameFiles& files, bool steam_account_known);  // and the legacy steam.dll
  std::string InstallScriptsStep(const GameFiles& files);                        // and redistributables
  // The Steam app ID the game's emulator uses.
  SteamworksAppView SteamworksAppFor(const GameFiles& files) const;
  // Whether the install's title runs the installed kit's runtime: its owner markers name this kit
  // (PackageInstaller::TitleCurrent) and its bound artifacts are the kit's. A title made from an earlier kit runs
  // that kit's runtime until Update.
  bool TitleRuntimeCurrent(const Composition& composition, const runtime::RuntimeInstall& record) const;
  // The installed kit's capabilities as this install's title can use them (runtime::KitForTitleRuntime): profile
  // keys only a newer runtime takes are left out until Update. Use it wherever a profile is built for the title.
  runtime::KitCapabilities TitleKit(const Composition& composition, const runtime::RuntimeInstall& record) const;
  // Empty while the kit on disk is the one admitted at startup; otherwise what to tell the player.
  std::string KitReplaced(const Composition& composition) const;
  // Makes an owned, world-writable folder from root down to working 0755 (dxvk.conf goes there).
  std::string TightenWorkingFolder(const std::filesystem::path& root, const std::string& working);
  // Checks (and fixes, as root) config.writable_folders, the game's root and its working folder
  // (relative to the root; empty: none) before anything is written; empty, or which can't be written.
  // Call before any ManagedDirectory of the operation is opened.
  std::string EnsureWritable(const std::string& install_path, const std::string& working);
  // Once the game is published unowned (kit with game-root-unowned): opens what older Playdens
  // tightened, the folders from the game root down to its working folder that the app user owns
  // and that are 0755 become 0777, so FTP can write into them (mods). Folders of other users are
  // left alone. Call after the publication, while none of its ManagedDirectory objects is open.
  void OpenGameFolders(const Composition& composition, const runtime::RuntimeInstall& record);
  // A dxvk.conf with more than one link fails the title's start check; it becomes a copy of its own.
  std::string UnlinkDxvkConfig(const runtime::RuntimeInstall& record);
  // The bottle's way to its user profile takes the kit's mode, and with bottle-profile-shared its
  // profile is opened to FTP again (files Wine made since are 0600). Only for a stopped title,
  // while no ManagedDirectory of the bottle is open. Failures are logged; the start check decides.
  void SettleBottle(Composition& composition, const runtime::RuntimeInstall& record, const char* when);
  runtime::LaunchPreflight Preflight(Composition& composition, const runtime::RuntimeInstall& record);
  // Worker only. Tightens the bottle at data_root (console path) when it looks opened up and its title is stopped.
  void HealBottle(Composition& composition, const std::string& data_root, const std::string& title_id);
  runtime::LaunchEvidence Evidence(Composition& composition, const runtime::RuntimeInstall& record,
                                   const std::string& session_id);
  void RunPlay(Composition& composition, std::uint32_t runtime_number, const std::string& setup_program = {});
  // Removes a game's PS5 title; empty when it has none left, otherwise why not.
  // moving: the title goes because its game was installed again elsewhere (journal "remove-move"),
  // so Prepare, not Uninstall, finishes a removal that stopped part way.
  std::string RunRemove(Composition& composition, std::uint32_t runtime_number, bool delete_saves, bool moving = false);
  struct RemovalFailure { std::string code, message; };
  std::optional<RemovalFailure> RetireTitle(Composition& composition, const std::string& title_id,
                                           const std::string& operation_id,
                                           const runtime::LeftoverTitle* expected = nullptr);
  std::optional<RemovalFailure> UnregisterTitle(Composition& composition, const std::string& title_id,
                                               const std::string& operation_id);
  std::string DeleteRetiredTitle(const std::string& title_id, const std::string& operation_id);
  // Marks a bottle as kept saves (<install id>.kept), as Uninstall without "delete saves" does.
  std::optional<RemovalFailure> KeepBottle(const std::filesystem::path& bottle, const std::string& install_id,
                                           const GameId& game, std::uint32_t runtime_number, const std::string& name,
                                           const std::string& operation_id);
  // Keeps bottles no install record and no unrecorded PS5 title names (their title was deleted
  // as a leftover, or its record was lost) as kept saves, so Storage lists them.
  void KeepUnrecordedBottles(Composition& composition);
  struct LeftoverDelete {
    runtime::LeftoverTitle title;
    std::string operation_id;
    std::string step = "retire";
  };
  std::string RunDeleteLeftover(Composition& composition, LeftoverDelete request);
  std::string SaveLeftoverDelete(Composition& composition, const LeftoverDelete& request);
  void ResumeLeftoverDeletes(Composition& composition);
  void PublishLeftoverTitles(Composition& composition);
  // Whether the console still lists the title (app.db or /user/app); unknown counts as listed.
  bool TitleListed(Composition& composition, const std::string& title_id);
  // Moves the saves of a kept bottle into the game's new bottle and drops the kept copy.
  std::string RestoreKeptSaves(Composition& composition, std::uint32_t runtime_number);
  std::string DeleteKept(Composition& composition, std::uint32_t runtime_number);
  // Lists the kept bottles; a non-Steam game's number is remembered (RememberNumber) for it.
  void PublishKeptBottles(Composition& composition);
  // Finished preparations, in prepared_history_ and the state root's prepared-history file (worker thread).
  void LoadPreparedHistory();
  void SavePreparedHistory();
  std::vector<PreparedGame> ListPrepared(const Composition* composition) const;
  void PublishPrepared(const Composition* composition);
  // With an any-title kit, lists every recorded game title in the helper's allow-list so their
  // titles may start; empty on success (or with no such kit), otherwise why not.
  std::string SyncTitleAllowList(Composition& composition);
  std::filesystem::path HostPath(const std::string& console_path) const;
  // The param.json Playden wrote for the game's title, or nothing.
  std::optional<std::string> InstalledTitleParameters(const runtime::RuntimeInstall& record) const;
  std::optional<std::string> InstalledTitleName(const runtime::RuntimeInstall& record) const;
  bool TitleNameCurrent(const runtime::RuntimeInstall& record) const;
  // The kit can declare a title VRR-supported (display-vrr).
  static bool KitDeclaresVariableRefresh(const Composition& composition);
  // The title's written parameters declare VRR support exactly when the kit can (an unreadable layout counts as current).
  bool TitleVariableRefreshCurrent(const Composition& composition, const runtime::RuntimeInstall& record) const;
  // Writes the game's own title name (and icon) for its PS5 title.
  runtime::PackageActionResult WriteTitleMetadata(Composition& composition, const runtime::RuntimeInstall& record,
                                                  const std::string& title_name);
  // Polls a pending launch session and ends it once its outcome is final.
  // Returns true while a session is still undecided.
  bool PollLaunch(Composition& composition);
  void PublishLaunch(Composition& composition, const runtime::LaunchSnapshot& launch);
  // Settings request files that no record's journal names; with remove, deletes them.
  std::size_t LeftoverRequests(Composition& composition, bool remove);
  void RemoveFinishedRequests(Composition& composition);
  bool Stopping() const;
  void Log(const std::string& line) const;
  void LogSteamStubPrograms(std::uint32_t app, const std::vector<runtime::GameProgram>& programs) const;
  // Worker thread: publishes the work fraction when its whole percent changes; ClearWork removes it.
  void ReportWork(std::uint64_t done, std::uint64_t total);
  void ClearWork();
  // Worker thread: makes the loaded repository the one RuntimeNumberFor asks (nullptr: none) and
  // learns its records' numbers.
  void ShareNumbers(runtime::RuntimeInstallRepository* repository);
  // Remembers a non-Steam game's number for RuntimeNumberFor and RuntimeSnapshot::runtime_games.
  void LearnNumber(const GameId& game, std::uint32_t runtime_number);

  RuntimeHostConfig config_;
  // When each redistributable's download last failed (worker only): a preparation runs its steps more than once,
  // and Play shouldn't wait for a network that just failed.
  std::map<std::string, std::chrono::steady_clock::time_point> redist_download_failed_;
  // What the work in progress lets MfcStep do (worker only; RedistWorkScope sets it): download only for work the
  // player started, never at start-up or for other background republishing. play_app: the Play that waits, for
  // its progress line; notice: what that Play went ahead without.
  struct RedistWork {
    bool downloads = false;
    std::optional<std::uint32_t> play_app;
    std::string notice;
  };
  RedistWork redist_work_;
  struct RedistWorkScope;
  // Set by Shutdown: a download in progress gives up.
  std::atomic<bool> cancel_downloads_{false};
  mutable std::mutex mutex_;
  std::condition_variable wake_;
  std::condition_variable published_;  // notified on every Publish
  RuntimeSnapshot snapshot_;
  mutable std::shared_ptr<const RuntimeSnapshot> shared_;  // Shared()'s copy of snapshot_ at shared_revision_
  mutable std::uint64_t shared_revision_ = 0;
  std::vector<RuntimePrepareRequest> prepare_requests_;
  struct PlayRequest {
    std::uint32_t app = 0;
    std::string setup_program;  // Play(…, setup_program)
  };
  std::vector<PlayRequest> play_requests_;
  struct RemovalRequest {
    std::uint32_t app = 0;
    bool delete_saves = false;
    std::optional<LeftoverDelete> leftover;
    std::uint64_t order = 0;
  };
  std::vector<RemovalRequest> remove_requests_;
  std::uint64_t next_work_order_ = 0;
  std::map<std::uint32_t, std::uint64_t> prepare_order_;
  std::vector<std::uint32_t> kept_delete_requests_;
  std::vector<std::pair<std::uint32_t, std::string>> scan_requests_;
  std::vector<std::pair<std::uint32_t, RuntimeMaintenance>> maintenance_requests_;
  std::vector<std::uint32_t> activity_requests_;
  std::vector<std::shared_ptr<PendingRelocation>> relocation_requests_;  // guarded by mutex_
  int work_percent_ = -1;  // worker thread only: the published work percent, -1 for none
  bool launch_poll_ = false;
  // More games to publish for a USB drive that changed places, and when to try next. Guarded by mutex_.
  bool drive_updates_pending_ = false;
  std::chrono::steady_clock::time_point drive_update_not_before_{};
  bool cleanup_requested_ = false;
  bool measure_requested_ = false;
  bool kit_reload_requested_ = false;  // guarded by mutex_
  bool prepares_held_ = false;
  std::vector<PreparedGame> prepared_dismissals_;  // guarded by mutex_
  bool prepared_clear_requested_ = false;          // guarded by mutex_
  std::vector<PreparedGame> prepared_history_;     // worker thread only, oldest first
  std::map<std::uint32_t, std::string> title_names_;  // guarded by mutex_
  std::string steam_account_name_;                     // guarded by mutex_
  std::uint64_t steam_id_ = 0;                         // guarded by mutex_
  bool title_names_changed_ = false;
  bool installs_recheck_requested_ = false;
  // Guards the worker's launch service and preflight cache for Handoff.
  std::mutex launch_mutex_;
  runtime::LaunchService* launch_ = nullptr;
  Composition* launch_composition_ = nullptr;
  pthread_t application_thread_{};
  // Runtime numbers of games from other stores. Lock order: the effective-UID hold (which the
  // worker keeps around startup and each batch, repository use included), then numbers_mutex_,
  // then the repository's own lock (never the other way round), then mutex_. A number lookup that
  // may write the repository takes the hold first: a repository write waits for the hold itself.
  mutable std::mutex numbers_mutex_;
  std::unordered_map<GameId, std::uint32_t> numbers_;     // guarded by numbers_mutex_
  runtime::RuntimeInstallRepository* numbers_repository_ = nullptr;  // guarded by numbers_mutex_
  bool stopping_ = false;
  bool closing_ = false;  // BeginClosing: relocations not started answer at once
  bool started_ = false;
  void* thread_ = nullptr;  // pthread_t storage, owned by the implementation
};

// Canonical random (version 4) UUID from /dev/urandom, or nothing (platform/random_id.h).
std::optional<std::string> RandomUuid();

}  // namespace playden::homebrew