[hckrman101]

Windows and Linux each have their own Builder today, and a PC keeps only one built version of Hookshot at a time. Hookshot 3.0 replaces both with one launcher that builds, updates and plays several versions side by side (release, release candidate and nightly), and copies saves between them and the emulators.

Depends on: #2733 (nightly naming) and #2722 (the 2.x hand-over contract and upgrader). This branch carries their commits until they merge. Please review only the four launcher commits on top of them:

1. feat(launcher): the launcher's core library, with its tests
2. feat(launcher): the Avalonia app shell
3. feat(launcher): what the launcher's screens need from the core: game files found, checked, built and timed
4. feat(launcher): the launcher's screens, from the design mockup

Related:

• feat(builder): the launcher, one window to play, build and update (Windows and Linux) #2373 by madebyjordan is also a launcher for 3.0.0, built on the existing WPF/Qt and Tk Builders. This PR is a new Avalonia app instead: one codebase for both systems, several versions in parallel on each channel, a core library with game-free tests, a port of the saves tool, and the 2.x hand-over contract from feat(builder): hand a 2.x install over to the Hookshot Launcher #2722.
• feat(linux-launcher): add profiles, each with saves of its own  #1958 (Linux profiles and emulator import) overlaps with the Saves page here and with the profiles planned next.

What changed

Core (launcher/Core, no UI and no packages):

• Versions and channels: the rules of Updater.cs and linux_update.py, checked against tests/test_update_tracks.py's own vectors. Nightlies use feat(release): name a nightly by its commit count on main and its commit #2733's nightly-<count>-<commit> names, and nightlies and releases are never ordered against each other. Each build follows its own channel, and an update is offered only when it is newer on that channel.
• Build tools per version: each version gets its own tools in <home>/toolchains/<tag>, installed from that release's parts list (hookshot-setup.txt or hookshot-linux.txt). Every part is checked for size and SHA-256 before it is unpacked. Zip entries that would land outside the folder are refused, and so are links that escape it. A part another version already has is hard-linked rather than downloaded again. Downloads are https only, also after redirects.
• builds.json: the list of builds, with exactly one default.
• The 2.x hand-over (docs/launcher-upgrade.md): reads the import files and, on a first start, the Builder's own settings. An import file is deleted only once what it brought has been saved.
• Running make_game.py: its command line and environment as Runner.Info and AppRun build them. Its @@ lines become one progress bar that never goes back. Cancel kills make_game's own process tree and nothing else.
• Saves: a rule-for-rule port of scripts/oot_saves.py. It finds saves in Hookshot and the emulators, takes a backup before every copy, and refuses while a game or emulator runs.
• Also: game-file discovery (the Builder's Finder), disk space, shortcuts, the GPU makers on Linux.

App (launcher/App, Avalonia 12):

• The window draws its own title bar, in the Builder's Slate palette with its Inter font.
• View models are plain INotifyPropertyChanged, with one compiled-binding view per page.
• The 2.x command line still works: --launch, --update [--tag] [--fetched] and --play, so the game's own update prompt and the shortcuts keep working.

Screens (from the design mockup):

• Home: empty, one or several versions, update offers, the hand-over notice.
• The channel picker.
• A three-step wizard:
  1. The version's tools download while the game files on this PC are found and checked.
  2. Settings: saves, DLSS and FSR 4 behind their licences, the game folder with the space it needs, language, shaders, and memory and workers under Advanced.
  3. The build, with one bar and a row for each stage.
• Ready, and a problem screen with Copy for a bug report.
• The launcher's settings.
• Saves: copy from another build, import from an emulator, export to one. Each shows a confirm screen with what gets replaced and where the backup goes.
• Design notes: focus rings for keyboard and controller, quick transitions that stop when the desktop asks for less motion, tabular digits where numbers change, paths on one line (middle-elided, with the full path in a tooltip) and the home folder shown as ~ on Linux.

Safety calls worth checking:

• Delete removes a folder only if make_game.py made it. It refuses:
  • a link;
  • the home folder;
  • a folder that holds another build or the launcher's home (a 2.x install at ~/Games/Hookshot holds the new builds for now);
  • any folder while Hookshot runs.
• Free up space deletes only what make_game made in the build-files folder, never the folder itself.
• DLSS and FSR 4: NVIDIA's and AMD's SDKs are fetched only after their licence is accepted. A test checks that the licence texts name the commits scripts/ngx_sdk.py and scripts/ffx_sdk.py fetch.
• No game data leaves the PC. Nothing in the launcher uploads anything. The only network calls are GitHub's release API and file downloads. The bug-report copy holds the launcher's log, the settings and the PC's memory and GPU makers.
• Closing the window during a build asks first, as Cancel does, so make_game is never left running without a window.

Why Avalonia, and the first NuGet dependency

One UI codebase has to run natively on Windows and Linux, and WPF and Tk each cover only one. Avalonia is MIT-licensed, mature and draws the same on both, with native Wayland. This is the repository's first NuGet dependency, so it is kept tight:

• The four Avalonia packages are pinned exactly in Directory.Packages.props, with packages.lock.json for everything they bring in. Those are SkiaSharp, HarfBuzzSharp, Tmds.DBus, NWayland and MicroCom, all MIT.
• NuGet.Config allows nuget.org only.
• Avalonia.BuildServices' telemetry target is replaced by an empty one. The build log shows the override, so builds report nothing.
• launcher/Core has no packages at all: the tests compile its sources directly.
• UseWaylandWithFallback() uses native Wayland where there is a compositor and falls back to X11 otherwise. On Windows it does nothing (Avalonia's docs).

How it was tested

• python -I -B tests/run_all.py on Linux: 425 passed, 67 skipped. The only failures are the two known local ones, test_bake_portability (no zstandard here) and test_builder_log_read_only (no Tk here).

• tests/test_launcher_core.py: 453 checks over temporary folders, with a UTF-8 scratch path (ゲーム Zélda 🎮). They cover:

  • the version vectors and the hand-over fixtures;
  • the saves cases from test_oot_saves.py;
  • the tool installs: size and SHA-256, zip-slip, escaping links, reuse;
  • the progress, the delete guards and Free up space;
  • the shortcuts' quoting.

  It also passes at each of the four commits.

• dotnet build launcher/HookshotLauncher.slnx: 0 warnings, with warnings as errors.

• An end-to-end run on Linux, using a fake parts list (file://) and a stand-in make_game: download, check, build, Ready, and the row in builds.json.

• CI: source-regressions.yml now installs .NET 10 next to the Builder's 8 on Linux and Windows, so the core test runs in "Every test". Part 1 of each system compiles the solution with RestoreLockedMode.

Not tested:

• Nothing on Windows: the hard links (CreateHardLinkW), the PowerShell shortcuts, the reduced-motion check, process detection, and %LOCALAPPDATA% paths. CI's Windows compile with SDK 10 has not run yet.
• No real toolchain download from a release, and no real game build.
• Play on Linux starts bin/hookshot directly. It does not go through play-diagnostics.sh or its own systemd scope as the 2.x Linux Builder does.
• The X11 fallback was not run here.
• The screenshots are headless renders with fake data.

Planned next (not in this PR)

• Profiles and a clean folder layout: builds in ~/Games/Hookshot/versions/<version> and saves and settings in ~/Games/Hookshot/profiles, with an importer that moves a 2.x install into it.
• CI and release packaging:
  • building the launcher (the Windows zip and the Linux AppImage);
  • publishing hookshot-launcher.txt and the per-platform tools lists;
  • the 2.x bridge payload (docs/launcher-upgrade.md, sections 1 and 5).

Open design decisions

The calls this PR makes are listed in launcher/README.md, "Open design decisions". Each one can be changed:

• saves are copied, never moved;
• an update takes its build's row and leaves the old folder on disk;
• building a version you already have rebuilds it;
• Delete's guards;
• shortcuts are made on Ready, ticked by default;
• the 2.x Builders' time and space figures;
• the slots are shown as "Slot N";
• "Your GPU" is shown on Linux only for now.

Screenshots

These are headless renders (Avalonia.Headless and Skia, 960x600 at 1x) with fake builds, saves and game files, and a fake home folder shown as ~. Headless rendering draws blurred shadows poorly: the glows under Play and the main buttons show as dark corners here, though they are soft glows in the app.

Before and after the styling pass

Before	After

Every other screen

Before	After

[Joey-Magnus]

A PR for this branch: hckrman101#20 (one commit on top of fabb12c). It adds plain-language problem screens with the fix, finds a game crash in the last run's log at the next start, and a Send report button with consent asked once. Sending needs a report inbox; docs/launcher-reports.md there has the API, and until one exists the button copies the report and opens the issue form. Could magicbean.dev host the inbox? (_trash.panda's agent)