hearthstone-linux-gui README

The project's README from github.com/DawnMagnet/hearthstone-linux-gui. As one markdown file: README.md.

hearthstone-linux-gui

hearthstone-linux-gui desktop launcher preview

中文说明 · Latest release

Linux x86_64 GTK4 Rust Packages

hearthstone-linux-gui is a native GTK4 desktop manager for installing, updating, logging into, and launching Hearthstone on Linux. It is migrated from the original hearthstone-linux project, but the old script-driven workflow has been replaced by a packaged Rust application with a graphical interface.

No terminal workflow is required for normal users. Download a release, install or open it with your desktop environment, click Install / Update, click Login, then click Play.

What Changed From The Original Project

The original hearthstone-linux proved that Hearthstone can run on Linux by combining Blizzard's official game files with Unity's Linux runtime. This project keeps that idea, but turns it into a desktop application that is easier to distribute and maintain.

Old script workflow replaced by a GTK4 desktop workflow

Original hearthstone-linux This project
Script-oriented setup GTK4/libadwaita desktop application
Manual command-line flow Button-driven install, login, update, and launch
Python/Bash toolchain expected by users Packaged runtime; no Python or Bash environment needed for normal use
External keg downloader workflow Native Rust NGDP downloader with cache and verification
Distro-specific setup pain AppImage, DEB, RPM, and native Nix package outputs

Highlights

Packages

Release package formats: AppImage, DEB, RPM, and Nix

Package Best for User experience
AppImage Any x86_64 Linux desktop, including NixOS Download and open the application directly
DEB Debian, Ubuntu, Linux Mint, Pop!_OS, and related systems Open with the graphical software installer
RPM Fedora, RHEL-compatible, openSUSE-style workflows Open with the graphical software installer
Nix NixOS and Nix package users Native package output with desktop file and launcher

Release builds are produced from the unified Nix build pipeline so every format comes from the same source, version, and dependency graph.

Installation For Users

  1. Open the latest release page.
  2. Download the package that matches your system.
  3. Open it with your desktop environment:
    • AppImage: open the downloaded AppImage. If your file manager asks for it, enable "Allow executing file as program" in file properties.
    • DEB/RPM: double-click the package and install it with your graphical software center.
    • Nix/NixOS: install the native Nix package through your normal Nix workflow.
  4. Launch hearthstone-linux-gui from the application menu.

After the app opens, the normal flow is:

  1. Choose your Region and Locale.
  2. Click Install / Update.
  3. Click Login and complete Battle.net login in your browser.
  4. Return to the app and click Play.

The app stores user data under standard XDG locations in your home directory. Interrupted Unity downloads are resumed automatically, and already downloaded game data is reused when possible.

Nix, NixOS, And Home Manager

This repository is a flake for x86_64-linux. It currently exposes package, app, and development shell outputs; it does not expose dedicated NixOS or Home Manager modules. Use the package output in your system or home package list.

Run the application directly from GitHub:

nix run github:DawnMagnet/hearthstone-linux-gui

Build outputs from a local checkout:

nix build .#default
nix build .#AppImage
nix build .#runtime

The available flake outputs are:

Output Purpose
packages.x86_64-linux.default Native Nix package for the GTK launcher
packages.x86_64-linux.runtime FHS runtime wrapper used to launch the downloaded Unity player
packages.x86_64-linux.AppImage Portable AppImage build
packages.x86_64-linux.AppDir Intermediate AppDir used to build the AppImage
apps.x86_64-linux.default nix run entrypoint
devShells.x86_64-linux.default Rust/GTK development shell

For NixOS flakes, add the repository as an input and install the package with environment.systemPackages:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hearthstone-linux-gui.url = "github:DawnMagnet/hearthstone-linux-gui";
  };

  outputs = { nixpkgs, hearthstone-linux-gui, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [
            hearthstone-linux-gui.packages.${pkgs.stdenv.hostPlatform.system}.default
          ];
        })
      ];
    };
  };
}

For standalone Home Manager flakes, add it to home.packages:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    hearthstone-linux-gui.url = "github:DawnMagnet/hearthstone-linux-gui";
  };

  outputs = { nixpkgs, home-manager, hearthstone-linux-gui, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in
    {
      homeConfigurations.my-user = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [
          {
            home.username = "my-user";
            home.homeDirectory = "/home/my-user";
            home.stateVersion = "25.05";
            home.packages = [
              hearthstone-linux-gui.packages.${system}.default
            ];
          }
        ];
      };
    };
}

If you use Home Manager as a NixOS module, put the same package expression in home-manager.users.<name>.home.packages.

How It Works

Hearthstone ships official data through Blizzard's NGDP distribution system. The game is built with Unity, and the Linux Unity player can run the game data after the platform layout is adapted.

This launcher automates that process:

  1. Downloads the official Hearthstone game data for the selected region and locale.
  2. Verifies and caches downloaded content.
  3. Transforms the macOS-style payload into a Linux-ready layout.
  4. Detects the required Unity version and installs the matching Linux Unity player.
  5. Installs compatibility files and configuration needed by the game.
  6. Registers the login callback handler and stores the encrypted token locally.
  7. Launches the game through a controlled Linux runtime environment.

No proprietary Hearthstone files are stored in this repository or shipped in the launcher packages. The application retrieves official files from their upstream distribution endpoints during installation.

Status And Limitations

Troubleshooting

Symptom What to try
The app says Login Required Click Login again and finish the browser flow (see Browser login).
--write-token says the token format is invalid Keep the region prefix and both dashes (XX-<32 characters>-<account id>); the account id length varies between accounts.
The game closes the Battle.net connection with TLS errors See Certificate failures on rolling distros.
The game window is solid white / flickers at launch See White screen on some AMD GPUs.
Install was interrupted Click Install / Update again; resumable and cached downloads will be reused.
The game does not launch after an update Click Install / Update once to repair Unity/runtime files.
The game exits immediately with Unable to load mono library (NixOS flake) Update the flake; the FHS environment now ships zlib, which the bundled Mono runtime requires.
A package opens but does not start on an unusual distro Try the AppImage release, which carries the widest runtime set.

Browser login

Clicking Login registers the launcher as the system handler for the blizzard-hearthstone:// URL scheme and opens the Battle.net sign-in page. After you sign in, the browser redirects to that scheme and the launcher writes the login token automatically — no copy-paste needed. The token is stored encrypted at <game dir>/token.

If the browser instead shows http://localhost:0/... failing with ERR_UNSAFE_PORT (Chrome) or NS_ERROR_PORT_ACCESS_NOT_ALLOWED (Firefox), the handler was not registered or your release predates the callback fix. You can finish the login manually:

  1. Copy the value of the ST= parameter from the blocked URL (everything after ST= up to the next &).
  2. Run:
    hearthstone-linux-gui --write-token 'US-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-1234567'
    With the AppImage: ./hearthstone-linux-gui_*.AppImage --write-token '...'. Passing the whole failed URL to --auth-callback also works.

A valid token is a two-character region prefix, a dash, 32 alphanumeric characters, a dash, and your numeric account id. If the command still rejects the value, check that the region prefix was not stripped while copying.

Certificate failures on rolling distros

If the game starts but cannot sign in to Battle.net, and ~/.config/unity3d/Blizzard Entertainment/Hearthstone/Player.log or <game dir>/Logs/**/BattleNet.log contains Curl error 35 ... UnityTls error code: 7 or Ssl error ... CERTIFICATE_VERIFY_FAILED / ERROR_SDK_SOCKET_CLOSED (1901), the game cannot find the system certificate store. The Unity player hard-codes Debian/RHEL CA bundle paths that do not exist on openSUSE and some other rolling distros. Related upstream discussion: 0xf4b1/hearthstone-linux#108.

On openSUSE Tumbleweed:

# 1) Provide the CA bundle paths the Unity player expects (once, needs root)
sudo ln -sf /var/lib/ca-certificates/ca-bundle.pem /etc/ssl/certs/ca-bundle.crt
sudo ln -sf /var/lib/ca-certificates/ca-bundle.pem /etc/ssl/certs/ca-certificates.crt

# 2) Import the system roots into Mono's user trust store
#    (cert-sync comes with the distro mono-core package)
cert-sync --user /etc/ssl/certs/ca-bundle.crt

If BattleNet.log still reports a missing libmono-btls-shared.so, copy that library from your distro's mono-core package into <game dir>/Bin/Hearthstone_Data/MonoBleedingEdge/x86_64/ and launch with MONO_TLS_PROVIDER=btls.

White screen on some AMD GPUs

On some AMD integrated GPUs (for example Rembrandt / Radeon 680M), the game window renders solid white and flickers, while Player.log shows ERROR: Shader Hidden/Universal Render Pipeline/DBufferClear shader is not supported on this GPU. The Linux-repackaged game data is missing the shader variants these feature levels need; this cannot be fixed from the launcher at runtime and is tracked in #13. Forcing a different renderer (-force-glcore, -force-vulkan) does not help, but enabling Use discrete GPU in the launcher may.

Release builds default to INFO-level logging. Detailed diagnostic logs can be enabled by developers with the standard RUST_LOG environment variable when debugging locally.

Hearthstone, Battle.net, Blizzard Entertainment, and related names, trademarks, game assets, services, and other materials are owned by Blizzard Entertainment, Inc. or its affiliates and licensors.

This project is an unofficial compatibility launcher. It is not produced, published, sponsored, approved, endorsed, maintained, or supported by Blizzard Entertainment, Battle.net, Microsoft, Activision Blizzard, or any of their affiliates. No proprietary Hearthstone game assets are stored in this repository or shipped in the launcher packages.

See LEGAL.md for the full legal information, project boundaries, user responsibilities, and rights-holder request process.

hearthstone-linux-gui (DawnMagnet/hearthstone-linux-gui)

login
Searching Database…

217 ·GitHub
Hearthstone-linux-gui
What is this?It is a native GTK4 desktop manager for installing, updating, logging into, and launching Hearthstone on Linux, written in Rust.
Is this still a script, or a packaged app like the original hearthstone-linux project it's based on?It replaces the old script-driven workflow with a fully packaged Rust/GTK4 desktop application; normal users never touch a terminal.
How do I install it and get playing?Download the release package matching your distro (AppImage, DEB, RPM, or Nix), open it with your desktop environment, then click Install/Update, Login, and Play inside the app.
Do I need Python or Bash installed first?No. The launcher is a single packaged Rust binary with its own runtime, so no Python or Bash toolchain is required for normal use.
Does everything just work once installed?Mostly, but it's unofficial: the in-game shop may stay unavailable, some AMD integrated GPUs show a white flickering screen from missing shader variants, and rolling-release distros can hit TLS certificate errors on login.
Does it work on any Linux distro, or only NixOS?It targets x86_64 Linux broadly — the same project ships as AppImage, DEB, RPM, and a native Nix package for NixOS, Debian/Ubuntu, Fedora/RHEL-style systems.
How is my Battle.net login handled?After signing in through the browser, the launcher captures the login token automatically via a URL scheme handler and keeps it stored encrypted on disk.
How does the launcher actually get the Hearthstone game files?It pulls official Hearthstone data from Blizzard's NGDP distribution system, verifies and caches it, converts the macOS-style payload into a Linux-ready layout, and installs the matching Linux Unity player to run it.
Does any Blizzard game data ship inside the repo or releases?No. The project states no proprietary Hearthstone files are stored in the repository or packages; everything is fetched from Blizzard's official endpoints during installation.
What happens if a download gets interrupted?Unity runtime and game data downloads resume automatically from the partial file, and already-downloaded, verified content is reused instead of re-downloading.
Can I use this from a Nix flake instead of downloading a release?Yes, the repo is an x86_64-linux flake exposing package, app, and devShell outputs that can be added as a NixOS or Home Manager input.
What are similar projects?bloodborne_pc, juhradial-mx, exodium, omarchy-meeting-recorder, codex-desktop-linux, gow3_pc, flea, gtkx
Which topics is it in?libadwaita, login, resumable, gtk4, unity3d, nixos, nix, x86-64, launcher, linux-desktop, appimage, linux-app
Creator
DawnMagnet
Size
1.1 MB
Stars
217
Updated
CommitOct 15Releasev0.3.0Oct 15
Age
5mo
Commits · 90 Days